Codex環境で`gh`が使えない理由と実務的な回避策（検証手順付き）¶

要旨¶

Codex CLIは安全性のため「ファイル操作・ネットワーク・権限」を段階的に制限します。
ghは「インストール」「ネットワーク」「トークン」の前提が必要で、いずれか欠けると失敗します。
実務では「REST API直叩き」または「GitHub Actionsへ移譲」が堅実。この記事では両方の手順を提示し、Codex環境で実際に動く検証コマンドも付けています。

典型的な失敗パターン¶

gh: command not found（プリインストールなし）
HTTP 401/403（GH_TOKENや権限不足）
ネットワーク未承認で外部通信が拒否（Codexの承認フローが必要）

回避アーキテクチャ¶

1) Codex内では「読み・編集・小さな検証」までに絞る（ネットワークは必要時のみ承認） 2) 書き込み系の外部作用（Issue作成/Workflow起動）は、GitHub Actionsに移譲（GITHUB_TOKENとpermissions:で管理）

実務レシピ（Codex内でRESTを使う）¶

前提: ネットワークは必要時のみ承認。トークンは環境変数GH_TOKENに設定（最小権限）。

リポジトリ情報を取得（認証不要のGET）¶

curl -sS https://api.github.com/repos/<owner>/<repo> | head -n 5

ワークフローを手動トリガー（POST; 要`GH_TOKEN`）¶

curl -sS -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer $GH_TOKEN" \
  https://api.github.com/repos/<owner>/<repo>/actions/workflows/<file>.yml/dispatches \
  -d '{"ref":"main"}'

安全運用ポイント: - トークンはファイル保存せず環境変数で一時注入 - 必要最小スコープのみ付与 - Codexでの外部通信は承認フローを通す（監査性）

GitHub Actionsへ移譲する例¶

Issue作成/ラベル付与/PR更新などは、actions/github-scriptや公式アクションで完結可能
Secrets/Permissionsはワークフロー側で集中管理し、Codex側では編集のみ

この環境での動作検証（手順）¶

読み取りの疎通確認（認証なしGET）
上記のGETを実行し、JSONが返ること（Codexで承認ダイアログが出た場合は承認）
書き込み系（任意）
export GH_TOKEN=...（repoスコープ）
上記のdispatch APIを実行（対象ワークフローとブランチを自分のリポジトリに合わせる）

Codexの強みは「変更提案と安全運用」。外部作用はCIに委譲し、Codexは編集と最小限の検証にフォーカスする設計が、実務では最も安定します。

Codex環境でghが使えない理由と実務的な回避策（検証手順付き）¶

要旨¶