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

opencode 配置完全指南:配置文件、目录与字段详解一份面向 opencode 用户的配置指南:讲清楚配置写在哪里、每个字段是干什么的、provider / skill / plugin / command / 自定义工具各自从哪些目录被自动发现,以及合并优先级。文末附一章内部实现原理,供想深挖的读者参考。一、配置文件在哪里opencode 的配置不是单个文件,而是一组从多个位置自动发现并按优先级合并的 JSON©文件。核心位置有三类:1. 全局配置目录Linux:~/.config/opencodemacOS:~/Library/Application Support/opencodeWindows:遵循 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 的配置优先级越高(后者覆盖前者):顺序来源说明1远端 well-known 配置{url}/.well-known/opencode(企业/远端管理场景)2全局文件~/.config/opencode下的 config.json → opencode.json → opencode.jsonc3OPENCODE_CONFIG环境变量指定一个配置文件路径4项目级文件cwd 向上到 worktree 根的 opencode.json/jsonc5.opencode目录各层.opencode里的配置文件 markdown 资源6OPENCODE_CONFIG_CONTENT内联 JSON 字符串7组织/受管配置控制台组织配置、macOS MDM 受管配置合并是深度合并:标量以后者为准,数组(如instructions、plugin)会拼接去重。设置OPENCODE_DISABLE_PROJECT_CONFIG1可以整体跳过项目级配置和 AGENTS.md。小提示:TUI 界面主题、快捷键等已从主配置剥离,改由tui.json/tui.jsonc管理(同样支持全局 项目级,变量OPENCODE_TUI_CONFIG)。二、配置字段总览以下是 opencode.json 的主要顶层字段(按源码中的配置 schema 整理):字段用途model默认模型,格式provider-id/model-idsmall_model标题生成、摘要等轻量任务的模型default_agent默认主 agent(如build、plan)agent自定义 agent(也支持 markdown 文件,见第四章)provider自定义模型提供方与模型覆盖(见第三章)disabled_providers/enabled_providers禁用/白名单提供方permission工具权限规则(allow / ask / deny)mcpMCP 服务器配置(见第九章)plugin插件列表(见第六章)command斜杠命令(见第七章)skills技能目录与远程技能(见第五章)instructions额外的环境指令文件路径或 URL(注入系统提示词)references项目引用目录(可被模型按需访问的额外路径)formatter代码格式化器配置lspLSP 服务器配置compaction上下文压缩策略(auto、prune、token 预算)tool_output工具输出截断限制(max_lines / max_bytes)shell默认 shellsnapshot是否启用改动快照(可撤销)watcher文件监视忽略规则share会话分享策略(manual / auto / disabled)autoupdate自动更新(true / false / “notify”)enterprise企业版配置experimental实验特性(如policies策略规则)三、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 按以下顺序取第一个可用的:配置里的options.apiKeyprovider.env声明的环境变量(如MY_GATEWAY_API_KEY)opencode auth login写入的auth.json(位于数据目录,如 Linux~/.local/share/opencode/auth.json)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: primaryfrontmatter 写字段,正文就是系统提示词:--- 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文件的形式存在,从以下位置自动扫描(按顺序):外部 agent 目录:~/.claude/skills/**/SKILL.md、~/.agents/skills/**/SKILL.md,以及项目内向上发现的.claude/、.agents/目录(OPENCODE_DISABLE_EXTERNAL_SKILLS1可关闭)每个配置目录下的skill/**/SKILL.md或skills/**/SKILL.md(即~/.config/opencode/skill/...和.opencode/skill/...)skills.paths指定的额外目录(~会被展开,相对路径按项目 cwd 解析)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 ] }两种加载方式本地文件插件:在每个配置目录下放plugin/*.{ts,js}或plugins/*.{ts,js}(仅顶层,不递归)——即~/.config/opencode/plugin/my-plugin.ts或项目.opencode/plugin/*.ts,路径相对于声明它的配置文件解析。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_PLUGINS1可禁用内置插件。七、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 同上,正文是模板。模板语法语法含义$1…$N位置参数(最后一个占位符吞掉所有剩余参数)$ARGUMENTS完整原始参数串!cmd内联 shell:执行命令并用输出替换file引用文件内容作为输入无占位符时,参数自动追加到模板末尾。此外内置/init、/review,MCP 服务器的 prompt 和 skill 也会注册为命令。八、自定义工具与 MCP自定义工具注意:没有config.tool定义字段——tools字段只是内置工具的开关 map。真正的自定义工具有两个来源:本地文件:每个配置目录下tool/*.{js,ts}或tools/*.{js,ts},导出{ args, description, execute }的对象即注册为工具:// .opencode/tool/random-uuid.tsimport{z}fromzodexportconstRandomUuid{description:生成一个随机 UUID,args:z.object({}).strict(),asyncexecute(){returncrypto.randomUUID()},}插件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_CONFIG_DIR覆盖全局配置目录OPENCODE_CONFIG指定配置文件路径OPENCODE_CONFIG_CONTENT内联 JSON 配置OPENCODE_DISABLE_PROJECT_CONFIG跳过项目级配置与 AGENTS.mdOPENCODE_PERMISSION追加权限规则(JSON)OPENCODE_DISABLE_EXTERNAL_SKILLS禁用外部技能目录OPENCODE_DISABLE_DEFAULT_PLUGINS禁用内置插件OPENCODE_MODELS_URL覆盖模型目录源OPENCODE_DISABLE_AUTOCOMPACT/OPENCODE_DISABLE_PRUNE关闭自动压缩/裁剪各 provider 的env字段凭证环境变量(如OPENAI_API_KEY)十、完整示例// 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、permissiontools→permissions、agent.prompt→agent.system、plugin元组→对象、mcp[].enabled→disabled、compaction.preserve_recent_tokens→keep.tokens等。各资源的运行时加载点:资源主要源码配置合并packages/opencode/src/config/config.ts、config/paths.tsProvider 实例化packages/opencode/src/provider/provider.ts(resolveSDK、内置 provider 注册表)模型目录packages/core/src/models-dev.ts(models.dev 拉取与缓存)Skill 发现packages/opencode/src/skill/index.ts(discoverSkills目录清单)Plugin 解析packages/opencode/src/plugin/shared.ts、plugin/loader.tsCommand 发现packages/opencode/src/config/command.ts;模板替换在session/prompt.ts自定义工具packages/opencode/src/tool/registry.ts({tool,tools}/*.ts扫描)凭证存储packages/opencode/src/auth/index.ts(auth.json)磁盘位置小结(Linux 为例,跨平台由 XDG 规则决定):配置:~/.config/opencode数据(auth.json、日志等):~/.local/share/opencode缓存(models.json、npm 包、远程 skill):~/.cache/opencode配置变量替换:配置文本在解析前会做${VAR}与${file:path}展开(packages/opencode/src/config/variable.ts),所以配置文件里可以引用环境变量或文件内容。