Config

Config 是 OpenCode 的配置系统，支持多层合并配置。

概述

Config 使用分层配置系统，允许从多个来源加载配置并合并。配置支持 JSONC（带注释的 JSON）格式，并按优先级合并：远程 < 全局 < 项目 < 环境变量/命令行标志。

配置加载顺序（从低到高优先级）

主要配置字段

command

定义自定义命令。

{
  "command": {
    "deploy": {
      "description": "Deploy to production",
      "agent": "build",
      "template": "Deploy following changes: $1"
    }
  }
}

agent

定义自定义 Agent。

{
  "agent": {
    "my-agent": {
      "description": "Custom agent",
      "mode": "primary",
      "permission": {
        "*": "allow",
        "write": "ask"
      }
    }
  }
}

mode (已废弃)

旧版 Agent 定义，会自动迁移到 agent 字段。

plugin

插件列表（支持数组合并）。

{
  "plugin": [
    "plugin-package@1.0.0",
    "file:///path/to/local/plugin.js"
  ]
}

permission

权限配置。

{
  "permission": {
    "*": "allow",
    "write": "ask",
    "bash": {
      "rm -rf": "deny"
    }
  }
}

mcp

MCP 服务器配置。

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem"]
    },
    "remote-server": {
      "type": "remote",
      "url": "https://example.com/mcp"
    }
  }
}

instructions

全局指令（支持数组合并）。

{
  "instructions": [
    "Be concise",
    "Use TypeScript"
  ]
}

compaction

消息压缩设置。

{
  "compaction": {
    "auto": true,
    "prune": true,
    "threshold": 50
  }
}

share

会话分享设置。

{
  "share": "auto"  // "auto" | "disabled" | "manual"
}

snapshot

快照设置。

{
  "snapshot": true  //   // true | false
}

username

用户名显示。

keybinds

键盘绑定配置。

配置文件位置

全局配置

~/.opencode/opencode.jsonc
~/.opencode/opencode.json

项目配置

./opencode.jsonc
./opencode.json

环境变量覆盖

OPENCODE_CONFIG=/path/to/config.jsonc
OPENCODE_CONFIG_CONTENT='{"key": "value"}'
OPENCODE_PERMISSION='{"write": "ask"}'

命令行标志

标志说明
OPENCODE_CONFIG自定义配置文件路径
OPENCODE_CONFIG_CONTENT内联 JSON 配置
OPENCODE_PERMISSION权限配置（JSON 字符串）
OPENCODE_CONFIG_DIR额外的配置目录
OPENCODE_DISABLE_AUTOCOMPACT禁用自动压缩
OPENCODE_DISABLE_PRUNE禁用快照修剪
OPENCODE_DISABLE_DEFAULT_PLUGINS禁用默认插件

典型使用场景

1. 获取当前配置

const config = await Config.get()

console.log(config.agent) // Agent 配置
console.log(config.permission) // 权限配置
console.log(config.mcp) // MCP 配置

2. 修改配置

在 opencode.jsonc 中编辑：

{
  // 我的自定义配置
  "agent": {
    "my-custom-agent": {
      "description": "Custom agent for my needs",
      "mode": "primary",
    },
  },
  "permission": {
    "*": "allow",
    "write": "ask",
  },
}

3. 使用环境变量覆盖

# 设置权限
export OPENCODE_PERMISSION='{"write": "ask", "bash": "deny"}'

# 使用自定义配置文件
export OPENCODE_CONFIG=/path/to/custom.jsonc

# 运行 OpenCode
opencode

4. 配置 MCP 服务器

{
  "mcp": {
    "gitlab": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextusn-protocol/server-gitlab"],
    },
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem"],
    },
    "remote-mcp": {
      "type": "remote",
      "url": "https://api.example.com/sse",
    },
  },
}

5. 配置插件

{
  "plugin": [
    // 从 npm 安装
    "my-plugin@1.0.0",

    // 本地文件
    "file:///home/user/my-plugin.js",

    // 相对路径
    "./my-plugin.js",
  ],
}

配置合并规则

数组字段合并

以下字段使用数组合并（去重）：

  • plugin
  • instructions

对象字段合并

以下字段使用深度合并：

  • agent
  • command
  • permission
  • mcp
  • keybinds

配置验证

配置在加载时会进行验证，无效的配置会记录错误：

// 错误示例
{
  "permission": "invalid"  // 应该是对象，不是字符串
}

从 Well-known 加载配置

OpenCode 支持从 .well-known/opencode 端点加载远程配置：

// Auth 配置中的 well-known 类型
{
  "type": "wellknown",
  "url": "https://example.com",
  "key": "OPENCODE_AUTH_TOKEN",
  "token": "your-token"
}

这允许组织提供默认配置，用户可以覆盖。

配置目录扫描

OpenCode 扫描以下目录查找配置：

  1. 全局配置目录：~/.opencode/
  2. 项目配置目录（向上搜索）：./.opencode/
  3. 自定义配置目录（通过 OPENCODE_CONFIG_DIR 指定）

每个目录还扫描：

  • agent/ 或 agents/ - Agent 定义
  • command/ 或 commands/ - 命令定义
  • skill/ 或 skills/ - Skill 定义

配置示例

完整示例

{
  // 用户配置
  "username": "John Doe",

  // Agent 配置
  "agent": {
    "reviewer": {
      "description": "Code reviewer agent",
      "mode": "primary",
      "permission": {
        "*": "allow",
        "write": "ask",
      },
    },
  },

  // 权限配置
  "permission": {
    "*": "allow",
    "write": "ask",
    "bash": {
      "rm -rf": "deny",
    },
  },

  // 命令配置
  "command": {
    "deploy": {
      "description": "Deploy to production",
      "agent": "build",
      "template": "Deploy changes: $1",
    },
  },

  // MCP 配置
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "@modelcontextprotocol/server-filesystem"],
    },
  },

  // 插件
  "plugin": ["my-plugin@1.0.0"],

  // 压缩设置
  "compaction": {
    "auto": true,
    "prune": true,
  },

  // 分享设置
  "share": "auto",

  // 快照设置
  "snapshot": true,

  // 键盘绑定
  "keybinds": {
    "quit": "ctrl+d",
    "submit": "ctrl+enter",
  },
}

配置迁移

autoshare → share

旧版 autoshare 配置自动迁移到 share：

if (result.autoshare === true && !result.share) {
  result.share = "auto"
}

mode → agent

旧版 mode 字段自动迁移到 agent：

for (const [name, mode] of Object.entries(result.mode)) {
  result.agent = mergeDeep(result.agent ?? {}, {
    [name]: {
      ...mode,
      mode: "primary" as const,
    },
  })
}

tools → permission

旧版 tools 配置自动迁移到 permission：

if (result.tools) {
  const perms: Record<string, PermissionAction> = {}
  for (const [tool, enabled] of Object.entries(result.tools)) {
    const action: PermissionAction = enabled ? "allow" : "deny"
    // 映射到新权限系统
    if (tool === "write" || tool === "edit" || tool === "patch" || tool === "multiedit") {
      perms.edit = action
      continue
    }
    perms[tool] = action
  }
  result.permission = mergeDeep(perms, result.permission ?? {})
}

变更历史

版本变更内容日期
v1初始 Config 架构-
v1.1添加 MCP 配置-
v1.2添加 well-known 支持-
v1.3添加数组字段合并逻辑-

相关文档