OpenCode 配置文件系统深度解析：一张 opencode.json 掌控全局

OpenCode 之所以能被开发者称为"可编程的 AI 编程助手"，很大程度上要归功于它那套灵活而强大的配置文件系统。从默认模型、权限策略到 MCP 服务器、LSP 集成，几乎所有的行为都可以通过一个 JSON 文件来精确控制。

然而很多刚接触 OpenCode 的朋友都有一个困惑：配置文件到底该放哪？全局配置和项目配置谁说了算？opencode.json 里到底能写哪些东西？这篇文章就从零开始，带你彻底搞懂 OpenCode 的配置文件系统。

配置文件的基础格式

OpenCode 支持两种格式：JSON 和 JSONC（带注释的 JSON）。后者对开发者尤其友好，因为它允许在配置里写注释解释每一行的作用。

一个最基本的配置文件长这样：

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

注意第一行的 $schema 字段，它指向官方提供的 JSON Schema。加上这个字段后，你的编辑器就能对配置内容进行自动校验和智能补全，大大降低写错配置的概率。

配置文件的存放位置与优先级

OpenCode 的配置可以放在多个位置，它们不是互相替换，而是按优先级合并的。不同位置的配置会被加载并融合，只有冲突的键才会被后面的配置覆盖。

加载顺序如下（越靠后优先级越高）：

远程配置：组织通过 .well-known/opencode 端点下发的默认配置

全局配置：~/.config/opencode/opencode.json，存放个人偏好

自定义配置：通过 OPENCODE_CONFIG 环境变量指定的文件

项目配置：项目根目录下的 opencode.json

.opencode 目录：项目内的 agents、commands、plugins 等

内联配置：通过 OPENCODE_CONFIG_CONTENT 环境变量注入

托管配置：由管理员统一管理的配置，优先级最高

这种设计非常实用。举个例子，你在全局配置里设置了 autoupdate: true，项目配置里设置了 model: "anthropic/claude-sonnet-4-5"，最终生效的配置会同时包含这两个设置——非冲突的键不会丢失。

项目配置最有价值

在实际开发中，最有价值的是项目配置。把 opencode.json 放在项目根目录，提交到 Git 仓库，整个团队就能共享同一套 AI 编程环境配置。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "bash": "ask",
    "edit": "allow"
  }
}

当 OpenCode 启动时，它会先找当前目录的配置，然后逐级向上搜索直到最近的 Git 目录，这保证了无论你在项目哪个子目录启动它，都能加载到正确的项目配置。

通过环境变量定制配置路径

除了标准位置，OpenCode 还提供了两个环境变量来灵活指定配置来源：

# 指定自定义配置文件路径
export OPENCODE_CONFIG=/path/to/my/custom-config.json

# 指定自定义配置目录（目录结构类似 .opencode）
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory

opencode run "Hello world"

其中 OPENCODE_CONFIG_DIR 指定的目录会被当作 .opencode 目录来搜索 agents、commands、modes 和 plugins，并且它的优先级比全局配置和 .opencode 目录都高，可以覆盖它们。

配置项速览

opencode.json 支持非常多的配置项，下面挑几个核心的来介绍。

模型配置

通过 provider、model 和 small_model 三个字段控制模型：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

small_model 用来处理标题生成之类的轻量任务，OpenCode 默认会优先使用更便宜的模型，如果提供商没有可用的便宜模型，则回退到主模型。

权限控制

默认情况下 OpenCode 允许所有操作而不需要用户确认，这虽然流畅但存在风险。通过 permission 字段可以精细控制：

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

设置 ask 后，AI 执行 edit 和 bash 工具时就会先征求你的同意，相当于给 AI 套上安全绳。

自定义命令

把重复性的工作封装成斜杠命令，一按就执行：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
      "description": "Run tests with coverage",
      "agent": "build"
    }
  }
}

这样在会话中输入 /test，OpenCode 就会按模板执行测试任务。

工具开关

可以用 tools 字段禁用某些工具，例如让 AI 只读不改：

{
  "$schema": "https://opencode.ai/config.json",
  "tools": {
    "write": false,
    "bash": false
  }
}

这在代码审查、只读分析等场景非常有用。

上下文压缩（Compaction）

长时间会话中上下文会越来越满，OpenCode 会自动压缩。你可以通过 compaction 字段精细控制：

{
  "$schema": "https://opencode.ai/config.json",
  "compaction": {
    "auto": true,
    "prune": false,
    "reserved": 10000
  }
}

auto：上下文满时自动压缩（默认开启）
prune：删除旧的工具输出以节省 token
reserved：为压缩过程预留的 token 缓冲

快照与自动更新

OpenCode 用快照（snapshot）记录 agent 操作期间的文件变更，让你能通过 /undo 回退。但大仓库下快照会占用较多磁盘，可以关闭：

{
  "$schema": "https://opencode.ai/config.json",
  "snapshot": false,
  "autoupdate": false
}

autoupdate: false 则禁止自动更新，改为 "notify" 可以在不更新的情况下收到新版本提醒。

提供商黑白名单

公司环境里往往只想用固定的几个提供商，可以这样限制：

{
  "$schema": "https://opencode.ai/config.json",
  "enabled_providers": ["anthropic", "openai"],
  "disabled_providers": ["gemini"]
}

注意 disabled_providers 的优先级高于 enabled_providers，两者冲突时以禁用名单为准。

变量替换：让配置可复用

OpenCode 配置支持变量替换，可以引用环境变量和文件内容，这让配置更加灵活和安全。

引用环境变量

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

如果环境变量未设置，会被替换为空字符串。

引用文件内容

更推荐的做法是把 API Key 这类敏感信息放在独立文件里，而不是直接写进配置：

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

文件路径可以是相对配置文件的路径，也可以是 / 或 ~ 开头的绝对路径。这样做的好处有三个：敏感数据不进版本库、大段指令文件不必挤在配置里、公共配置片段可以跨项目共享。

TUI 专属配置：tui.json

如果你主要使用终端界面，还有一些 UI 相关的配置放在独立的 tui.json 中，比如滚动速度、鼠标支持、桌面通知等：

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

把 attention.enabled 打开后，AI 完成任务时就会通过桌面通知和声音提醒你，不用一直盯着终端。项目专属的 TUI 设置放在项目根目录的 tui.json，全局的放在 ~/.config/opencode/tui.json。

企业级托管配置

如果你的团队规模较大，还可以通过托管配置来强制统一所有成员的设置，用户无法自行覆盖：

Linux：/etc/opencode/
macOS：/Library/Application Support/opencode/
Windows：%ProgramData%\opencode

macOS 上还支持通过 MDM（如 Jamf、FleetDM）下发 .mobileconfig 配置文件，把 OpenCode 的配置键直接放进 ai.opencode.managed payload 中即可。

常见问题与调试技巧

配置没生效？ 先用调试命令查看最终合并后的配置：

opencode debug config

想临时覆盖配置？ 用 OPENCODE_CONFIG_CONTENT 注入内联配置，它优先级很高，适合临时实验：

export OPENCODE_CONFIG_CONTENT='{"model":"openai/gpt-4o"}'
opencode

不想让某个模型出现在列表里？ 加入 disabled_providers 即可，配置了 API Key 也不会加载。

总结

OpenCode 的配置文件系统设计得相当优雅：多层级合并、JSONC 注释支持、变量替换、托管配置，几乎覆盖了从个人开发者到企业团队的所有场景。

对于个人开发者，建议把通用偏好放在 ~/.config/opencode/opencode.json，把项目相关的配置（模型、命令、权限）放进项目根目录的 opencode.json 并提交到 Git；对于 API Key 等敏感信息，务必通过 {file:...} 变量引用独立文件，而不是直接写进配置。

一张配置，全局掌控。善用这套配置文件系统，你的 OpenCode 才能真正成为一台为你量身定制的 AI 编程机器。