coding-agent

コーディングエージェント

バックグラウンドでの機能実装、PR レビュー、大規模なリファクタリング、issue から 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 で監視します。理由なく低速なワーカーを kill しないでください。
• ユーザーが特定のエージェントを指定した場合は、そのエージェントを使用します。
• ワーカーが失敗/ハングした場合は、再起動するか確認します。代わりに黙って手書きでコーディングしないでください。
• ~/Projects/openclaw でブランチをチェックアウトしたり、バックグラウンドのコーディングエージェントを実行したりしないでください。隔離されたチェックアウトを使用します。
• チェックアウトや worktree の作成前に、ソース ref を信頼済みか信頼できないかに分類します。コントリビューターが制御する ref を、リポジトリで承認された信頼できない PR のサンドボックス/レビューワークフローの外部で実体化しないでください。また、その中で権限バイパスされたワーカーを起動しないでください。
• Git で管理されたプロジェクトを変更するタスクでは、起動前に Git worktree を準備して検証し、以下の正確な Git 準備ブロックをワーカーのプロンプトに含めます。

必須の Git 準備

Git で管理されたプロジェクトを変更する作業のために Codex、Claude Code、または OpenCode を起動する前に:

1. 意図するターゲットリポジトリを確定し、その正規のリモートを選択します。upstream が存在し、そのターゲットと一致する場合は upstream を優先します。そうでなければ origin を検証します。選択したリモートのデフォルトブランチを動的に解決します。明示的なタスクブランチまたは権威ある既存 PR のメタデータからターゲットベースを決定します。その他の共有ブランチについては、設定済み/追跡対象のベースを証明するか、確認します。他のベースが指定されていない新規作業に限り、正規のデフォルトを使用します。リポジトリ、リモート、またはターゲットベースを証明できない場合は停止します。
2. チェックアウトや worktree の作成前に、ソース ref を信頼済みか信頼できないかに分類します。コントリビューターが制御する ref については、リポジトリで承認された信頼できない PR のサンドボックス/レビューワークフローを使用します。これはサンドボックス内で ref の実体化を担う必要があり、そうでなければ停止します。残りの手順と起動形式は信頼済みの ref に限り適用されます。
3. 信頼済みの新規作業では、新しい隔離された worktree を作成する直前に git fetch --prune <canonical> を実行し、<canonical>/<targetBaseBranch> からブランチを作成します。
4. 信頼済みの新規作業では、worktree の初期 HEAD がフェッチしたターゲットベースの SHA と等しいことを検証します。正規のリモート、正規のデフォルトブランチ、ターゲットベースブランチ、ベース SHA、worktree パス、ブランチを記録します。
5. 信頼済みの既存 PR または共有ブランチでは、フェッチしたソースブランチから隔離された worktree を作成する直前に、正規のターゲットベースとソースブランチをフェッチします。そのソース ref と開始 SHA を記録し、更新されたターゲットベースからの分岐を報告し、共有履歴を自動的に rebase、merge、reset、force-push、その他の方法で書き換えないでください。
6. ワーカーは隔離された worktree で起動し、プライマリチェックアウトでは決して起動しないでください。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.

信頼済みの ref の場合、ランチャーは編集ワーカーを開始する前に worktree を作成して検証する必要があります。worktree の作成をそのワーカーに委任しないでください。承認された信頼できない PR のワークフローは、代わりにそのサンドボックス内でチェックアウトと worktree の実体化を担う必要があります。~/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.

信頼できる経路が存在しない場合は、完了時の自動通知は利用できないと伝えてください。

起動形式

まずワーカープロンプトを一時ファイルに書き込んでください。これにより、必須の通知ブロックに引用符や改行が含まれる場合のシェルクォートの不具合を回避できます。

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

同じシェル/セッションから起動する場合は $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 にもミラーされている場合は、そこからキャンセルします。

スクラッチ 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 で開始されたかを伝えます。
• マイルストーン、ワーカーからの質問、エラー、ユーザーの対応が必要な場合、または完了時のみ更新します。
• 強制終了された場合は、その理由を伝えます。