Coding Agent (bash-first)
Use bash (with optional background mode) for all coding agent work. Simple and effective.
⚠️ PTY Mode Required!
Coding agents (Codex, Claude Code, Pi) are interactive terminal applications that need a pseudo-terminal (PTY) to work correctly. Without PTY, you'll get broken output, missing colors, or the agent may hang.
Always use pty:true when running coding agents:
CODEBLOCK0
Bash Tool Parameters
| Parameter | Type | Description |
|---|
| INLINECODE1 | string | The shell command to run |
| INLINECODE2 |
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) |
Process Tool Actions (for background sessions)
| Action | Description |
|---|
| INLINECODE7 | List all running/recent sessions |
| INLINECODE8 |
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 |
Quick Start: One-Shot Tasks
For quick prompts/chats, create a temp git repo and run:
CODEBLOCK1
Why git init? Codex refuses to run outside a trusted git directory. Creating a temp repo solves this for scratch work.
The Pattern: workdir + background + pty
For longer tasks, use background mode with PTY:
CODEBLOCK2
Why workdir matters: Agent wakes up in a focused directory, doesn't wander off reading unrelated files (like your soul.md 😅).
Codex CLI
Model: gpt-5.2-codex is the default (set in ~/.codex/config.toml)
Flags
| Flag | Effect |
|---|
| INLINECODE16 | One-shot execution, exits when done |
| INLINECODE17 |
Sandboxed but auto-approves in workspace |
|
--yolo | NO sandbox, NO approvals (fastest, most dangerous) |
Building/Creating
CODEBLOCK3
Reviewing PRs
⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!
Clone to temp folder or use git worktree.
CODEBLOCK4
Batch PR Reviews (parallel army!)
CODEBLOCK5
Claude Code
CODEBLOCK6
OpenCode
CODEBLOCK7
Pi Coding Agent
CODEBLOCK8
Note: Pi now has Anthropic prompt caching enabled (PR #584, merged Jan 2026)!
Parallel Issue Fixing with git worktrees
For fixing multiple issues in parallel, use git worktrees:
CODEBLOCK9
⚠️ Rules
- 1. Always use pty:true - coding agents need a terminal!
- 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.
- 3. 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!
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.
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):
CODEBLOCK10
Example:
CODEBLOCK11
This triggers an immediate wake event — Skippy gets pinged in seconds, not 10 minutes.
Learnings (Jan 2026)
- - 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" 🦞
Coding Agent (bash优先)
所有编码代理工作请使用 bash（可选用后台模式）。简单高效。
⚠️ 需要PTY模式！
编码代理（Codex、Claude Code、Pi）是交互式终端应用，需要伪终端（PTY）才能正常工作。没有PTY，你会得到损坏的输出、缺失的颜色，或者代理可能会挂起。
运行编码代理时始终使用 pty:true：
bash
✅ 正确 - 使用PTY
bash pty:true command:codex exec 你的提示词
❌ 错误 - 没有PTY，代理可能崩溃
bash command:codex exec 你的提示词
Bash工具参数
| 参数 | 类型 | 描述 |
|---|
| command | string | 要运行的shell命令 |
| pty |
boolean |
用于编码代理！为交互式CLI分配伪终端 |
| workdir | string | 工作目录（代理只能看到此文件夹的上下文） |
| background | boolean | 后台运行，返回sessionId用于监控 |
| timeout | number | 超时秒数（到期后终止进程） |
| elevated | boolean | 在主机而非沙箱中运行（如果允许） |
进程工具操作（用于后台会话）
| 操作 | 描述 |
|---|
| list | 列出所有运行中/最近的会话 |
| poll |
检查会话是否仍在运行 |
| log | 获取会话输出（可选偏移量/限制） |
| write | 向stdin发送原始数据 |
| submit | 发送数据+换行（如打字后按回车） |
| send-keys | 发送按键令牌或十六进制字节 |
| paste | 粘贴文本（可选括号粘贴模式） |
| kill | 终止会话 |
快速开始：一次性任务
对于快速提示/聊天，创建一个临时git仓库并运行：
bash
快速聊天（Codex需要git仓库！）
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec 你的提示词
或在真实项目中 - 使用PTY！
bash pty:true workdir:~/Projects/myproject command:codex exec 为API调用添加错误处理
为什么要git init？ Codex拒绝在受信任的git目录之外运行。创建临时仓库可以解决临时工作的问题。
模式：workdir + background + pty
对于较长的任务，使用带PTY的后台模式：
bash
在目标目录中启动代理（使用PTY！）
bash pty:true workdir:~/project background:true command:codex exec --full-auto 构建一个贪吃蛇游戏
返回sessionId用于跟踪
监控进度
process action:log sessionId:XXX
检查是否完成
process action:poll sessionId:XXX
发送输入（如果代理提问）
process action:write sessionId:XXX data:y
按回车提交（如输入yes后按回车）
process action:submit sessionId:XXX data:yes
如果需要则终止
process action:kill sessionId:XXX
为什么workdir重要： 代理在聚焦的目录中启动，不会乱读无关文件（比如你的灵魂.md 😅）。
Codex CLI
模型： gpt-5.2-codex 是默认模型（在 ~/.codex/config.toml 中设置）
标志
| 标志 | 效果 |
|---|
| exec prompt | 一次性执行，完成后退出 |
| --full-auto |
沙箱化但在工作空间中自动批准 |
| --yolo | 无沙箱，无批准（最快，最危险） |
构建/创建
bash
快速一次性（自动批准）- 记住使用PTY！
bash pty:true workdir:~/project command:codex exec --full-auto 构建一个深色模式切换按钮
后台运行较长时间的工作
bash pty:true workdir:~/project background:true command:codex --yolo 重构认证模块
审查PR
⚠️ 关键：绝不要在OpenClaw自己的项目文件夹中审查PR！
克隆到临时文件夹或使用git worktree。
bash
克隆到临时文件夹进行安全审查
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
清理：trash $REVIEW_DIR
或使用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
批量PR审查（并行大军！）
bash
先获取所有PR引用
git fetch origin +refs/pull/
/head:refs/remotes/origin/pr/
部署大军 - 每个PR一个Codex（全部使用PTY！）
bash pty:true workdir:~/project background:true command:codex exec 审查PR #86。git diff origin/main...origin/pr/86
bash pty:true workdir:~/project background:true command:codex exec 审查PR #87。git diff origin/main...origin/pr/87
监控所有
process action:list
将结果发布到GitHub
gh pr comment
--body <审查内容>
Claude Code
bash
使用PTY以获得正确的终端输出
bash pty:true workdir:~/project command:claude 你的任务
后台运行
bash pty:true workdir:~/project background:true command:claude 你的任务
OpenCode
bash
bash pty:true workdir:~/project command:opencode run 你的任务
Pi编码代理
bash
安装：npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:pi 你的任务
非交互模式（仍建议使用PTY）
bash pty:true command:pi -p 总结 src/
不同的提供商/模型
bash pty:true command:pi --provider openai --model gpt-4o-mini -p 你的任务
注意： Pi现在已启用Anthropic提示缓存（PR #584，2026年1月合并）！
使用git worktrees并行修复问题
要并行修复多个问题，请使用git worktrees：
bash
1. 为每个问题创建工作树
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main
2. 在每个工作树中启动Codex（后台 + PTY！）
bash pty:true workdir:/tmp/issue-78 background:true command:pnpm install && codex --yolo 修复问题 #78：<描述>。提交并推送。
bash pty:true workdir:/tmp/issue-99 background:true command:pnpm install && codex --yolo 根据已批准的工单摘要修复问题 #99。仅实现范围内的编辑，审查后提交。
3. 监控进度
process action:list
process action:log sessionId:XXX
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. 清理
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99
⚠️ 规则
- 1. 始终使用 pty:true - 编码代理需要终端！
- 尊重工具选择 - 如果用户要求使用Codex，就使用Codex。
- 编排器模式：不要自己手写补丁。
- 如果代理失败/挂起，重新生成它或询问用户方向，但不要默默接管。
- 3. 保持耐心 - 不要因为慢就终止会话
- 使用 process:log 监控 - 在不干扰的情况下检查进度
- 构建时使用 --full-auto - 自动批准更改
- 审查时使用
