Coding Agent (bash-first)
Use bash (with optional background mode) for all coding agent work. Simple and effective.
⚠️ PTY Mode: Codex/Pi/OpenCode yes, Claude Code no
For Codex, Pi, and OpenCode, PTY is still required (interactive terminal apps):
CODEBLOCK0
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:
CODEBLOCK1
Bash Tool Parameters
| Parameter | Type | Description |
|---|
| INLINECODE4 | string | The shell command to run |
| INLINECODE5 |
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 |
|---|
| INLINECODE10 | List all running/recent sessions |
| INLINECODE11 |
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:
CODEBLOCK2
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:
CODEBLOCK3
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 |
|---|
| INLINECODE19 | One-shot execution, exits when done |
| INLINECODE20 |
Sandboxed but auto-approves in workspace |
|
--yolo | NO sandbox, NO approvals (fastest, most dangerous) |
Building/Creating
CODEBLOCK4
Reviewing PRs
⚠️ CRITICAL: Never review PRs in OpenClaw's own project folder!
Clone to temp folder or use git worktree.
CODEBLOCK5
Batch PR Reviews (parallel army!)
CODEBLOCK6
Claude Code
CODEBLOCK7
OpenCode
CODEBLOCK8
Pi Coding Agent
CODEBLOCK9
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:
CODEBLOCK10
⚠️ Rules
- 1. Use the right execution mode per agent:
- Codex/Pi/OpenCode:
pty:true
- Claude Code:
--print --permission-mode bypassPermissions (no PTY required)
- 2. 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):
CODEBLOCK11
Example:
CODEBLOCK12
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/Pi/OpenCode 需要，Claude Code 不需要
对于 Codex、Pi 和 OpenCode，仍需 PTY（交互式终端应用）：
bash
✅ Codex/Pi/OpenCode 正确用法
bash pty:true command:codex exec 你的提示
对于 Claude Code（claude CLI），请改用 --print --permission-mode bypassPermissions。
使用 PTY 的 --dangerously-skip-permissions 可能在确认对话框后退出。
--print 模式保持完整的工具访问权限，避免交互式确认：
bash
✅ Claude Code 正确用法（无需 PTY）
cd /path/to/project && claude --permission-mode bypassPermissions --print 你的任务
后台执行：在 exec 工具上使用 background:true
❌ Claude Code 错误用法
bash pty:true command:claude --dangerously-skip-permissions task
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 提示 | 一次性执行，完成后退出 |
| --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
前台
bash workdir:~/project command:claude --permission-mode bypassPermissions --print 你的任务
后台
bash workdir:~/project background:true command:claude --permission-mode bypassPermissions --print 你的任务
OpenCode
bash
bash pty:true workdir:~/project command:opencode run 你的任务
Pi Coding Agent
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 修复：... --body ...
5. 清理
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99
⚠️ 规则
- 1. 为每个代理使用正确的执行模式：
- Codex/Pi/Open
