OpenCode 中文社区

Appearance

D. 配置选项参考 ​

💡 一句话总结：opencode.json 中可用的每一个字段详解

配置文件位置与优先级 ​

OpenCode 按以下顺序加载配置（优先级从低到高）：

  1. 远程/默认配置：从 .well-known/opencode 加载
  2. 全局配置：~/.config/opencode/opencode.json
  3. 自定义全局路径：OPENCODE_CONFIG 环境变量指定的路径
  4. 项目配置：项目根目录下的 opencode.json
  5. 内联配置：OPENCODE_CONFIG_CONTENT 环境变量的内容

顶层配置 ​

基础设置 ​

字段类型说明默认值
usernamestring在对话中显示的用户名系统用户
themestring界面主题名称-
autoupdateboolean | "notify"自动更新行为-
logLevelenum日志级别"INFO"
snapshotboolean是否启用 Git 快照备份true

模型与 Agent ​

字段类型说明
modelstring主模型 ID
small_modelstring小模型 ID
default_agentstring默认启动的 Primary Agent

行为控制 ​

字段类型说明默认值
shareenum会话分享行为"manual"
disabled_providersstring[]禁用的 Provider 列表[]
enabled_providersstring[]仅启用的 Provider 列表-

tui（界面配置） ​

控制终端界面的显示行为。

字段类型说明默认值
scroll_speednumber鼠标滚轮滚动速度倍率3
scroll_acceleration.enabledboolean是否启用惯性滚动加速false
diff_styleenum差异对比显示样式"auto"

provider（Provider 配置） ​

配置模型提供商的 API Key、端点和模型参数。

json
"provider": {
  "anthropic": {
    "options": {
      "apiKey": "sk-...",
      "timeout": 600000
    }
  }
}

通用选项 (options) ​

字段类型说明
apiKeystringAPI 密钥
baseURLstring自定义 API 端点地址
timeoutnumber | false请求超时时间（毫秒）
setCacheKeyboolean是否启用 Prompt Cache 键

agent（Agent 配置） ​

定义或覆盖 Agent 的行为。

json
"agent": {
  "code-reviewer": {
    "mode": "subagent",
    "prompt": "You are a code reviewer...",
    "permission": { "edit": "deny" }
  }
}
字段类型说明
descriptionstringAgent 的简短描述
modeenumAgent 类型
modelstring该 Agent 专用的模型 ID
promptstringSystem Prompt
temperaturenumber温度系数 (0.0 - 1.0)
top_pnumber核采样参数 (0.0 - 1.0)
stepsnumber最大自动迭代步数
colorstring界面中显示的颜色
hiddenboolean是否在自动补全菜单中隐藏
permissionobject该 Agent 的专用权限配置
disableboolean是否禁用此 Agent

permission（权限配置） ​

控制 OpenCode 访问系统资源的权限。

值可以是以下字符串之一：

  • "allow": 自动允许
  • "ask": 每次询问
  • "deny": 拒绝
json
"permission": {
  "read": "ask",
  "bash": {
    "*": "ask",
    "git *": "allow",
    "rm *": "deny"
  }
}

可用权限项：

  • read: 读取文件
  • edit: 编辑/写入文件
  • bash: 执行命令
  • webfetch: 访问网页
  • websearch: 搜索引擎
  • codesearch: 代码搜索
  • glob: 文件查找
  • grep: 内容搜索
  • list: 列出目录
  • external_directory: 访问外部目录
  • lsp: LSP 操作
  • task: 调用子 Agent

command（命令配置） ​

定义自定义斜杠命令。

json
"command": {
  "commit": {
    "template": "Generate a commit message for these changes:\n$DIFF",
    "agent": "build"
  }
}

keybinds（快捷键配置） ​

自定义快捷键。

json
"keybinds": {
  "leader": "ctrl+x",
  "session_new": "<leader>n"
}

server（服务器配置） ​

配置 opencode serve 的行为。

字段类型说明默认值
portnumber监听端口4096
hostnamestring监听地址127.0.0.1
mdnsboolean是否启用 mDNS 本地网络发现false
corsstring[]允许跨域请求的来源列表-

experimental（实验性功能） ​

启用正在开发中的实验性功能。

json
"experimental": {
  "batch_tool": true,
  "openTelemetry": true
}

compaction（压缩） ​

控制上下文压缩行为。

字段说明
auto上下文满时自动触发压缩
prune压缩时移除旧的工具输出

watcher（监视器） ​

控制文件系统监视。

json
"watcher": {
  "ignore": ["node_modules/**", ".git/**"]
}

plugin（插件） ​

要加载的插件列表。

json
"plugin": ["opencode-helicone-session", "./my-plugin.js"]

📚 更多完整模板：Prompt 模板库

微信群