OpenCode 配置、规则与自定义命令实战教程

📚 分类: OpenCode 教程 ⏱️ 预计耗时: 30 分钟 🎯 难度: 入门 🔧 环境要求: 已安装并运行过 OpenCode（参考本系列教程第 02 篇） 🌐 原文来源: OpenCode 官方文档

你将学到什么

完成本教程后，你将能够：

[ ] 清晰区分 OpenCode 中 Config、Rules 和 Commands 的核心职责
[ ] 配置 opencode.json 文件，管理模型、权限等运行策略
[ ] 编写 AGENTS.md 文件，为 AI 助手设定项目级行为规范
[ ] 创建一个自定义命令 (Command)，将重复性任务封装成一条斜杠指令
[ ] 应用“逐步沉淀”原则，避免一次性将配置写死，实现经验的持续积累

最终效果

你将拥有一个配置合理的 OpenCode 工作区。在这个工作区里：

AI 助手（Agent）知道项目的技术栈和编码规范，不会随意修改关键文件。
你可以通过输入 /review-diff 这样的命令，一键让 AI 审查代码差异。
你的配置、规则和命令各司其职，不会互相干扰。

前置准备

在开始前，请确认你的环境满足以下条件：

检查项	要求版本	验证命令
OpenCode	最新稳定版	`opencode --version`

1. 创建一个测试项目

为了安全地练习，我们创建一个全新的项目目录。

bash

# 创建并进入测试项目
$ mkdir opencode-practice && cd opencode-practice

# 初始化一个 Git 仓库（OpenCode 推荐在有 Git 的项目中使用）
$ git init

✅ 验证：执行后，你应该在 opencode-practice 目录下，并且该目录下有一个隐藏的 .git 文件夹。

第 1 步：理解三者的职责分工

🎯 目标：清晰区分 Config、Rules、Commands 各自解决什么问题，避免混淆。

在动手之前，我们先明确这三个核心概念的分工。这是构建高效工作流的基础。

概念	解决的问题	类比
Config (配置)	机器怎么运行？它定义了 OpenCode 的全局或项目级行为，比如使用哪个 AI 模型、文件读写权限、编辑器样式等。	汽车的仪表盘和引擎设置。
Rules (规则)	Agent 在这个项目里怎么做事？它告诉 AI 助手应该遵守哪些项目约定，比如“必须使用 pnpm 安装依赖”、“不要修改 `config/` 目录下的文件”。	公司的员工手册。
Commands (命令)	重复任务怎么一键触发？它将一个复杂的、重复性的任务（如“审查代码差异”）封装成一个简单的斜杠命令（如 `/review-diff`）。	办公室里的快捷按钮。

🤔 为什么要这样做？ 很多新手会把所有东西都塞进一个超长的 AGENTS.md 文件里。这会让 AI 模型抓不住重点，就像一个员工手册里混入了汽车保养说明书和公司打印机使用指南一样混乱。清晰的职责划分能让每一部分都更有效。

第 2 步：配置 `opencode.json` —— 设定运行策略

🎯 目标：创建一个项目级的 opencode.json 文件，配置模型、权限和引用外部规则。

📝 操作：

在项目根目录下创建 opencode.json 文件，并写入以下内容。

jsonc

// opencode.json
{
  "$schema": "https://opencode.ai/config.json", // 提供代码补全和校验
  // 配置默认模型（请根据官方推荐选择稳定模型）
  "model": "anthropic/claude-sonnet-4-5",
  // 配置小模型用于简单任务
  "small_model": "anthropic/claude-haiku-4-5",
  // 配置权限：精细控制 Agent 的行为
  "permission": {
    "*": "ask",          // 默认所有操作都询问
    "read": "allow",     // 读取文件自动允许
    "edit": "ask",       // 编辑文件需要询问
    "bash": {
      "*": "ask",        // 默认所有终端命令都询问
      "git status*": "allow", // git status 命令自动允许
      "git diff*": "allow",   // git diff 命令自动允许
      "rm *": "deny",         // 禁止删除文件
      "git push*": "deny"     // 禁止推送代码
    }
  },
  // 分享策略：手动确认后才分享上下文
  "share": "manual",
  // 引用外部规则文件，无需复制内容
  "instructions": [
    "CONTRIBUTING.md",
    "docs/development.md"
  ]
}

✅ 验证：

在终端输入 opencode 启动 OpenCode。
输入 /settings 或查看 TUI 界面，确认模型和权限设置已被加载。
尝试让 AI 读取一个文件，它应该不会询问你。尝试让 AI 运行 git push，它应该会拒绝执行。

⚠️ 常见错误：

❌ 把 API Key 写进配置文件：这是非常危险的做法！OpenCode 有更安全的认证方式（如 /connect 命令）。配置文件只应包含模型名称、权限等策略。
❌ 模型号写死：AI 模型更新很快。团队配置里写一个当前稳定可用的模型即可，并在项目文档里注明如何查看官方最新的模型列表。

第 3 步：编写 `AGENTS.md` —— 制定项目规则

🎯 目标：创建一个 AGENTS.md 文件，告诉 AI 助手本项目的基本约定。

📝 操作：

在项目根目录下创建 AGENTS.md 文件。

markdown

# AGENTS.md - 项目 AI 助手规则

## 技术栈
- 前端: React 18, TypeScript
- 后端: Node.js, Express
- 包管理器: pnpm
- 测试框架: Vitest

## 项目约定
1.  **包管理器**：所有依赖操作必须使用 `pnpm`，禁止使用 `npm` 或 `yarn`。
2.  **代码风格**：遵循项目现有的 ESLint 和 Prettier 配置。
3.  **文件修改**：修改 `src/` 目录下的文件前，必须先阅读 `src/README.md`。
4.  **禁止修改**：未经明确授权，禁止修改 `config/` 和 `deploy/` 目录下的任何文件。
5.  **测试**：为所有新增的功能编写单元测试，测试文件放在 `__tests__` 目录下。

## 命令
- 运行测试: `pnpm test`
- 构建项目: `pnpm build`
- 启动开发服务器: `pnpm dev`

🤔 为什么要这样做？AGENTS.md 是 Agent 的“项目说明书”。它把你在对话中反复强调的约定（如“用 pnpm”、“不要改 config 目录”）固化下来。这样，每次开启新会话，AI 助手都会自动读取并遵守这些规则，无需你重复说明。

✅ 验证：

在 OpenCode 会话中输入 /init 命令，OpenCode 会自动读取并更新 AGENTS.md。
尝试让 AI 运行 npm install，它应该会因为规则中指定了 pnpm 而拒绝执行，或先询问你。

💡 提示：AGENTS.md 只存放未来 10 次任务都应该遵守的稳定约束。一次性的任务目标（如“帮我修复这个 bug”）不要写在这里，以免污染长期规则。

第 4 步：创建自定义命令 —— 固化重复流程

🎯 目标：创建一个 .opencode/commands/review-diff.md 文件，将“审查代码差异”这个重复性任务封装成 /review-diff 命令。

📝 操作：

创建命令目录：
bash
```
$ mkdir -p .opencode/commands
```

创建命令文件 .opencode/commands/review-diff.md：

markdown

---
description: Review current git diff for bugs and regressions
agent: build
---

请审查当前 git 差异，并执行以下操作：

1.  **分析改动**：理解每处改动的目的。
2.  **审查问题**：找出潜在的 bug、回归问题或不符合项目规范的地方。
3.  **输出排序**：按严重程度（阻断性 > 主要 > 次要）输出发现的问题。
4.  **总结**：如果没有发现阻断性问题，请明确说明“没有发现阻断问题”。

✅ 验证：

在项目中进行一些代码修改（例如，创建一个新文件并写入一些内容）。
在 OpenCode 会话中输入 /review-diff。
AI 助手应该会执行 git diff 命令，获取改动内容，然后按照你在命令文件中设定的流程进行审查并输出结果。

🤔 为什么要这样做？ 当一个提示词（Prompt）你反复使用三次以上，就应该把它做成命令。这不是为了少打几个字，而是为了固定任务边界、检查顺序和输出格式。这样可以确保每次执行的结果都符合你的预期，质量稳定。

⚠️ 常见错误：

❌ 在命令中使用危险 Shell 命令：命令文件中可以使用 ! 来执行命令并注入输出。但请确保这些命令是只读的（如 git diff），绝不要在里面写 rm -rf、DROP DATABASE 等危险操作。
❌ 一个命令做太多事：一个命令只做一类任务。如果命令的 Prompt 写成了“万能 Prompt”，那么每次执行结果仍然会发散。

进阶技巧（可选）

命令参数：在命令 Prompt 中使用 $ARGUMENTS 或 $1、$2 等占位符，让命令更灵活。
markdown
```
---
description: Explain one module
---
请解释 `$ARGUMENTS` 这个模块的职责、核心逻辑和潜在风险。
```
运行：/explain src/auth

注入 Shell 输出：在 Prompt 中使用 ! 执行命令并注入结果。

markdown

当前改动如下：
! `git diff --stat`
! `git diff`
请只做审查，不要修改文件。

使用 subtask：对于需要大量读取文件或长时间运行的任务，可以在 frontmatter 中设置 subtask: true。这会让该命令在一个独立的子会话中运行，不会污染你当前的主对话上下文。

常见问题 (FAQ)

Q1: AGENTS.md 和 CLAUDE.md 是什么关系？A: OpenCode 优先读取 AGENTS.md。如果找不到，会兼容读取 CLAUDE.md（Claude Code 的规则文件）。如果你从 Claude Code 迁移过来，可以保留 CLAUDE.md 作为备选，但建议将核心规则统一到 AGENTS.md 中，避免维护两份重复文档。

Q2: 如何引用其他项目的规则文件？A: 在 opencode.json 的 instructions 数组中，可以引用本地文件（如 "CONTRIBUTING.md"），也可以引用远程 URL（如 "https://raw.githubusercontent.com/.../style.md"）。远程 URL 有 5 秒超时限制，如果拉取失败，当次会话将缺失该规则。

Q3: 我该从哪里开始沉淀？A: 遵循“逐步沉淀”原则：

先用普通提示词。
同一提醒出现 3 次 → 写入 AGENTS.md。
同一流程出现 3 次 → 封装成 .opencode/commands/*.md。
需要不同角色和权限 → 创建 Agents。
需要跨项目复用 → 创建 Skills。
需要运行时扩展 → 创建 Plugins。

总结

恭喜你完成了本教程！🎉

回顾一下我们今天学到的核心内容：

职责分工：Config 管机器运行，Rules 管项目约定，Commands 管重复流程。
配置文件：通过 opencode.json 管理模型、权限和外部规则引用，避免硬编码敏感信息。
项目规则：通过 AGENTS.md 将项目约定固化，让 AI 助手每次都能自动遵守。
自定义命令：通过 .opencode/commands/*.md 将重复性任务封装成 /xxx 命令，提升效率和质量。
逐步沉淀：不要一次性配置满，而是让经验从对话中自然沉淀到更持久的配置层。

OpenCode 配置、规则与自定义命令实战教程 ​

你将学到什么 ​

最终效果 ​

前置准备 ​

1. 创建一个测试项目 ​

第 1 步：理解三者的职责分工 ​

第 2 步：配置 opencode.json —— 设定运行策略 ​

第 3 步：编写 AGENTS.md —— 制定项目规则 ​

第 4 步：创建自定义命令 —— 固化重复流程 ​

进阶技巧（可选） ​

常见问题 (FAQ) ​

总结 ​

OpenCode 配置、规则与自定义命令实战教程

你将学到什么

最终效果

前置准备

1. 创建一个测试项目

第 1 步：理解三者的职责分工

第 2 步：配置 `opencode.json` —— 设定运行策略

第 3 步：编写 `AGENTS.md` —— 制定项目规则

第 4 步：创建自定义命令 —— 固化重复流程

进阶技巧（可选）

常见问题 (FAQ)

总结