codex

Codex CLI

Hermes ターミナルから Codex にコーディングタスクを委任します。Codex は OpenAI の自律型コーディングエージェント CLI です。

使用する場面

• 機能の開発
• リファクタリング
• PR レビュー
• 複数の issue の一括修正

codex CLI と git リポジトリが必要です。

前提条件

• Codex がインストールされていること：npm install -g @openai/codex
• OpenAI 認証が設定されていること：OPENAI_API_KEY または Codex CLI のログインフローで取得した OAuth 認証情報
• git リポジトリ内で実行すること — Codex はリポジトリ外での実行を拒否します
• ターミナル呼び出しでは pty=true を使用すること — Codex は対話型ターミナルアプリです

Hermes 自体では、model.provider: openai-codex を設定し、hermes auth add openai-codex を実行すると、~/.hermes/auth.json の Hermes 管理下にある Codex OAuth を使用します。スタンドアロンの Codex CLI では、有効な CLI OAuth セッションが ~/.codex/auth.json に保存されている場合があります。OPENAI_API_KEY が設定されていないことだけを理由に、Codex の認証がないと判断しないでください。

単発タスク

terminal(command="codex exec 'Add dark mode toggle to settings'", workdir="~/project", pty=true)

一時的な作業の場合（Codex には git リポジトリが必要です）：

terminal(command="cd $(mktemp -d) && git init && codex exec 'Build a snake game in Python'", pty=true)

バックグラウンドモード（長時間のタスク）

# Start in background with PTY
terminal(command="codex exec --sandbox workspace-write 'Refactor the auth module'", workdir="~/project", background=true, pty=true)
# Returns session_id

# Monitor progress
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

# Send input if Codex asks a question
process(action="submit", session_id="<id>", data="yes")

# Kill if needed
process(action="kill", session_id="<id>")

主なフラグ

フラグ	効果
exec "prompt"	単発で実行し、完了すると終了します
--sandbox workspace-write (-s)	サンドボックス内で実行し、ワークスペース内のファイル変更を自動承認します（推奨される自動ビルドモードです）
--dangerously-bypass-approvals-and-sandbox	サンドボックスも承認も使用しません（最速ですが、最も危険です。--yolo も引き続き非公開エイリアスとして使用できます）
--sandbox danger-full-access	Codex のサンドボックスを無効にします。ホストサービスのコンテキストによって bubblewrap が正常に動作しない場合に便利です

非推奨： --full-auto は引き続き動作しますが、現在の CLI では代わりに --sandbox workspace-write を使用するよう警告されます。

Hermes ゲートウェイに関する注意点

Hermes のゲートウェイ／サービスのコンテキスト（たとえば、Telegram から操作するエージェントセッション）で Codex CLI を呼び出すと、同じコマンドがユーザーの対話型シェルでは動作しても、Codex の workspace-write サンドボックスが失敗する場合があります。典型的な症状として、setting up uid map: Permission denied や loopback: Failed RTM_NEWADDR: Operation not permitted などの bubblewrap／ユーザーネームスペースのエラーが発生します。

そのような状況では、代わりに以下を使用してください。

codex exec --sandbox danger-full-access "<task>"

安全性は、プロセスの境界で確保してください。具体的には、workdir を明示し、起動前に git の状態をクリーンにし、タスクのプロンプトを限定し、git diff を確認し、対象を絞ったテストを実行したうえで、広範な変更をコミットする前に人間／エージェントの確認を得てください。

PR レビュー

安全にレビューできるよう、一時ディレクトリにクローンします。

terminal(command="REVIEW=$(mktemp -d) && git clone https://github.com/user/repo.git $REVIEW && cd $REVIEW && gh pr checkout 42 && codex review --base origin/main", pty=true)

Worktree を使った issue の並列修正

# Create worktrees
terminal(command="git worktree add -b fix/issue-78 ~/.hermes/cache/scratch/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 ~/.hermes/cache/scratch/issue-99 main", workdir="~/project")

# Launch Codex in each
terminal(command="codex --sandbox workspace-write exec 'Fix issue #78: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-78", background=true, pty=true)
terminal(command="codex --sandbox workspace-write exec 'Fix issue #99: <description>. Commit when done.'", workdir="~/.hermes/cache/scratch/issue-99", background=true, pty=true)

# Monitor
process(action="list")

# After completion, push and create PRs
terminal(command="cd ~/.hermes/cache/scratch/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")

# Cleanup
terminal(command="git worktree remove ~/.hermes/cache/scratch/issue-78", workdir="~/project")

PR の一括レビュー

# Fetch all PR refs
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")

# Review multiple PRs in parallel
terminal(command="codex exec 'Review PR #86. git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec 'Review PR #87. git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)

# Post results
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")

ルール

1. 必ず pty=true を使用すること — Codex は対話型ターミナルアプリのため、PTY がないとハングします
2. git リポジトリが必要 — Codex は git ディレクトリの外では実行できません。一時作業には mktemp -d && git init を使用してください
3. 単発タスクには exec を使用すること — codex exec "prompt" は実行後、正常に終了します
4. ビルドには --sandbox workspace-write を使用すること — サンドボックス内の変更が自動承認されます（--full-auto は非推奨です）
5. 長時間のタスクはバックグラウンドで実行すること — background=true を使用し、process ツールで監視します
6. 干渉しないこと — poll／log で監視し、長時間かかるタスクは辛抱強く待ちます
7. 並列実行して問題ありません — 一括作業では、複数の Codex プロセスを同時に実行できます