Custom commands（自定义命令）允许你指定一个 prompt（提示词），当该命令在 TUI 中被执行时自动运行这个 prompt。

```bash frame=”none” /my-command

  2. Custom commands 是对内置命令（built-in commands）的补充，例如 `/init`、`/undo`、`/redo`、`/share`、`/help`。
  3. 更多信息请参考 [Learn more](/docs/tui#commands)。
  5. ---
  7. ## Create command files（创建命令文件）
  9. 在 `command/` 目录下创建 markdown 文件来定义 custom commands。
  11. 创建 `.opencode/command/test.md`：
  13. ```md title=".opencode/command/test.md"
  14. ---
  15. description: Run tests with coverage
  16. agent: build
  17. model: anthropic/claude-3-5-sonnet-20241022
  18. ---
  20. Run the full test suite with coverage report and show any failures.
  21. Focus on the failing tests and suggest fixes.

frontmatter（文件头元数据）定义了 command 的属性，正文内容会作为 template（模板）。

使用命令时，只需要输入 / 加上命令名即可。

```bash frame=”none” “/test”

  2. ---
  4. ## Configure（配置）
  6. 你可以通过 OpenCode config，或者在 `command/` 目录下创建 markdown 文件来添加 custom commands。
  8. ---
  10. ### JSON
  12. 在 OpenCode [config](/docs/config) 中使用 `command` 配置项：
  14. {
  15. "$schema": "https://opencode.ai/config.json",
  16. "command": {
  17. // This becomes the name of the command
  18. "test": {
  19. // This is the prompt that will be sent to the LLM
  20. "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
  21. // This is show as the description in the TUI
  22. "description": "Run tests with coverage",
  23. "agent": "build",
  24. "model": "anthropic/claude-3-5-sonnet-20241022"
  25. }
  26. }
  27. }
  29. 现在你就可以在 TUI 中运行这个命令：
  31. ```bash frame="none"
  32. /test

Markdown

你也可以使用 markdown 文件来定义 commands。将文件放在以下路径之一：

  • Global（全局）：~/.config/opencode/command/
  • Per-project（项目级）：.opencode/command/

```markdown title=”~/.config/opencode/command/test.md”

description: Run tests with coverage agent: build

model: anthropic/claude-3-5-sonnet-20241022

Run the full test suite with coverage report and show any failures. Focus on the failing tests and suggest fixes.

  2. markdown 文件名会成为 command name（命令名）。
  3. 例如，`test.md` 允许你运行：
  5. ```bash frame="none"
  6. /test

Prompt config（Prompt 配置）

custom commands 的 prompt 支持多种特殊占位符（placeholders）和语法。

Arguments（参数）

你可以使用 $ARGUMENTS 占位符向命令传递参数。

```md title=”.opencode/command/component.md”

description: Create a new component

Create a new React component named $ARGUMENTS with TypeScript support. Include proper typing and basic structure.

  2. 运行带参数的命令：
  4. ```bash frame="none"
  5. /component Button

此时 $ARGUMENTS 会被替换为 Button。

你也可以通过位置参数（positional parameters）访问单个参数：

  • $1 - 第一个参数
  • $2 - 第二个参数
  • $3 - 第三个参数
  • 以此类推…

例如：

```md title=”.opencode/command/create-file.md”

description: Create a new file with content

Create a file named $1 in the directory $2 with the following content: $3

  2. 运行命令：
  4. ```bash frame="none"
  5. /create-file config.json src "{ \"key\": \"value\" }"

替换结果如下：

  • $1 会被替换为 config.json
  • $2 会被替换为 src
  • $3 会被替换为 { "key": "value" }

Shell output（Shell 输出）

你可以使用 !command 将 bash command 的输出注入到 prompt 中。

例如，创建一个用于分析测试覆盖率（test coverage）的 custom command：

```md title=”.opencode/command/analyze-coverage.md”

description: Analyze test coverage

Here are the current test results: !npm test

Based on these results, suggest improvements to increase coverage.

  2. 或者用于审查最近的变更：
  4. ```md title=".opencode/command/review-changes.md"
  5. ---
  6. description: Review recent changes
  7. ---
  9. Recent git commits:
  10. !`git log --oneline -10`
  12. Review these changes and suggest any improvements.

命令会在你的 project root directory（项目根目录）中执行，其输出会自动成为 prompt 的一部分。

File references（文件引用）

你可以在 command 中使用 @ 加文件名来引用文件。

```md title=”.opencode/command/review-component.md”

description: Review component

Review the component in @src/components/Button.tsx. Check for performance issues and suggest improvements.

  2. 被引用的文件内容会自动注入到 prompt 中。
  4. ---
  6. ## Options（配置选项）
  8. 下面详细介绍各个配置项。
  10. ---
  12. ### Template（模板）
  14. `template` 配置项定义了当 command 执行时发送给 LLM 的 prompt 内容。
  16. ```json title="opencode.json"
  17. {
  18.   "command": {
  19.     "test": {
  20.       "template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes."
  21.     }
  22.   }
  23. }

这是一个 必填（required） 配置项。

Description（描述）

使用 description 配置项为 command 提供一个简短说明。

```json title=”opencode.json” { “command”: { “test”: { “description”: “Run tests with coverage” } } }

  2. 当你在 TUI 中输入命令时，这段描述会显示出来。
  4. ---
  6. ### Agent（代理）
  8. 使用 `agent` 配置可以指定由哪个 [agent](/docs/agents) 来执行该 command。
  9. 如果该 agent 是一个 [subagent](/docs/agents/#subagents)，默认会触发一次 subagent invocation（子代理调用）。
  10. 如果你希望关闭该行为，可以将 `subtask` 设置为 `false`。
  12. ```json title="opencode.json"
  13. {
  14.   "command": {
  15.     "review": {
  16.       "agent": "plan"
  17.     }
  18.   }
  19. }

这是一个 可选（optional） 配置项。如果未指定，则默认使用当前 agent。

Subtask（子任务）

使用 subtask 布尔值可以强制该 command 触发一次 subagent 调用。 这在你希望该 command 不污染主上下文（primary context）时非常有用，并且会 强制（force） agent 以 subagent 方式执行， 即使在 agent 配置中 mode 被设置为 primary。

```json title=”opencode.json” { “command”: { “analyze”: { “subtask”: true } } }

  2. 这是一个 **可选（optional）** 配置项。
  4. ---
  6. ### Model（模型）
  8. 使用 `model` 配置可以为该 command 覆盖默认使用的 model。
  10. ```json title="opencode.json"
  11. {
  12.   "command": {
  13.     "analyze": {
  14.       "model": "anthropic/claude-3-5-sonnet-20241022"
  15.     }
  16.   }
  17. }

这是一个 可选（optional） 配置项。

Built-in（内置命令）

opencode 内置了多个 commands，例如 /init、/undo、/redo、/share、/help

如果你定义了一个与内置命令同名的 custom command，它将会覆盖对应的 built-in command。