Codex CLI
コーディングタスクを Hermes ターミナル経由で Codex に委任します。Codex は OpenAI の自律コーディングエージェント CLI です。
使用するタイミング
- 機能開発
- リファクタリング
- PR レビュー
- バグの一括修正
Codex CLI と Git リポジトリが必要です。
前提条件
- Codex のインストール:
npm install -g @openai/codex - OpenAI 認証の構成:
OPENAI_API_KEYまたは Codex CLI ログインフローからの Codex OAuth 認証情報のいずれか - Git リポジトリ内で実行する必要があります — Codex は Git リポジトリ外では動作しません
- ターミナル呼び出しで
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 '設定にダークモードトグルを追加'", workdir="~/project", pty=true)
スクラッチ作業の場合（Codex は Git リポジトリが必要です）:
terminal(command="cd $(mktemp -d) && git init && codex exec 'Python でスネークゲームを作成'", pty=true)
バックグラウンドモード（長時間タスク）
# PTY 付きでバックグラウンド開始
terminal(command="codex exec --full-auto '認証モジュールをリファクタリング'", workdir="~/project", background=true, pty=true)
# session_id が返されます
# 進捗を監視
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")
# Codex が質問した場合に入力送信
process(action="submit", session_id="<id>", data="yes")
# 必要に応じて強制終了
process(action="kill", session_id="<id>")
主要フラグ
| フラグ | 効果 |
|---|---|
exec "prompt" | ワンショット実行、完了後に終了 |
--full-auto | サンドボックス内だが、ワークスペース内のファイル変更を自動承認 |
--yolo | サンドボックスなし、承認なし（最速、最も危険） |
--sandbox danger-full-access | Codex サンドボックスなし。ホストサービスのコンテキストが bubblewrap を破壊する場合に有用 |
Hermes ゲートウェイに関する注意点
Hermes ゲートウェイ / サービスのコンテキスト（例：Telegram 駆動のエージェントセッション）から Codex CLI を呼び出す場合、同じコマンドがユーザーの対話型シェルで動作しても、Codex の workspace-write サンドボックス化が失敗する可能性があります。典型的な症状は、bubblewrap / ユーザーネームスペースエラー（例：setting up uid map: Permission denied や loopback: Failed RTM_NEWADDR: Operation not permitted）です。
そのようなコンテキストでは、以下を優先して使用してください:
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)
ワークツリーを使った並列 Issue 修正
# ワークツリーを作成
terminal(command="git worktree add -b fix/issue-78 /tmp/issue-78 main", workdir="~/project")
terminal(command="git worktree add -b fix/issue-99 /tmp/issue-99 main", workdir="~/project")
# 各ワークツリーで Codex を起動
terminal(command="codex --yolo exec 'Issue #78 を修正: <説明>。完了したらコミット。'", workdir="/tmp/issue-78", background=true, pty=true)
terminal(command="codex --yolo exec 'Issue #99 を修正: <説明>。完了したらコミット。'", workdir="/tmp/issue-99", background=true, pty=true)
# 監視
process(action="list")
# 完了後、プッシュして PR を作成
terminal(command="cd /tmp/issue-78 && git push -u origin fix/issue-78")
terminal(command="gh pr create --repo user/repo --head fix/issue-78 --title 'fix: ...' --body '...'")
# クリーンアップ
terminal(command="git worktree remove /tmp/issue-78", workdir="~/project")
バッチ PR レビュー
# すべての PR 参照を取得
terminal(command="git fetch origin '+refs/pull/*/head:refs/remotes/origin/pr/*'", workdir="~/project")
# 複数の PR を並列レビュー
terminal(command="codex exec 'PR #86 をレビュー。git diff origin/main...origin/pr/86'", workdir="~/project", background=true, pty=true)
terminal(command="codex exec 'PR #87 をレビュー。git diff origin/main...origin/pr/87'", workdir="~/project", background=true, pty=true)
# 結果を投稿
terminal(command="gh pr comment 86 --body '<review>'", workdir="~/project")
ルール
- 常に
pty=trueを使用する — Codex は対話型ターミナルアプリであり、PTY がないとハングします - Git リポジトリ必須 — Codex は Git ディレクトリ外では動作しません。スクラッチ作業には
mktemp -d && git initを使用 - ワンショットには
execを使う —codex exec "prompt"で実行し、完了後クリーンに終了します - 開発時は
--full-autoを使う — サンドボックス内の変更を自動承認します - 長時間タスクはバックグラウンドで —
background=trueを使用し、processツールで監視します - 干渉しない —
poll/logで監視し、長時間タスクには辛抱強く待ちます - 並列実行しても問題ない — バッチ処理では複数の Codex プロセスを同時に実行できます