---
name: opencode-config
description: 配置 opencode 自身 (agents / skills / MCP servers / custom tools / 内置工具权限) 的工作流与速查。基于 opencode 官方中文文档 (agents、skills、mcp-servers、custom-tools、tools 五篇)。Use ONLY when 用户要创建/修改 opencode.json、子代理文件、SKILL.md、MCP server 配置、.opencode/tools/ 自定义工具、或调整工具权限策略;不用于改业务代码或运行应用。
license: MIT
compatibility: opencode
metadata:
  audience: opencode maintainers
  scope: opencode-self-config
  source: https://opencode.ai/docs/zh-cn/
---

# opencode-config

opencode 自身配置的**导航 + 摘要** skill。详细字段/示例/边界场景放 `references/`,按需加载,避免主文件膨胀。

## 何时加载我

- 用户说"加个子代理 / 改 opencode.json / 配置 MCP / 写个自定义工具 / 调权限"
- 用户要求排查"skill 没显示 / MCP 连不上 / 自定义工具不生效"
- 用户给 opencode 官方文档链接,要求落地

> 反向场景 (不要加载): 改 RuoYi 业务、跑 `mvn install`、查 MySQL、调小程序 — 这些走 `ruoyi-cs-platform` / `dba` 子代理。

## 文件位置约定 (本仓库)

| 类别 | 路径 | 备注 |
|---|---|---|
| 主配置 | `opencode.json` 或 `opencode.jsonc` | 必须含 `"$schema": "https://opencode.ai/config.json"` |
| 子代理 (文件) | `.opencode/agent/<name>.md` 或 `.opencode/agents/<name>.md` | 文件名即 agent 名 |
| 技能 | `.opencode/skill/<name>/SKILL.md` | frontmatter `name` 与目录名一致 |
| 技能 (外部) | `.agents/skills/<name>/SKILL.md` | 兼容 Claude 风格 |
| MCP | 写在 `opencode.json` 的 `mcp.<server>` | 不用单独文件 |
| 自定义工具 | `.opencode/tools/<name>.ts` | 文件名即工具名,`@opencode-ai/plugin` 的 `tool()` |
| 插件 | `.opencode/plugin/*.ts` 或 `opencode.json` 的 `plugin` 数组 | TS 文件自动发现 |

> 配置**只读一次**,改完任何 opencode 配置文件都需告诉用户**退出并重启 opencode** 才生效。

## 5 篇官方文档 → 5 个子文件 (按需 `read` 加载)

| 子文件 | 对应官方页 | 涵盖内容 |
|---|---|---|
| `references/01-agents.md` | [agents](https://opencode.ai/docs/zh-cn/agents/) | 主/子代理、内置代理 (build/plan/general/explore/scout)、JSON vs Markdown 配置、description/temperature/steps/prompt/model/tools/permission/mode/hidden/task/color/top_p、文档/安全审计样例 |
| `references/02-skills.md` | [skills](https://opencode.ai/docs/zh-cn/skills/) | SKILL.md frontmatter (`name`/`description` 必填)、name 正则 `^[a-z0-9]+(-[a-z0-9]+)*$`、description 1-1024 字符、发现路径、glob 通配符权限、agent 级 skill 权限覆盖、禁用 skill 工具、加载问题排查 |
| `references/03-mcp-servers.md` | [mcp-servers](https://opencode.ai/docs/zh-cn/mcp-servers/) | `mcp` 段结构、local (`type:"local"`, `command` 数组, `environment`) / remote (`type:"remote"`, `url`, `headers`) / OAuth (auto/preregister/manual)、`enabled: false` 临时禁用、按 agent 控制 MCP 工具 (`mymcp_*` glob)、Context7/Sentry/gh_grep 示例 |
| `references/04-custom-tools.md` | [custom-tools](https://opencode.ai/docs/zh-cn/custom-tools/) | `.opencode/tools/*.ts`、`tool()` 辅助函数 + Zod (`tool.schema`)、多导出命名 `<file>_<export>`、context (agent/sessionID/messageID/directory/worktree)、与内置工具同名时覆盖、Python 等非 TS 实现 |
| `references/05-tools.md` | [tools](https://opencode.ai/docs/zh-cn/tools/) | 12 个内置工具清单:bash/edit/write/read/grep/glob/lsp/patch/skill/todowrite/webfetch/websearch/question,以及 `permission` 字段 (`allow`/`ask`/`deny`)、glob 通配符、`.ignore` 文件覆盖 `.gitignore` |

> 加载方式: 用 `read` 工具读 `references/0X-xxx.md` 的完整内容。主文件只保留"我要做 X,先读哪个引用"的导航。

## 速查决策树

```
用户想…
├─ 加子代理 ──────────→ references/01-agents.md §"Markdown 形式"
│                         落地: .opencode/agent/<name>.md (frontmatter + prompt)
├─ 改 opencode.json ──→ 对应类别的 references/ + 校验 $schema
├─ 加 skill ──────────→ references/02-skills.md §"编写 frontmatter"
│                         落地: .opencode/skill/<name>/SKILL.md (主文件) + 视情况 references/ scripts/ templates/
├─ 加 MCP server ─────→ references/03-mcp-servers.md §"本地/远程/OAuth"
│                         落地: opencode.json 的 mcp.<name>
├─ 写自定义工具 ─────→ references/04-custom-tools.md §"结构/参数/上下文"
│                         落地: .opencode/tools/<name>.ts (import { tool } from "@opencode-ai/plugin")
├─ 调工具权限 ───────→ references/05-tools.md §"配置" + references/01 §"权限"
│                         落地: opencode.json 的 permission 段
└─ 排查加载问题 ─────→ references/02 §"排查加载问题" / references/03 §"OAuth 调试" / references/05 §"忽略模式"
```

## 硬约束 (违反 opencode 拒启 / 静默失败)

1. **JSON Schema**: `opencode.json` 顶部必须 `"$schema": "https://opencode.ai/config.json"`,未知顶层键 `ConfigInvalidError`。
2. **SKILL.md frontmatter**: `name` 必填 + 1-64 字符 + 小写连字符正则;`description` 必填 + 1-1024 字符。无 description 的 skill **从模型视野过滤掉**,不报错也不出现。
3. **MCP `command`** 是字符串数组,不是单个字符串;`type: local|remote` 必填。
4. **`mcp[name].disabled` 静默**: 想要临时关 → `enabled: false`;彻底删 → 从 `mcp` 段移除。
5. **Skill 权限拒绝后**: 代理在 `<available_skills>` 里**看不到**该 skill,会安静地以为不存在。
6. **MCP 工具 glob**: 禁用某 server 全部工具用 `"<server>_*": false`,因为工具注册时带 server 前缀。
7. **`todowrite` 默认对子代理禁用**: 要用就 `agent.<name>.tools.todowrite: true`。
8. **LSP 工具**: 需 `OPENCODE_EXPERIMENTAL_LSP_TOOL=true` (或 `OPENCODE_EXPERIMENTAL=true`)。
9. **websearch 工具**: 需 OpenCode 提供商,或 `OPENCODE_ENABLE_EXA=1|true`。
10. **配置热重载**: 不支持 — 改完**必须**告诉用户退出重启 opencode。

## 写配置的标准动作

1. **读对应 references/ 子文件** 拿到字段/示例/边界。
2. **校验字段** — 不确定就 `webfetch https://opencode.ai/config.json` 看 schema。
3. **保留用户原有字段** — 只动用户明确指出的部分,别顺手改 model/username/keys。
4. **加 `$schema`** — 帮编辑器即时校验。
5. **写完后** — 输出"修改清单 + 提醒用户退出重启 opencode"。

## 相关 skill (本仓库已存在)

- `ruoyi-cs-platform` — 业务入口 skill,改 RuoYi 代码前必读
- `customize-opencode` (内置) — opencode 自身配置速查,与本 skill 互补但**本 skill 更细、含子文件分页**
- `.qwen/skills/*` — 历史 Qwen 风格 skill,与 `.opencode/skill/*` 并存,迁移时按需搬运