进阶 opencode.ai 2026-11-11 16:13:22 · 15 阅读

第11章 OpenCode 自定义命令配置指南

Commands创建 .opencode/commands/review.md 文件,即可将提示词转换为 /review 命令: .opencode/commands/review.mdReview $ARGUMENTS for bugs and missing tests. 在 TUI 中指定目标运行: /review src/auth.ts OpenCode 会将 "Review src/auth.ts for bugs and missing tests." 作为用户提示词提交。

将全局命令放在 ~/.config/opencode/commands/ 目录,项目命令放在 .opencode/commands/ 目录。 ~/.config/opencode/commands/review.md .opencode/commands/review.md 系统仅发现 .md 文件。嵌套路径中的斜杠 / 会成为命令名称的分隔符: .opencode/commands/team/review.mdReview $ARGUMENTS using the team's checklist. 嵌套命令以 /team/review src/auth.ts 形式运行。虽然旧版的单数目录 command/ 也能被识别,但新文件请使用 commands/。

当命令需要元数据时,添加 YAML frontmatter。裁剪后的 Markdown 正文始终作为提示词模板。 .opencode/commands/review.md--- description: Review code for correctness agent: plan model: anthropic/claude-sonnet-5-5#high ---

Review $ARGUMENTS. Report bugs first.

在 OpenCode 的任意 JSON 或 JSONC 配置文件的 commands 字段下定义命令。每个命令都必须包含 template。 opencode.jsonc{ "$schema": "https://opencode.ai/config.json", "commands": { "review": { "description": "Review code for correctness", "template": "Review $ARGUMENTS. Report bugs first.", }, }, }

Markdown frontmatter 和 JSON 条目接受相同的字段,区别在于 Markdown 的 template 取自文件正文。 FieldRequiredBehaviortemplateJSON onlyPrompt template.descriptionNoText shown in command lists and discovery.agentNoAgent selected when the command runs.modelNoModel override in provider/model or provider/model#variant format.subagentNotrue runs in a background child session; false forces the current session.subtaskNoDeprecated alias for subagent. 例如,以下 JSON 命令设置了所有当前的可选字段: opencode.jsonc{ "commands": { "audit": { "template": "Audit $ARGUMENTS.", "description": "Audit a package", "agent": "general", "model": "anthropic/claude-sonnet-5-5#high", "subagent": true, }, }, } 不要在 Markdown frontmatter 中写 template,正文本身即充当模板。

使用 $ARGUMENTS 表示用户输入的完整参数字符串。 .opencode/commands/component.mdCreate a typed React component named $ARGUMENTS. 对于 /component Account Settings,占位符会被替换为 Account Settings。

使用 $1、$2 及更高序号表示解析出的位置参数。单词可用单引号或双引号分组,引号会被移除。 .opencode/commands/check.mdCheck $1. Focus on $2. 对于 /check src/auth.ts "error handling",$1 变为 src/auth.ts,$2 变为 error handling。 最高序号的占位符会消耗其后的所有参数。缺失的位置会被替换为空字符串。 .opencode/commands/compare.mdCompare $1 with $2. 对于 /compare api stable branch,OpenCode 提交的提示词为 "Compare api with stable branch"。

当模板中不含 $ARGUMENTS 或位置占位符时,OpenCode 会在空行后附加非空参数。 .opencode/commands/explain.mdExplain this code clearly. 对于 /explain src/cache.ts,提示词变为: Explain this code clearly.

src/cache.ts

用 ! 加反引号包裹 shell 命令,可在提交提示词前插入其执行输出。 .opencode/commands/review-diff.mdReview this diff:

!`git diff --stat && git diff` OpenCode 会在当前项目路径下使用配置的 shell 运行每个代码块,并插入合并后的输出。 参数占位符会先被展开: .opencode/commands/history.mdSummarize these commits:

!`git log --oneline -$1` 对于 /history 5,shell 接收到的命令是 git log --oneline -5。请勿将不可信的参数放入 shell 代码块中。

存储的模板不会展开 @path,它仅作为普通提示词文本保留。 .opencode/commands/readme.mdReview @README.md. 要附加文件,请在调用命令时通过 composer 添加。OpenCode 在提交展开后的提示词时会保留这些 composer 附件。

命令在提交持久化用户提示词前,先展开参数和 shell 代码块。默认在当前会话中运行。 .opencode/commands/plan.md--- agent: plan ---

Plan $ARGUMENTS. 运行 /plan migration 会在提交提示词前将当前会话切换至 plan 模式。 模型选择遵循以下规则:

* 命令中的 model 字段会覆盖其他所有模型设置。 * 否则,所选命令 agent 配置的模型会覆盖调用时活动的模型。 * 否则,保持当前会话的模型不变。

例如,此命令同时指定了 agent 和显式模型: .opencode/commands/design.md--- agent: plan model: openai/gpt-6.1-sol#high ---

Design $ARGUMENTS.

设置 subagent: true 可在后台子会话中运行命令。 .opencode/commands/audit.md--- description: Audit changes agent: general subagent: true ---

Audit $ARGUMENTS for bugs and missing tests. 父会话保持可用,并保留其 agent 和模型。子会话结束后,OpenCode 会将结果或失败信息回传给父会话。 ValueBehaviortrueAlways use a child, even when the selected agent has mode: primary.falseAlways use the current session, even when the selected agent has mode: subagent.OmittedUse a child only when the selected agent has mode: subagent. 子会话依次使用:命令模型、所选 agent 的模型、父会话的模型。旧字段 subtask 仍被接受;若同时存在两个字段,subagent 优先。 YAMLsubagent: false subtask: true 此示例在当前会话中运行,因为 subagent 优先于 subtask。

Markdown 和 JSON 命令共享同一个注册表。后续来源会替换同名命令。 ~/.config/opencode/commands/review.md # Lower priority .opencode/commands/review.md # Replaces the global command 项目来源优先于全局来源,较近的项目来源优先于祖先来源。 自定义定义也可以替换早期的内置命令。OpenCode 会自动重新加载命令文件和配置变更。 .opencode/commands/review.mdReview only the staged changes: !`git diff --cached` 保存此文件即可更新 /review,无需重启 OpenCode。

评论 (0)