正文内容
编码智能体（Coding Agent）
通过 OpenClaw 使用 Bash 启动并管理 AI 编码智能体（Codex、Claude Code、Kiro CLI、OpenCode、Pi），支持后台进程控制。
必须启用 PTY 模式
编码智能体是交互式终端应用，必须运行在伪终端（PTY）环境中。缺少 PTY 会导致输出错乱或智能体挂起。
务必设置 pty:true：
# 正确 — 启用 PTY bash pty:true command:"codex exec 'Your prompt'" # 错误 — 智能体可能异常或挂起 bash command:"codex exec 'Your prompt'"
工具参考
Bash 参数说明
| 参数 | 类型 | 说明 |
|---|---|---|
command |
string | 要执行的 Shell 命令 |
pty |
boolean | 分配伪终端（编码智能体必需） |
workdir |
string | 工作目录（智能体仅可见该目录下的文件） |
background |
boolean | 后台运行；返回 sessionId 用于后续监控 |
timeout |
number | 超时时间（单位：秒；超时后自动终止进程） |
elevated |
boolean | 在宿主机而非 sandbox 中运行（需权限允许） |
进程操作（仅适用于后台会话）
| 操作 | 说明 |
|---|---|
list |
列出所有正在运行或最近结束的会话 |
poll |
检查指定会话是否仍在运行 |
log |
获取会话输出日志（可选指定偏移量与条数限制） |
write |
向 stdin 写入原始数据（不附加换行符） |
submit |
向 stdin 写入数据并追加换行符（模拟输入后按 Enter） |
send-keys |
发送按键字符或十六进制字节 |
paste |
粘贴文本（可选启用 bracketed paste 模式） |
kill |
终止该会话 |
核心模式：workdir + background + pty
对于耗时较长的任务，应同时启用三项：
# 1. 启动智能体 bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'" # → 返回 sessionId # 2. 监控进度 process action:log sessionId:XXX # 3. 检查是否完成 process action:poll sessionId:XXX # 4. 若智能体提出问题，则发送输入 process action:submit sessionId:XXX data:"yes" # 文本 + Enter process action:write sessionId:XXX data:"y" # 原始按键输入 # 5. 若卡死则终止 process action:kill sessionId:XXX
为何需要 workdir？
智能体会以该目录为根启动，不会访问无关路径下的文件，确保上下文聚焦、安全可控。
Claude Code
# 单次执行 bash pty:true workdir:~/project command:"claude 'Your task'" # 后台运行 bash pty:true workdir:~/project background:true command:"claude 'Your task'"
name: pr-review
description: 审查 Pull Request，检查代码质量、安全漏洞及测试覆盖率。
OpenCode
bash pty:true workdir:~/project command:"opencode run 'Your task'"
并行问题修复（使用 git worktree）
利用隔离的 git worktree 同时修复多个问题：
# 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. 启动智能体（后台 + PTY） bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78:. Commit and push.'" bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99:. Commit and push.'" # 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
进度通知规范
当以后台方式启动编码智能体时，需持续向用户同步关键状态：
- 启动时 —— 发送一条简明消息：说明正在运行什么任务、在哪个目录、使用哪个智能体；
-
状态变更时 —— 仅在发生以下事件时更新：
- 达成重要里程碑（如构建完成、测试通过）；
- 智能体主动提问或等待用户输入；
- 出现错误，或需用户介入处理；
- 智能体正常结束（需说明变更内容及影响范围）；
- 被终止时 —— 立即告知用户已终止，并说明原因（如超时、手动中止、异常卡死等）。
经验总结
-
PTY 不可省略 —— 缺少
pty:true将导致输出异常或智能体挂起； -
Codex 需要 Git 仓库 —— 对于临时开发任务，可使用
mktemp -d && git init初始化空仓库； -
单次任务推荐
exec——codex exec "prompt"可保证执行完毕后干净退出； -
submit与write的区别 ——submit自动添加换行符，适合提交完整输入；write发送原始字节流，适用于模拟按键等精细控制； -
技能自动匹配 —— 无需
/命令触发；Kiro 会根据用户请求自动匹配技能描述； -
复杂构建前先规划 —— 使用
/plan可显著提升多步骤功能开发效率，提前明确需求与边界。