OpenCode 自定义命令（Commands）完全指南：用斜杠命令打造你的专属 AI 编程工作流

OpenCode 自定义命令（Commands）完全指南：用斜杠命令打造你的专属 AI 编程工作流

在 OpenCode 的日常使用中，你可能会反复执行某些相似的任务：运行测试并分析失败原因、创建特定模式的新组件、审查最近的代码变更、或者按照固定流程部署项目。每次都要手动输入冗长的提示词，不仅效率低下，而且容易遗漏关键信息。

OpenCode 的自定义命令（Custom Commands）功能正是为解决这一问题而设计。它允许你将在 TUI 中频繁使用的提示词封装为可复用的斜杠命令，只需输入 /command-name 即可一键触发。本文将系统性地介绍自定义命令的配置、使用和高级技巧，帮助你打造真正属于自己的 AI 编程工作流。

什么是自定义命令

自定义命令是 OpenCode 提供的一种快捷方式机制。你可以在配置文件或独立的 Markdown 文件中定义一个带有元数据的提示词模板，然后在 TUI 中输入 / 加命令名来调用它。当命令执行时，OpenCode 会将模板内容（包括你传入的参数）发送给 LLM，就像你手动输入了那段提示词一样。

自定义命令的常见使用场景包括：

• 运行测试：一键运行测试套件并让 AI 分析失败原因
• 创建模板代码：快速生成符合团队规范的新组件或文件
• 代码审查：自动加载最近变更并让 AI 进行代码审查
• 项目初始化：为新模块创建标准化的目录结构和配置文件
• 部署流程：执行特定的构建和部署检查

配置自定义命令

OpenCode 支持两种配置自定义命令的方式：JSON 配置文件和 Markdown 文件。

通过 JSON 配置

在项目根目录的 opencode.json 或 opencode.jsonc 文件中，使用 command 字段定义命令：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件并输出覆盖率报告。分析所有失败的测试用例，给出修复建议。",
      "description": "运行测试并分析失败原因"
    }
  }
}

配置完成后，在 TUI 中输入 /test 即可触发该命令。

通过 Markdown 文件配置

你也可以将命令定义在独立的 Markdown 文件中，这种方式更便于管理和分享。文件可以放在两个位置：

• 全局目录：~/.config/opencode/commands/
• 项目目录：.opencode/commands/

创建 .opencode/commands/test.md：

---
description: 运行测试并分析失败原因
---

运行完整的测试套件并输出覆盖率报告。分析所有失败的测试用例，给出修复建议。

文件的名字就是命令名，因此 test.md 对应 /test 命令。文件内容分为两部分：YAML 格式的 frontmatter 元数据，以及正文的提示词模板。

传递参数

大多数命令需要根据不同的上下文动态调整行为。自定义命令支持通过 $ARGUMENTS 和位置参数来接收输入。

使用 $ARGUMENTS

$ARGUMENTS 会被替换为命令后面跟随的所有文本。例如创建一个生成新组件的命令 .opencode/commands/component.md：

---
description: 创建新的 React 组件
---

使用 TypeScript 创建一个名为 `$ARGUMENTS` 的新 React 组件。包含完整的类型定义、Props 接口和基本的组件结构。

然后在 TUI 中输入：

/component UserProfile

$ARGUMENTS 就被替换为 UserProfile，最终发送给 LLM 的提示词是："使用 TypeScript 创建一个名为 UserProfile 的新 React 组件..."

使用位置参数

当你需要更精确地控制参数时，可以使用位置参数 $1、$2、$3 等。创建 .opencode/commands/make-controller.md：

---
description: 创建 Laravel 控制器
---

在 Laravel 项目中创建一个名为 `$1` 的控制器，放在 `$2` 目录下。包含标准的 CRUD 方法：index、create、store、show、edit、update、destroy。模型名称为 `$3`。

使用方式：

/make-controller UserController Api User

参数按顺序替换：$1=UserController，$2=Api，$3=User。

注入 Shell 输出

自定义命令最强大的特性之一是可以将 Shell 命令的输出注入到提示词中。使用 !\command\`` 语法来嵌入命令执行结果。

创建 .opencode/commands/review.md：

---
description: 审查最近代码变更
---

最近的 Git 提交记录：
!\`git log --oneline -10\`

变更的文件列表：
!\`git diff --name-only HEAD~3\`

差异内容：
!\`git diff HEAD~3\`

请审查这些变更，检查潜在的问题、安全漏洞和代码质量问题。

当执行 /review 时，OpenCode 会在你的项目根目录执行这些命令，将输出嵌入到提示词中。这样 LLM 就能基于真实的代码变更进行审查。

另一个实用的例子是分析测试覆盖率的命令：

---
description: 分析测试覆盖率
---

以下是最新的测试覆盖率报告：
!\`npm test -- --coverage\`

基于这些结果，请分析哪些模块覆盖率不足，建议需要补充测试用例的关键路径。

引用文件

使用 @ 符号可以将文件内容自动包含到提示词中。创建 .opencode/commands/optimize.md：

---
description: 分析并优化代码
---

请分析 @src/services/payment.ts 中的性能瓶颈。
检查以下方面：
- 数据库查询是否可优化
- 是否存在 N+1 查询问题
- 是否有不必要的重复计算
- 内存使用是否合理

给出具体的优化建议和代码示例。

文件引用在命令执行时解析，文件的相对路径基于项目根目录。

高级选项

自定义命令提供了多个配置选项，让你能够精细控制命令的行为。

agent

指定由哪个 Agent 来执行此命令。可以使用内置的 build、plan 或自定义 Agent：

{
  "command": {
    "review": {
      "template": "审查代码变更...",
      "agent": "plan"
    }
  }
}

指定 agent 后，命令将使用该 Agent 的模型、提示词和权限配置来执行。当该 Agent 是子代理时，命令默认会触发子代理调用。

subtask

subtask 选项可以强制命令以子代理形式执行，即使引用的 Agent 配置为 primary 模式。子代理执行的好处是它不会污染当前会话的上下文：

{
  "command": {
    "analyze": {
      "template": "分析数据库性能...",
      "subtask": true
    }
  }
}

model

覆盖执行命令时使用的模型。这对于需要在不同任务间切换不同模型的场景非常有用——快速任务用轻量模型，复杂任务用高性能模型：

{
  "command": {
    "quick-lint": {
      "template": "快速检查代码语法和风格问题",
      "model": "anthropic/claude-haiku-4-20250514"
    },
    "deep-refactor": {
      "template": "对 @src/core 进行深度重构分析",
      "model": "anthropic/claude-sonnet-4-20250514"
    }
  }
}

description

在 TUI 中输入 / 时，会弹出命令列表，description 就是你给每条命令添加的说明文字，方便快速了解命令用途。这个选项是可选的，但强烈建议添加，尤其是在你定义了多条命令后。

覆盖内置命令

OpenCode 自带了一些内置命令，如 /init、/undo、/redo、/share、/help。有趣的是，你可以通过定义同名的自定义命令来覆盖它们。

例如，如果你想在每次执行 /undo 时额外做一些清理工作，可以定义 .opencode/commands/undo.md：

---
description: 撤销上一次变更并清理临时文件
---

执行撤销操作后，检查项目中是否有临时文件（如 .tmp、.log 等），如果有则删除它们。

但请注意：覆盖内置命令可能会影响你的工作流，建议只在确实需要扩展默认行为时才这样做。

实战：构建完整的命令库

下面是一个完整的自定义命令集配置示例，可以作为你搭建自己命令库的起点：

{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "test": {
      "template": "运行完整的测试套件，输出覆盖率和失败测试。分析失败原因并给出修复建议。",
      "description": "运行测试并分析结果",
      "agent": "build"
    },
    "review": {
      "template": "审查最新的代码变更（!\`git diff HEAD~1\`），关注安全性、性能和代码质量。",
      "description": "审查最近一次提交",
      "agent": "plan",
      "model": "anthropic/claude-sonnet-4-20250514"
    },
    "fix": {
      "template": "分析 @$1 文件中的语法错误和类型问题，逐一给出修复方案并应用。",
      "description": "修复指定文件的错误",
      "subtask": true
    },
    "deploy": {
      "template": "检查当前分支是否为 main，检查 CI 状态，然后执行部署脚本。先列出部署计划，确认后再执行。",
      "description": "执行部署检查与部署",
      "agent": "plan"
    },
    "refactor": {
      "template": "对 $ARGUMENTS 进行重构分析，识别设计模式问题、代码异味和改进机会。给出重构方案。",
      "description": "分析并重构代码"
    }
  }
}

总结

OpenCode 的自定义命令系统是一个强大但容易被忽视的效率工具。它将你每天重复输入的高频提示词转化为可复用的快捷命令，减少了上下文切换的心智负担。通过合理运用参数注入、Shell 输出嵌入和文件引用，你可以构建出高度智能化和上下文感知的命令集。

建议你从简单的命令开始，逐步积累和完善自己的命令库。当你发现某个操作重复了三次以上，就值得为它创建一个自定义命令。让 AI 编程助手真正按照你的习惯和节奏工作。