はじめに

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の更新でクラウドモデルが追加された際には、結合カタログの再生成が必要になる。

できた！