OpenCode 配置完全指南：从零开始理解 JSON 配置文件

如果你最近开始接触 OpenCode 这款工具，可能会注意到它背后有一套非常灵活的配置系统。简单来说，OpenCode 允许开发者通过一个 JSON 格式的配置文件来调整它的行为------比如选择哪个 AI 模型、是否允许自动更新、如何管理文件权限等等。这篇文章将从头到尾梳理 OpenCode 的配置方式，尽量用通俗的语言讲清楚每个部分的作用，不偏不漏。

配置文件长什么样

OpenCode 支持标准的 JSON 格式，同时也接受带注释的 JSONC。也就是说，开发者可以在配置文件里写 // 这样的注释，方便自己记录某个选项是干什么用的。一个典型的配置文件可能叫 opencode.jsonc，内容大致如下：

plain 复制代码

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

其中 $schema 这一行不是必选的，但加上之后，代码编辑器就能自动校验和提示配置项，省去不少查文档的时间。

配置文件可以放在哪里

OpenCode 支持把配置放在多个不同的地方，而且这些配置不是互相覆盖，而是合并在一起。也就是说，如果某个选项在多个地方都设置了，后面加载的会覆盖前面的；但不同选项之间不会互相影响，所有地方的设置最终都会生效。

加载的顺序从早到晚是这样的：

远程配置 （来自 .well-known/opencode）------ 一般是组织统一设定的默认值。
全局配置 （~/.config/opencode/opencode.json）------ 用户个人偏好。
自定义路径配置 （通过 OPENCODE_CONFIG 环境变量指定）。
项目配置 （项目根目录下的 opencode.json）------ 针对某个仓库的特殊设置。
.opencode** 目录** ------ 里面可以放代理、命令、插件等。
内联配置 （OPENCODE_CONFIG_CONTENT 环境变量）------ 运行时临时覆盖。
托管配置文件 （macOS 上 /Library/Application Support/opencode/ 等）------ 管理员控制。
macOS 托管偏好设置 （通过 MDM 下发的 .mobileconfig）------ 最高优先级，用户无法覆盖。

举个例子，如果远程配置里把某个 MCP 服务器设为 enabled: false，但开发者在自己的项目配置里把它改成 enabled: true，那么最终生效的是 true。反过来，如果管理员通过托管设置强行禁止了某项操作，那么用户再怎么改自己的配置也没用。

几个特殊位置的说明

全局配置 放在 ~/.config/opencode/opencode.json，适合放一些通用的东西，比如默认的模型、API 密钥、权限策略。如果只想改终端界面（TUI）的外观或按键绑定，建议单独放到 ~/.config/opencode/tui.json 里。
项目配置 放在仓库根目录的 opencode.json，可以和代码一起提交到 Git，这样团队里每个人都能共用一套设置。
自定义路径 ：通过设置环境变量 export OPENCODE_CONFIG=/path/to/my-config.json 来指定一个完全自定义的配置文件。这个文件会在全局配置之后、项目配置之前被加载。
自定义目录 ：通过 OPENCODE_CONFIG_DIR 环境变量指定一个目录，OpenCode 会从这个目录里读取代理、命令、模式、插件等，结构跟标准的 .opencode 目录一样。

托管设置（管理员强制）

对于企业环境，管理员可能希望统一规范所有人的 OpenCode 行为，不让用户随便绕过。有两种方式：

文件方式 ：在 macOS 的 /Library/Application Support/opencode/、Linux 的 /etc/opencode/ 或者 Windows 的 %ProgramData%\opencode 里放一个 opencode.json。因为这些目录需要管理员权限才能写入，普通用户没法修改。
macOS 托管偏好 ：通过 MDM（比如 Jamf、Kandji、FleetDM）下发一个 .mobileconfig 描述文件，使用 ai.opencode.managed 作为负载类型。OpenCode 会自动读取其中的设置，并且用户无法在本地覆盖。可以用 opencode debug config 命令来验证当前生效的配置。

核心配置项逐一拆解

下面按字母顺序介绍几个最常用的配置选项。

代理（Agent）

代理可以理解为专门处理某类任务的"子助手"。开发者可以在配置文件中定义自己的代理，比如：

plain 复制代码

{
  "agent": {
    "code-reviewer": {
      "description": "审查代码的最佳实践和潜在问题",
      "model": "anthropic/claude-sonnet-4-5",
      "prompt": "你是一个代码审查专家，重点关注安全、性能和可维护性。",
      "tools": {
        "write": false,
        "edit": false
      }
    }
  }
}

这个例子定义了一个只读的代码审查代理，不允许它修改文件。代理也可以用 Markdown 文件定义，放在 ~/.config/opencode/agents/ 或 .opencode/agents/ 目录下。

默认代理 ：通过 default_agent 选项可以指定没有明确选用哪个代理时默认使用哪一个。比如设为 "plan" 或 "build"。这个设置对 TUI、命令行、桌面应用和 GitHub Action 都有效。

自动更新（Autoupdate）

OpenCode 默认会在启动时自动下载新版本。如果不想让它自动更新，可以设置 "autoupdate": false。还有一种折中方案："autoupdate": "notify"，只提醒有新版本但不自动下载。注意如果 OpenCode 是通过 Homebrew 这类包管理器安装的，这个选项可能不会生效。

命令（Command）

自定义命令可以让开发者用简短的指令触发复杂的模板。例如：

plain 复制代码

{
  "command": {
    "test": {
      "template": "运行完整的测试套件并生成覆盖率报告，展示所有失败项。重点关注失败的测试并给出修复建议。",
      "description": "运行测试并输出覆盖率",
      "agent": "build",
      "model": "anthropic/claude-haiku-4-5"
    },
    "component": {
      "template": "创建一个名为 $ARGUMENTS 的新 React 组件，支持 TypeScript，包含合适的类型定义和基本结构。",
      "description": "创建一个新组件"
    }
  }
}

命令也支持用 Markdown 文件定义，放在 ~/.config/opencode/commands/ 或 .opencode/commands/ 下。

压缩（Compaction）

对话上下文太长的时候，OpenCode 可以自动压缩。相关选项有：

auto：默认为 true，上下文占满时自动压缩。
prune：默认为 true，删除旧的工具输出以节省 token。
reserved：保留一定数量的 token 作为缓冲，防止压缩过程中溢出。

禁用/启用提供者（Disabled / Enabled Providers）

OpenCode 会自动加载它能找到的所有 AI 模型提供者（比如 OpenAI、Anthropic、Google Gemini 等）。如果想屏蔽某些提供者，可以用 disabled_providers 数组：

json 复制代码

{
  "disabled_providers": ["openai", "gemini"]
}

反过来，如果只想保留某几个提供者，可以用 enabled_providers 作为白名单。注意 disabled_providers 的优先级更高------如果同一个提供者同时出现在两个数组里，它会被禁用。

实验性功能（Experimental）

所有带 experimental 键的选项都是正在开发中的不稳定功能，随时可能变更或移除，使用时要小心。

格式化器（Formatter）

可以配置代码格式化工具，比如 Prettier：

plain 复制代码

{
  "formatter": {
    "prettier": {
      "disabled": true
    },
    "custom-prettier": {
      "command": ["npx", "prettier", "--write", "$FILE"],
      "environment": { "NODE_ENV": "development" },
      "extensions": [".js", ".ts", ".jsx", ".tsx"]
    }
  }
}

每个格式化器可以指定命令、环境变量和适用的文件扩展名。

指令（Instructions）

通过 instructions 选项，可以把一些额外的指导文件喂给模型。比如：

json 复制代码

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

支持具体的文件路径，也支持 glob 通配符模式。

MCP 服务器

MCP 是一种扩展协议，可以在配置文件的 mcp 对象里声明要使用的服务器。例如连接 Jira 的 MCP 服务。

模型（Model）

model 指定主要的模型，small_model 指定用于轻量级任务（比如生成标题）的模型。如果没有单独指定小模型，OpenCode 会尝试从同一个提供者那里找一个便宜的型号，找不到就回退到主模型。

提供者还可以设置额外的选项，比如超时时间（timeout）、流式响应的块超时（chunkTimeout）和缓存键（setCacheKey）。以 Anthropic 为例：

json 复制代码

{
  "provider": {
    "anthropic": {
      "options": {
        "timeout": 600000,
        "chunkTimeout": 30000,
        "setCacheKey": true
      }
    }
  }
}

对于 Amazon Bedrock，还支持 region、profile、endpoint 等特有选项。

权限（Permission）

默认情况下 OpenCode 允许所有操作（读写文件、执行 bash 命令等）而不需要用户确认。如果想更安全一点，可以设置权限策略：

json 复制代码

{
  "permission": {
    "edit": "ask",
    "bash": "ask"
  }
}

这样每次编辑文件或执行 shell 命令之前，OpenCode 都会弹窗询问。还可以针对特定命令做更细的规则，比如禁止 rm -rf *。

插件（Plugin）

插件可以通过 npm 包的形式加载：

json 复制代码

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

也可以把插件文件放在 .opencode/plugins/ 或 ~/.config/opencode/plugins/ 目录下。

服务器（Server）

当运行 opencode serve 或 opencode web 时，可以通过 server 对象配置网络相关参数：

port：监听的端口。
hostname：监听的主机名，如果启用了 mDNS 且没设 hostname，默认用 0.0.0.0。
mdns：是否开启 mDNS 服务发现，让同网络的其他设备能找到这个 OpenCode 实例。
mdnsDomain：自定义 mDNS 域名，默认为 opencode.local。
cors：额外的跨域白名单，需要写完整的源（包括协议、主机、端口）。

通过 share 选项控制对话分享功能：

"manual"（默认）：需要手动执行 /share 命令才能分享。
"auto"：新对话自动分享。
"disabled"：完全禁用分享。

快照（Snapshot）

OpenCode 默认会为每次会话创建文件快照，方便撤销和回滚。但对于超大仓库或者有很多子模块的项目，快照系统可能会拖慢索引速度并占用大量磁盘空间。如果不需要撤销功能，可以关闭快照：

json 复制代码

{
  "snapshot": false
}

关掉之后，代理做的更改就无法通过界面回退了。

主题（Theme）

主题相关设置放在 tui.json 里，例如：

json 复制代码

{
  "$schema": "https://opencode.ai/tui.json",
  "theme": "tokyonight"
}

工具（Tools）

tools 选项可以整体禁用某些工具。比如不让模型写文件，也不让它执行 bash：

json 复制代码

{
  "tools": {
    "write": false,
    "bash": false
  }
}

TUI 设置

终端界面的专属配置（滚动速度、鼠标支持、差异显示样式等）放在 tui.json 或 tui.jsonc 中。旧版 opencode.json 里的 theme、keybinds、tui 等键已被弃用，但 OpenCode 会在可能的情况下自动迁移。

变量替换

配置文件里可以使用 {env:变量名} 来引用环境变量，比如 "model": "{env:OPENCODE_MODEL}"。也可以用 {file:路径} 来读取文件内容，比如把 API 密钥存在一个单独的密钥文件里：

json 复制代码

{
  "provider": {
    "openai": {
      "options": {
        "apiKey": "{file:~/.secrets/openai-key}"
      }
    }
  }
}

文件路径可以是相对路径（相对于配置文件所在目录），也可以是绝对路径或带 ~ 的主目录路径。

观察器（Watcher）

文件观察器可以忽略某些目录，避免不必要的监听开销：

json 复制代码

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

最后几点补充

旧版配置中的 keybinds 现在已经迁移到 tui.json 里单独管理。
OpenCode 的完整 JSON Schema 可以在 https://opencode.ai/config.json 找到，TUI 的 Schema 在 https://opencode.ai/tui.json。
所有配置的加载都是合并而非替换，这意味着远程、全局、项目等不同层级的配置可以共存，只在冲突键上以后者为准。

总的来说，OpenCode 的配置系统设计得相当灵活，既能满足个人开发者随手修改的便利，也能满足企业级统一管控的需求。从最简单的单文件配置，到复杂的多层级合并，再到 MDM 强制的托管策略，每个场景都能找到合适的方式。

OpenCode 配置完全指南：从零开始理解 JSON 配置文件

配置文件长什么样

配置文件可以放在哪里

几个特殊位置的说明

托管设置（管理员强制）

核心配置项逐一拆解

代理（Agent）

自动更新（Autoupdate）

命令（Command）

压缩（Compaction）

禁用/启用提供者（Disabled / Enabled Providers）

实验性功能（Experimental）

格式化器（Formatter）

指令（Instructions）

MCP 服务器

模型（Model）

权限（Permission）

插件（Plugin）

服务器（Server）

分享（Share）

快照（Snapshot）

主题（Theme）

工具（Tools）

TUI 设置

变量替换

观察器（Watcher）

最后几点补充