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 的配置优先级越高(后者覆盖前者):

顺序	来源	说明
1	远端 well-known 配置	`{url}/.well-known/opencode`(企业/远端管理场景)
2	全局文件	`~/.config/opencode` 下的 config.json → opencode.json → opencode.jsonc
3	`OPENCODE_CONFIG` 环境变量	指定一个配置文件路径
4	项目级文件	cwd 向上到 worktree 根的 opencode.json/jsonc
5	`.opencode` 目录	各层 `.opencode` 里的配置文件 + markdown 资源
6	`OPENCODE_CONFIG_CONTENT`	内联 JSON 字符串
7	组织/受管配置	控制台组织配置、macOS MDM 受管配置

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

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

二、配置字段总览

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

字段	用途
`model`	默认模型,格式 `provider-id/model-id`
`small_model`	标题生成、摘要等轻量任务的模型
`default_agent`	默认主 agent(如 `build`、`plan`)
`agent`	自定义 agent(也支持 markdown 文件,见第四章)
`provider`	自定义模型提供方与模型覆盖(见第三章)
`disabled_providers` / `enabled_providers`	禁用/白名单提供方
`permission`	工具权限规则(allow / ask / deny)
`mcp`	MCP 服务器配置(见第九章)
`plugin`	插件列表(见第六章)
`command`	斜杠命令(见第七章)
`skills`	技能目录与远程技能(见第五章)
`instructions`	额外的环境指令文件路径或 URL(注入系统提示词)
`references`	项目引用目录(可被模型按需访问的额外路径)
`formatter`	代码格式化器配置
`lsp`	LSP 服务器配置
`compaction`	上下文压缩策略(auto、prune、token 预算)
`tool_output`	工具输出截断限制(max_lines / max_bytes)
`shell`	默认 shell
`snapshot`	是否启用改动快照(可撤销)
`watcher`	文件监视忽略规则
`share`	会话分享策略(manual / auto / disabled)
`autoupdate`	自动更新(true / false / "notify")
`enterprise`	企业版配置
`experimental`	实验特性(如 `policies` 策略规则)

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

配置字段

jsonc 复制代码

{
  "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.apiKey
provider.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:自定义智能体

方式一:配置字段

jsonc 复制代码

{
  "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 写字段,正文就是系统提示词:

markdown 复制代码

---
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_SKILLS=1 可关闭)
每个配置目录下的 skill/**/SKILL.md 或 skills/**/SKILL.md(即 ~/.config/opencode/skill/... 和 .opencode/skill/...)
skills.paths 指定的额外目录(~ 会被展开,相对路径按项目 cwd 解析)
skills.urls 指定的远程技能索引

SKILL.md 格式

markdown 复制代码

---
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:插件

配置字段

jsonc 复制代码

{
  "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_PLUGINS=1 可禁用内置插件。

七、Command:斜杠命令

配置字段

jsonc 复制代码

{
  "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 } 的对象即注册为工具:

ts 复制代码

// .opencode/tool/random-uuid.ts
import { z } from "zod"

export const RandomUuid = {
  description: "生成一个随机 UUID",
  args: z.object({}).strict(),
  async execute() {
    return crypto.randomUUID()
  },
}

插件 tool hook:Zod schema 会被自动转换成 JSON Schema。

MCP 服务器

jsonc 复制代码

{
  "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.md
`OPENCODE_PERMISSION`	追加权限规则(JSON)
`OPENCODE_DISABLE_EXTERNAL_SKILLS`	禁用外部技能目录
`OPENCODE_DISABLE_DEFAULT_PLUGINS`	禁用内置插件
`OPENCODE_MODELS_URL`	覆盖模型目录源
`OPENCODE_DISABLE_AUTOCOMPACT` / `OPENCODE_DISABLE_PRUNE`	关闭自动压缩/裁剪
各 provider 的 `env` 字段	凭证环境变量(如 `OPENAI_API_KEY`)

十、完整示例

jsonc 复制代码

// 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 等。

各资源的运行时加载点:

资源	主要源码
配置合并	`packages/opencode/src/config/config.ts`、`config/paths.ts`
Provider 实例化	`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.ts`
Command 发现	`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),所以配置文件里可以引用环境变量或文件内容。