Codex CLIをosFoundryのワーカーにする前に手元で確かめておくこと

この記事でやること

• osFoundryのエージェントに cli:codex:agent を付ける前に、Codex CLIの状態をターミナルで確認する
• osFoundryの「サインインを確認」と同じコマンドを自分で叩き、出てくるイベントを読んでみる
• 実行ログの各行が何を意味するかを対応表で押さえる
• 最後に、つまずきやすい点をFAQ形式でまとめる

前提・環境

• macOSのosFoundryデスクトップアプリ
• Codex CLIをインストール済みで、ChatGPTのアカウントがある
• 作業させたいフォルダ。osFoundryのツール（memory_search など）もCodexから使わせるなら、gitリポジトリになっていること
• python3（イベントを眺めるのに使うだけです）

ここで叩くコマンドは、どれも読み取りか、-s read-only での1回きりの実行です。

確認1 osFoundryから見える場所にバイナリがあるか

osFoundryがCodexを探すのは、次の3か所です。

• PATH
• ~/.codex/bin
• /Applications/Codex.app の中（Contents/Resources/codex）

where-is-codex.sh

command -v codex
ls -l ~/.codex/bin/codex 2>/dev/null
ls -l /Applications/Codex.app/Contents/Resources/codex 2>/dev/null

caskで入れた場合、本体はアプリの中にあるので、which codex では何も出ないことがあります。3行目にパスが出ていれば、osFoundryからは見つかります。

アプリ側では、鍵アイコン（ツールチップは「APIキー（BYOK）」）→「外部AI」タブのCodexの行を見ます。「インストール済み」と「ライブストリームなし」が並び、IDは cli:codex:agent （自律） の1つだけです。

表示例：外部AIタブのClaude CodeとCodex

確認2 ログインと課金の経路

まずCodex自身でサインインしておきます。

codex login

続けて、環境変数を確かめます。osFoundryは起動前に、子プロセスの環境から CODEX_API_KEY・OPENAI_API_KEY・OPENAI_BASE_URL を外します。これらが残っていると、ChatGPTのサインインではなく従量課金のAPIアカウントに流れてしまうからです。ターミナルで自分で試すときも、同じ条件にそろえておくと結果を比べやすくなります。

check-env.sh

# 値は伏せて、設定されているかだけ見る
env | grep -E '^(CODEX_API_KEY|OPENAI_API_KEY|OPENAI_BASE_URL)=' | sed 's/=.*/=<set>/'

# 手元で試すときは、この3つを外した環境で叩く
alias codex-sub='env -u CODEX_API_KEY -u OPENAI_API_KEY -u OPENAI_BASE_URL codex'

osFoundryで動かした実行は、サブスク扱いでコスト 0.0 として記録されます。

確認3 「サインインを確認」と同じコマンドを叩く

外部AIタブの「サインインを確認」は、本番と同じコマンド組み立て関数で、ごく小さい1回分を流します。中身は次のとおりです。これを自分で叩けば、osFoundryが見るのと同じ出力を確かめられます。

signin-check.sh

codex-sub exec "Reply with the single word: ok" \
  --json --skip-git-repo-check --ignore-user-config --ignore-rules \
  -s read-only -c 'approval_policy="never"'

--ignore-rules で止まる場合は、手元のCodexのビルドがそのフラグを知りません。osFoundryはバージョン表を持たず、codex exec --help にフラグが載っているときだけ付けます。手元でも同じように確かめられます。

codex exec --help | grep -q -- --ignore-rules && echo "ignore-rules: あり" || echo "ignore-rules: なし（osFoundryは付けない）"

出力は1行1オブジェクトのJSONです。種類だけ抜き出すと、流れが追いやすくなります。

show-events.sh

codex-sub exec "Reply with the single word: ok" \
  --json --skip-git-repo-check --ignore-user-config -s read-only \
  -c 'approval_policy="never"' |
python3 -c '
import sys, json
for raw in sys.stdin:
    try:
        v = json.loads(raw)
    except ValueError:
        continue                      # JSONでない行は読み飛ばす
    item = v.get("item") or {}
    print(v.get("type"), item.get("type") or "")
'

item.completed agent_message が出て、最後に turn.completed が来れば、サインインからモデルの応答まで一通り通っています。途中で turn.failed や error が出た場合は、そこに書かれた文面を見ます。osFoundryは文面を 401、unauthorized、please log in、sign in などの語と照合し、認証まわりだと判断するとアプリ側のサインイン案内を出します。

確認4 作業フォルダとワークツリー

CodexがosFoundryのツールを使えるかどうかは、作業フォルダで決まります。

作業フォルダ	起動のされ方	osFoundryのツール
gitワークツリーあり	--dangerously-bypass-approvals-and-sandbox ＋ 127.0.0.1 のMCPブリッジ	使える
ワークツリーなし	-s workspace-write、ブリッジなし	使わない（実行ログにその旨が1行出る）

非対話の codex exec では、承認とサンドボックスの両方を外さない限り、CodexはMCPツールの呼び出しをキャンセルします。そこでosFoundryは、gitの隔離が代わりに入るときに限って、CodexのOSサンドボックスを外しています。

手元のフォルダがgitリポジトリかどうかは、次の1行で分かります。

git -C /path/to/folder rev-parse --is-inside-work-tree

true が返ったら、設定 → ローカルフォルダにそのフォルダを追加し、Codeサーフェスで「このワークスペースで有効にする」を押します。実行ごとに専用のブランチと作業コピーが切られるようになります。フォルダの選ばれ方は、Codeサーフェスのリポジトリが優先で、なければ最初の許可済みローカルフォルダです。

確認5 エージェントに割り当てる

Studioでエージェントを開き、Model Preferenceのピッカーで「CLI agents」セクションの cli:codex:agent（プロバイダー表記は External AI (subscription)）を選びます。ワーカーの手順を担当させるなら、Runtime Roleを worker にします。Model Preferenceの場所はStudioのエージェント画面の紹介にあります。

実行ログの読み方

実行が始まると、Codexが出すイベントがosFoundryの実行ログの1行に変わります。対応はこうです。

Codexのイベント	実行ログの行
reasoning	Thinking: …
command_execution	Using shell — <コマンド>
mcp_tool_call	Using <ツール名>…
file_change	Edited <パス>
todo_list	Plan: 1. … 2. …
agent_message	回答の本文
turn.completed	使用量（input_tokens・cached_input_tokens・output_tokens）

以下は表示例です。ワークツリーのあるフォルダで、テストとメモリの両方が要るタスクを渡したときのイメージです。

実行ログ（表示例）

Thinking: Look up the release notes before touching the changelog.
Using memory_search…
Using shell — git log --oneline -5
Edited CHANGELOG.md
Added the three merged fixes to CHANGELOG.md.

Using memory_search… と Using shell が同じ実行に並べば、ブリッジ経由のツールとCodex自身のシェルの両方が通っています。

回答の本文が最後にまとめて出るのは、Codexがトークン単位ではなく、完了したアイテム単位でイベントを出すからです。外部AIタブの「ライブストリームなし」はこのことを指しています。進捗行は作業中にも1行ずつ届くので、止まっているかどうかは進捗行のほうで判断します。

よくある疑問

cli:codex というチャット用のIDはありませんか

ありません。Codexの設定にはシェルツールを切るスイッチがないので、「ツールなしの補完」として呼んでも中身はシェル付きのエージェントになります。osFoundryはチャット用IDを受け付けず、"codex has no tool-less chat mode — use 'cli:codex:agent' for an autonomous run instead." と返します。

自分の ~/.codex/config.toml の設定は効きますか

osFoundryの実行では読まれません。--ignore-user-config が付くので、自分で足したMCPサーバーはosFoundryの実行に混ざりません。.rules のexecpolicyファイルも --ignore-rules で外れます。認証は CODEX_HOME から読まれるので、ログインはそのまま使えます。

ツール単位で呼べるものを絞れますか

-s が絞るのは、ファイルシステムとコマンド実行の範囲です。モデルがどのツールを呼べるかは絞りません。Codexには --disallowedTools に当たるフラグもありません。チャンネルにCodexを追加するときのAdd agentシートにも、「このハーネスにはツール単位の制限フラグがない」と表示されます。

システムプロンプトはどこに入りますか

Codexにはシステムプロンプトを足すフラグがありません。osFoundryはシステムプロンプトを、空行1つを挟んで会話の前に連結します。それまでのやり取りは User: / Assistant: のトランスクリプトとして後ろに続きます。

長いタスクはどこまで待ってくれますか

自律実行は1,800秒、「サインインを確認」は300秒が上限です。超えると子プロセスは破棄されてkillされます。大きな作業は、小さいタスクに分けて渡すほうが扱いやすくなります。

まとめ

• caskで入れたCodexは which に出なくても、/Applications/Codex.app の中にあればosFoundryから見つかります
• 「サインインを確認」と同じコマンドを自分で叩けば、イベントの流れをその場で確かめられます
• osFoundryのツールを使わせたいなら、作業フォルダをgitリポジトリにしてCodeサーフェスで有効にします
• 本文はまとめて届くので、動いているかどうかは進捗行で判断します