coding-agent

编码智能体（Coding Agent）

所有编码智能体任务均使用 bash（可选后台模式）执行。

PTY：Codex / Pi / OpenCode 需启用，Claude Code 不需要

对于 Codex、Pi 和 OpenCode，必须启用 PTY（用于交互式终端类应用）：

# Codex / Pi / OpenCode
bash pty:true command:"codex exec 'Your prompt'"

对于 Claude Code（claude CLI），请改用 --print --permission-mode bypassPermissions 参数。  
--print 模式可保留完整的工具访问权限，并跳过交互式确认：

# Claude Code（无需 PTY）
cd /path/to/project && claude --permission-mode bypassPermissions --print 'Your task'

# 后台执行：在 exec 工具中设置 background:true

Bash 工具参数说明

进程（Process）工具操作说明

标准模式：workdir + background + pty

针对耗时较长的任务，请始终启用后台模式：

# 在目标项目目录中启动智能体
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# 返回 sessionId，可用于后续跟踪

# 监控进度
process action:log sessionId:XXX

# 查询是否完成
process action:poll sessionId:XXX

# 若智能体发起提问，发送响应
process action:submit sessionId:XXX data:"yes"

# 如需中止，可手动终止
process action:kill sessionId:XXX

为何 workdir 至关重要？  
智能体将在指定目录中启动，其上下文感知范围被严格限制在此路径内，从而避免误读无关文件。

OpenCode

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

Pi

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

# 非交互模式（仅输出结果，不等待用户输入）
bash pty:true command:"pi -p 'Summarize src/'"

# 指定不同 provider 或 model
bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"

行为准则（Rules）

1. 按智能体类型选择正确执行模式：Claude Code 使用 --print --permission-mode bypassPermissions（禁用 PTY）；Codex / Pi / OpenCode 必须启用 pty:true
2. 尊重用户指定的智能体：若用户明确要求某款智能体，请严格使用，不得静默替换
3. 采用编排（Orchestrator）模式：当任务已委托给智能体时，切勿自行手写补丁或修改代码
4. 保持耐心：不要因执行缓慢就贸然终止会话；应先通过 process:log 查看当前状态
5. 允许多任务并行：批量任务可同时启动多个智能体并行处理
6. 禁止在 OpenClaw workspace 目录中启动智能体：否则它们可能读取 soul 文档，导致角色认知混乱（分不清谁是主控方）
7. 禁止在正在运行的 OpenClaw 项目目录中切换分支（checkout）：该目录即为生产环境实例所在位置

完成自动通知（Auto-Notify on Completion）

对于长时间运行的后台任务，可在 Prompt 末尾添加唤醒指令，使 Miki 在智能体完成时立即收到通知：

... your task here.

When completely finished, run:
openclaw system event --text "Done: [brief summary]" --mode now

示例：

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" --mode now'"

补充说明（Notes）

• PTY 对 Codex / Pi / OpenCode 至关重要：缺失 PTY 将导致输出异常或智能体挂起
• Codex 需要 Git 仓库环境：临时工作可使用 mktemp -d && git init 创建空白仓库
• exec 是最干净的调用方式：codex exec "prompt" 执行完毕即退出，适合一次性任务
• submit 与 write 的区别：submit 自动附加换行符（等效于输入后回车）；write 发送原始数据，不添加任何额外字符

命令行