使用 JSON 配置 OpenCode

你可以通过一个 JSON 配置文件（JSON config file） 来配置 OpenCode。

格式（Format）

OpenCode 同时支持 JSON 和 JSONC（JSON with Comments） 格式。

```jsonc title=”opencode.jsonc” { “$schema”: “https://opencode.ai/config.json“, // Theme 配置 “theme”: “opencode”, “model”: “anthropic/claude-sonnet-4-5”, “autoupdate”: true }

  2. ---
  4. ## 配置位置（Locations）
  6. 你可以把配置文件放在多个不同位置，并且它们存在 **优先级顺序（order of precedence）**。
  8. 多个配置文件会被合并，而不是覆盖。来自不同位置的配置会组合在一起：
  9. 如果键（key）冲突，后加载的配置会覆盖先加载的配置；如果没有冲突，则会全部保留。
  11. 例如：
  13. * 全局配置（global config）设置了 `theme: "opencode"` 和 `autoupdate: true`
  14. * 项目配置（project config）设置了 `model: "anthropic/claude-sonnet-4-5"`
  16. 最终生效的配置将同时包含这三个设置。
  18. ---
  20. ### 优先级顺序（Precedence order）
  22. 配置来源按以下顺序加载（后面的会覆盖前面的）：
  24. 1. **Remote config**（来自 `.well-known/opencode`）— 组织级默认配置（organizational defaults）
  25. 2. **Global config**（`~/.config/opencode/opencode.json`）— 用户级偏好设置（user preferences）
  26. 3. **Custom config**（`OPENCODE_CONFIG` 环境变量）— 自定义覆盖配置（custom overrides）
  27. 4. **Project config**（项目中的 `opencode.json`）— 项目级配置（project-specific settings）
  28. 5. **`.opencode` 目录** — agents、commands、plugins
  29. 6. **Inline config**（`OPENCODE_CONFIG_CONTENT` 环境变量）— 运行时覆盖配置（runtime overrides）
  31. 这意味着：
  33. * 项目配置可以覆盖全局默认配置
  34. * 全局配置可以覆盖组织级 Remote 默认配置
  36. ---
  38. ### Remote 配置
  40. 组织可以通过 `.well-known/opencode` 端点（endpoint）提供默认配置。
  41. 当你使用支持该功能的 Provider 进行认证（authenticate）时，OpenCode 会自动拉取该配置。
  43. Remote config 是最先加载的基础层（base layer），后续的 global 和 project 配置都可以覆盖它。
  45. 示例：如果你的组织提供了一些默认禁用的 MCP servers：
  47. ```json title="Remote config from .well-known/opencode"
  48. {
  49.   "mcp": {
  50.     "jira": {
  51.       "type": "remote",
  52.       "url": "https://jira.example.com/mcp",
  53.       "enabled": false
  54.     }
  55.   }
  56. }

你可以在本地配置中启用指定的 server：

```json title=”opencode.json” { “mcp”: { “jira”: { “type”: “remote”, “url”: “https://jira.example.com/mcp“, “enabled”: true } } }

  2. ---
  4. ### Global 配置
  6. 将全局 OpenCode 配置文件放在：

~/.config/opencode/opencode.json

  2. Global config 适用于用户级通用设置，例如：
  4. * theme
  5. * provider
  6. * keybinds
  8. Global config 会覆盖 Remote 的组织级默认配置。
  10. ---
  12. ### 项目级配置（Per project）
  14. 在项目根目录添加 `opencode.json`。
  16. 项目配置在标准配置文件中具有最高优先级，会覆盖 global 和 remote 配置。
  18. 当 OpenCode 启动时，会在当前目录查找配置文件，并向上遍历到最近的 Git 目录。
  20. 项目配置可以安全地提交到 Git，并且使用与 global 配置相同的 schema。
  22. ---
  24. ### 自定义路径（Custom path）
  26. 可以通过 `OPENCODE_CONFIG` 环境变量指定自定义配置文件路径。
  28. ```bash
  29. export OPENCODE_CONFIG=/path/to/my/custom-config.json
  30. opencode run "Hello world"

Custom config 在优先级中位于 global 和 project 之间。

自定义目录（Custom directory）

可以通过 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。

该目录会像标准的 .opencode 目录一样，被用于加载：

  • agents
  • commands
  • modes
  • plugins

目录结构需保持一致。

  1. export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
  2. opencode run "Hello world"

该自定义目录在加载顺序中位于 global config 和 .opencode 目录之后，因此 可以覆盖它们的设置。

Schema

配置文件的 schema 定义在：

opencode.ai/config.json

你的编辑器（editor）可以基于该 schema 自动进行校验（validate）和自动补全（autocomplete）。

TUI 配置

可以通过 tui 选项配置 TUI 专属设置。

```json title=”opencode.json” { “$schema”: “https://opencode.ai/config.json“, “tui”: { “scroll_speed”: 3, “scroll_acceleration”: { “enabled”: true }, “diff_style”: “auto” } }

  2. 可用选项：
  4. * `scroll_acceleration.enabled`
  5.   启用 macOS 风格的滚动加速（scroll acceleration），**优先级高于 `scroll_speed`**。
  6. * `scroll_speed`
  7.   自定义滚动速度倍率（默认值：`3`，最小值：`1`）。当 `scroll_acceleration.enabled` 为 `true` 时会被忽略。
  8. * `diff_style`
  9.   控制 diff 的渲染方式：
  11.   * `"auto"`：根据终端宽度自适应
  12.   * `"stacked"`：始终单列显示
  14. 更多内容请参考：[TUI 使用说明](/docs/tui)。
  16. ---
  18. ## Server 配置
  20. 可以通过 `server` 选项配置 `opencode serve` 和 `opencode web` 命令的服务参数。
  22. ```json title="opencode.json"
  23. {
  24.   "$schema": "https://opencode.ai/config.json",
  25.   "server": {
  26.     "port": 4096,
  27.     "hostname": "0.0.0.0",
  28.     "mdns": true,
  29.     "cors": ["http://localhost:5173"]
  30.   }
  31. }

可用选项：

  • port — 监听端口
  • hostname — 监听主机名 当启用 mdns 且未设置 hostname 时，默认使用 0.0.0.0
  • mdns — 启用 mDNS 服务发现（service discovery），允许局域网内其他设备发现你的 OpenCode server
  • cors — 为浏览器客户端使用 HTTP server 时，额外允许的 CORS 来源（origin），必须是完整 origin（协议 + 主机 + 可选端口），例如 https://app.example.com

更多说明请参考：Server 文档。

Tools 配置

可以通过 tools 选项管理 LLM 可使用的工具权限。

```json title=”opencode.json” { “$schema”: “https://opencode.ai/config.json“, “tools”: { “write”: false, “bash”: false } }

  2. 参考文档：[Tools 说明](/docs/tools)。
  4. ---
  6. ## Models 配置
  8. 可以通过 `provider`、`model` 和 `small_model` 选项配置使用的模型和 Provider。
  10. ```json title="opencode.json"
  11. {
  12.   "$schema": "https://opencode.ai/config.json",
  13.   "provider": {},
  14.   "model": "anthropic/claude-sonnet-4-5",
  15.   "small_model": "anthropic/claude-haiku-4-5"
  16. }

small_model 用于轻量任务（例如 title 生成）。 默认情况下，OpenCode 会优先使用更便宜的模型；如果 Provider 不支持，则回退到主模型（main model）。

Provider 可配置项包括：

  1. "timeout", "setCacheKey"
  • timeout — 请求超时时间（毫秒，默认：300000），设置为 false 可关闭超时
  • setCacheKey — 确保 Provider 始终设置 cache key

你也可以配置 local models。更多内容参考：Models 文档。

Provider 专属配置（Provider-Specific Options）

部分 Provider 支持额外配置。

Amazon Bedrock

支持 AWS 相关配置：

```json title=”opencode.json” { “provider”: { “amazon-bedrock”: { “options”: { “region”: “us-east-1”, “profile”: “my-aws-profile”, “endpoint”: “https://bedrock-runtime.us-east-1.vpce-xxxxx.amazonaws.com“ } } } }

  2. * `region` — AWS 区域（默认取 `AWS_REGION` 环境变量或 `us-east-1`）
  3. * `profile` — AWS 凭证配置文件（来自 `~/.aws/credentials`）
  4. * `endpoint` — 自定义 VPC endpoint，优先级高于通用的 `baseURL`
  6. ---
  8. ## Themes
  10. 通过 `theme` 选项配置主题。
  12. ```json
  13. "theme": ""

参考：Themes 文档。

Agents

通过 agent 选项配置专用 Agent。

  1. "agent": {
  2.   "code-reviewer": {
  3.     "description": "Reviews code for best practices and potential issues",
  4.     "model": "anthropic/claude-sonnet-4-5",
  5.     "prompt": "You are a code reviewer...",
  6.     "tools": {
  7.       "write": false,
  8.       "edit": false
  9.     }
  10.   }
  11. }

也可以在：

  • ~/.config/opencode/agent/
  • .opencode/agent/

目录中使用 Markdown 文件定义 Agent。

Default agent

通过 default_agent 设置默认 Agent。

  1. "default_agent": "plan"

默认 Agent 必须是主 Agent（primary agent），不能是 subagent。 如果指定的 Agent 不存在，OpenCode 会自动回退到 "build"。

该设置适用于：

  • TUI
  • CLI（opencode run）
  • desktop app
  • GitHub Action

Sharing

通过 share 选项配置分享功能。

  1. "share": "manual"

可选值：

  • "manual" — 手动分享（默认）
  • "auto" — 自动分享
  • "disabled" — 禁用分享

Commands

通过 command 选项配置自定义命令（custom commands）。

  1. "command": {
  2.   "test": {
  3.     "template": "...",
  4.     "description": "Run tests with coverage",
  5.     "agent": "build",
  6.     "model": "anthropic/claude-haiku-4-5"
  7.   }
  8. }

也可以通过 Markdown 文件定义命令。

Keybinds

通过 keybinds 配置快捷键。

  1. "keybinds": {}

Autoupdate

OpenCode 默认启动时自动更新。

  1. "autoupdate": false

如只希望提醒更新，可设置为 "notify"。

Formatters

通过 formatter 配置代码格式化工具。

支持自定义命令和环境变量。

Permissions

默认情况下，opencode 允许所有操作。 可通过 permission 控制敏感操作是否需要用户确认：

  1. "permission": {
  2.   "edit": "ask",
  3.   "bash": "ask"
  4. }

Compaction

通过 compaction 控制上下文压缩行为：

  • auto — 自动压缩上下文
  • prune — 清理旧的 tool 输出以节省 token

Watcher

通过 watcher.ignore 配置文件监听忽略规则（glob 语法）。

MCP servers

通过 mcp 配置 MCP servers。

Plugins

Plugins 可以扩展 OpenCode 的能力。

支持：

  • 本地目录加载
  • npm 插件加载

Instructions

通过 instructions 指定模型指令文件路径或 glob 规则。

Disabled providers

通过 disabled_providers 禁用指定 Provider。

即使存在环境变量或 API Key，也不会加载。

Enabled providers

通过 enabled_providers 指定允许加载的 Provider 白名单。

⚠️ disabled_providers 优先级高于 enabled_providers。

Experimental

experimental 包含实验性功能，可能随时变更或删除。

Variables（变量替换）

配置文件支持变量替换，用于引用：

  • 环境变量（env vars）
  • 文件内容（files）

Env vars

使用：

  1. {env:VARIABLE_NAME}

引用环境变量。 如果环境变量不存在，会替换为空字符串。

Files

使用：

  1. {file:path/to/file}

引用文件内容。

支持：

  • 相对路径
  • 绝对路径（/ 或 ~）

常见用途：

  • 将 API Key 等敏感信息放在独立文件中
  • 引入大型 instruction 文件
  • 复用公共配置片段