coding-agent

编码代理

用于后台功能构建、PR 审查、大型重构以及从问题到 PR 的循环。不要用于简单编辑、只读查询、ACP 线程绑定工作，或任何在 ~/.openclaw、$OPENCLAW_STATE_DIR 或活跃的 OpenClaw 状态目录内的运行。

硬性规则

• 始终以 background:true 启动。
• Codex 和 OpenCode：使用 pty:true。
• Claude Code：不使用 PTY；使用 claude --permission-mode bypassPermissions --print。
• 在生成工作进程之前，捕获一个真实的通知路由。
• 工作进程必须通过 openclaw message send 发送完成/失败消息。
• 不要依赖心跳、系统事件或退出通知。
• 使用 process 监控；不要无故杀死慢速工作进程。
• 如果用户指定了某个代理，则使用该代理。
• 如果工作进程失败/挂起，重新生成或询问；不要默默手动编码代替。
• 永远不要在 ~/Projects/openclaw 中检出分支或运行后台编码代理；使用隔离的检出。
• 在任何检出或工作树创建之前，将源引用分类为可信或不可信。绝不要在仓库批准的不可信 PR 沙箱/审查工作流之外实例化贡献者控制的引用，也绝不要在其中启动权限绕过的工作进程。
• 对于修改 Git 项目的任务，在启动前准备并验证 Git 工作树，然后将确切的 Git 准备块包含在工作进程提示中。

强制 Git 准备

在启动 Codex、Claude Code 或 OpenCode 进行修改 Git 项目的工作之前：

1. 确定目标仓库，然后选择其规范远程。优先使用 upstream（如果存在且匹配目标）；否则验证 origin。动态解析所选远程的默认分支。从明确的任务分支或权威的现有 PR 元数据确定目标基础；对于其他共享分支，证明配置/跟踪的基础或询问。仅在没有指定其他基础的新工作中使用规范默认分支。如果无法证明仓库、远程或目标基础，则停止。
2. 在任何检出或工作树创建之前，将源引用分类为可信或不可信。对于贡献者控制的引用，使用仓库批准的不可信 PR 沙箱/审查工作流，该工作流必须拥有沙箱内的引用实例化，否则停止。后续步骤和启动形式仅适用于可信引用。
3. 对于可信的新工作，在从 <canonical>/<targetBaseBranch> 创建新的隔离工作树和分支之前，立即运行 git fetch --prune <canonical>。
4. 对于可信的新工作，验证工作树的初始 HEAD 等于获取的目标基础 SHA。记录规范远程、规范默认分支、目标基础分支、基础 SHA、工作树路径和分支。
5. 对于可信的现有 PR 或共享分支，在从获取的源分支创建隔离工作树之前，立即获取规范目标基础和源分支。记录该源引用和起始 SHA，报告其与刷新后的目标基础的分歧，不要自动变基、合并、重置、强制推送或以其他方式重写共享历史。
6. 在隔离的工作树中启动工作进程，绝不在主检出中。对于 OpenClaw，~/Projects/openclaw 下的主检出仍然禁止。

对于修改 Git 项目的任务，将以下块附加到工作进程提示中，并填入实际值：

Git 准备（编辑前强制）：
- 规范远程：<canonicalRemote>
- 规范默认分支：<canonicalDefaultBranch>
- 目标基础分支：<targetBaseBranch>
- 获取的目标基础 SHA：<targetBaseSha>
- 准备模式：<新工作 | 现有 PR/共享分支>
- 检出信任：可信
- 准备的源引用：<canonicalRemote/targetBaseBranch | 获取的可信源引用>
- 准备的起始 SHA：<preparedStartSha>
- 隔离工作树：<worktreePath>
- 工作分支：<branch>
- 准备收据：<新工作：在从 `<canonicalRemote>/<targetBaseBranch>` 创建之前立即运行了 `git fetch --prune <canonicalRemote>` | 现有分支：在从 `<preparedSourceRef>` 在 `<preparedStartSha>` 创建工作树之前立即获取了规范目标基础和可信源引用>

在编辑之前，验证当前目录是隔离工作树，并且其初始 HEAD 等于 <preparedStartSha>。对于新工作，该 SHA 必须等于 <targetBaseSha>。永远不要编辑主检出。对于现有 PR/共享分支工作，报告分歧，不要变基、合并、重置、强制推送或以其他方式重写共享历史，除非明确要求。
在最终推送或为新创作的工作创建 PR 之前，立即运行 `git fetch --prune <canonicalRemote>` 和 `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`。如果祖先检查失败，将新分支更新到最新的目标基础，重新运行相关证明，然后才推送而不强制。对于现有 PR/共享分支工作，报告祖先检查失败，并遵循仓库工作流而不重写分支。

对于可信引用，启动器必须在启动编辑工作进程之前创建并验证工作树；不要将工作树创建委托给该工作进程。批准的不可信 PR 工作流必须在其沙箱内拥有检出和工作树实例化。永远不要在 ~/Projects/openclaw 中启动工作进程。只读任务和非项目临时工作不需要 Git 准备块。

通知块

将以下形状附加到每个工作进程提示中，并填入实际值：

通知路由：
- 通道：<notifyChannel>
- 目标：<notifyTarget>
- 账户：<notifyAccount 或省略>
- 回复到：<notifyReplyTo 或省略>
- 线程 ID：<notifyThreadId 或省略>

完成后，使用以下命令发送一条完成或失败消息：
openclaw message send --channel <channel> --target '<target>' --message '<简要结果>'
仅当上面存在时才添加 --account、--reply-to 或 --thread-id。
不要使用 openclaw 系统事件或心跳。

如果没有可信的路由，则说明完成自动通知不可用。

启动形式

首先将工作进程提示写入临时文件。这可以避免当必需的通知块包含引号或换行符时出现 shell 引用错误。

PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
任务。
<强制 Git 准备块>
<通知块>
EOF
printf '提示文件：%s\n' "$PROMPT"

在同一个 shell/会话中启动时使用 $PROMPT。如果使用单独的工具调用，则替换为打印的路径。以下启动形式仅适用于可信检出；不可信的贡献者引用需要仓库批准的沙箱/审查工作流。

Codex：

bash pty:true background:true workdir:/path/isolated-worktree command:"codex exec - < \"$PROMPT\""

Claude Code：

bash background:true workdir:/path/isolated-worktree command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\""

OpenCode：

bash pty:true background:true workdir:/path/isolated-worktree command:"opencode run < \"$PROMPT\""

长期问题到 PR 的工作

1. 创建/重用 GitHub 问题作为持久规范。
2. 包含问题 URL、仓库、规范远程/默认分支、目标基础分支/SHA、隔离工作树、工作分支、预期 PR、证明和通知路由。
3. 包含强制 Git 准备块，然后告诉工作进程实现、测试、运行审查直到没有可接受的可操作发现，并打开 PR。
4. 立即返回问题 URL 和 sessionId。
5. 使用 process 监控；如果任务注册表中镜像了，则通过其取消。

临时 Codex

Codex 需要一个可信的 git 仓库。这个一次性脚手架不是项目工作，也没有规范远程，因此 Git 准备块不适用：

SCRATCH=$(mktemp -d)
git -C "$SCRATCH" init
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
构建 X。
<通知块>
EOF
printf '提示文件：%s\n' "$PROMPT"
bash pty:true background:true workdir:$SCRATCH command:"codex exec - < \"$PROMPT\""

进程操作

• list：运行中/最近的会话。
• poll：状态。
• log：输出。
• submit：发送输入 + 回车。
• write：原始标准输入。
• paste：粘贴文本。
• kill：终止。

向用户报告状态

• 说明启动了什么、在哪里以及 sessionId。
• 仅在里程碑、工作进程问题、错误、需要用户操作或完成时更新。
• 如果被杀死，说明原因。