第4章 OpenCode 配置指南
在你的项目中创建 opencode.jsonc 文件来配置 OpenCode。添加 $schema$ 字段以启用编辑器校验,然后仅设置你需要的选项。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"model": "anthropic/claude-sonnet-5-5",
}
你也可以让 OpenCode 帮你更新此文件。
OpenCode 支持 JSON 和 JSONC。如果你需要注释或尾随逗号,请使用 JSONC。
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
// 默认使用此模型。
"model": "anthropic/claude-sonnet-5-5",
}
将受管理的机器级设置放在系统配置目录中:
| 平台 | 目录 |
|---|---|
| macOS | /Library/Application Support/opencode |
| Linux | /etc/opencode |
| Windows | %ProgramData%\opencode |
系统目录的作用与全局目录类似。除了 opencode.json(c),它为机器上的每个用户加载 agents/、commands/、skills/ 和 plugins/:
Files
/etc/opencode/
├── opencode.json
├── agents/review.md
├── commands/release.md
└── skills/deploy/SKILL.md
在 macOS 上,OpenCode 还会读取 MDM 工具部署到 ai.opencode.managed 域中的受管理偏好设置。用户特定的配置文件会替换机器级的配置:
/Library/Managed Preferences/<user>/ai.opencode.managed.plist
/Library/Managed Preferences/ai.opencode.managed.plist
受管理设置的优先级最高,因此用户和项目无法覆盖其设置的值,且受管理偏好设置优先于系统目录中的设置。仅靠设置无法阻止用户添加提供商、MCP 服务器、代理或插件;请在受管理的配置中使用策略(policies)来强制执行限制。
将所有项目的用户设置放在全局配置中:
~/.config/opencode/opencode.json(c)
将项目设置放在以下任一文件中:
/home/user/projects/my-app/opencode.json(c)
/home/user/projects/my-app/.opencode/opencode.json(c)
OpenCode 从当前目录搜索到文件系统根目录。它首先从最远目录到最近目录合并直接的 opencode.json(c) 文件,然后按相同顺序合并 .opencode 目录内的文件。这意味着发现的每个 .opencode 配置都会覆盖每个直接配置。除非需要这种行为,否则在目录树中请始终使用其中一种形式。
例如,从 /home/user/projects/acme/packages/web 启动 OpenCode:
Files
/etc/opencode/opencode.json
~/.config/opencode/opencode.json
/home/user/projects/acme/
├── opencode.json
└── packages/
└── web/
├── opencode.json
└── src/
OpenCode 按以下从低到高的优先级应用这些文件:
~/.config/opencode/opencode.json
/home/user/projects/acme/opencode.json
/home/user/projects/acme/packages/web/opencode.json
/etc/opencode/opencode.json
包配置覆盖仓库配置中冲突的设置,而仓库配置覆盖全局配置。系统配置覆盖所有这些。不冲突的设置会被保留。来自全局和项目文件的策略按相反顺序评估,且系统策略优先于所有其他策略。
完整的 OpenCode 配置架构(schema)可在 opencode.ai/config.json 获取。在你的配置文件中添加 $schema 字段,以启用支持 JSON Schema 的编辑器中的校验和自动补全:
opencode.json{
"$schema": "https://opencode.ai/config.json"
}
使用该架构作为可用字段、允许值和嵌套配置结构的唯一事实来源。
shell
设置终端和 shell 工具使用的 shell。
JSONC{
"shell": "/bin/zsh",
}
model
以 provider/model 格式设置默认模型。根级别的默认值目前不会保留 #variant;代理和命令的模型引用可以选择一个。
JSONC{
"model": "anthropic/claude-sonnet-5-5",
}
有关模型选择和本地模型,请参阅模型指南。
default_agent
选择会话未显式指定时使用的默认代理。
JSONC{
"default_agent": "build",
}
有关内置和自定义代理,请参阅代理指南。
update
从全局配置控制更新检查。将 update 设为 "disable" 可跳过检查,"notify" 会在安装前显示可用更新,"auto" 会自动安装更新。省略时,update 默认为 "notify"。自动安装不会重启正在运行的服务器。需手动重启以激活已安装的更新。忽略项目级的值。
JSONC{
"update": "notify",
}
username
设置用户名。OpenCode 接受此字段,但在对话中不显示。
JSONC{
"username": "alice",
}
permissions
定义有序规则,允许、禁止或在代理对匹配资源使用工具前询问。
JSONC{
"permissions": [
{
"action": "shell",
"resource": "git push *",
"effect": "ask",
},
],
}
有关规则匹配和可用操作,请参阅权限指南。
policies
使用有序语句允许或禁止使用提供商、硬性拒绝权限检查、或阻止 MCP 服务器、技能或插件,且更广泛的配置可以覆盖这些语句。
JSONC{
"policies": [
{ "action": "provider.use", "resource": "*", "effect": "deny" },
{ "action": "provider.use", "resource": "anthropic", "effect": "allow" },
{ "action": "tool.use", "resource": "shell:git push *", "effect": "deny" },
],
}
有关匹配、跨配置文件的优先级以及控制台管理的策略,请参阅策略指南。
agents
覆盖内置代理或定义具有自己的模型、指令、模式和权限的专用代理。
JSONC{
"agents": {
"reviewer": {
"description": "审查变更而不编辑文件",
"mode": "subagent",
"system": "关注正确性、安全性和缺失的测试。",
"permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }],
},
},
}
有关所有代理选项和基于文件的代理,请参阅代理指南。
snapshots
启用或禁用文件系统快照,用于撤销和回退行为。
JSONC{
"snapshots": false,
}
有关撤销和重做行为,请参阅快照指南。
watcher
忽略不应触发文件系统更新的文件和目录。
JSONC{
"watcher": {
"ignore": ["dist/**", "coverage/**"],
},
}
formatter
在 write、edit 或 patch 工具更改文件后进行格式化。将 formatter 设为 true 以启用可用的内置格式化器。
JSONC{
"formatter": true,
}
有关内置和自定义格式化器,请参阅格式化器指南。
media
控制 read 工具加载的过大图像在发送给模型前如何被缩放或拒绝。
JSONC{
"media": {
"image": {
"auto_resize": true,
"max_width": 2000,
"max_height": 2000,
"max_base64_bytes": 5242880,
},
},
}
有关图像处理和限制,请参阅附件指南。
tool_output
设置从工具结果中保留的最大行数和字节数。
JSONC{
"tool_output": {
"max_lines": 2000,
"max_bytes": 51200,
},
}
websearch
选择 OpenCode 如何搜索网络。使用 "random" 自动选择可用提供商。
JSONC{
"websearch": {
"provider": "random",
},
}
有关提供商、凭据、选择、速率限制和禁用搜索,请参阅网络搜索指南。
mcp
配置本地和远程 Model Context Protocol 服务器。全局 mcp.timeout 值适用于配置文件中定义的服务器;每个服务器的超时设置会覆盖它们。
JSONC{
"mcp": {
"servers": {
"playwright": {
"type": "local",
"command": ["bunx", "@playwright/mcp"],
},
},
},
}
有关远程服务器、OAuth、环境变量的超时的设置,请参阅 MCP 指南。
compaction
控制自动上下文压缩及其保留的近期上下文量。
JSONC{
"compaction": {
"auto": true,
"keep": {
"tokens": 15000,
},
"buffer": "15%",
},
}
buffer 是在自动压缩开始之前保留的空闲模型上下文窗口比例。本地摘要仍是默认选项。通过提供商或模型策略为自动和手动请求启用原生提供商压缩:
JSONC{
"providers": {
"openai": {
"settings": { "compaction": { "type": "native" } },
"models": {
"gpt-6.1-sol": { "settings": { "compaction": { "type": "summary" } } },
},
},
},
}
模型设置覆盖提供商设置。自动压缩使用所选模型可用的输入预算。提供商检查点会在与本地摘要用于保留尾部的相同 compaction.keep.tokens 预算内保留最近的 user 消息。顶层 compaction.auto: false 会禁用新的自动压缩,而不会丢弃已安装的检查点。有关预算和溢出恢复,请参阅压缩指南。
warming
通过周期性瞬态请求保持最近活跃的模型会话处于热状态。预热默认禁用;设为 true 可在每个模型缓存过期前进行预热,最长 30 分钟。
JSONC{
"warming": {
"prompt": "Do not perform any work. Reply with exactly: OK",
"interval": "auto",
"duration": "30 minutes",
},
}
提供商或模型的 settings.cache.warming 会覆盖此设置,settings.cache.ttl 设置提供商保留缓存的时长。有关请求行为、自定义和成本考虑,请参阅预热指南;有关 cache.ttl,请参阅缓存生命周期。
skills
添加 OpenCode 应搜索代理技能的目录或 URL。
JSONC{
"skills": ["./team-skills", "https://example.com/.well-known/skills/"],
}
有关技能结构和 .opencode/skills/ 下的自动发现,请参阅技能指南。
commands
将可重用的斜杠命令定义为命名提示模板。
JSONC{
"commands": {
"review": {
"description": "审查当前变更",
"template": "审查当前 diff 的正确性和缺失的测试。",
},
},
}
有关参数、模型、代理和基于文件的命令,请参阅命令指南。
instructions
声明额外的指令文件、glob 模式或 HTTP(S) URL。OpenCode 会将其与发现的 AGENTS.md 文件一起加载。
JSONC{
"instructions": ["CONTRIBUTING.md", "docs/guidelines/*.md"],
}
有关项目指令和 AGENTS.md,请参阅指令指南。
references
将本地目录或 Git 仓库作为命名的支持上下文提供。
JSONC{
"references": {
"docs": {
"path": "../product-docs",
"description": "产品行为和术语",
},
"effect": {
"repository": "Effect-TS/effect",
"branch": "main",
},
},
}
有关简写、可见性和路径解析,请参阅引用指南。
worktree
设置新本地工作树(worktree)的父目录。OpenCode 会附加请求或生成的工作树名称。
JSONC{
"worktree": {
"directory": "../worktrees",
},
}
相对路径相对于项目保存的规范检出(canonical checkout)解析。这对全局和项目配置均适用;绝对路径按原样使用,~/ 相对于用户的家目录解析。例如,此全局配置将新工作树放在每个项目自己的 .lane/trees/ 目录下:
JSONC{
"worktree": {
"directory": ".lane/trees",
},
}
若未设置此项,创建时将使用服务器数据目录下 worktree/<项目ID前六个字符>。工作树的创建和刷新会从项目的规范检出加载配置,包括其他克隆共享其项目 ID 的情况。更改此项不会移动现有的工作树。Git 是内置默认值。注册策略的插件会在该插件运行时自动成为默认值。项目操作使用规范检出的运行时。特定于策略的选项属于该插件,而非 worktree 配置对象。
plugins
从包或本地插件目录加载插件。当插件接受选项时,使用对象形式。
JSONC{
"plugins": [
"opencode-example-plugin",
{
"package": "./plugins/local",
"options": {
"enabled": true,
},
},
],
}
有关插件加载和配置,请参阅插件指南。
providers
配置提供商,添加或覆盖其模型、请求设置、请求头和模型变体。
JSONC{
"providers": {
"openai": {
"models": {
"gpt-6.1-sol-custom": {
"modelID": "gpt-6.1-sol",
"name": "GPT-6.1 Sol Custom",
"limit": {
"context": 200000,
"output": 32000,
},
},
},
},
},
}
Provider settings.transport: "websocket" 选择其会话 WebSocket。有关凭据、自定义端点、提供商包、WebSocket 传输和模型配置,请参阅提供商指南。
你可以在配置文件中使用时,使用变量替换来引用环境变量和文件内容。将引用放在 JSON 字符串内部。
环境变量
使用 {env:VARIABLE_NAME} 替换环境变量:
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"model": "{env:OPENCODE_MODEL}",
"providers": {
"anthropic": {
"settings": {
"apiKey": "{env:ANTHROPIC_API_KEY}",
},
},
},
}
如果环境变量未设置,它将被替换为空字符串。
文件内容
使用 {file:path/to/file} 替换文件内容:
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"providers": {
"openai": {
"settings": {
"apiKey": "{file:~/.secrets/openai-key}",
},
},
},
}
文件路径可以是:
- 相对于配置文件目录
- 绝对路径,或以
~/开头指向家目录
如果文件不存在,它将被替换为空字符串。这些功能适用于:
- 将 API 密钥等敏感数据保存在单独的文件中。
- 在多个配置文件之间共享通用配置片段。
所有实验性设置都位于 experimental 键下:
opencode.jsonc{
"$schema": "https://opencode.ai/config.json",
"experimental": {
"todo": true,
"subagent_depth": 2,
"background_compaction": true,
"image_generate": { "model": "openai/gpt-image-2" },
"location_idle_timeout": "4 hours",
},
}
experimental.todo
将 todo 设为 true 可为代理提供 todowrite 工具以跟踪多步工作。默认为 false。
experimental.subagent_depth
subagent_depth 设置子代理可以启动自身子代理的深度。默认为 1,即子代理不能启动另一个子代理。
experimental.background_compaction
将 background_compaction 设为 true 可在需要之前后台写入压缩摘要,以便自动压缩不会暂停会话。默认为 false。有关其工作原理,请参阅压缩。
JSONC{
"experimental": {
"background_compaction": true,
},
}
experimental.image_generate
image_generate 设置 experimental_image_generate 工具的默认模型,格式为 providerID/modelID,可选附带 #variant。如果该模型不可用或无法处理请求,OpenCode 会自动选择另一个图像模型。
JSONC{
"experimental": {
"image_generate": {
"model": "openai/gpt-image-2",
},
},
}
experimental.location_idle_timeout
location_idle_timeout 控制项目位置在没有会话活动的情况下可以保持多久,之后 OpenCode 会卸载其服务。它接受持续时间(如 "2 hours"),默认为 "60 minutes"。正在运行的会话和后台任务会使位置保持加载。设为 false 以永不卸载空闲位置。项目配置可以覆盖全局值。
JSONC{
"experimental": {
"location_idle_timeout": false,
},
}
experimental.policies 已弃用。请使用顶层 policies 代替。旧键仍然有效并会合并到 policies 中。