opencode

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

OpenCode CLI

Use OpenCode as an autonomous coding worker orchestrated by Hermes terminal/process tools. OpenCode is a provider-agnostic, open-source AI coding agent with a TUI and CLI.

使用OpenCode作为由Hermes终端/进程工具编排的自主编码工作者。OpenCode是一款与供应商无关的开源AI编码Agent，具备TUI和CLI界面。

When to Use

适用场景

User explicitly asks to use OpenCode
You want an external coding agent to implement/refactor/review code
You need long-running coding sessions with progress checks
You want parallel task execution in isolated workdirs/worktrees

用户明确要求使用OpenCode
你需要外部编码Agent实现/重构/评审代码
需要带有进度检查的长期编码会话
希望在独立工作目录/工作树中执行并行任务

Prerequisites

前置条件

OpenCode installed:

npm i -g opencode-ai@latest

brew install anomalyco/tap/opencode

Auth configured:
```
opencode auth login
```
or set provider env vars (OPENROUTER_API_KEY, etc.)
Verify:
```
opencode auth list
```
should show at least one provider
Git repository for code tasks (recommended)
```
pty=true
```
for interactive TUI sessions

已安装OpenCode：

npm i -g opencode-ai@latest

或

brew install anomalyco/tap/opencode

已配置认证：
```
opencode auth login
```
或设置供应商环境变量（如OPENROUTER_API_KEY）
验证：
```
opencode auth list
```
应显示至少一个供应商
代码任务对应的Git仓库（推荐）
交互式TUI会话需设置
```
pty=true
```

Binary Resolution (Important)

二进制文件解析（重要）

Shell environments may resolve different OpenCode binaries. If behavior differs between your terminal and Hermes, check:

terminal(command="which -a opencode")
terminal(command="opencode --version")

If needed, pin an explicit binary path:

terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)

Shell环境可能会解析不同的OpenCode二进制文件。如果你的终端与Hermes中的行为不一致，请检查：

terminal(command="which -a opencode")
terminal(command="opencode --version")

如有需要，指定明确的二进制文件路径：

terminal(command="$HOME/.opencode/bin/opencode run '...'", workdir="~/project", pty=true)

One-Shot Tasks

一次性任务

Use

opencode run

for bounded, non-interactive tasks:

terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")

Attach context files with

-f

terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")

Show model thinking with

--thinking

terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")

Force a specific model:

terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")

使用

opencode run

执行有界、非交互式任务：

terminal(command="opencode run 'Add retry logic to API calls and update tests'", workdir="~/project")

使用

-f

附加上下文文件：

terminal(command="opencode run 'Review this config for security issues' -f config.yaml -f .env.example", workdir="~/project")

使用

--thinking

查看模型思考过程：

terminal(command="opencode run 'Debug why tests fail in CI' --thinking", workdir="~/project")

指定特定模型：

terminal(command="opencode run 'Refactor auth module' --model openrouter/anthropic/claude-sonnet-4", workdir="~/project")

Interactive Sessions (Background)

交互式会话（后台运行）

For iterative work requiring multiple exchanges, start the TUI in background:

terminal(command="opencode", workdir="~/project", background=true, pty=true)

对于需要多次交互的迭代工作，在后台启动TUI：

terminal(command="opencode", workdir="~/project", background=true, pty=true)

Returns session_id

返回session_id

Send a prompt

发送提示词

process(action="submit", session_id="<id>", data="Implement OAuth refresh flow and add tests")

Monitor progress

监控进度

process(action="poll", session_id="<id>") process(action="log", session_id="<id>")

Send follow-up input

发送后续输入

process(action="submit", session_id="<id>", data="Now add error handling for token expiry")

Exit cleanly — Ctrl+C

干净退出 — Ctrl+C

process(action="write", session_id="<id>", data="\x03")

Or just kill the process

或者直接终止进程

process(action="kill", session_id="<id>")


**Important:** Do NOT use `/exit` — it is not a valid OpenCode command and will open an agent selector dialog instead. Use Ctrl+C (`\x03`) or `process(action="kill")` to exit.

process(action="kill", session_id="<id>")


**重要提示：** 请勿使用`/exit` — 这不是有效的OpenCode命令，会打开Agent选择对话框。请使用Ctrl+C（`\x03`）或`process(action="kill")`退出。

TUI Keybindings

TUI快捷键

Key	Action
`Enter`	Submit message (press twice if needed)
`Tab`	Switch between agents (build/plan)
`Ctrl+P`	Open command palette
`Ctrl+X L`	Switch session
`Ctrl+X M`	Switch model
`Ctrl+X N`	New session
`Ctrl+X E`	Open editor
`Ctrl+C`	Exit OpenCode

按键	操作
`Enter`	提交消息（必要时按两次）
`Tab`	在Agent间切换（build/plan）
`Ctrl+P`	打开命令面板
`Ctrl+X L`	切换会话
`Ctrl+X M`	切换模型
`Ctrl+X N`	新建会话
`Ctrl+X E`	打开编辑器
`Ctrl+C`	退出OpenCode

Resuming Sessions

恢复会话

After exiting, OpenCode prints a session ID. Resume with:

terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # Continue last session
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # Specific session

退出后，OpenCode会打印会话ID。使用以下命令恢复：

terminal(command="opencode -c", workdir="~/project", background=true, pty=true)  # 继续上一个会话
terminal(command="opencode -s ses_abc123", workdir="~/project", background=true, pty=true)  # 继续指定会话

Common Flags

常用参数

Flag	Use
`run 'prompt'`	One-shot execution and exit
`--continue` / `-c`	Continue the last OpenCode session
`--session <id>` / `-s`	Continue a specific session
`--agent <name>`	Choose OpenCode agent (build or plan)
`--model provider/model`	Force specific model
`--format json`	Machine-readable output/events
`--file <path>` / `-f`	Attach file(s) to the message
`--thinking`	Show model thinking blocks
`--variant <level>`	Reasoning effort (high, max, minimal)
`--title <name>`	Name the session
`--attach <url>`	Connect to a running opencode server

参数	用途
`run 'prompt'`	一次性执行后退出
`--continue` / `-c`	继续上一个OpenCode会话
`--session <id>` / `-s`	继续指定会话
`--agent <name>`	选择OpenCode Agent（build或plan）
`--model provider/model`	指定特定模型
`--format json`	机器可读的输出/事件
`--file <path>` / `-f`	向消息附加文件
`--thinking`	显示模型思考块
`--variant <level>`	推理强度（high, max, minimal）
`--title <name>`	为会话命名
`--attach <url>`	连接到运行中的opencode服务器

Procedure

操作流程

Verify tool readiness:

```
terminal(command="opencode --version")
```
```
terminal(command="opencode auth list")
```

For bounded tasks, use
```
opencode run '...'
```
(no pty needed).
For iterative tasks, start
```
opencode
```
with
```
background=true, pty=true
```
.
Monitor long tasks with
```
process(action="poll"|"log")
```
.
If OpenCode asks for input, respond via
```
process(action="submit", ...)
```
.

Exit with

process(action="write", data="\x03")

process(action="kill")

Summarize file changes, test results, and next steps back to user.

验证工具就绪状态：

```
terminal(command="opencode --version")
```
```
terminal(command="opencode auth list")
```

对于有界任务，使用
```
opencode run '...'
```
（无需pty）。
对于迭代任务，启动
```
opencode
```
并设置
```
background=true, pty=true
```
。
使用
```
process(action="poll"|"log")
```
监控长期任务。
如果OpenCode请求输入，通过
```
process(action="submit", ...)
```
响应。

使用

process(action="write", data="\x03")

或

process(action="kill")

退出。

向用户总结文件变更、测试结果和后续步骤。

PR Review Workflow

PR评审流程

OpenCode has a built-in PR command:

terminal(command="opencode pr 42", workdir="~/project", pty=true)

Or review in a temporary clone for isolation:

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)

OpenCode内置PR命令：

terminal(command="opencode pr 42", workdir="~/project", pty=true)

或者在临时克隆中进行隔离评审：

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && opencode run 'Review this PR vs main. Report bugs, security risks, test gaps, and style issues.' -f $(git diff origin/main --name-only | head -20 | tr '\n' ' ')", pty=true)

Parallel Work Pattern

并行工作模式

Use separate workdirs/worktrees to avoid collisions:

terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
process(action="list")

使用独立工作目录/工作树避免冲突：

terminal(command="opencode run 'Fix issue #101 and commit'", workdir="/tmp/issue-101", background=true, pty=true)
terminal(command="opencode run 'Add parser regression tests and commit'", workdir="/tmp/issue-102", background=true, pty=true)
process(action="list")

Session & Cost Management

会话与成本管理

List past sessions:

terminal(command="opencode session list")

Check token usage and costs:

terminal(command="opencode stats")
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")

列出过往会话：

terminal(command="opencode session list")

查看令牌使用情况和成本：

terminal(command="opencode stats")
terminal(command="opencode stats --days 7 --models anthropic/claude-sonnet-4")

Pitfalls

注意事项

Interactive
```
opencode
```
(TUI) sessions require
```
pty=true
```
. The
```
opencode run
```
command does NOT need pty.
```
/exit
```
is NOT a valid command — it opens an agent selector. Use Ctrl+C to exit the TUI.
PATH mismatch can select the wrong OpenCode binary/model config.
If OpenCode appears stuck, inspect logs before killing:
- ```
process(action="log", session_id="<id>")
```
Avoid sharing one working directory across parallel OpenCode sessions.
Enter may need to be pressed twice to submit in the TUI (once to finalize text, once to send).

交互式
```
opencode
```
（TUI）会话需要
```
pty=true
```
。
```
opencode run
```
命令不需要pty。
```
/exit
```
不是有效命令 — 会打开Agent选择器。请使用Ctrl+C退出TUI。
PATH不匹配可能会选择错误的OpenCode二进制文件/模型配置。
如果OpenCode似乎卡住，在终止前检查日志：
- ```
process(action="log", session_id="<id>")
```
避免在并行OpenCode会话间共享同一个工作目录。
在TUI中提交可能需要按两次Enter（一次确认文本，一次发送）。

Verification

验证方法

Smoke test:

terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")

Success criteria:

Output includes
```
OPENCODE_SMOKE_OK
```
Command exits without provider/model errors
For code tasks: expected files changed and tests pass

冒烟测试：

terminal(command="opencode run 'Respond with exactly: OPENCODE_SMOKE_OK'")

成功标准：

输出包含
```
OPENCODE_SMOKE_OK
```
命令执行完成且无供应商/模型错误
对于代码任务：预期文件已变更且测试通过

Rules

规则

Prefer
```
opencode run
```
for one-shot automation — it's simpler and doesn't need pty.
Use interactive background mode only when iteration is needed.
Always scope OpenCode sessions to a single repo/workdir.
For long tasks, provide progress updates from
```
process
```
logs.
Report concrete outcomes (files changed, tests, remaining risks).
Exit interactive sessions with Ctrl+C or kill, never
```
/exit
```
.

优先使用
```
opencode run
```
进行一次性自动化 — 更简单且无需pty。
仅在需要迭代时使用交互式后台模式。
始终将OpenCode会话限定在单个仓库/工作目录中。
对于长期任务，从
```
process
```
日志中提供进度更新。
报告具体结果（文件变更、测试情况、剩余风险）。
使用Ctrl+C或终止进程退出交互式会话，绝不使用
```
/exit
```
。