配置

使用 OpenCode JSON 配置文件。

你可以使用 JSON 配置文件来配置 OpenCode。

# 格式#

OpenCode 支持 JSON 和 JSONC（带注释的 JSON）两种格式。

jsonc
1// opencode.jsonc
2{
3  "$schema": "https://opencode.ai/config.json",
4  // 主题配置
5  "theme": "opencode",
6  "model": "anthropic/claude-sonnet-4-5",
7  "autoupdate": "notify"
8}

# 位置#

你可以将配置放在多个不同的位置，它们具有不同的优先级。

注意： 配置文件会合并在一起，而不是替换。

配置文件会合并在一起，而不是替换。以下配置位置的设置会组合在一起。后面的配置仅对冲突的键覆盖前面的配置。所有配置中的非冲突设置都会保留。

例如，如果你的全局配置设置了 theme: "opencode" 和 autoupdate: "notify"，而项目配置设置了 model: "anthropic/claude-sonnet-4-5"，最终配置将包含所有三个设置。

## 全局配置#

将全局 OpenCode 配置放在 ~/.config/opencode/opencode.json。你可能希望在全局配置中设置主题、提供商或快捷键等内容。

## 项目配置#

你也可以在项目中添加 opencode.json。此配置中的设置会与全局配置合并，并可以覆盖全局配置。这对于配置特定于项目的提供商或模式很有用。

提示： 将项目特定的配置放在项目根目录。

当 OpenCode 启动时，它会在当前目录中查找配置文件，或向上遍历到最近的 Git 目录。

这也可以安全地提交到 Git，并使用与全局配置相同的 schema。

## 自定义路径#

你也可以使用 OPENCODE_CONFIG 环境变量指定自定义配置文件路径。

bash
export OPENCODE_CONFIG=/path/to/my/custom-config.json
opencode run "Hello world"

此配置中的设置会与全局和项目配置合并，并可以覆盖它们。

## 自定义目录#

你可以使用 OPENCODE_CONFIG_DIR 环境变量指定自定义配置目录。此目录将像标准 .opencode 目录一样搜索代理、命令、模式和插件，并应遵循相同的结构。

bash
export OPENCODE_CONFIG_DIR=/path/to/my/config-directory
opencode run "Hello world"

自定义目录在全局配置和 .opencode 目录之后加载，因此它可以覆盖它们的设置。

# Schema#

配置文件有一个在 opencode.ai/config.json↗ 定义的 schema。

你的编辑器应该能够根据 schema 进行验证和自动补全。

## TUI#

你可以通过 tui 选项配置 TUI 特定的设置。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tui": {
4    "scroll_speed": 3,
5    "scroll_acceleration": {
6      "enabled": true
7    },
8    "diff_style": "auto"
9  }
10}

可用选项：

scroll_acceleration.enabled - 启用 macOS 风格的滚动加速。优先于 scroll_speed。
scroll_speed - 自定义滚动速度倍数（默认：1，最小：1）。如果 scroll_acceleration.enabled 为 true，则忽略此项。
diff_style - 控制差异渲染。"auto" 根据终端宽度自适应，"stacked" 始终显示单列。

了解更多关于使用 TUI 的信息。

## Server#

你可以通过 server 选项为 opencode serve 和 opencode web 命令配置服务器设置。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "server": {
4    "port": 4096,
5    "hostname": "0.0.0.0",
6    "mdns": true,
7    "cors": ["http://localhost:5173"]
8  }
9}

可用选项：

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

了解更多关于服务器的信息。

## Tools#

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "tools": {
4    "write": false,
5    "bash": false
6  }
7}

了解更多关于工具的信息。

## Models#

你可以通过 provider、model 和 small_model 选项在 OpenCode 配置中配置你想使用的提供商和模型。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {},
4  "model": "anthropic/claude-sonnet-4-5",
5  "small_model": "anthropic/claude-haiku-4-5"
6}

small_model 选项为轻量级任务（如标题生成）配置单独的模型。默认情况下，OpenCode 会尝试使用提供商的较便宜模型（如果可用），否则回退到主模型。

提供商选项可以包括 timeout 和 setCacheKey：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "provider": {
4    "anthropic": {
5      "options": {
6        "timeout": 600000,
7        "setCacheKey": true
8      }
9    }
10  }
11}

timeout - 请求超时（毫秒）（默认：300000）。设置为 false 可禁用。
setCacheKey - 确保始终为指定提供商设置缓存键。

你也可以配置本地模型。了解更多。

## Themes#

你可以通过 theme 选项在 OpenCode 配置中配置你想使用的主题。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "theme": ""
4}

了解更多。

## Agents#

你可以通过 agent 选项为特定任务配置专门的代理。

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "agent": {
4    "code-reviewer": {
5      "description": "审查代码的最佳实践和潜在问题",
6      "model": "anthropic/claude-sonnet-4-5",
7      "prompt": "你是一个代码审查员。专注于安全性、性能和可维护性。",
8      "tools": {
9        // 为仅审查的代理禁用文件修改工具
10        "write": false,
11        "edit": false
12      }
13    }
14  }
15}

你也可以使用 ~/.config/opencode/agent/ 或 .opencode/agent/ 中的 markdown 文件定义代理。了解更多。

## 默认代理#

你可以使用 default_agent 选项设置默认代理。这决定了未明确指定时使用哪个代理。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "default_agent": "plan"
4}

默认代理必须是主代理（不是子代理）。这可以是内置代理如 "build" 或 "plan"，或者你定义的自定义代理。如果指定的代理不存在或是子代理，OpenCode 将回退到 "build" 并发出警告。

此设置适用于所有界面：TUI、CLI（opencode run）、桌面应用和 GitHub Action。

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

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "share": "manual"
4}

这接受：

"manual" - 允许通过命令手动分享（默认）
"auto" - 自动分享新对话
"disabled" - 完全禁用分享

默认情况下，分享设置为手动模式，你需要使用 /share 命令明确分享对话。

## Commands#

你可以通过 command 选项为重复任务配置自定义命令。

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "command": {
4    "test": {
5      "template": "运行完整的测试套件并生成覆盖率报告，显示任何失败。\n专注于失败的测试并建议修复。",
6      "description": "运行带覆盖率的测试",
7      "agent": "build",
8      "model": "anthropic/claude-haiku-4-5"
9    },
10    "component": {
11      "template": "创建一个名为 $ARGUMENTS 的新 React 组件，支持 TypeScript。\n包含适当的类型和基本结构。",
12      "description": "创建新组件"
13    }
14  }
15}

你也可以使用 ~/.config/opencode/command/ 或 .opencode/command/ 中的 markdown 文件定义命令。了解更多。

## Keybinds#

你可以通过 keybinds 选项自定义快捷键。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "keybinds": {}
4}

了解更多。

## Autoupdate#

版本说明（核验：2026-10-12）：以下行为按 OpenCode v1.19.0 核验。 2026-10-11 发布说明↗ 明确取消了自动安装更新；旧版本文档中“启动时自动下载更新”的描述不适用于该版本，也不要据此推断所有历史版本或 OpenCode 2 的行为。

在 v1.19.0 中，autoupdate 控制更新检查和通知：

值	行为
`true`、`"notify"` 或未设置	检查更新并按检查结果提示，不自动安装
`false`	禁用更新检查

例如，保留检查与通知：

jsonc
1{
2  "$schema": "https://opencode.ai/config.json",
3  "autoupdate": "notify"
4}

如需关闭检查，将其改为 false；环境变量 OPENCODE_DISABLE_AUTOUPDATE 也可禁用检查。上述含义依据 v1.19.0 更新检查源码↗，避免与尚未同步的通用配置文档或 Schema 字段描述混淆。

安装更新需主动使用 TUI 的 /update 或 CLI 的 opencode upgrade。跨到 OpenCode 2 需要明确选择升级，CLI 使用 opencode upgrade --major；这是跨主版本操作，应先查看对应版本的迁移说明。

## Formatters#

你可以通过 formatter 选项配置代码格式化工具。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "formatter": {
4    "prettier": {
5      "disabled": true
6    },
7    "custom-prettier": {
8      "command": ["npx", "prettier", "--write", "$FILE"],
9      "environment": {
10        "NODE_ENV": "development"
11      },
12      "extensions": [".js", ".ts", ".jsx", ".tsx"]
13    }
14  }
15}

了解更多关于格式化工具。

## Permissions#

默认情况下，opencode 允许所有操作而无需明确批准。你可以使用 permission 选项更改此设置。

例如，要确保 edit 和 bash 工具需要用户批准：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "permission": {
4    "edit": "ask",
5    "bash": "ask"
6  }
7}

了解更多关于权限。

## Compaction#

你可以通过 compaction 选项控制上下文压缩行为。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "compaction": {
4    "auto": true,
5    "prune": true
6  }
7}

auto - 当上下文已满时自动压缩会话（默认：true）。
prune - 删除旧的工具输出以节省令牌（默认：true）。

## Watcher#

你可以通过 watcher 选项配置文件监视器忽略模式。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "watcher": {
4    "ignore": ["node_modules/**", "dist/**", ".git/**"]
5  }
6}

模式遵循 glob 语法。使用此选项可以从文件监视中排除嘈杂的目录。

## MCP 服务器#

你可以通过 mcp 选项配置你想使用的 MCP 服务器。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "mcp": {}
4}

了解更多。

## Plugins#

插件使用自定义工具、钩子和集成扩展 OpenCode。

将插件文件放在 .opencode/plugin/ 或 ~/.config/opencode/plugin/。你也可以通过 plugin 选项从 npm 加载插件。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
4}

了解更多。

## Instructions#

你可以通过 instructions 选项配置你使用的模型的指令。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
4}

这接受指令文件的路径和 glob 模式数组。了解更多关于规则。

## 禁用的提供商#

你可以通过 disabled_providers 选项禁用自动加载的提供商。当你想阻止某些提供商加载（即使它们的凭据可用）时，这很有用。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "disabled_providers": ["openai", "gemini"]
4}

注意： disabled_providers 优先于 enabled_providers。

disabled_providers 选项接受提供商 ID 数组。当提供商被禁用时：

即使设置了环境变量，它也不会被加载。
即使通过 /connect 命令配置了 API 密钥，它也不会被加载。
提供商的模型不会出现在模型选择列表中。

## 启用的提供商#

你可以通过 enabled_providers 选项指定提供商的允许列表。设置后，只有指定的提供商将被启用，所有其他提供商将被忽略。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "enabled_providers": ["anthropic", "openai"]
4}

当你想限制 OpenCode 仅使用特定提供商而不是逐个禁用它们时，这很有用。

注意： disabled_providers 优先于 enabled_providers。

如果提供商同时出现在 enabled_providers 和 disabled_providers 中，为了向后兼容，disabled_providers 优先。

## Experimental#

experimental 键包含正在积极开发中的选项。

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "experimental": {}
4}

警告： 实验性选项不稳定。它们可能会在没有通知的情况下更改或删除。

# 变量#

你可以在配置文件中使用变量替换来引用环境变量和文件内容。

## 环境变量#

使用 {env:VARIABLE_NAME} 替换环境变量：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "model": "{env:OPENCODE_MODEL}",
4  "provider": {
5    "anthropic": {
6      "models": {},
7      "options": {
8        "apiKey": "{env:ANTHROPIC_API_KEY}"
9      }
10    }
11  }
12}

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

## 文件#

使用 {file:path/to/file} 替换文件内容：

json
1{
2  "$schema": "https://opencode.ai/config.json",
3  "instructions": ["./custom-instructions.md"],
4  "provider": {
5    "openai": {
6      "options": {
7        "apiKey": "{file:~/.secrets/openai-key}"
8      }
9    }
10  }
11}

文件路径可以是：

相对于配置文件目录的路径
或以 / 或 ~ 开头的绝对路径

这些对于以下用途很有用：

将敏感数据（如 API 密钥）保存在单独的文件中。
包含大型指令文件而不会使配置变得混乱。
跨多个配置文件共享通用配置片段。

配置

相关文档