OpenCode 指南

opencode 是一个开源的 AI 代码助手/代理（Open Source AI Coding Agent）。

我的 opencode 配置

我的配置收藏于下面仓库，供参考：

• dotbox - 个人常用、可公开分享的配置文件归档。

opencode 配置通常位于 ~/.config/opencode，可以通过配置自定义模型、技能路径、MCP 工具等。

下面针对常用配置项进行说明。

自定义模型

编辑 ~/.config/opencode/opencode.jsonc 文件来实现自定义模型和一些配置：

{

  "$schema": "https://opencode.ai/config.json",
  // 默认主模型。字段名必须是 `model`（单数），不是 `models`。
  // 实际可用模型以 opencode 内的 `/models` 列表为准。
  "model": "openai/gpt-5.5",

  // 轻量模型：用于标题生成、摘要等低价值辅助任务，避免占用主 Codex 模型额度。
  "small_model": "opencode/big-pickle",

  // 长会话省 token：自动压缩上下文，并丢弃旧工具输出。
  // tail_turns=2 保留最近两轮完整上下文，兼顾省 token 和连续性。
  "compaction": {
    "auto": true,
    "prune": true,
    "reserved": 10000,
    "tail_turns": 2,
  }
}

MCP 工具

轻量：

• Context7 MCP：获取最新文档，减少代码幻觉
• GitHub MCP：让 AI 处理仓库、PR 和代码分析
• FileSystem MCP：让 AI 读取并处理本地文件
• Browser automation CLI for AI agents. Fast native Rust CLI.

较重：

• Playwright MCP：让 AI 操作浏览器，做自动化验证
• Memory MCP：让 AI 记住长期上下文
• Docker MCP：让 AI 管理本地 Docker 容器

特定：

• Grafana MCP：让 AI 查询监控并生成报表

Context7 需要 API Key，可免费申请，示例：gQAAAAAAAZ65AAIgcDI5ZjIyY2Y4YzJiNjI0MDU4YmQyYWZmZTg4ZTVmZjkwNg

以上 mcp 工具可直接告诉 opencode 安装，会自行进行配置安装，无需额外操作。

Skill

轻量：

• 给 AI 编码助手添加工程化技能，让它按规范完成需求、开发、测试、审查和发布流程
• 受 Karpathy 启发的 Claude Code 指南
• Agent Skills used by the Sentry team for development.

较重：

• Spec-driven development (SDD) for AI coding assistants.
• An agentic skills framework & software development methodology that works.

这些 skill 仓库可以根据需要克隆到本地，并在配置文件中通过 skills.paths 指定其路径，我通常习惯克隆到配置目录下，并在 opencode.jsonc 中进行配置：

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

  // ....
  
  // 额外技能目录：扫描其中的 **/SKILL.md，上面的 skill 根据需要克隆，然后在此处指明其 skill 目录即可。
  "skills": {
    "paths": ["/root/.config/opencode/skills"],
  },
}

AGENTS.md

AGENTS.md 文件分项目级和全局级，用于定义不同代理的配置和行为。项目级 AGENTS.md 通常位于项目根目录，而全局级 AGENTS.md 位于 ~/.config/opencode/ 下。

项目级 AGENTS.md 优先级高于全局级 AGENTS.md，当项目中存在 AGENTS.md 时，全局配置会被覆盖。

我通常会在全局级 AGENTS.md 中定义一些默认代理配置，以便在全局范围去统一不同的项目风格和开发配置，具体可参考仓库内 AGENTS.md 的配置。

agents/

agents/ 目录用于存放不同代理的配置文件，每个代理一个文件，文件名通常与代理名对应。这样可以将代理的配置与 AGENTS.md 分离，便于管理和维护。

我通常会定义 ops 和 coding 代理用于区分运维相关任务和编码相关任务。

例如：

/root/.config/opencode/agents/
├── ops.md
└── coding.md