OpenCode 配置与 Skill 安装完全教程

OpenCode 是一个开源的终端 AI 编程助手，所有配置都通过 JSON 文件完成，扩展能力靠 Skill、Agent、Plugin、MCP Server 四大机制。本文讲清楚配置文件放哪、怎么配，以及 Skill 怎么装、怎么写。

一、配置文件放哪里

OpenCode 的配置按作用域分层，项目配置会覆盖全局配置：

注意：全局配置在 ~/.config/opencode/，不是 ~/.opencode/，这是常见误区。

强烈建议每个 opencode.json 都声明 schema，这样编辑器能实时提示和校验：

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

OpenCode 对自己的配置校验很严格，字段写错会直接拒绝启动，所以配 schema 很重要。

二、核心配置项速览

一个典型的 opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-6",
  "small_model": "anthropic/claude-haiku",
  "shell": "/bin/zsh",
  "logLevel": "INFO",

  "mcp": {
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp"],
      "enabled": true,
      "environment": { "BROWSER": "chromium" }
    },
    "github": {
      "type": "remote",
      "url": "https://...",
      "enabled": true,
      "headers": { "Authorization": "Bearer {env:GITHUB_TOKEN}" }
    }
  },

  "provider": {
    "anthropic": { "options": { "apiKey": "..." } }
  },

  "permission": {
    "edit": "ask",
    "bash": { "git *": "allow", "*": "ask" }
  }
}

关键点：

• model 必须带 provider 前缀，格式 provider/model-id。
• mcp[name].command 是字符串数组，不能写成单个字符串；type 必填。
• permission 可以是字符串动作（allow/ask/deny），也可以是按工具名匹配的规则对象。

三、Skill 是什么

Skill 是 OpenCode 的「专项技能包」——给 AI 注入针对特定任务的详细工作流和资源。当你描述的任务命中某个 Skill 的触发条件时，OpenCode 会加载它，让 AI 按 Skill 里的规范执行。

四、Skill 放哪里

Skill 是一个文件夹，里面必须有一个名为 SKILL.md 的文件：

OpenCode 会递归扫描 skill 目录，找所有 **/SKILL.md。

五、Skill 怎么写

一个 Skill 的最小结构——目录名、frontmatter 里的 name、正文：

.opencode/skills/my-skill/SKILL.md

---
name: my-skill
description: 用一句话说明这个 Skill 做什么、什么时候触发。把用户可能说的关键词前置。
---

# My Skill

（Skill 正文：指令、示例、参考，markdown 格式）

几个容易忽略的规则：

• name 必填，小写连字符分隔，最长 64 字符，要和文件夹名一致。
• description 实际上也必填——没写 description 的 Skill 会被过滤掉，永远不会被加载。
• description 用第三人称写，既说明「做什么」也说明「何时触发」，并在开头就放上具体触发关键词（文件名、术语等）。

六、从非默认位置注册 Skill

除了上面几个默认目录，还能通过配置注册额外的 skill 路径或远程 URL：

{
  "skills": {
    "paths": [".opencode/skills", "/abs/path/to/skills"],
    "urls": ["https://example.com/.well-known/skills/"]
  }
}

注意 skills 是对象（含 paths / urls），不是数组。

七、配置改动如何生效

配置只在 OpenCode 启动时加载一次，不会热更新。改完 opencode.json、agent、skill、plugin 等，都需要退出并重启 OpenCode 才生效。

八、配置坏了救急

如果配置写错导致 OpenCode 起不来，有几个环境变量救急：

• OPENCODE_DISABLE_PROJECT_CONFIG=1：跳过项目配置，从全局启动。
• OPENCODE_CONFIG=/path/to/file.json：加载额外的显式配置。
• OPENCODE_CONFIG_CONTENT='{...}'：注入内联 JSON 作为最后合并层。
• OPENCODE_PURE=1：跳过所有外部插件。

先用第一个变量启动，进去改好配置文件，再正常重启即可。

九、小结

1. 配置文件在 ~/.config/opencode/（全局）或项目根的 opencode.json。
2. 配 $schema，写错会拒绝启动，别硬猜字段形状。
3. Skill = 一个含 SKILL.md 的文件夹，name 和 description 是命脉。
4. 配置不热更新，改完记得重启。
5. 配坏了用 OPENCODE_DISABLE_PROJECT_CONFIG 兜底。

掌握了这些，就能用 OpenCode 的 Skill / Agent / Plugin / MCP 体系把 AI 编程助手调教成趁手的工具。有疑问欢迎交流。