opencode.json 配置详解

本文档是 OpenCode 配置文件的完整参考手册，详细解释 opencode.json 中可用的每一个字段。

📝 课程笔记

本课核心知识点整理：

配置选项参考学霸笔记

配置文件位置与优先级

OpenCode 按以下顺序加载配置（优先级从低到高，后者覆盖前者）：

优先级	位置	说明
1（最低）	远程 `.well-known/opencode`	远程组织默认配置（通过 Auth 机制获取）
2	`~/.config/opencode/opencode.json`	全局用户配置
3	`OPENCODE_CONFIG` 环境变量	自定义配置文件路径
4	`./opencode.json`	项目根目录配置
5	`./.opencode/opencode.json`	项目 .opencode 目录配置
6	`OPENCODE_CONFIG_CONTENT` 环境变量	内联配置内容（JSON 字符串）
7（最高）	受管配置目录	企业部署，管理员控制

受管配置目录（企业部署，最高优先级）：

平台	路径
macOS	`/Library/Application Support/opencode`
Windows	`%ProgramData%\opencode`
Linux	`/etc/opencode`

顶层配置 (Top Level)

配置文件的根对象中包含的字段。

基础设置

字段	类型	说明	默认值
`username`	string	在对话中显示的用户名。如果不设置，使用系统用户名。	系统用户
`theme`	string	界面主题名称。详见主题列表。	-
`autoupdate`	boolean \| "notify"	自动更新行为。`true`=自动更新，`false`=禁用，`"notify"`=仅通知。	-
`logLevel`	enum	日志级别。可选值：`"DEBUG"`, `"INFO"`, `"WARN"`, `"ERROR"`。	-
`snapshot`	boolean	是否启用 Git 快照备份机制。设为 `false` 禁用。	未设置时启用

模型与 Agent

字段	类型	说明
`model`	string	主模型 ID (格式: `provider/model`)，用于复杂任务。
`small_model`	string	小模型 ID，用于生成标题、摘要等简单任务。
`default_agent`	string	默认启动的 Primary Agent 名称。默认为 `build`。

行为控制

字段	类型	说明	默认值
`share`	enum	会话分享行为。`"manual"`(手动), `"auto"`(自动), `"disabled"`(禁用)。	`"manual"`
`disabled_providers`	string[]	禁用的 Provider 列表。即使有 Key 也不会加载。	`[]`
`enabled_providers`	string[]	仅启用的 Provider 列表。设置后，不在列表中的都会被忽略。	-

界面配置 (tui)

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

json

"tui": {
  "scroll_speed": 3,
  "diff_style": "auto"
}

字段	类型	说明	默认值
`scroll_speed`	number	鼠标滚轮滚动速度倍率（最小 0.001）。	3
`scroll_acceleration`	object	滚动加速配置。	-
`scroll_acceleration.enabled`	boolean	是否启用 macOS 风格的惯性滚动加速。	`false`
`diff_style`	enum	差异对比显示样式。`"auto"`(自适应), `"stacked"`(始终单列)。	`"auto"`

Provider 配置 (provider)

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

键名：provider (单数)
类型：Record<string, ProviderConfig>

json

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

通用选项 (options)

所有 Provider 都支持的 options 字段：

字段	类型	说明
`apiKey`	string	API 密钥。建议使用 `{env:VAR}` 引用环境变量。
`baseURL`	string	自定义 API 端点地址（用于代理或兼容服务）。
`timeout`	number \| false	请求超时时间（毫秒）。默认 300000 (5分钟)。`false` 禁用超时。
`setCacheKey`	boolean	是否启用 Prompt Cache 键（用于 Anthropic/DeepSeek 等）。默认 `false`。
`enterpriseUrl`	string	GitHub Enterprise URL (仅 Copilot Provider)。

Provider 级字段

Provider 对象本身还支持以下字段：

字段	类型	说明
`name`	string	Provider 显示名称。
`env`	string[]	环境变量名列表（用于自动检测 API Key）。
`whitelist`	string[]	仅允许使用的模型列表。
`blacklist`	string[]	禁止使用的模型列表。

模型特定配置 (models)

针对特定模型进行微调：

json

"provider": {
  "anthropic": {
    "models": {
      "claude-3-7-sonnet": {
        "variants": {
          "thinking": { "disabled": true }
        }
      }
    }
  }
}

Agent 配置 (agent)

定义或覆盖 Agent 的行为。

键名：agent (单数)
类型：Record<string, AgentConfig>

json

"agent": {
  "code-reviewer": {
    "mode": "subagent",
    "prompt": "You are a code reviewer...",
    "permission": { "edit": "deny" }
  }
}

字段	类型	说明
`description`	string	Agent 的简短描述，显示在 `/agent` 列表中。
`mode`	enum	Agent 类型。`"primary"`(独立模式), `"subagent"`(子代理), `"all"`。
`model`	string	该 Agent 专用的模型 ID。
`variant`	string	默认模型变体（仅在使用该 Agent 配置的模型时生效）。
`prompt`	string	System Prompt (人设指令)。
`temperature`	number	温度系数 (0.0 - 1.0)。
`top_p`	number	核采样参数 (0.0 - 1.0)。
`steps`	number	最大自动迭代步数。
`color`	string	在界面中显示的颜色 (Hex 格式，如 `#FF0000`)，或主题色名（如 `primary`）。
`hidden`	boolean	是否在 `@` 自动补全菜单中隐藏此 Agent。
`permission`	object	该 Agent 的专用权限配置 (覆盖全局权限)。
`disable`	boolean	是否禁用此 Agent。

权限配置 (permission)

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

键名：permission (单数)
类型：Record<string, Rule | Action>

值可以是以下字符串之一（Action）：

"allow": 自动允许
"ask": 每次询问
"deny": 拒绝

也可以是对象（Rule）进行更细粒度控制。

json

"permission": {
  "edit": "ask",
  "bash": {
    "*": "ask",
    "git *": "allow",
    "rm *": "deny"
  }
}

可用权限项：

read: 读取文件
edit: 编辑/写入文件
bash: 执行命令
glob: 文件查找
grep: 内容搜索
list: 列出目录
task: 调用子 Agent
external_directory: 访问外部目录
todowrite: TODO 写入
todoread: TODO 读取
question: 提问工具
webfetch: 访问网页
websearch: 搜索引擎
codesearch: 代码搜索
lsp: LSP 操作
doom_loop: 死循环检测
skill: 技能调用

命令配置 (command)

定义自定义斜杠命令。

键名：command (单数)
类型：Record<string, CommandConfig>

json

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

字段	类型	说明
`template`	string	提示词模板。支持 `$ARGUMENTS` 等变量。
`description`	string	命令描述。
`agent`	string	执行此命令的 Agent。
`model`	string	执行此命令的模型。
`subtask`	boolean	是否作为子任务运行。

快捷键配置 (keybinds)

自定义快捷键。

键名：keybinds (复数)

json

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

常用配置项（完整列表见快捷键速查）：

leader: 前缀键（默认 ctrl+x）
app_exit: 退出应用
session_new: 新建会话
session_list: 会话列表
model_list: 切换模型
agent_list: 切换 Agent
input_submit: 发送消息
input_newline: 换行

服务器配置 (server)

配置 opencode serve 或 opencode web 的行为。

json

"server": {
  "port": 4096,
  "hostname": "0.0.0.0",
  "mdns": true,
  "mdnsDomain": "opencode.local"
}

字段	类型	说明	默认值
`port`	number	监听端口。	4096
`hostname`	string	监听地址。启用 mdns 时默认为 `0.0.0.0`。	127.0.0.1
`mdns`	boolean	是否启用 mDNS 本地网络发现。	false
`mdnsDomain`	string	mDNS 服务的自定义域名。	`opencode.local`
`cors`	string[]	允许跨域请求的来源列表。	-

实验性功能 (experimental)

启用正在开发中的实验性功能。注意：这些功能不稳定，可能随时变更。

json

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

字段	类型	说明
`batch_tool`	boolean	启用批量操作工具。
`openTelemetry`	boolean	启用 OpenTelemetry 链路追踪。
`disable_paste_summary`	boolean	禁用粘贴大段文本时的自动摘要。
`continue_loop_on_deny`	boolean	当工具调用被用户拒绝时，是否让 Agent 继续思考（而不是中断）。
`primary_tools`	string[]	指定仅限 Primary Agent 使用的工具列表。
`mcp_timeout`	number	MCP 请求的全局超时时间（毫秒）。

Hook（事件钩子）功能通过插件系统实现，不是 experimental 配置。详见 Hooks 机制。

其他配置

compaction (压缩)

控制上下文压缩行为。

json

"compaction": {
  "auto": true,
  "prune": true,
  "reserved": 10000
}

字段	类型	说明	默认值
`auto`	boolean	上下文满时自动触发压缩。	`true`
`prune`	boolean	压缩时移除旧的工具输出。	`true`
`reserved`	number	压缩时的 Token 缓冲区，预留足够窗口避免溢出。	-

watcher (监视器)

控制文件系统监视。

json

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

ignore: 忽略监视的文件 glob 模式列表。

instructions (指令)

json

"instructions": ["docs/rules.md", ".cursor/rules/*.md"]

指定额外的全局指令文件列表。

plugin (插件)

json

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

要加载的插件列表。支持 npm 包名或本地文件路径。

skills (技能路径)

json

"skills": {
  "paths": ["./skills", "~/shared-skills"],
  "urls": ["https://example.com/.well-known/skills/"]
}

字段	类型	说明
`paths`	string[]	额外的 Skill 文件夹路径。
`urls`	string[]	远程 Skill 获取地址。

mcp (扩展协议)

配置 Model Context Protocol 服务器。详见 MCP 文档。

formatter (格式化)

配置代码格式化工具。详见格式化器文档。

lsp (语言服务)

配置 LSP 服务器。详见 LSP 文档。

enterprise (企业版)

json

"enterprise": {
  "url": "https://github.example.com"
}

配置 GitHub Enterprise 实例地址。

附录：源码参考

点击展开查看源码位置

更新时间：2026-02-14

所有配置 Schema 定义均在 packages/opencode/src/config/config.ts 文件中。

配置项	对应 Schema	行号范围
顶层 Info	`Info`	L1004-L1197
Provider	`Provider`	L951-L1001
Agent	`Agent`	L672-L758
Permission	`Permission`	L621-L652
Keybinds	`Keybinds`	L761-L917
TUI	`TUI`	L919-L931
Server	`Server`	L933-L944
Command	`Command`	L654-L661
Skills	`Skills`	L663-L670
MCP	`Mcp`	L523-L584
Experimental	`experimental`	L1172-L1192

opencode.json 配置详解 ​

📝 课程笔记 ​

配置文件位置与优先级 ​

顶层配置 (Top Level) ​

基础设置 ​

模型与 Agent ​

行为控制 ​

界面配置 (tui) ​

Provider 配置 (provider) ​

通用选项 (options) ​

Provider 级字段 ​

模型特定配置 (models) ​

Agent 配置 (agent) ​

权限配置 (permission) ​

命令配置 (command) ​

快捷键配置 (keybinds) ​

服务器配置 (server) ​

实验性功能 (experimental) ​

其他配置 ​

compaction (压缩) ​

watcher (监视器) ​

instructions (指令) ​

plugin (插件) ​

skills (技能路径) ​

mcp (扩展协议) ​

formatter (格式化) ​

lsp (语言服务) ​

enterprise (企业版) ​

附录：源码参考 ​

opencode.json 配置详解

📝 课程笔记

配置文件位置与优先级

顶层配置 (Top Level)

基础设置

模型与 Agent

行为控制

界面配置 (tui)

Provider 配置 (provider)

通用选项 (options)

Provider 级字段

模型特定配置 (models)

Agent 配置 (agent)

权限配置 (permission)

命令配置 (command)

快捷键配置 (keybinds)

服务器配置 (server)

实验性功能 (experimental)

其他配置

compaction (压缩)

watcher (监视器)

instructions (指令)

plugin (插件)

skills (技能路径)

mcp (扩展协议)

formatter (格式化)

lsp (语言服务)

enterprise (企业版)

附录：源码参考