coding-agent

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Coding Agent (bash-first)

编码Agent（优先使用bash）

Use bash (with optional background mode) for all coding agent work. Simple and effective.

所有编码Agent任务都使用bash（支持可选后台模式），简单高效。

⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no

⚠️ PTY模式：Codex/Pi/OpenCode需开启，Claude Code无需开启

For Codex, Pi, and OpenCode, PTY is still required (interactive terminal apps):

bash

undefined

对于Codex、Pi和OpenCode，仍然需要PTY（交互式终端应用）：

bash

undefined

✅ Correct for Codex/Pi/OpenCode

✅ Codex/Pi/OpenCode正确用法

bash pty:true command:"codex exec 'Your prompt'"


For **Claude Code** (`claude` CLI), use `--print --permission-mode bypassPermissions` instead.
`--dangerously-skip-permissions` with PTY can exit after the confirmation dialog.
`--print` mode keeps full tool access and avoids interactive confirmation:

```bash

bash pty:true command:"codex exec 'Your prompt'"


对于**Claude Code**（`claude` CLI），请使用`--print --permission-mode bypassPermissions`替代。
搭配PTY使用`--dangerously-skip-permissions`可能会在确认弹窗后退出。
`--print`模式保留完整工具权限，同时避免交互式确认：

```bash

✅ Correct for Claude Code (no PTY needed)

✅ Claude Code正确用法（无需PTY）

cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'

For background execution: use background:true on the exec tool

后台执行：在exec工具上添加background:true即可

❌ Wrong for Claude Code

❌ Claude Code错误用法

bash pty:true command:"claude --dangerously-skip-permissions 'task'"

undefined

bash pty:true command:"claude --dangerously-skip-permissions 'task'"

undefined

Bash Tool Parameters

Bash工具参数

Parameter	Type	Description
`command`	string	The shell command to run
`pty`	boolean	Use for coding agents! Allocates a pseudo-terminal for interactive CLIs
`workdir`	string	Working directory (agent sees only this folder's context)
`background`	boolean	Run in background, returns sessionId for monitoring
`timeout`	number	Timeout in seconds (kills process on expiry)
`elevated`	boolean	Run on host instead of sandbox (if allowed)

参数	类型	说明
`command`	string	要运行的Shell命令
`pty`	boolean	编码Agent请务必使用！为交互式CLI分配伪终端
`workdir`	string	工作目录（Agent仅能看到该文件夹的上下文）
`background`	boolean	后台运行，返回sessionId用于监控
`timeout`	number	超时时间（单位为秒，超时后杀死进程）
`elevated`	boolean	（权限允许时）在主机而非沙箱中运行

Process Tool Actions (for background sessions)

进程工具操作（用于后台会话）

Action	Description
`list`	List all running/recent sessions
`poll`	Check if session is still running
`log`	Get session output (with optional offset/limit)
`write`	Send raw data to stdin
`submit`	Send data + newline (like typing and pressing Enter)
`send-keys`	Send key tokens or hex bytes
`paste`	Paste text (with optional bracketed mode)
`kill`	Terminate the session

操作	说明
`list`	列出所有正在运行/最近的会话
`poll`	检查会话是否仍在运行
`log`	获取会话输出（支持可选偏移/限制）
`write`	向标准输入发送原始数据
`submit`	发送数据+换行（类似输入后按回车）
`send-keys`	发送按键标识或十六进制字节
`paste`	粘贴文本（支持可选括号模式）
`kill`	终止会话

Quick Start: One-Shot Tasks

快速入门：一次性任务

For quick prompts/chats, create a temp git repo and run:

bash

undefined

对于快速提示/聊天场景，创建临时git仓库后运行：

bash

undefined

Quick chat (Codex needs a git repo!)

快速聊天（Codex需要git仓库支持！）

SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

Or in a real project - with PTY!

或者在实际项目中使用 - 记得开启PTY！

bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"


**Why git init?** Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.

---

bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"


**为什么要git init？** Codex拒绝在受信任的git目录外运行，创建临时仓库可以解决临时工作的运行问题。

---

The Pattern: workdir + background + pty

标准模式：workdir + background + pty

For longer tasks, use background mode with PTY:

bash

undefined

对于耗时更长的任务，使用带PTY的后台模式：

bash

undefined

Start agent in target directory (with PTY!)

在目标目录启动Agent（开启PTY！）

bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"

Returns sessionId for tracking

返回sessionId用于追踪进度

Monitor progress

监控进度

process action:log sessionId:XXX

Check if done

检查是否完成

process action:poll sessionId:XXX

Send input (if agent asks a question)

发送输入（如果Agent提问）

process action:write sessionId:XXX data:"y"

Submit with Enter (like typing "yes" and pressing Enter)

带回车提交（类似输入"yes"后按回车）

process action:submit sessionId:XXX data:"yes"

Kill if needed

按需终止任务

process action:kill sessionId:XXX


**Why workdir matters:** Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).

---

process action:kill sessionId:XXX


**为什么workdir很重要：** Agent会在指定目录下运行，不会乱跑读取无关文件（比如你的soul.md 😅）。

---

Codex CLI

Model:

gpt-5.2-codex

is the default (set in ~/.codex/config.toml)

模型： 默认使用

gpt-5.2-codex

（可在~/.codex/config.toml中设置）

Flags

可用Flag

Flag	Effect
`exec "prompt"`	One-shot execution, exits when done
`--full-auto`	Sandboxed but auto-approves in workspace
`--yolo`	NO sandbox, NO approvals (fastest, most dangerous)

Flag	作用
`exec "prompt"`	一次性执行，完成后自动退出
`--full-auto`	沙箱环境，但工作区内自动批准操作
`--yolo`	无沙箱、无审批（速度最快，风险最高）

Building/Creating

构建/创建场景

bash

undefined

bash

undefined

Quick one-shot (auto-approves) - remember PTY!

快速一次性任务（自动批准） - 记得开启PTY！

bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"

Background for longer work

后台运行处理更长的任务

bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"

undefined

bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"

undefined

Reviewing PRs

PR评审场景

⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder! Clone to temp folder or use git worktree.

bash

undefined

⚠️ 重要提示：绝对不要在OpenClaw自身的项目文件夹中评审PR！ 克隆到临时文件夹或使用git worktree。

bash

undefined

Clone to temp for safe review

克隆到临时目录安全评审

REVIEW_DIR=$(mktemp -d) git clone https://github.com/user/repo.git $REVIEW_DIR cd $REVIEW_DIR && gh pr checkout 130 bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"

Clean up after: trash $REVIEW_DIR

完成后清理：trash $REVIEW_DIR

Or use git worktree (keeps main intact)

或使用git worktree（不影响主分支）

git worktree add /tmp/pr-130-review pr-130-branch bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"

undefined

git worktree add /tmp/pr-130-review pr-130-branch bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"

undefined

Batch PR Reviews (parallel army!)

批量PR评审（并行处理！）

bash

undefined

bash

undefined

Fetch all PR refs first

先拉取所有PR引用

git fetch origin '+refs/pull//head:refs/remotes/origin/pr/'

Deploy the army - one Codex per PR (all with PTY!)

启动批量处理 - 每个PR对应一个Codex实例（全部开启PTY！）

bash pty:true workdir:~~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'" bash pty:true workdir:~~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

Monitor all

监控所有任务

process action:list

Post results to GitHub

把结果发布到GitHub

gh pr comment <PR#> --body "<review content>"

---

gh pr comment <PR#> --body "<review content>"

---

Claude Code

bash

undefined

bash

undefined

Foreground

前台运行

bash workdir:~/project command:"claude --permission-mode bypassPermissions --print 'Your task'"

Background

后台运行

bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'"

---

bash workdir:~/project background:true command:"claude --permission-mode bypassPermissions --print 'Your task'"

---

OpenCode

bash

bash pty:true workdir:~/project command:"opencode run 'Your task'"

bash

bash pty:true workdir:~/project command:"opencode run 'Your task'"

Pi Coding Agent

Pi编码Agent

bash

undefined

bash

undefined

Install: npm install -g @mariozechner/pi-coding-agent

安装：npm install -g @mariozechner/pi-coding-agent

bash pty:true workdir:~/project command:"pi 'Your task'"

Non-interactive mode (PTY still recommended)

非交互模式（仍推荐开启PTY）

bash pty:true command:"pi -p 'Summarize src/'"

Different provider/model

使用其他提供商/模型

bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"


**Note:** Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!

---

bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"


**说明：** Pi现已支持Anthropic提示词缓存（PR #584，2026年1月合并）！

---

Parallel Issue Fixing with git worktrees

基于git worktrees的并行问题修复

For fixing multiple issues in parallel, use git worktrees:

bash

undefined

如果需要并行修复多个问题，使用git worktrees：

bash

undefined

1. Create worktrees for each issue

1. 为每个问题创建worktree

git worktree add -b fix/issue-78 /tmp/issue-78 main git worktree add -b fix/issue-99 /tmp/issue-99 main

2. Launch Codex in each (background + PTY!)

2. 为每个worktree启动Codex（后台运行+开启PTY！）

bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'" bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99 from the approved ticket summary. Implement only the in-scope edits and commit after review.'"

3. Monitor progress

3. 监控进度

process action:list process action:log sessionId:XXX

4. Create PRs after fixes

4. 修复完成后创建PR

cd /tmp/issue-78 && git push -u origin fix/issue-78 gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

5. Cleanup

5. 清理资源

git worktree remove /tmp/issue-78 git worktree remove /tmp/issue-99

---

git worktree remove /tmp/issue-78 git worktree remove /tmp/issue-99

---

⚠️ Rules

⚠️ 使用规则

Use the right execution mode per agent:
- Codex/Pi/OpenCode:
```
pty:true
```
- Claude Code:
```
--print --permission-mode bypassPermissions
```
  (no PTY required)
Respect tool choice - if user asks for Codex, use Codex.
- Orchestrator mode: do NOT hand-code patches yourself.
- If an agent fails/hangs, respawn it or ask the user for direction, but don't silently take over.
Be patient - don't kill sessions because they're "slow"
Monitor with process:log - check progress without interfering
--full-auto for building - auto-approves changes
vanilla for reviewing - no special flags needed
Parallel is OK - run many Codex processes at once for batch work
NEVER start Codex in ~/.openclaw/ - it'll read your soul docs and get weird ideas about the org chart!
NEVER checkout branches in ~/Projects/openclaw/ - that's the LIVE OpenClaw instance!

根据Agent类型选择正确的执行模式：
- Codex/Pi/OpenCode：开启
```
pty:true
```
- Claude Code：使用
```
--print --permission-mode bypassPermissions
```
  （无需PTY）
尊重工具选择 - 如果用户指定用Codex，就使用Codex。
- 编排模式下：不要自己手动编写补丁。
- 如果Agent运行失败/卡住，重新启动或询问用户方向，不要默默接管任务。
保持耐心 - 不要因为会话“运行慢”就直接杀死。
使用process:log监控 - 不干扰任务运行的前提下查看进度。
构建场景使用--full-auto - 自动批准变更。
评审场景使用原生配置 - 不需要特殊Flag。
支持并行运行 - 批量任务可以同时启动多个Codex进程。
绝对不要在~/.openclaw/目录下启动Codex - 它会读取你的私密文档，对组织架构产生奇怪的认知！
绝对不要在~/Projects/openclaw/目录下切换分支 - 这是线上运行的OpenClaw实例！

Progress Updates (Critical)

进度更新（非常重要）

When you spawn coding agents in the background, keep the user in the loop.

Send 1 short message when you start (what's running + where).
Then only update again when something changes:
- a milestone completes (build finished, tests passed)
- the agent asks a question / needs input
- you hit an error or need user action
- the agent finishes (include what changed + where)
If you kill a session, immediately say you killed it and why.

This prevents the user from seeing only "Agent failed before reply" and having no idea what happened.

当你后台启动编码Agent时，要及时同步用户进度。

启动时发送1条短消息说明：运行的任务+运行位置。
只有发生变化时再更新：
- 完成某个里程碑（构建完成、测试通过）
- Agent提问/需要输入
- 遇到错误或需要用户操作
- Agent完成任务（说明变更内容+位置）
如果你杀死了会话，立刻告知用户杀死的原因。

避免用户只看到“Agent运行失败无响应”，完全不知道发生了什么。

Auto-Notify on Completion

完成自动通知

For long-running background tasks, append a wake trigger to your prompt so OpenClaw gets notified immediately when the agent finishes (instead of waiting for the next heartbeat):

... your task here.

When completely finished, run this command to notify me:
openclaw system event --text "Done: [brief summary of what was built]" --mode now

Example:

bash

bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.

对于长时间运行的后台任务，可以在提示词末尾添加唤醒触发逻辑，这样Agent完成时OpenClaw会立刻收到通知（不需要等待下一次心跳）：

... 你的任务描述

全部完成后，运行以下命令通知我：
openclaw system event --text "Done: [任务完成的简短说明]" --mode now

示例：

bash

bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

这会触发即时唤醒事件——Skippy几秒内就会收到通知，不需要等10分钟。

Learnings (Jan 2026)

经验总结（2026年1月）

PTY is essential: Coding agents are interactive terminal apps. Without
```
pty:true
```
, output breaks or agent hangs.
Git repo required: Codex won't run outside a git directory. Use
```
mktemp -d && git init
```
for scratch work.
exec is your friend:
```
codex exec "prompt"
```
runs and exits cleanly - perfect for one-shots.
submit vs write: Use
```
submit
```
to send input + Enter,
```
write
```
for raw data without newline.
Sass works: Codex responds well to playful prompts. Asked it to write a haiku about being second fiddle to a space lobster, got: "Second chair, I code / Space lobster sets the tempo / Keys glow, I follow" 🦞

PTY是必要配置： 编码Agent是交互式终端应用，没有
```
pty:true
```
会导致输出异常或Agent卡住。
必须有Git仓库： Codex不会在git目录外运行，临时任务可以使用
```
mktemp -d && git init
```
创建临时仓库。
exec非常好用：
```
codex exec "prompt"
```
运行完成后会干净退出，非常适合一次性任务。
submit和write的区别： 用
```
submit
```
发送输入+回车，
```
write
```
发送不带换行的原始数据。
趣味提示有效： Codex对 playful 的提示词响应很好，让它写一首关于给太空龙虾当副手的俳句，得到了："Second chair, I code / Space lobster sets the tempo / Keys glow, I follow" 🦞