opencode 配置完全指南:配置文件、目录与字段详解

opencode 配置完全指南:配置文件、目录与字段详解

一份面向 opencode 用户的配置指南:讲清楚配置写在哪里、每个字段是干什么的、provider / skill / plugin / command / 自定义工具各自从哪些目录被自动发现,以及合并优先级。文末附一章内部实现原理,供想深挖的读者参考。

一、配置文件在哪里

opencode 的配置不是单个文件,而是一组从多个位置自动发现并按优先级合并的 JSON©文件。核心位置有三类:

1. 全局配置目录

• Linux:~/.config/opencode
• macOS:~/Library/Application Support/opencode
• Windows:遵循 XDG 规则,可用环境变量OPENCODE_CONFIG_DIR覆盖为任意路径

目录下的候选文件按顺序取用:opencode.jsonc→opencode.json→config.json(后两者是兼容旧版的写法,建议统一用opencode.jsonc,支持注释和尾逗号)。

2. 项目级配置

从你启动 opencode 的目录(cwd)逐级向上到 git worktree 根,每一层目录都会被检查:

• 该层的opencode.json/opencode.jsonc文件
• 该层的.opencode/目录(目录里的opencode.json/jsonc+ 各类自动发现的 markdown 资源,见下文各章)

另外~/.opencode/也会作为用户级目录参与扫描。

3. 合并优先级

多个来源合并时,越靠近 cwd 的配置优先级越高(后者覆盖前者):

合并是深度合并:标量以后者为准,数组(如instructions、plugin)会拼接去重。设置OPENCODE_DISABLE_PROJECT_CONFIG=1可以整体跳过项目级配置和 AGENTS.md。

小提示:TUI 界面主题、快捷键等已从主配置剥离,改由tui.json/tui.jsonc管理(同样支持全局 + 项目级,变量OPENCODE_TUI_CONFIG)。

二、配置字段总览

以下是 opencode.json 的主要顶层字段(按源码中的配置 schema 整理):

三、Provider:自定义模型提供方

配置字段

{ "provider": { "my-gateway": { "name": "我的自建网关", // 展示名 "env": ["MY_GATEWAY_API_KEY"], // 凭证来源环境变量名列表 "npm": "@ai-sdk/openai-compatible", // AI SDK 包(省略时自动推断) "options": { "apiKey": "sk-...", // 也可不写,走 env/auth(见下) "baseURL": "https://gateway.example.com/v1" }, "whitelist": ["model-a"], // 只保留这些模型 "blacklist": ["legacy-model"], // 排除这些模型 "models": { // 模型覆盖/新增 "deepseek-chat": { "name": "DeepSeek V3", "tool_call": true, "reasoning": true, "cost": { "input": 0.2, "output": 0.4 }, // 每百万 token 价格(美元) "limit": { "context": 65536 } } } } }, "model": "my-gateway/deepseek-chat", "disabled_providers": ["vercel"] }

常用 model 字段:id、name、family、cost(input/output/cache_read/cache_write)、limit(context/input/output)、tool_call、reasoning、temperature、attachment、modalities、variants(变体,如 reasoning 开关)、status(active/alpha/beta/deprecated)。

模型目录从哪来

绝大多数内置模型的元数据不写死在代码里,而是来自 models.dev 的在线目录(https://models.opencode.ai/api.json),缓存于~/.cache/opencode/models.json,每 60 分钟自动刷新。离线时回退到构建期打包的快照。可用OPENCODE_MODELS_URL指向自建目录。

凭证解析顺序

请求模型时,API Key 按以下顺序取第一个可用的:

1. 配置里的options.apiKey
2. provider.env声明的环境变量(如MY_GATEWAY_API_KEY)
3. opencode auth login写入的auth.json(位于数据目录,如 Linux~/.local/share/opencode/auth.json)
4. SDK 自带的默认环境变量(如OPENAI_API_KEY、ANTHROPIC_API_KEY)

管理凭证用opencode auth list/opencode auth login/opencode auth logout。

自定义 npm provider 包

npm字段可以指向任意 AI SDK 风格的 provider 包。首次使用时自动安装到~/.cache/opencode/packages/<包名>,包需导出create*工厂函数(接收{ name, apiKey, baseURL, ... })。options.baseURL支持${ENV_VAR}占位符。

四、Agent:自定义智能体

方式一:配置字段

{ "agent": { "reviewer": { "description": "严格的代码审查员", "prompt": "你是资深代码审查员,重点关注 bug、性能与安全……", // 系统提示词 "model": "my-gateway/deepseek-chat", "temperature": 0.2, "mode": "subagent", // primary | subagent | all "permission": { "edit": "deny", "bash": "ask" }, "steps": 30 // 单次任务最大步数 } }, "default_agent": "reviewer" }

方式二:Markdown 文件(推荐团队共享)

在每个配置目录(全局或.opencode/)下放置 markdown 文件,会被自动发现:

• agent/**/*.md或agents/**/*.md—— 文件名即 agent 名
• mode/*.md或modes/*.md—— 旧式写法,等价于mode: "primary"

frontmatter 写字段,正文就是系统提示词:

--- description: 严格的代码审查员 model: my-gateway/deepseek-chat temperature: 0.2 permission: edit: deny --- 你是资深代码审查员。审查时按严重程度排序输出问题清单……

内置 agent 有build(默认)、plan(只读规划模式)、general、explore,以及隐藏的compaction/title/summary(分别负责上下文压缩、生成标题、生成摘要)。配置文件里的同名 agent 会与内置定义合并覆盖。

五、Skill:技能

自动发现的目录

Skill 以SKILL.md文件的形式存在,从以下位置自动扫描(按顺序):

1. 外部 agent 目录:~/.claude/skills/**/SKILL.md、~/.agents/skills/**/SKILL.md,以及项目内向上发现的.claude/、.agents/目录(OPENCODE_DISABLE_EXTERNAL_SKILLS=1可关闭)
2. 每个配置目录下的skill/**/SKILL.md或skills/**/SKILL.md(即~/.config/opencode/skill/...和.opencode/skill/...)
3. skills.paths指定的额外目录(~会被展开,相对路径按项目 cwd 解析)
4. skills.urls指定的远程技能索引

SKILL.md 格式

--- name: api-review # 必填,技能名(同名时后加载的覆盖) description: 审查 REST API 设计是否合理 # 可选,决定模型何时选用 --- 正文是技能的实际内容,当模型调用 skill 工具时完整注入。

技能列表会以<available_skills>形式注入系统提示词,模型按需通过 skill 工具加载完整内容(含同目录下最多 10 个支持文件)。远程技能通过skills.urls配置:opencode会拉取<url>/index.json(格式{ "skills": [{ "name", "version", "files" }] })并缓存到~/.cache/opencode/skills。

六、Plugin:插件

配置字段

{ "plugin": [ "@my-org/opencode-plugin", // 包名 ["@my-org/another-plugin", { "apiUrl": "..." }] // 带 options ] }

两种加载方式

1. 本地文件插件:在每个配置目录下放plugin/*.{ts,js}或plugins/*.{ts,js}(仅顶层,不递归)——即~/.config/opencode/plugin/my-plugin.ts或项目.opencode/plugin/*.ts,路径相对于声明它的配置文件解析。
2. npm 插件:首次使用时安装到~/.cache/opencode/packages/<包名>。包结构要求:package.json的main或exports["./server"]作为入口,可选engines.opencode声明兼容版本。没有plugin.json 清单文件,manifest 就是 package.json。

插件能做什么

插件以 hooks 形式接入运行时,能力包括:注入自定义工具(tool)、定义凭证登录流程(auth)、注册 provider 与模型(provider)、拦截聊天消息与系统提示词(chat.message、experimental.chat.system.transform)、拦截工具执行(tool.execute.before/after)、注入 shell 环境变量(shell.env)、权限询问回调(permission.ask)、命令执行前钩子(command.execute.before)等。OPENCODE_DISABLE_DEFAULT_PLUGINS=1可禁用内置插件。

七、Command:斜杠命令

配置字段

{ "command": { "review": { "template": "审查当前分支相对 main 的改动,$1", "description": "审查改动,可指定目录", "agent": "reviewer", // 指定 agent "model": "...", // 或直接指定模型 "subtask": true // 作为子任务运行 } } }

Markdown 文件方式

每个配置目录下command/**/*.md或commands/**/*.md(递归)自动注册:文件名即命令名,commands/mr/review.md→/mr/review。frontmatter 同上,正文是模板。

模板语法

无占位符时,参数自动追加到模板末尾。此外内置/init、/review,MCP 服务器的 prompt 和 skill 也会注册为命令。

八、自定义工具与 MCP

自定义工具

注意:没有config.tool定义字段——tools字段只是内置工具的开关 map。真正的自定义工具有两个来源:

1. 本地文件:每个配置目录下tool/*.{js,ts}或tools/*.{js,ts},导出{ args, description, execute }的对象即注册为工具:

// .opencode/tool/random-uuid.tsimport{z}from"zod"exportconstRandomUuid={description:"生成一个随机 UUID",args:z.object({}).strict(),asyncexecute(){returncrypto.randomUUID()},}

2. 插件toolhook:Zod schema 会被自动转换成 JSON Schema。

MCP 服务器

{ "mcp": { "local-server": { "type": "local", "command": ["npx", "-y", "@some/mcp-server"], "environment": { "TOKEN": "..." }, // 传给子进程的环境变量 "enabled": true, "timeout": 30000 }, "remote-server": { "type": "remote", "url": "https://example.com/mcp", "headers": { "Authorization": "Bearer ..." }, "oauth": false // 远程 OAuth 配置或直接关闭 }, "disabled-one": { "enabled": false } // 快捷禁用写法 } }

MCP 服务器的工具指令会以<mcp_instructions>块注入系统提示词。

九、环境变量速查

十、完整示例

// opencode.jsonc { "$schema": "https://opencode.ai/config.json", // 模型 "model": "my-gateway/deepseek-chat", "small_model": "my-gateway/deepseek-chat", "provider": { "my-gateway": { "name": "自建网关", "npm": "@ai-sdk/openai-compatible", "env": ["MY_GATEWAY_API_KEY"], "options": { "baseURL": "https://gateway.example.com/v1" }, "models": { "deepseek-chat": { "name": "DeepSeek V3", "tool_call": true } } } }, // agent(也可拆到 .opencode/agent/reviewer.md) "agent": { "reviewer": { "description": "严格的代码审查员", "prompt": "你是资深代码审查员,重点关注 bug、性能与安全,按严重程度排序输出。", "temperature": 0.2, "permission": { "edit": "deny", "bash": "ask" } } }, "default_agent": "build", // 技能与指令 "skills": { "paths": ["./team-skills"] }, "instructions": ["./docs/coding-standards.md"], // 插件 "plugin": [["@my-org/opencode-plugin", { "apiUrl": "https://internal.example.com" }]], // 命令 "command": { "review": { "template": "审查当前分支相对 main 的改动,重点看 $1", "description": "审查分支改动", "agent": "reviewer" } }, // MCP "mcp": { "github": { "type": "remote", "url": "https://api.githubcopilot.com/mcp/", "enabled": true } }, // 权限(未列出的动作默认 ask) "permission": { "edit": "allow", "bash": "ask", "webfetch": "allow" }, // 压缩策略 "compaction": { "auto": true, "prune": false } }

附录:内部实现原理

给想深挖源码的读者。仓库里并存两代配置体系:

• V1(现行运行时,packages/opencode/src/config/config.ts):把所有来源深度合并成单个配置对象,CLI/TUI 会话直接消费。
• V2(新内核,packages/core/src/config.ts):返回有序的配置文档流(Entry[],global → 项目文件 →.opencode),各子系统通过插件按域消费;冲突解析用latest()(取最后一个定义该字段的文档)。V2 配置在每个 location 启动时读取一次,location 服务树有 60 分钟空闲 TTL,重开目录即重读。

V1 → V2 自动迁移(packages/core/src/v1/config/migrate.ts):旧格式会被自动转成 V2 形状,例如snapshot→snapshots、permission+tools→permissions、agent.prompt→agent.system、plugin元组→对象、mcp[].enabled→disabled、compaction.preserve_recent_tokens→keep.tokens等。

各资源的运行时加载点:

磁盘位置小结(Linux 为例,跨平台由 XDG 规则决定):

• 配置:~/.config/opencode
• 数据(auth.json、日志等):~/.local/share/opencode
• 缓存(models.json、npm 包、远程 skill):~/.cache/opencode

配置变量替换:配置文本在解析前会做${VAR}与${file:path}展开(packages/opencode/src/config/variable.ts),所以配置文件里可以引用环境变量或文件内容。