coding-agent

Coding Agent

用於背景功能建置、PR 審查、大型重構以及 issue 到 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，報告其與重新整理後的目標基礎的差異，並且不要自動 rebase、合併、重置、強制推送或以其他方式改寫共享歷史。
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/共享分支工作，報告差異，並且除非明確要求，否則不要 rebase、合併、重置、強制推送或以其他方式改寫共享歷史。
在對新撰寫的工作進行最終推送或 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 system event 或 heartbeat。

如果沒有可靠的途徑，則說明完成自動通知不可用。

啟動形式

先將工作者提示寫入暫存檔。這可以避免當所需的通知區塊包含引號或換行時出現 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\""

長期的 issue 到 PR 工作

1. 建立/重複使用 GitHub issue 作為持久規格。
2. 包含 issue URL、儲存庫、規範遠端/預設分支、目標基礎分支/SHA、隔離工作樹、工作分支、預期 PR、證明和通知途徑。
3. 包含強制性 Git 準備區塊，然後告訴工作者實作、測試、執行審查直到沒有可接受的可操作發現，並開啟 PR。
4. 立即回傳 issue 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：發送輸入 + Enter。
• write：原始 stdin。
• paste：貼上文字。
• kill：終止。

向使用者報告狀態

• 說明啟動了什麼、在哪裡以及 sessionId。
• 僅在里程碑、工作者提問、錯誤、需要使用者操作或完成時更新。
• 如果被終止，說明原因。