程式碼開發代理

程式碼開發代理 是做什麼的？

用於背景功能建置、PR 審查、大型重構和議題到 PR 循環。請勿用於簡單編輯、唯讀查詢、ACP 繫結執行緒工作，或任何在 ~/.openclaw、$OPENCLAW_STATE_DIR 或活動中的 OpenClaw 狀態目錄內執行的操作。

嚴格規則

• 始終以 background:true 啟動。
• Codex 和 OpenCode：使用 pty:true。
• Codex：絕不繼承環境中的 CODEX_HOME 或預設的 ~/.codex。使用單獨驗證的編碼代理家目錄，並將其範圍限定在每個 Codex 命令。
• 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>
- 準備收據: <新工作: `git fetch --prune <canonicalRemote>` 在從 `<canonicalRemote>/<targetBaseBranch>` 建立之前立即執行 | 現有分支: 規範目標基礎和受信任來源引用在從 `<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 <頻道> --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 工作者之前，請在前景準備一個專用的驗證家目錄。不要從環境中的 ~/.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 編碼代理登入 %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 工作者家目錄: %s\n' "$CODEX_WORKER_HOME"

登入是一個互動式前景設定步驟，不是背景工作者。啟動命令重複固定、帶引號的家目錄並移除環境中的 Codex 和 OpenAI 驗證覆寫。絕不將工作者家目錄匯出到 OpenClaw 閘道環境。

Codex：

bash pty:true background:true workdir:/路徑/隔離工作樹 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:/路徑/隔離工作樹 command:"claude --permission-mode bypassPermissions --print < \"$PROMPT\""

OpenCode：

bash pty:true background:true workdir:/路徑/隔離工作樹 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:"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：原始標準輸入。
• paste：貼上文字。
• kill：終止。

狀態通知使用者

• 告知已啟動的內容、位置和 sessionId。
• 僅在里程碑、工作者問題、錯誤、需要使用者操作或完成時更新。
• 如果被終止，說明原因。