コーディングエージェント (bash-first)

すべてのコーディングエージェント作業に bash を使用します(オプションのバックグラウンドモード付き)。シンプルで効果的です。

[警告] PTYモードが必須です!

コーディングエージェント(Codex、Claude Code、Pi)は 対話的なターミナルアプリケーション であり、正しく動作するために疑似ターミナル(PTY)が必要です。PTYなしでは、出力が破損したり、色が失われたり、エージェントがハングする可能性があります。

コーディングエージェント実行時は常に pty:true を使用してください:

# [OK] 正しい - PTY付き
bash pty:true command:"codex exec 'Your prompt'"

# [失敗] 間違い - PTYなし、エージェントが破損する可能性
bash command:"codex exec 'Your prompt'"

Bashツールのパラメータ

パラメータ	型	説明
command	string	実行するシェルコマンド
pty	boolean	コーディングエージェント用! 対話的なCLI用の疑似ターミナルを割り当てる
workdir	string	作業ディレクトリ(エージェントはこのフォルダのコンテキストのみを見る)
background	boolean	バックグラウンドで実行し、監視用のsessionIdを返す
timeout	number	タイムアウト(秒) (タイムアウト時にプロセスを終了)
elevated	boolean	サンドボックスではなくホストで実行(許可されている場合)

プロセスツールのアクション (バックグラウンドセッション用)

アクション	説明
list	すべての実行中/最近のセッションをリスト表示
poll	セッションがまだ実行中かチェック
log	セッション出力を取得(オプションのオフセット/リミット付き)
write	stdinに生データを送信
submit	データ + 改行を送信(入力とEnter押下のように)
send-keys	キートークンまたは16進バイトを送信
paste	テキストを貼付け(オプションのブラケットモード付き)
kill	セッションを終了

---

クイックスタート: ワンショットタスク

簡単なプロンプト/チャットの場合は、一時的なgitリポジトリを作成して実行してください:

# クイックチャット (Codexはgitリポジトリが必要です!)
SCRATCH=$(mktemp -d) && cd $SCRATCH && git init && codex exec "Your prompt here"

# または実際のプロジェクトで - PTY付き!
bash pty:true workdir:~/Projects/myproject command:"codex exec 'Add error handling to the API calls'"

なぜgit initが必要? Codexは信頼できるgitディレクトリ外での実行を拒否します。一時的なリポジトリを作成することで、スクラッチワーク用にこれを解決できます。

---

パターン: workdir + background + pty

長期タスクの場合は、PTY付きのバックグラウンドモードを使用してください:

# 対象ディレクトリでエージェントを起動 (PTY付き!)
bash pty:true workdir:~/project background:true command:"codex exec --full-auto 'Build a snake game'"
# 追跡用のsessionIdを返します

# 進行状況を監視
process action:log sessionId:XXX

# 完了したかチェック
process action:poll sessionId:XXX

# 入力を送信 (エージェントが質問する場合)
process action:write sessionId:XXX data:"y"

# Enterで送信 (「yes」と入力してEnter押下のように)
process action:submit sessionId:XXX data:"yes"

# 必要に応じて終了
process action:kill sessionId:XXX

workdirが重要な理由: エージェントは集中したディレクトリで起動し、関係のないファイル(soul.mdなど😅)を読むため彷徨いません。

---

Codex CLI

モデル: gpt-5.2-codex がデフォルト(~/.codex/config.toml で設定)

フラグ

フラグ	効果
exec "prompt"	ワンショット実行、完了時に終了
--full-auto	サンドボックス化されているが、ワークスペースで自動承認
--yolo	サンドボックスなし、承認なし(最速、最も危険)

ビルド/作成

# クイックワンショット (自動承認) - PTYを忘れずに!
bash pty:true workdir:~/project command:"codex exec --full-auto 'Build a dark mode toggle'"

# 長期作業向けバックグラウンド
bash pty:true workdir:~/project background:true command:"codex --yolo 'Refactor the auth module'"

PRのレビュー

[警告] 重大: OpenClawの自身のプロジェクトフォルダでPRをレビューしないでください! 一時フォルダにクローンするか、git worktreeを使用してください。

# セーフレビュー用に一時フォルダにクローン
REVIEW_DIR=$(mktemp -d)
git clone https://github.com/user/repo.git $REVIEW_DIR
cd $REVIEW_DIR && gh pr checkout 130
bash pty:true workdir:$REVIEW_DIR command:"codex review --base origin/main"
# その後クリーンアップ: trash $REVIEW_DIR

# またはgit worktreeを使用 (mainを保持)
git worktree add /tmp/pr-130-review pr-130-branch
bash pty:true workdir:/tmp/pr-130-review command:"codex review --base main"

バッチPRレビュー (並列アーミー!)

# 最初にすべてのPRリファレンスをフェッチ
git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'

# アーミーをデプロイ - PR毎に1つのCodex (すべてPTY付き!)
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #86. git diff origin/main...origin/pr/86'"
bash pty:true workdir:~/project background:true command:"codex exec 'Review PR #87. git diff origin/main...origin/pr/87'"

# すべてを監視
process action:list

# 結果をGitHubに投稿
gh pr comment <PR#> --body "<review content>"

---

Claude Code

# 適切なターミナル出力用にPTY付き
bash pty:true workdir:~/project command:"claude 'Your task'"

# バックグラウンド
bash pty:true workdir:~/project background:true command:"claude 'Your task'"

---

OpenCode

bash pty:true workdir:~/project command:"opencode run 'Your task'"

---

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

# インストール: npm install -g @mariozechner/pi-coding-agent
bash pty:true workdir:~/project command:"pi 'Your task'"

# 非対話モード (PTY推奨)
bash pty:true command:"pi -p 'Summarize src/'"

# 異なるプロバイダー/モデル
bash pty:true command:"pi --provider openai --model gpt-4o-mini -p 'Your task'"

注: Piは現在、Anthropicプロンプトキャッシングが有効になっています(PR #584、2026年1月にマージ)!

---

git worktreeを使用した並列イシュー修正

複数のイシューを並列で修正するには、git worktreeを使用してください:

# 1. 各イシュー用のworktreeを作成
git worktree add -b fix/issue-78 /tmp/issue-78 main
git worktree add -b fix/issue-99 /tmp/issue-99 main

# 2. 各フォルダでCodexを起動 (バックグラウンド + PTY!)
bash pty:true workdir:/tmp/issue-78 background:true command:"pnpm install && codex --yolo 'Fix issue #78: <description>. Commit and push.'"
bash pty:true workdir:/tmp/issue-99 background:true command:"pnpm install && codex --yolo 'Fix issue #99: <description>. Commit and push.'"

# 3. 進行状況を監視
process action:list
process action:log sessionId:XXX

# 4. 修正後にPRを作成
cd /tmp/issue-78 && git push -u origin fix/issue-78
gh pr create --repo user/repo --head fix/issue-78 --title "fix: ..." --body "..."

# 5. クリーンアップ
git worktree remove /tmp/issue-78
git worktree remove /tmp/issue-99

---

[警告] ルール

1. 常に pty:true を使用 - コーディングエージェントはターミナルが必要です!
2. ツール選択を尊重 - ユーザーがCodexを要求した場合、Codexを使用します。
   • オーケストレーターモード: 自分でパッチをコード化しないでください。
   • エージェントが失敗/ハングしている場合は、それを再起動するか、ユーザーに指示を求めてください。ただし、静かに引き継ぐことはしません。
3. 忍耐強く - セッションが「遅い」という理由で終了しないでください。
4. process:logで監視 - 干渉することなく進行状況をチェック
5. ビルド用に--full-auto - 変更を自動承認
6. レビュー用にvanilla - 特別なフラグは不要
7. 並列はOK - バッチ作業用に多数のCodexプロセスを同時実行
8. ~/clawd/でCodexを起動しないでください - ソウルドキュメントを読み、組織図について奇妙な考えを持つようになります!
9. ~/Projects/openclaw/でブランチをチェックアウトしないでください - それはLiveなOpenClawインスタンスです!

---

進行状況更新 (重大)

バックグラウンドでコーディングエージェントを起動した場合、ユーザーをループに保ちます。

• 開始時に1つの短いメッセージを送信(実行中の内容と場所)。
• その後、何か変わった場合のみ再度更新:
  • マイルストーンが完了(ビルド完了、テスト合格)
  • エージェントが質問する/入力が必要
  • エラーが発生したり、ユーザー操作が必要
  • エージェントが完了(変更内容と場所を含める)
• セッションを終了した場合は、直ちに終了したこと、および理由を伝えます。

これにより、ユーザーが「エージェントが返信前に失敗しました」というメッセージだけを見て、何が起きたのか分からないのを防ぎます。

---

完了時の自動通知

長期実行のバックグラウンドタスクの場合は、プロンプトにウェイクトリガーを追加して、OpenClawが次のハートビートを待つのではなく、エージェント完了時に直ちに通知されるようにしてください:

... your task here.

When completely finished, run this command to notify me:
openclaw system event --text "Done: [brief summary of what was built]" --mode now

例:

bash pty:true workdir:~/project background:true command:"codex --yolo exec 'Build a REST API for todos.

When completely finished, run: openclaw system event --text \"Done: Built todos REST API with CRUD endpoints\" --mode now'"

これにより、直ちなウェイクイベントがトリガーされます — Skippy は10分ではなく、数秒でpingされます。

---

学習事項 (2026年1月)

• PTYは必須: コーディングエージェントは対話的なターミナルアプリです。pty:trueなしでは、出力が破損したり、エージェントがハングします。
• Gitリポジトリが必要: Codexはgitディレクトリ外では実行されません。スクラッチワーク用に mktemp -d && git init を使用してください。
• execは味方: codex exec "prompt" は実行してきれいに終了します — ワンショット用に完璧です。
• submitとwrite: submit を使用して入力 + Enter を送信、write を改行なしで生データを送信する場合に使用します。
• Sassは機能: Codexは楽しいプロンプトに良く応答します。宇宙ロブスターの脇役について俳句を書くよう求めたところ、以下が返ってきました: "Second chair, I code / Space lobster sets the tempo / Keys glow, I follow"