当前位置：首页 > news >正文

第四章：配置体系详解与优先级

news 2026/6/4 7:29:12

第四章：配置体系详解与优先级

OpenCode 的强大之处在于一切皆可配置，且配置即代码。本章系统讲解配置文件的格式、存放位置、合并与优先级规则、变量替换，以及全部主要配置项。吃透本章是后续所有自定义与「最优化配置」的前提。

4.1 配置文件格式：JSON / JSONC

OpenCode 同时支持 JSON 和 JSONC（带注释的 JSON）。推荐用 .jsonc 写注释，便于团队理解：

{"$schema": "https://opencode.ai/config.json","model": "anthropic/claude-sonnet-4-5","autoupdate": true,"server": {"port": 4096}
}

务必加上 $schema，编辑器即可基于 opencode.ai/config.json 提供校验与自动补全。TUI 专属设置使用另一套 Schema：opencode.ai/tui.json。

4.2 配置文件位置

配置可以放在多个位置，它们各自承担不同角色：

角色	路径	用途
全局配置	`~/.config/opencode/opencode.json`	用户级偏好（Provider、模型、权限等）
全局 TUI	`~/.config/opencode/tui.json`	用户级 TUI 设置（主题、键位等）
项目配置	项目根目录 `opencode.json`	项目专属设置，可提交进 Git
项目 TUI	项目根 `tui.json`	项目专属 TUI 设置
自定义路径	`OPENCODE_CONFIG` 环境变量指向的文件	自定义覆盖
自定义目录	`OPENCODE_CONFIG_DIR` 指向的目录	存放 agents/commands/plugins 等

.opencode/ 与 ~/.config/opencode/ 目录下使用复数子目录名：agents/、commands/、modes/、plugins/、skills/、tools/、themes/（单数名也兼容）。

启动时，OpenCode 先在当前目录找配置，再向上回溯到最近的 Git 目录。

4.3 关键机制：配置是「合并」而非「替换」

这是最容易踩坑、也最重要的一点：多个配置文件会被合并，而不是后者整体替换前者。只有发生冲突的键才会被后者覆盖，其余设置全部保留。

例如：全局配置设了 autoupdate: true，项目配置设了 model: "anthropic/claude-sonnet-4-5"，最终配置会同时包含这两项。

这意味着你可以：

把通用偏好（Provider、权限、主题）放全局；
把项目专属设置（模型、规则、命令）放项目；
二者自动合并，互不丢失。

4.4 优先级顺序

配置源按以下顺序加载，后者覆盖前者的冲突键：

远程配置（来自组织的 .well-known/opencode）—— 组织默认值
全局配置（~/.config/opencode/opencode.json）—— 用户偏好
自定义配置（OPENCODE_CONFIG 环境变量）—— 自定义覆盖
项目配置（项目内 opencode.json）—— 项目专属
.opencode 目录（agents / commands / plugins）
内联配置（OPENCODE_CONFIG_CONTENT 环境变量）—— 运行时覆盖
托管配置文件（如 macOS 的 /Library/Application Support/opencode/）—— 管理员控制
macOS 托管偏好（通过 MDM 下发的 .mobileconfig）—— 最高优先级，用户不可覆盖

简单记：远程 < 全局 < 自定义 < 项目 < 内联 < 托管。托管设置覆盖一切，常用于企业统一管控（详见第十章/官方 policies 文档）。

4.5 远程配置（组织默认值）

组织可以通过 .well-known/opencode 端点提供默认配置，在你认证某个支持该机制的 Provider 时自动拉取。它作为最底层，其它配置都能覆盖它。

典型用法：组织默认提供一批 MCP 服务器但默认禁用，你在本地按需开启：

{"$schema": "https://opencode.ai/config.json","mcp": {"jira": {"type": "remote","url": "https://jira.example.com/mcp","enabled": true}}
}

4.6 TUI 专属配置（`tui.json`）

主题、键位、滚动、提醒等 TUI 设置放在独立的 tui.json：

{"$schema": "https://opencode.ai/tui.json","theme": "tokyonight","scroll_speed": 3,"diff_style": "auto","mouse": true,"attention": {"enabled": true,"notifications": true,"sound": true,"volume": 0.4}
}

attention.enabled 可开启桌面通知与提示音，适合长任务跑完时提醒你。

opencode.json 里旧的 theme、keybinds、tui 顶层键已废弃，会在可能时自动迁移到 tui.json。新配置请直接写到 tui.json。

可用 OPENCODE_TUI_CONFIG 指向自定义 TUI 配置文件。

4.7 主要配置项总览

以下是 opencode.json 中最常用的配置项，后续章节会逐一深入。先建立全局印象：

配置项	作用	相关章节
`model` / `small_model`	主模型 / 轻量任务模型	第五、九章
`provider`	Provider 与模型选项（密钥、超时、缓存、推理强度等）	第五章
`enabled_providers` / `disabled_providers`	启用 / 禁用 Provider	第五章
`agent`	自定义 / 覆盖 Agent	第六章
`default_agent`	默认主智能体	第六章
`command`	自定义命令	第七章
`instructions`	额外规则文件（路径 / glob / URL）	第七章
`mcp`	MCP 服务器	第八章
`plugin`	插件（npm 包）	第八章
`tools`	（旧）工具开关，已并入 `permission`	第八章
`permission`	权限系统（allow/ask/deny）	第八章
`formatter`	代码格式化器	第八章
`lsp`	LSP 服务器	第八章
`compaction`	上下文压缩与裁剪	第九章
`snapshot`	文件快照开关	第九、十章
`watcher`	文件监听忽略规则	第九章
`share`	分享模式（manual/auto/disabled）	本章
`autoupdate`	自动更新	本章
`shell`	交互终端使用的 shell	本章
`attachment`	图片附件归一化限制	本章
`experimental`	实验特性（含 policies）	第十章

分享、自动更新、Shell

{"$schema": "https://opencode.ai/config.json","share": "manual",     // manual（默认，需手动 /share）| auto | disabled"autoupdate": true,    // true | false | "notify"（只通知不更新）"shell": "pwsh"        // 不写则按系统自动选择
}

autoupdate: "notify" 仅在非包管理器安装时有效。

4.8 变量替换：`{env:...}` 与 `{file:...}`

配置文件支持两类变量替换，非常适合把密钥与大段文本从配置中剥离。

环境变量

用 {env:VARIABLE_NAME} 引用环境变量（未设置时替换为空字符串）：

{"$schema": "https://opencode.ai/config.json","model": "{env:OPENCODE_MODEL}","provider": {"anthropic": {"options": { "apiKey": "{env:ANTHROPIC_API_KEY}" }}}
}

文件内容

用 {file:path/to/file} 把文件内容内联进来：

{"$schema": "https://opencode.ai/config.json","instructions": ["./custom-instructions.md"],"provider": {"openai": {"options": { "apiKey": "{file:~/.secrets/openai-key}" }}}
}

文件路径可相对于配置文件目录，或以 /、~ 开头的绝对路径。常见用途：