---
title: "创建自定义命令"
description: "用自定义命令把重复提示词沉淀成可复用入口。"
verifiedAt: "2026-05-09"
---

Custom commands 让你把重复提示词做成 TUI 里的 `/xxx` 入口。它不是为了少打几个字，而是把任务边界、执行 agent、模型选择、参数和输出结构固定下来。

> [!NOTE]
> **这一篇用 10 分钟换什么**：你会知道什么时候该写 command、Markdown 和 JSON 两种方式怎么选、`$ARGUMENTS` / `$1` 怎么用、`!` 和 `@` 怎么注入上下文，以及为什么不要随便覆盖内置命令。

## 先判断该不该沉淀成 command

一条提示词至少反复用过几次，再考虑写成 command。

```mermaid
flowchart LR
    Prompt["一次性提示词"] --> Repeat{"同类流程反复出现?"}
    Repeat -->|否| Keep["继续在对话里写"]
    Repeat -->|是| Stable{"边界和输出稳定?"}
    Stable -->|否| Improve["先打磨提示词"]
    Stable -->|是| Command["写成 /command"]
    Command --> Share{"团队也需要?"}
    Share -->|是| Project["放 .opencode/commands/"]
    Share -->|否| Global["放 ~/.config/opencode/commands/"]

    style Command fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
    style Project fill:#dcfce7,stroke:#22c55e
```

适合做成 command：

- 每周都会做的固定动作，例如测试、审查、生成发布说明。
- 需要稳定输出结构的动作，例如“先列风险，再给改法，再列测试”。
- 团队希望统一做法的动作，例如 PR 自检、迁移检查、文档审查。

不适合：一次性问题、边界还没想清楚的复杂需求、开放式探索任务、已经有内置命令覆盖的动作。

## 1. Markdown command 推荐起步

项目级命令放在 `.opencode/commands/`。例如：

```md title=".opencode/commands/test.md"
---
description: Run tests with coverage
agent: build
---

Run the full test suite with coverage report.
If anything fails, identify the failing case, likely cause, and smallest next fix.
```

文件名就是命令名。`test.md` 对应：

```text
/test
```

Markdown 文件更适合长 prompt，因为它容易阅读、review、版本化。项目命令可以提交到 Git，让团队使用同一套任务入口。

## 2. 全局和项目级怎么选

| 位置 | 适合什么 |
| --- | --- |
| `.opencode/commands/` | 当前仓库的测试、发布、迁移、PR 审查、文档检查 |
| `~/.config/opencode/commands/` | 个人跨项目通用命令，例如总结 diff、解释报错、整理提交信息 |

默认从项目级开始。只要 prompt 里引用了项目路径、测试命令、目录结构或团队规则，就不要放进全局。

## 3. JSON command 适合短命令

也可以在 `opencode.json` / `opencode.jsonc` 里用 `command` 配置。

```jsonc title="opencode.jsonc"
{
  "$schema": "https://opencode.ai/config.json",
  "command": {
    "review": {
      "template": "Review the current git diff. Focus on bugs, regressions, security, and missing tests.",
      "description": "Review current changes",
      "agent": "plan"
    }
  }
}
```

`template` 是必填项，`description` 会显示在 TUI 命令列表里。JSON 适合一两个短命令；长提示词、步骤和示例更适合 Markdown 文件。

## 4. 参数怎么用

`$ARGUMENTS` 代表命令后面的整段输入。

```md title=".opencode/commands/component.md"
---
description: Create a component plan
---

Create an implementation plan for $ARGUMENTS.
Include files to touch, edge cases, and tests.
```

运行：

```text
/component Button
```

这里 `$ARGUMENTS` 会变成 `Button`。

也可以使用位置参数：`$1`、`$2`、`$3`。但位置参数越多，命令越像脚本，越容易误用。新手优先用 `$ARGUMENTS`。

## 5. 注入 shell 输出和文件

Command prompt 可以使用 `!` 注入 shell 输出，也可以用 `@` 引用文件。

```md title=".opencode/commands/review-diff.md"
---
description: Review current diff
---

Current changes:
!`git diff --stat`
!`git diff`

Review only. Do not modify files.
```

文件引用示例：

`Review @src/components/Button.tsx for performance and accessibility issues.`

> [!WARNING]
> `!` 会执行命令并把输出放进 prompt。只读命令适合，删除、发布、数据库写操作和修改全局环境的命令不适合写进 command。

## 6. agent、subtask 和 model

Command 可以指定执行它的 agent 和 model。

几个边界要记住：

- `agent` 可选；不指定时使用当前 agent。
- 如果 `agent` 是 subagent，官方文档说明 command 默认会触发 subagent invocation。
- 如果不想让 subagent 默认执行，可以设置 `subtask: false`。
- `subtask: true` 可以强制让命令作为 subagent 运行，避免污染主会话上下文。
- `model` 可以覆盖当前默认模型，但只在确实需要特殊模型时配置，不要每个 command 都硬绑模型。

## 7. 不要覆盖内置命令

OpenCode 已有 `/init`、`/undo`、`/redo`、`/share`、`/help` 等内置命令。官方文档说明 custom commands 可以覆盖内置命令。

> [!CAUTION]
> 除非你明确知道后果，否则不要创建 `init.md`、`undo.md`、`share.md` 这类同名 command。要改变安全边界，用 config 和 permission；不要靠覆盖内置命令制造隐性行为。

## 8. 怎么判断写对了

一个可交付的 command 应该满足：

- 名字短，一眼能看懂。
- 一个 command 只做一类任务。
- 输出结构稳定，不需要每次再补说明。
- 参数少，最好先用 `$ARGUMENTS`。
- shell 注入只用只读命令。
- 项目级命令可 review、可删除、可追踪影响范围。

如果每次运行还要补一大段解释，说明 command 没有把任务边界写清楚。

## 接下来去哪

<Cards>
  <Card title="配置" description="理解 command 应该放在项目配置、Markdown 文件还是全局配置。" href="/docs/opencode/official/01-customization/config" />
  <Card title="Rules" description="长期约束写进 rules，重复流程写成 command，不要混用。" href="/docs/opencode/official/02-agents-skills/rules" />
  <Card title="Agents" description="当 command 需要固定角色、模型或权限时，再考虑自定义 agent。" href="/docs/opencode/official/02-agents-skills/agents" />
  <Card title="TUI" description="Command 最终在 TUI 里使用，先理解 `/` 命令和快捷键。" href="/docs/opencode/official/00-getting-started/tui" />
</Cards>

## 官方资料

- OpenCode Commands：[https://opencode.ai/docs/commands](https://opencode.ai/docs/commands)
- OpenCode TUI Commands：[https://opencode.ai/docs/tui#commands](https://opencode.ai/docs/tui#commands)
- OpenCode Config：[https://opencode.ai/docs/config](https://opencode.ai/docs/config)
- OpenCode Agents：[https://opencode.ai/docs/agents](https://opencode.ai/docs/agents)
