OpenCode 自定义命令
自定义命令允许你将常用的提示词封装成一个短命令,在 TUI 中通过 /命令名称 的方式一键执行,避免重复输入相同的提示词。
例如,将"运行测试并分析失败原因"这个复杂提示词封装为 /test,每次只需输入两个字符即可触发。
自定义命令是 /init、/undo、/redo、/share、/help 等内置命令之外的扩展。
如果你定义的自定义命令与内置命令同名,自定义命令会覆盖内置命令。请避免使用
init、undo、redo、share、help作为自定义命令名称,除非你明确需要替换内置行为。
两种定义方式
自定义命令支持两种定义方式,效果完全相同,可以按照个人习惯选择:
| 方式 | 文件 | 适用场景 |
|---|---|---|
| JSON 配置 | opencode.json 的 command 字段 |
命令较少,希望集中管理所有配置 |
| Markdown 文件 | commands/ 目录下的 .md 文件 |
命令内容较长,希望每个命令单独维护 |
方式一:JSON 配置
在 opencode.json 的 command 字段中定义,键名即为命令名称:
实例
{
"$schema": "https://opencode.ai/config.json",
"command": {
"test": { // 命令名称,在 TUI 中通过 /test 调用
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
// template:发送给 LLM 的提示词内容(必填)
"description": "Run tests with coverage",
// description:在 TUI 命令列表中显示的说明(可选)
"agent": "build", // agent:指定执行此命令的代理(可选)
"model": "anthropic/claude-3-5-sonnet-20241022"
// model:覆盖此命令使用的模型(可选)
}
}
}
"$schema": "https://opencode.ai/config.json",
"command": {
"test": { // 命令名称,在 TUI 中通过 /test 调用
"template": "Run the full test suite with coverage report and show any failures.\nFocus on the failing tests and suggest fixes.",
// template:发送给 LLM 的提示词内容(必填)
"description": "Run tests with coverage",
// description:在 TUI 命令列表中显示的说明(可选)
"agent": "build", // agent:指定执行此命令的代理(可选)
"model": "anthropic/claude-3-5-sonnet-20241022"
// model:覆盖此命令使用的模型(可选)
}
}
}
配置完成后,在 TUI 输入框中输入 /test 并回车即可执行该命令。
方式二:Markdown 文件
在 commands/ 目录下创建 .md 文件来定义命令,文件名即为命令名,文件内容分为两部分:
- Frontmatter(
---包裹的 YAML 部分):定义命令的属性 - 正文(Frontmatter 下方的内容):成为发送给 LLM 的提示词模板
Markdown 文件支持两个存放位置:
- 项目级:
.opencode/commands/命令名.md(仅对当前项目有效) - 全局:
~/.config/opencode/commands/命令名.md(对所有项目有效)
<!-- 文件路径:.opencode/commands/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.
该文件名为 test.md,因此命令名为 test,在 TUI 中通过 /test 调用。
提示词模板语法
命令的提示词(template 字段或 Markdown 正文)支持以下特殊语法,可以让提示词动态响应参数、实时注入命令输出或引用文件内容。
1、传入参数($ARGUMENTS)
使用 $ARGUMENTS 占位符接收命令调用时传入的参数,整体作为一个字符串插入:
<!-- 文件路径:.opencode/commands/component.md --> --- description: Create a new React component --- Create a new React component named $ARGUMENTS with TypeScript support. Include proper typing and basic structure.
调用时在命令名后附加参数:
/component Button
$ARGUMENTS 会被替换为 Button,实际执行的提示词变为:
Create a new React component named Button with TypeScript support. Include proper typing and basic structure.
2、位置参数(1ドル、2ドル、3ドル...)
当需要传入多个独立参数时,可以使用位置参数 1ドル、2ドル、3ドル 分别引用每个参数,空格分隔,含空格的参数用引号包裹:
<!-- 文件路径:.opencode/commands/create-file.md --> --- description: Create a new file with content --- Create a file named 1ドル in the directory 2ドル with the following content: 3ドル
调用示例(含空格的参数用引号包裹):
/create-file config.json src "{ \"key\": \"value\" }"
各占位符的替换结果:
| 占位符 | 替换为 |
|---|---|
1ドル |
config.json |
2ドル |
src |
3ドル |
{ "key": "value" } |
3、注入 Shell 命令输出(!`command`)
使用 !`shell命令` 语法可以在命令执行时运行一段 Shell 命令,并将其输出结果直接插入提示词中。Shell 命令在项目根目录下运行。这在需要让 LLM 分析实时数据(如测试结果、git 日志等)时非常有用:
<!-- 文件路径:.opencode/commands/analyze-coverage.md --> --- description: Analyze test coverage --- Here are the current test results: !`npm test` Based on these results, suggest improvements to increase coverage.
<!-- 文件路径:.opencode/commands/review-changes.md --> --- description: Review recent git changes --- Recent git commits: !`git log --oneline -10` Review these changes and suggest any improvements or potential issues.
执行命令时,!`git log --oneline -10` 会被替换为实际的 git 日志输出,然后连同提示词一起发送给 LLM。
4、引用文件内容(@文件路径)
使用 @文件路径 语法可以将指定文件的内容自动包含在提示词中,无需手动复制粘贴:
<!-- 文件路径:.opencode/commands/review-component.md --> --- description: Review a component for performance issues --- Review the component in @src/components/Button.tsx. Check for performance issues and suggest improvements.
执行命令时,@src/components/Button.tsx 会被替换为该文件的完整内容,LLM 可以直接分析文件代码。
配置选项详解
以下是自定义命令支持的所有配置选项,Markdown 文件中写在 frontmatter 里,JSON 配置中写在命令对象下:
| 选项 | 是否必填 | 类型 | 说明 |
|---|---|---|---|
template |
必填(JSON 方式) | 字符串 | 发送给 LLM 的提示词内容。Markdown 方式中正文即为 template,无需单独声明 |
description |
可选 | 字符串 | 命令的简要说明,输入 / 时在 TUI 命令列表中显示,帮助快速识别命令用途 |
agent |
可选 | 字符串 | 指定执行此命令的代理名称。未指定则使用当前选中的代理。若指定的是子代理,命令默认触发子代理调用 |
subtask |
可选 | 布尔值 | 设为 true 可强制命令以子代理方式运行,避免污染主会话上下文。设为 false 可禁止子代理调用行为 |
model |
可选 | 字符串 | 覆盖此命令使用的模型,格式为 provider/model-id,如 anthropic/claude-3-5-sonnet-20241022 |
agent 与 subtask 的关系
agent 和 subtask 共同控制命令的执行方式:
- 若
agent指定的是一个子代理(mode 为 subagent),命令默认触发子代理调用,在独立上下文中执行,不影响主会话 - 若不希望此行为,将
subtask设为false可强制在主会话中执行 - 若将
subtask设为true,无论代理的mode设置如何,命令始终以子代理方式运行,适合需要完全隔离上下文的场景
实例
{
"$schema": "https://opencode.ai/config.json",
"command": {
"analyze": {
"template": "Analyze the codebase for potential security vulnerabilities.",
"description": "Security analysis(独立运行,不污染主会话)",
"subtask": true, // 强制以子代理方式运行,分析结果不占用主会话上下文
"model": "anthropic/claude-3-5-sonnet-20241022"
},
"review": {
"template": "Review the current code changes.",
"description": "Code review(在当前代理中运行)",
"agent": "plan", // 使用 plan 代理执行
"subtask": false // 禁止子代理调用,在主会话中运行
}
}
}
"$schema": "https://opencode.ai/config.json",
"command": {
"analyze": {
"template": "Analyze the codebase for potential security vulnerabilities.",
"description": "Security analysis(独立运行,不污染主会话)",
"subtask": true, // 强制以子代理方式运行,分析结果不占用主会话上下文
"model": "anthropic/claude-3-5-sonnet-20241022"
},
"review": {
"template": "Review the current code changes.",
"description": "Code review(在当前代理中运行)",
"agent": "plan", // 使用 plan 代理执行
"subtask": false // 禁止子代理调用,在主会话中运行
}
}
}
综合使用示例
示例一:多参数代码生成命令
<!-- 文件路径:.opencode/commands/gen-api.md --> --- description: Generate a REST API endpoint agent: build --- Generate a 1ドル REST API endpoint for the resource "2ドル". Place the file in the 3ドル directory. Include input validation, error handling, and JSDoc comments. <!-- 调用示例:/gen-api POST user src/api --> <!-- 1ドル = POST,2ドル = user,3ドル = src/api -->
示例二:结合 Shell 输出和文件引用的代码审查命令
<!-- 文件路径:.opencode/commands/pr-review.md --> --- description: Review changes in current branch against main agent: plan subtask: true --- Please review the following changes for code quality, potential bugs, and security issues. ## Recent commits !`git log main..HEAD --oneline` ## Changed files !`git diff main --name-only` ## Diff content !`git diff main` ## Project coding guidelines @.opencode/AGENTS.md Provide structured feedback with severity levels (critical / warning / suggestion).
示例三:定时数据快照命令(JSON 方式)
{
"$schema": "https://opencode.ai/config.json",
"command": {
"healthcheck": {
"description": "Check project health status",
"template": "Analyze the project health based on the following data:\n\nDependency vulnerabilities:\n!`npm audit --json`\n\nOutdated packages:\n!`npm outdated`\n\nTest results:\n!`npm test -- --passWithNoTests 2>&1 | tail -20`\n\nSummarize the issues by severity and suggest a prioritized action plan.",
"model": "anthropic/claude-3-5-sonnet-20241022",
"subtask": true
}
}
}