はじめに
OpenAIのCodex CLIは、Ollamaで動作するローカルLLMも利用できる。
Ollamaの公式ドキュメントでは、Codex CLIをOSSモードで起動する方法としてcodex --ossが案内されている。
今回、macOS環境でOllamaのgpt-oss:20bをCodex CLIから利用したところ、認証エラーやモデルメタデータの警告が発生した。
この記事では、実際に発生した不具合、原因、適用した修正内容を整理する。
調査日は2026年6月1日である。Codex CLIやOllamaの更新により、将来は挙動が変わる可能性がある。
また、以下の処理はエラーが発生する都度CodexCLIに投げかけ調査してもらい、設定の書き換えもほぼCodexCLIが行っています。
同じように実施したい場合は、この記事のURLをプロンプトに入れて、設定を調整してもらうよう依頼するのが良いかもしれません。
検証環境
今回確認した環境は以下のとおり。
| 項目 | 内容 |
|---|---|
| OS | macOS（Apple Silicon、macos-aarch64） |
| Codex CLI | codex-cli 0.135.0 |
| Ollama | 0.24.0 |
| 利用モデル | gpt-oss:20b |
| モデルサイズ | 約13 GB |
| パラメーター数 | 20.9B |
| コンテキスト長 | 131072 tokens |
| Ollamaが認識した機能 |
completion、tools、thinking
|
Ollamaの公式ドキュメントでは、Codex CLIで利用するモデルに最低64k tokensのコンテキスト長が推奨されている。
今回のgpt-oss:20bは131072 tokensのため、この条件を満たしている。
最終的に使用した起動コマンド
ローカルのOllamaを明示してCodex CLIを起動する。
codex --oss --local-provider ollama -m gpt-oss:20b
~/.codex/config.tomlに次の設定を追加している場合は、
--local-provider ollamaを省略してcodex --oss -m gpt-oss:20bと書ける。
oss_provider = "ollama"
発生した不具合1: モデルメタデータの警告
Codex CLIを起動してプロンプトを入力すると、次の警告が表示された。
⚠ Model metadata for `gpt-oss:20b` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.
このメッセージは、Ollamaがモデルを読み込めないという意味ではない。
Codex CLI側がgpt-oss:20bのモデルメタデータを見つけられず、汎用のフォールバック設定を利用していることを示している。
Ollama側では、次のコマンドでモデル情報を正常に取得できた。
ollama show gpt-oss:20b
確認できた情報:
architecture gptoss
parameters 20.9B
context length 131072
capabilities completion, tools, thinking
原因: OSSモデルのメタデータがターン開始時に読み込まれない
この問題は、Codex CLIのIssue
#24659で報告されている。
Codex CLIは、通常の起動時に内蔵モデルカタログを読み込む。
しかし、Ollamaなどで利用するカスタムモデルは内蔵カタログに含まれていない。
~/.codex/models_cache.jsonにモデル情報があったとしても、
OSSモードのターン開始時には自動的に読み込まれない。
そのため、Codex CLIはgpt-oss:20bを見つけられず、フォールバック設定に切り替わる。
同じ警告はIssue #14757でも報告されている。
フォールバック時には性能低下だけでなく、apply_patchなどのツール利用に影響する可能性がある。
修正: 静的なモデルカタログを指定する
回避策として、model_catalog_jsonを使ってCodex CLIに静的なモデルカタログを読み込ませる。
まず、~/.codex/config.tomlに次の行を追加する。
model_catalog_json = "~/.codex/model-catalog.local.json"
oss_provider = "ollama"
次に、~/.codex/model-catalog.local.jsonにgpt-oss:20bの定義を追加する。
Codex CLI 0.135.0で動作確認したローカルモデル定義は以下のとおり。
{
"slug": "gpt-oss:20b",
"display_name": "gpt-oss:20b",
"description": "Local gpt-oss:20b model served by Ollama.",
"default_reasoning_level": "medium",
"supported_reasoning_levels": [
{
"effort": "medium",
"description": "Use the model's thinking capability."
}
],
"shell_type": "shell_command",
"visibility": "list",
"supported_in_api": true,
"base_instructions": "You are Codex, a coding agent. Inspect the workspace before editing. Use shell tools for investigation and the apply_patch tool for file edits. Verify changes with focused tests.",
"priority": 0,
"additional_speed_tiers": [],
"service_tiers": [],
"availability_nux": null,
"upgrade": null,
"supports_reasoning_summaries": false,
"default_reasoning_summary": "none",
"support_verbosity": false,
"default_verbosity": "low",
"apply_patch_tool_type": "freeform",
"truncation_policy": {
"mode": "tokens",
"limit": 10000
},
"supports_parallel_tool_calls": true,
"supports_image_detail_original": false,
"context_window": 131072,
"max_context_window": 131072,
"effective_context_window_percent": 95,
"experimental_supported_tools": [],
"input_modalities": [
"text"
],
"supports_search_tool": false
}
注意: カタログは追加ではなく置換される
model_catalog_jsonを設定すると、内蔵モデルカタログに追記されるのではなく、指定したJSONファイルで置き換えられる。
ローカルモデルだけを記述すると、Codex CLIで通常利用するクラウドモデルの定義が失われる可能性がある。
今回の環境では、~/.codex/models_cache.jsonに含まれる既存モデル定義を保持し、gpt-oss:20bを加えた結合カタログを作成した。
作業用のlocal-model.jsonが、次のような形式であるとする。
{
"models": [
{
"slug": "gpt-oss:20b"
}
]
}
実際には、上記の省略例ではなく、前節に掲載した全項目を含める。
結合にはjqを利用できる。
jq --slurpfile local local-model.json \
'{models: (.models + $local[0].models)}' \
~/.codex/models_cache.json \
> ~/.codex/model-catalog.local.json
設定を変更する前に、バックアップを作成しておく。
cp ~/.codex/config.toml ~/.codex/config.toml.bak
発生した不具合2: プロファイル設定形式の競合
Ollamaの自動設定を試した際には、別のエラーも発生した。
ollama launch codex --config --model gpt-oss:20b
表示されたエラー:
Error loading config.toml: --profile `ollama-launch` cannot be used while
~/.codex/config.toml contains legacy `profile = "ollama-launch"` or
`[profiles.ollama-launch]` config
Codex CLI 0.135.0では、--profile ollama-launchを指定すると~/.codex/ollama-launch.config.tomlが読み込まれる。
一方、Ollama 0.24.0の自動設定は、~/.codex/config.toml内に旧形式の[profiles.ollama-launch]を生成する場合がある。
新旧の設定形式が競合すると、プロファイルを利用できない。
この問題はOllamaのIssue #16348で報告されている。
2026年6月1日時点では、Ollamaの公式ドキュメントにも~/.codex/config.toml内へ[profiles.ollama-launch]を追加する例が掲載されている。一方、Codex CLI 0.135.0では別ファイル形式への移行を求められるため、バージョンの組み合わせに注意が必要である。
Ollama側では、Codexの新しいプロファイル形式に対応するPull Request #16351が作成されている。
発生した不具合3: APIキーログインの強制
プロファイルを手動移行した後、次のコマンドを実行した。
codex --profile ollama-launch -m gpt-oss:20b
すると、次のエラーが表示された。
API key login is required, but ChatGPT is currently being used. Logging out.
原因は、~/.codex/ollama-launch.config.tomlに含まれていた以下の設定だった。
forced_login_method = "api"
ローカルのOllamaを利用する場合、この設定は不要である。
削除またはコメントアウトすると、APIキーログインの強制を回避できる。
openai_base_url = "http://127.0.0.1:11434/v1/"
model_provider = "ollama-launch"
# forced_login_method = "api"
ただし、今回の用途ではプロファイルを使わず、--oss --local-provider ollamaを明示する方が分かりやすかった。
動作確認
静的モデルカタログを追加した後、次のコマンドで最小限の確認を行った。
codex --oss --local-provider ollama -m gpt-oss:20b \
--strict-config \
exec --skip-git-repo-check --ephemeral \
'Reply with exactly: OK'
起動時には次の内容が表示された。
model: gpt-oss:20b
provider: ollama
モデルからOKが返り、カスタムカタログも--strict-configの検証を通過した。
まとめ
今回発生したメタデータ警告は、Ollamaのモデル読込エラーではなく、Codex CLIがカスタムモデルの情報をターン開始時に読み込まないことが原因だった。
修正の要点は以下のとおり。
-
codex --oss --local-provider ollama -m gpt-oss:20bで起動する。 -
model_catalog_jsonで静的モデルカタログを指定する。 - カタログには既存モデル定義も含める。
- プロファイルを利用する場合は、旧形式設定と
forced_login_method = "api"を確認する。
静的カタログを使う場合、Codex CLIの更新でクラウドモデルが追加された際には、結合カタログの再生成が必要になる。
できた！