OpenCode 2.1 配置参数详解

目标：系统讲解 OpenCode 2.1（2.1.3）的配置体系——配置文件位置与合并优先级、模型与自定义 provider、Agent 与权限、会话与上下文、MCP 服务器、扩展机制等全部核心参数，并给出生产可直接套用的配置模板。参数取值与默认值溯源自官方文档（opencode.ai/v2/docs，查询日期 2026-10-23），配置文件加载、MCP 接入、Code Mode 行为等关键环节均在 Ubuntu 22.04 上实测验证。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• OpenCode 版本：2.1.3（npm 包 @opencode/cli，2026-10-23 实查 latest）
• 全局配置路径（opencode debug paths 实测）：/root/.config/opencode
• 数据与状态路径（实测）：/root/.local/share/opencode（含 SQLite 库 opencode.db）、缓存 /root/.cache/opencode
• 自定义 provider 实测端点：Ollama 0.40.8（http://127.0.0.1:11434/v1，OpenAI 兼容）
• 安装过程见《Ubuntu 22.04 安装 OpenCode 2.1 指南》，本文不重复安装步骤。

二、前置条件

1. 已按《Ubuntu 22.04 安装 OpenCode 2.1 指南》装好 opencode 2.1.3 并通过 opencode --version 验证：

opencode v2.1.3

2. 至少一个可用模型凭据：官方免费模型组（零配置可用）、商业 API Key，或本地 OpenAI 兼容端点（本文实测用 Ollama）。

三、参数查看与修改方式

3.1 配置文件位置与优先级

OpenCode 使用 JSON/JSONC 配置文件（JSONC 支持注释与尾逗号，官方文档明示），三层位置：

合并规则（官方文档原文要点）：OpenCode 从当前目录向上搜索到文件系统根；先按「由远及近」合并直存的 opencode.json(c)，再按同样顺序合并 .opencode 目录内的文件，因此每个发现的 .opencode 配置都会覆盖直存配置。同键冲突时高优先级覆盖低优先级，不冲突的设置全部保留。官方建议同一目录树内统一用一种形式，除非刻意需要该覆盖行为。

实测验证：全局配置 + 项目配置并存时，opencode debug config 输出两个 document 源（真实回显）：

"path": "/root/.config/opencode/opencode.json"
"path": "/root/demo-app/opencode.json"

3.2 修改方式

• 直接编辑 JSON/JSONC 文件，保存后执行重载：

opencode reload

实测回显：

Configuration reloaded

• 也可在 TUI 内让 OpenCode 帮你改配置（官方文档："You can also ask OpenCode to update this file for you"）。
• MCP 服务器可用 CLI 直接增删（写入项目配置文件）：opencode mcp add ...（见 5.5 节实测）。

3.3 Schema 校验

完整配置 Schema 官方发布在 https://opencode.ai/config.json。在配置文件首行加 "schema" 引用即可获得编辑器校验与补全（官方推荐写法）：

{
  "$schema": "https://opencode.ai/config.json"
}

3.4 查看当前生效配置

opencode debug config 列出全部配置来源与合并后的内容（实测节选，全局配置源）：

[
  {
    "type": "document",
    "path": "/root/.config/opencode/opencode.json",
    "info": {
      "$schema": "https://opencode.ai/config.json",
      "model": {
        "providerID": "ollama",
        "model": "qwen2.5:0.5b"
      },
      "providers": {
        "ollama": {
          "name": "Ollama",
          ...

opencode debug config 的输出已把凭据类敏感字段脱敏（官方 1.18.33 发布说明明确"Debug configuration output now redacts credentials and sensitive headers"）。

四、参数总览

按官方文档（opencode.ai/v2/docs/config）与 2.1.3 实测整理的全部顶层参数：

💡 说明：表中"默认"列凡标注"官方文档"处的默认行为均来自官方 config 文档原文；model、providers、mcp、permissions 四组为使用频率最高、坑最多的参数，逐项拆解见第五章。

五、核心参数分类详解

5.1 模型与 provider（model / providers）

model：provider/model 引用格式，全局默认模型。官方注明根级 model 目前不保留 #variant 后缀；agent 与 command 的模型引用可以选择 variant。

providers：接入 provider 的总入口。内置目录来自 models.dev（OpenCode 启动即有数百个 provider/模型可选）；对目录外的 API（自建网关、本地推理服务）用自定义 provider。provider 级全字段（官方文档表格整理）：

package 可选值（官方列出的原生包）：OpenAI 系 @opencode/ai/providers/openai（含 /chat、/responses 变体）、@opencode/ai/providers/openai-compatible（含 /responses）、Anthropic 系 .../anthropic、.../anthropic-compatible、Google 系 .../google、.../google-vertex（含 gemini/chat/responses/messages 变体）、.../azure（含 chat/responses）、.../amazon-bedrock（含 mantle 变体）、.../openrouter、.../xai；也可写任意 npm 包名或 file:// 本地包路径。OpenAI 兼容端点（Ollama、vLLM、OneAPI 网关等）统一用 @opencode/ai/providers/openai-compatible。

models 子字段（官方文档表格）：

settings 内的传输控制（官方文档）：

• baseURL：覆盖官方端点——既用于自定义 provider，也可把内置 provider 转发到代理/网关；
• headerTimeout / chunkTimeout：等响应头、流式块间隔上限，默认各 5 分钟（毫秒数，false 关闭）；WebSocket 传输下 chunkTimeout 默认 30 分钟；
• timeout：整个请求的总上限（无默认）；
• encoding：请求体压缩 zstd/gzip/none；OpenAI 包在 ChatGPT 登录且无自定义 baseURL 时默认 zstd，API Key 发纯 JSON；网关若不支持压缩务必显式 none。

实测：Ollama 自定义 provider。~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5:0.5b",
  "providers": {
    "ollama": {
      "name": "Ollama",
      "env": ["OLLAMA_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "http://127.0.0.1:11434/v1" },
      "models": {
        "qwen2.5:0.5b": { "name": "Qwen2.5 0.5B" },
        "qwen2.5-coder:1.5b": { "name": "Qwen2.5 Coder 1.5B" },
        "qwen3:0.6b": { "name": "Qwen3 0.6B" }
      }
    }
  }
}

生效验证（opencode models 过滤 + opencode debug config 解析结果）：

ollama/qwen2.5:0.5b

      "model": {
        "providerID": "ollama",
        "model": "qwen2.5:0.5b"
      },

TUI 的 /models 选择器实测同步出现 Ollama 分组与三个模型（● Qwen2.5 0.5B 为当前默认）。

⚠️ 注意：env 声明的变量（本文 OLLAMA_API_KEY）必须在启动 OpenCode 的环境里存在（opencode auth list 实测显示其来源为 environment），本地 Ollama 不校验值但变量缺失会影响凭据解析。

provider 级 baseURL 转发内置 provider（官方文档示例形态）：对目录内 provider 只改 settings.baseURL 即可把流量转发到兼容网关，其模型目录与连接方式保持不变。

5.2 Agent 与权限（default_agent / agents / permissions / policies）

内置 Agent：build（默认，全权开发）、plan（只读：默认禁止改文件、运行命令前先询问）、general（子代理，用于复杂搜索与多步任务，消息里 @general 调用）。TUI 内 shift+tab 切换（实测 TUI 底栏提示一致）。

agents：覆盖内置或定义新 Agent。官方示例（官方文档原文形态）：

{
  "agents": {
    "reviewer": {
      "description": "Review changes without editing files",
      "mode": "subagent",
      "system": "Focus on correctness, security, and missing tests.",
      "permissions": [{ "action": "edit", "resource": "*", "effect": "deny" }]
    }
  }
}

permissions 为有序规则：action（如 shell、edit）+ resource 匹配模式（如 git push *）+ effect（allow/deny/ask）；匹配时先到先得，允许精细到"允许所有编辑但 git push 必须确认"这类策略。

experimental.policies：更硬的策略层，官方形态：

{
  "experimental": {
    "policies": [
      { "action": "provider.use", "resource": "*", "effect": "deny" },
      { "action": "provider.use", "resource": "anthropic", "effect": "allow" },
      { "action": "permission", "resource": "shell:git push *", "effect": "deny" }
    ]
  }
}

上例含义：默认拒绝一切 provider，仅放行 anthropic；对 git push 类命令直接硬拒绝（不弹询问）。跨配置文件的优先级与 Console 托管策略见官方 policies 文档。

运行时交互：非交互场景用 --auto 自动放行未被显式 deny 的权限（opencode run --auto，实测可用）；交互 TUI 内按需弹窗确认。

5.3 会话与上下文（compaction / warming / snapshots / worktree）

compaction：上下文自动压缩。官方参数形态：

{
  "compaction": {
    "auto": true,
    "keep": { "tokens": 15000 },
    "buffer": 20000
  }
}

• auto：会话接近模型可用输入预算时自动压缩；false 只关自动、不丢已装检查点；
• keep.tokens：压缩时保留的近期上下文 token 预算；
• buffer：预留缓冲。
• 压缩算法有两类（技术拓展）：本地摘要（local summary，默认）——由当前模型生成会话摘要；原生压缩（native）——用 provider 自带能力，按 provider/模型策略开启（官方示例：provider 级 settings.compaction.type: "native"，模型级可回退 "summary"，模型设置覆盖 provider 设置）。OpenCode 实际采用本地摘要为默认，原生压缩需显式 opt-in。

warming：对近期活跃会话周期性发瞬态请求保温，默认关闭；开启后用 4 分钟闲置间隔、30 分钟活跃窗口（官方默认值），可自定义 prompt：

{ "warming": { "prompt": "Do not perform any work. Reply with exactly: OK", "interval": "4 minutes", "duration": "30 minutes" } }

snapshots：文件系统快照开关，支撑 undo/revert；磁盘紧张或只读场景可 false 关闭（官方文档）。

worktree.directory：新建 worktree 的父目录，相对路径基于项目规范检出解析；不设置时落在服务端数据目录 worktree/<项目 ID 前 6 位>（官方文档）。worktree 策略默认 Git，插件可注册替代策略并自动成为默认。

instructions：官方明确"接受该字段但不加载其条目，指令请使用 AGENTS.md"——这是 2.x 的一个行为变更点，不要照搬 1.x 的 instructions 用法。

references：把外部目录或 Git 仓库挂成命名上下文（如 docs 指向产品文档目录、effect 指向某 GitHub 仓库分支），供 Agent 引用（官方文档）。

5.4 工具与输出（shell / tool_output / media / formatter / watcher / websearch）

• shell：终端与 shell 工具用的 shell，如 "/bin/zsh"；
• tool_output：工具结果保留上限，官方默认形态 {"max_lines": 2000, "max_bytes": 51200}（超出截断，防上下文爆炸）；
• media.image：read 工具加载超大图片时的处理，官方默认形态 {"auto_resize": true, "max_width": 2000, "max_height": 2000, "max_base64_bytes": 5242880}——自动缩放，超 5 MB base64 拒绝；
• formatter：write/edit/patch 改完文件后自动跑格式化器；true 启用全部可用内置格式化器，对象形态可逐个配置；
• watcher.ignore：文件监视忽略项，官方示例 ["dist/**", "coverage/**"]，避免构建产物反复触发；
• websearch.provider：联网搜索后端选择，"random" 表示在可用 provider 中自动选；凭据与限流见官方 websearch 文档。

5.5 MCP 服务器（mcp.servers）

v2 的 MCP 配置键是 mcp.servers（官方明确 v2 不再把服务器名直接放在 mcp 下）。两种类型：

local（stdio）——OpenCode 拉起子进程：

remote（Streamable HTTP）——连接远程端点：url 必填绝对地址；headers 传凭据（配 oauth: false 时用于纯 API Key 认证）；oauth 默认开启（自动发现授权服务器、PKCE、刷新令牌、支持动态客户端注册），也可给 client_id/client_secret/scope/callback_port/redirect_uri 显式配置。其余 disabled/codemode/timeout/protocol 字段语义同 local。

环境变量替换用 {env:NAME} 形式（官方注明 JSON 字符串里不展开 $NAME 等 shell 表达式）：

{
  "environment": { "MCP_API_KEY": "{env:MCP_API_KEY}" }
}

实测全流程（Ubuntu 22.04，OpenCode 2.1.3）：

1. 用 CLI 注册一个本地 stdio 服务器（-- 之后为启动命令；测试用的最小 MCP 服务器是一个按 MCP stdio 协议应答 initialize/tools/list/tools/call 的 Node 脚本 /root/mcp/echo-mcp.mjs）：

opencode mcp add echo -- node /root/mcp/echo-mcp.mjs

实测回显：

MCP server "echo" added to /root/demo-app/opencode.json

命令实际写入的项目配置文件内容（实测 cat /root/demo-app/opencode.json）：

{
  "mcp": {
    "servers": {
      "echo": {
        "type": "local",
        "command": [
          "node",
          "/root/mcp/echo-mcp.mjs"
        ],
        "codemode": false
      }
    }
  }
}

2. 重载并列出状态：

opencode reload
opencode mcp list

实测回显：

Configuration reloaded
✓ echo  connected

⚠️ 排障实录（Code Mode）：codemode 默认为 true 时，MCP 工具经 Code Mode 间接暴露——实测本地小模型（qwen3:0.6b）在 agent 会话中报告"echo 工具不在可用工具集中"，把工具调用写成 JSON 文本而不执行。将该服务器设为 "codemode": false 后重测，工具注册路径变为直接暴露。服务器连接状态（✓ connected）与 codemode 无关，任何值下均正常连接；工具调用失败时优先排查模型对 function calling 的支持度与 codemode 形态，生产建议 7B 以上模型。

💡 技术拓展：MCP 传输方式业界常用三种——stdio（本地子进程）、Streamable HTTP（远程，v2 remote 采用）、SSE（旧版远程，逐步被 Streamable HTTP 取代）。OpenCode v2 内置支持前两种；旧配置若写 SSE 型 URL 需确认服务端兼容 Streamable HTTP。本文实测采用 stdio（本地 node 进程），远程场景加 type: "remote" + url 即可。

5.6 扩展机制（plugins / skills / commands）

• plugins：数组，元素为包名字符串或 { "package": "./plugins/local", "options": {...} } 对象形态（带选项时用对象，官方文档）；CLI 侧 opencode plugin add/list/update/remove 管理（写入全局配置）；
• skills：["./team-skills", "https://example.com/.well-known/skills/"]——目录或 URL；.opencode/skills/ 下的 skill 自动发现，无需配置；
• commands：命名斜杠命令模板：

{
  "commands": {
    "review": {
      "description": "Review the current changes",
      "template": "Review the current diff for correctness and missing tests."
    }
  }
}

模板支持参数、指定模型与 Agent（官方 commands 文档），定义后 TUI 内以 /review 调用。

六、生产配置模板

6.1 模板 A：商业 API 直连（个人开发者，8GB 内存级工作站即可）

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "default_agent": "build",
  "update": "notify",
  "permissions": [
    { "action": "shell", "resource": "git push*", "effect": "ask" },
    { "action": "shell", "resource": "rm -rf *", "effect": "deny" }
  ],
  "tool_output": { "max_lines": 2000, "max_bytes": 51200 },
  "watcher": { "ignore": ["dist/**", "coverage/**", "node_modules/**"] }
}

适用：个人或小团队，凭据走 opencode auth login；权限只收紧高危动作；更新保持"提示不自动装"。

6.2 模板 B：企业内网网关 / 本地推理（32GB 内存 + 本地 GPU 或内网 LLM 网关）

{
  "$schema": "https://opencode.ai/config.json",
  "model": "intranet/qwen3-coder",
  "providers": {
    "intranet": {
      "name": "Intranet Gateway",
      "env": ["INTRANET_LLM_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "http://llm-gateway.internal:8000/v1",
        "encoding": "none",
        "headerTimeout": 120000,
        "chunkTimeout": 600000
      },
      "models": {
        "qwen3-coder": {
          "name": "Qwen3 Coder",
          "limit": { "context": 262144, "output": 65536 }
        }
      }
    }
  },
  "update": "disable",
  "permissions": [
    { "action": "shell", "resource": "*", "effect": "ask" },
    { "action": "edit", "resource": "*", "effect": "allow" }
  ],
  "experimental": {
    "policies": [
      { "action": "provider.use", "resource": "*", "effect": "deny" },
      { "action": "provider.use", "resource": "intranet", "effect": "allow" }
    ]
  },
  "mcp": {
    "servers": {
      "company-tools": {
        "type": "remote",
        "url": "http://mcp.internal:8080/mcp",
        "oauth": false,
        "headers": { "Authorization": "Bearer {env:MCP_API_KEY}" }
      }
    }
  }
}

适用：内网隔离环境。要点逐条：流量只允许走内网 provider（policies 白名单硬拒绝其他 provider）；encoding: "none" 防网关不识压缩体；超时按内网吞吐放宽（等头 2 分钟、流间隔 10 分钟）；凭据全部走环境变量（INTRANET_LLM_KEY、MCP_API_KEY），不落配置文件；shell 一律先询问，编辑放行。

七、常见问题

Q1：改了配置文件为什么不生效？ OpenCode 对配置有加载时机（后台服务缓存）。执行 opencode reload（实测回显 Configuration reloaded）或重启会话；仍不生效时用 opencode debug config 核对该键是否被更高优先级文件覆盖（合并顺序见 3.1）。

Q2：项目里 .opencode/opencode.json 和 opencode.json 同时存在会怎样？ 按官方合并规则两者都生效，且 .opencode 形式覆盖直存形式（每个发现的 .opencode 配置覆盖全部直存配置）。官方建议同一目录树统一用一种形式。

Q3：API Key 写进配置文件安全吗？ 不建议。provider 凭据优先用 env 字段声明环境变量（如 OLLAMA_API_KEY、INTRANET_LLM_KEY），远程 MCP 凭据用 {env:NAME} 注入 headers；opencode debug config 输出已对凭据脱敏，但配置文件本身无脱敏。

Q4：MCP 服务器显示 connected 但模型说找不到工具？ 排查两处：一是 codemode 默认 true，工具经 Code Mode 间接暴露，小模型常感知不到（本文实测复现，见 5.5 排障实录），可设 codemode: false 直接暴露；二是模型本身 function calling 能力不足——0.5B–1.5B 量级本地模型实测多次把工具调用输出为 JSON 文本，换 7B+ 或商业模型。

Q5：instructions 里写的文件为什么没被加载？ 2.x 官方文档明确：instructions 字段"接受但不加载其条目"，项目指令请使用仓库根目录的 AGENTS.md。

Q6：如何限制 Agent 只能用某些模型？ experimental.policies 的 provider.use 规则做白名单/黑名单（见 5.2 与模板 B）；被 deny 的 provider 请求直接拒绝而非降级。

Q7：怎么知道当前配置到底合并成了什么样？ opencode debug config——列出全部来源（type: document 条目含路径）与合并后内容，且凭据已脱敏；临时验证单键改动时配合 opencode reload 使用。

八、参考链接

• 官方 Config 文档（本文参数来源）：https://opencode.ai/v2/docs/config
• 官方 Providers 文档：https://opencode.ai/v2/docs/providers
• 官方 MCP 文档：https://opencode.ai/v2/docs/mcp-servers
• 配置 Schema：https://opencode.ai/config.json
• models.dev 模型目录：https://models.dev/
• 安装与首次验证：《Ubuntu 22.04 安装 OpenCode 2.1 指南》
• 命令与 TUI 实测：《OpenCode 2.1 常用 CLI 命令详解》
• 定位与选型：《OpenCode 介绍与选型指南》