配置系统
格式
支持 JSON 和 JSONC（带注释的 JSON），文件名 opencode.json/opencode.jsonc。
多层配置来源与优先级（后者覆盖前者，但是”合并”不是”替换”）
不同来源的非冲突字段全部保留，只有同一 key 冲突时才按优先级取胜出者。
| 顺序（低→高） | 来源 | 说明 |
|---|---|---|
| 1 | Remote config（.well-known/opencode） | 组织级默认值，认证到支持该协议的 Provider 时自动拉取 |
| 2 | Global config（~/.config/opencode/opencode.json） | 用户级偏好 |
| 3 | Custom config（OPENCODE_CONFIG 环境变量指定路径） | 自定义覆盖 |
| 4 | Project config（项目根 opencode.json） | 项目专属设置，可入库共享 |
| 5 | .opencode/ 目录（agents/commands/plugins） | 项目内声明式扩展 |
| 6 | Inline config（OPENCODE_CONFIG_CONTENT 环境变量） | 运行时内联覆盖 |
| 7 | Managed config files（/Library/Application Support/opencode/ 等系统路径） | 管理员强制配置，需 root/admin 权限写入 |
| 8 | macOS managed preferences（.mobileconfig via MDM） | 最高优先级，用户不可覆盖 |
启动时先在当前目录找配置文件，再逐级向上找最近的 Git 目录。
.opencode/ 与 ~/.config/opencode/ 下子目录用复数命名：agents/、commands/、modes/、plugins/、skills/、tools/、themes/（单数形式向后兼容仍支持）。
Managed settings（组织强制配置）
- 文件方式：在系统级目录（macOS
/Library/Application Support/opencode/、Linux/etc/opencode/、Windows%ProgramData%\opencode）放opencode.json(c)，普通用户无写权限 - macOS MDM 方式：读取
ai.opencode.managedpreference domain，通过.mobileconfig部署（Jamf/Kandji/FleetDM），plist key 直接映射opencode.json字段，opencode debug config可验证生效情况
配置项一览（节选核心，完整详见官方文档）
| 配置项 | 作用 |
|---|---|
model/small_model | 默认模型 / 轻量任务模型（如生成标题） |
provider | Provider 选项（timeout/chunkTimeout/setCacheKey 等，也可传 Bedrock 的 region/profile/endpoint） |
agent | 定义/覆盖 Agent（见 Agent系统） |
default_agent | 默认使用的 primary agent，跨 TUI/CLI/桌面/GitHub Action 生效 |
command | 自定义命令（见 CLI与命令） |
permission | 权限规则（见 权限与安全） |
mcp | MCP Server 配置（见 工具与集成） |
plugin | npm 插件包列表 |
tools | 工具启用/禁用（legacy，逐步被 permission 取代） |
formatter/lsp | 格式化工具/LSP，默认关闭，需显式开启（true 或对象覆盖细项） |
instructions | 引入外部规则文件路径/glob（如 CONTRIBUTING.md），配合 Agent系统 的 Rules 机制 |
share | 分享模式 manual/auto/disabled（见 界面与客户端） |
snapshot | 是否用内部 git 跟踪文件变更以支持撤销（大仓库/多 submodule 场景可能拖慢索引，可关闭） |
autoupdate | 自动更新（true/false/"notify"，非包管理器安装才生效） |
server | serve/web 的端口/hostname/mDNS/CORS |
shell | 交互终端及 Agent bash 调用用的 shell，未指定则按 OS 自动探测 |
attachment.image | 图片附件自动缩放/上限（max_width/max_height/max_base64_bytes），超限图片：工具返回图片直接省略，用户上传图片直接报错 |
watcher.ignore | 文件监听忽略的 glob 模式 |
disabled_providers/enabled_providers | Provider 黑白名单（官方建议改用 权限与安全 中更细粒度的 Policy 机制） |
experimental | 实验特性总开关，包含 policies（见 权限与安全） |
TUI 专属设置不在 opencode.json 里，单独用 tui.json（见 界面与客户端）。
变量替换语法
{env:VARIABLE_NAME}— 替换为环境变量值（未设置则替换为空字符串）{file:path/to/file}— 替换为文件内容，路径可相对配置文件目录或绝对/~路径；常用于隔离敏感 key（如{file:~/.secrets/openai-key}）或复用大段 instructions
Schema
https://opencode.ai/config.json（server/runtime schema）与 https://opencode.ai/tui.json（TUI schema），编辑器可据此做校验和自动补全。
关联
来源
https://opencode.ai/docs/config.mdx（dev 分支）。整理：赵卫国 2026-07-07。