coding-agent

编码 Agent

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

硬性规则

• 始终使用 background:true 启动。
• Codex 和 OpenCode：使用 pty:true。
• Codex：绝不继承环境中的 CODEX_HOME 或默认的 ~/.codex。使用单独完成认证的编码 Agent 主目录，并将其作用域限定到每条 Codex 命令。
• Claude Code：不使用 PTY；使用 claude --permission-mode bypassPermissions --print。
• 启动前必须先配置实际可用的通知路由。
• 工作进程必须通过 openclaw message send 发送完成或失败消息。
• 不要依赖心跳、系统事件或退出时通知。
• 使用 process 监控；不要无故终止运行缓慢的工作进程。
• 如果用户指定了特定 Agent，请使用该 Agent。
• 如果工作进程失败或挂起，请重新启动或询问；不要默默改为自行编码。
• 绝不要在 ~/Projects/openclaw 中检出分支或运行后台编码 Agent；请使用隔离检出。
• 在进行任何检出或工作树创建之前，将源引用分类为受信任或不受信任。绝不在仓库经批准的不受信任 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 preparation (mandatory before edits):
- canonical remote: <canonicalRemote>
- canonical default branch: <canonicalDefaultBranch>
- target base branch: <targetBaseBranch>
- fetched target base SHA: <targetBaseSha>
- preparation mode: <new work | existing PR/shared branch>
- checkout trust: trusted
- prepared source ref: <canonicalRemote/targetBaseBranch | fetched trusted source ref>
- prepared start SHA: <preparedStartSha>
- isolated worktree: <worktreePath>
- working branch: <branch>
- preparation receipt: <new work: `git fetch --prune <canonicalRemote>` ran immediately before creation from `<canonicalRemote>/<targetBaseBranch>` | existing branch: the canonical target base and trusted source ref were fetched immediately before the worktree was created from `<preparedSourceRef>` at `<preparedStartSha>`>

Before editing, verify the current directory is the isolated worktree and its initial HEAD equals <preparedStartSha>. For new work, that SHA must equal <targetBaseSha>. Never edit the primary checkout. For existing PR/shared-branch work, report divergence and do not rebase, merge, reset, force-push, or otherwise rewrite shared history unless explicitly asked.
Immediately before the final push or PR for newly authored work, run `git fetch --prune <canonicalRemote>` and `git merge-base --is-ancestor <canonicalRemote>/<targetBaseBranch> HEAD`. If the ancestry check fails, update the new branch onto the latest target base, rerun the relevant proof, and only then push without force. For existing PR/shared-branch work, report a failed ancestry check and follow the repository workflow without rewriting the branch.

对于受信任的引用，启动器必须在启动执行编辑的工作进程之前创建并验证工作树；不要将工作树创建委托给该工作进程。经批准的不受信任 PR 工作流则必须负责在其沙箱内部完成检出和工作树创建。绝不要在 ~/Projects/openclaw 中启动工作进程。只读任务和非项目的临时工作不需要 Git 准备内容块。

通知块

将以下结构填入真实值后，附加到每个工作进程提示词中：

Notification route:
- channel: <notifyChannel>
- target: <notifyTarget>
- account: <notifyAccount or omit>
- reply_to: <notifyReplyTo or omit>
- thread_id: <notifyThreadId or omit>

When finished, send exactly one completion or failure message using:
openclaw message send --channel <channel> --target '<target>' --message '<brief result>'
Add --account, --reply-to, or --thread-id only when present above.
Do not use openclaw system event or heartbeat.

如果不存在可信的通知路由，请说明完成时自动通知不可用。

启动方式

先将工作进程提示词写入临时文件。这样，当必需的通知块包含引号或换行符时，可避免 shell 引号处理错误。

PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Task.
<mandatory Git preparation block>
<notification block>
EOF
printf 'prompt file: %s\n' "$PROMPT"

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

在主机上启动第一个 Codex 工作进程之前，请在前台 准备专用认证目录。请勿从环境中的 ~/.codex 复制 auth.json 或其他 凭据；请单独为此目录授权。Codex 会同时限定文件和密钥环 凭据的作用域，范围由 CODEX_HOME 决定。

CODEX_WORKER_HOME="$HOME/.codex-coding-agent"
mkdir -p "$CODEX_WORKER_HOME"
if ! env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
  CODEX_HOME="$CODEX_WORKER_HOME" codex login status >/dev/null 2>&1; then
  printf 'Codex coding-agent login required for %s\n' "$CODEX_WORKER_HOME"
  env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY \
    CODEX_HOME="$CODEX_WORKER_HOME" codex login --device-auth
fi
printf 'Codex worker home: %s\n' "$CODEX_WORKER_HOME"

登录是交互式的前台设置步骤，而不是后台工作进程。 启动命令会再次设置固定且带引号的目录，并移除环境中的 Codex 和 OpenAI 认证覆盖配置。切勿将工作进程目录导出到 OpenClaw Gateway 环境中。

Codex：

bash pty:true background:true workdir:/path/isolated-worktree command:"env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY CODEX_HOME=\"$HOME/.codex-coding-agent\" 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\""

长期 Issue 转 PR 工作

1. 创建或复用一个 GitHub issue，作为持久化规范。
2. 包含 issue URL、仓库、规范远程仓库/默认分支、目标基础分支/SHA、隔离工作树、工作分支、预期 PR、证据和通知路由。
3. 包含必需的 Git 准备块，然后指示工作进程进行实现、测试和执行审查，直到没有已接受的可操作性问题，再创建 PR。
4. 立即返回 issue URL 和 sessionId。
5. 使用 process 监控；如果会话已镜像到 Task Registry，则通过 Task Registry 取消。

临时 Codex

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

SCRATCH=$(mktemp -d)
git -C "$SCRATCH" init
PROMPT=$(mktemp -t openclaw-worker-prompt.XXXXXX)
cat >"$PROMPT" <<'EOF'
Build X.
<notification block>
EOF
printf 'prompt file: %s\n' "$PROMPT"
bash pty:true background:true workdir:$SCRATCH command:"env -u CODEX_API_KEY -u CODEX_ACCESS_TOKEN -u OPENAI_API_KEY CODEX_HOME=\"$HOME/.codex-coding-agent\" codex exec - < \"$PROMPT\""

进程操作

• list：正在运行/最近的会话。
• poll：状态。
• log：输出。
• submit：发送输入 + Enter。
• write：原始 stdin。
• paste：粘贴文本。
• kill：终止。

向用户报告状态

• 说明启动了什么、在哪里启动以及 sessionId。
• 仅在到达里程碑、工作进程提出问题、发生错误、需要用户操作或任务完成时更新。
• 如果已终止，说明原因。