CodexでOllamaのローカルモデルに接続するときのよくあるエラー：チュートリアル、トラブルシュート、FAQ

Codexからローカルモデルを使えるようになると、低リスクなコード作業をOllamaに任せたくなります。クォータを節約でき、機密性の高いテキストも手元で扱えます。ただし初期設定では、Ollamaは動いているのにCodexから接続できない、接続できても出力が弱い、という問題がよく起きます。

このガイドでは、Ollama単体の確認、Codex側の設定、エラー別の排障という順番で整理します。

ローカルモデルに向く作業

小さなコード説明、スクリプトの下書き、READMEや設定説明の編集、簡単なレビュー、クラウドに出しにくい私的なテキストには向いています。一方で、大規模リファクタ、深いリポジトリ推論、セキュリティ重要箇所、長時間の自律実行には向きません。

ステップ1：Ollama単体を確認する

1

ollama --version

コード向けモデルを取得します。

1

ollama pull qwen2.5-coder:7b

一度実行します。

1

ollama run qwen2.5-coder:7b

ここで失敗するなら、Codex設定ではなくOllama、モデル、リソース、ネットワークを先に直します。

ステップ2：Ollama APIを確認する

既定のAPIは通常次です。

1

http://localhost:11434

1

curl http://localhost:11434/api/tags

Windows PowerShellでは：

1

Invoke-RestMethod http://localhost:11434/api/tags

ここでモデル一覧が見えれば、Ollamaサービスは動いています。

ステップ3：Codex側を設定する

確認するのは主に3つです。

base_urlがOllamaを指している。
モデル名がollama listと完全一致している。
OllamaネイティブAPIかOpenAI互換APIかが合っている。

ポート抜け、タグ違い、WSLのlocalhost問題など、小さな設定ミスが多いです。

最小テスト

最初は読み取り専用で試します。

1

Please explain the main purpose of README.md in this directory. Do not modify files.

または：

1

Please inspect this function and list possible edge cases. Do not edit the code.

いきなり全体リファクタを頼まないことが大事です。

connection refused

1
2
3


connection refused
failed to connect
ECONNREFUSED 127.0.0.1:11434

Ollamaが起動していない、ポートが違う、CodexがWSLやコンテナ内にいてホストのlocalhostに届かない、プロキシやファイアウォールが邪魔している、などが原因です。

Codexと同じ環境で確認します。

1

curl http://localhost:11434/api/tags

WSLからWindows上のOllamaへ接続する場合は、WindowsホストIPを使います。

model not found

1
2
3


model not found
unknown model
pull model manifest: file does not exist

1

ollama list

表示がqwen2.5-coder:7bなら、Codex側にも完全に同じ名前を書きます。

1

qwen2.5-coder:7b

1

ollama pull qwen2.5-coder:7b

404またはAPIパス違い

OllamaにはネイティブAPIとOpenAI互換APIがあります。

1
2
3
4
5


Ollama native:
http://localhost:11434/api/chat

OpenAI compatible:
http://localhost:11434/v1/chat/completions

CodexがOpenAI互換を期待するなら、base URLは多くの場合：

1

http://localhost:11434/v1

悪い例：

1

http://localhost:11434/api

です。/apiを指定すると404になることがあります。

context length exceeded

1
2
3


context length exceeded
prompt is too long
input exceeds context window

ローカルモデルはコンテキストが狭いことがあります。対象ファイルを絞り、ログを短くし、関連箇所だけ渡します。大規模変更では、ローカルモデルは補助分析に使うのが安全です。

出力品質が悪い

モデルが小さい、コード向けでない、タスクが広すぎる、サンプリングが強すぎる、文脈が多すぎる、などが原因です。

狭い指示にします。

1

Only read src/api/user.ts. Find possible null-handling issues. Do not modify files; list findings only.

避けたい例：

1

Optimize the whole project.

遅い場合

速度はモデルサイズ、CPU/GPU、メモリ、コンテキスト長に依存します。最初は7Bから試し、必要なら14Bへ進みます。Codex用には、最大モデルより安定性と制御しやすさが重要です。

1

ollama pull qwen2.5-coder:7b

WindowsとWSLのlocalhost問題

OllamaがWindows、CodexがWSLの場合、WSL内のlocalhostはWSL自身を指すことがあります。

1

curl http://localhost:11434/api/tags

失敗したら：

1

cat /etc/resolv.conf

nameserverのアドレスを試します。

1

curl http://<windows-host-ip>:11434/api/tags

プロキシ環境変数

1
2
3


echo $HTTP_PROXY
echo $HTTPS_PROXY
echo $NO_PROXY

PowerShell：

1
2
3


$env:HTTP_PROXY
$env:HTTPS_PROXY
$env:NO_PROXY

NO_PROXYに追加します。

1

localhost,127.0.0.1

Ollamaを使わない方がよいケース

本番の重要パス、大規模な複数ファイル変更、長時間の自律実行、テストが少ないプロジェクト、すでに何度も誤解しているタスクでは無理に使わない方が安全です。

タスクテンプレート

1
2
3
4
5
6


Please only inspect src/auth/session.ts.
Goal: find edge cases that may cause session loss.
Requirements:
1. Do not modify files.
2. Output only a list of issues.
3. For each issue, include trigger conditions and a suggested verification method.

編集する場合：

1
2
3
4
5
6


Please only modify src/utils/format.ts.
Goal: handle empty string and null.
Requirements:
1. Do not change function signatures.
2. Keep existing exports.
3. After editing, state which test should run.

FAQ

完全オフラインで使えますか？

Codex、モデル、ツールがすべてローカルで動き、クラウドモデルを呼ばなければ推論はローカルです。必要ならネットワーク監視で確認します。

どのモデルから始めるべきですか？

コード用途ならqwen2.5-coder:7bまたはqwen2.5-coder:14bから始めます。

クラウドモデルではできるのにローカルでは失敗するのはなぜですか？

モデル規模、学習データ、コンテキスト、ツール適応が違うためです。タスクを小さくします。

リポジトリ全体を渡してよいですか？

最初は避けます。ファイル、関数、エラー単位から始めます。

Ollamaは起動し続ける必要がありますか？

はい。停止するとCodexは接続エラーやタイムアウトになります。

エラー：Codex が Ollama を使っていない

Codex がログインや API key を要求する場合、ローカル provider ではなく別 provider を使っている可能性があります。

1

codex --help

local provider、OSS mode、Ollama 関連のオプションを確認します。グローバル設定、プロジェクト設定、環境変数も見直します。

エラー：unknown option

チュートリアルと手元の Codex バージョンが違うと起きます。

1
2


codex --version
codex --help

手元の help を基準にし、必要なら Codex を更新します。

エラー：401、API key、認証関連

ローカル Ollama は通常 OpenAI API key を必要としません。この種のエラーが出る場合、Codex がクラウド provider や OpenAI-compatible endpoint を使っている可能性があります。

1
2


$env:OPENAI_API_KEY
$env:OPENAI_BASE_URL

純粋なローカル実行にしたいなら、競合する環境変数と provider 設定を整理します。

エラー：応答が止まる、非常に遅い

ローカルモデルは、CPU 実行、大きすぎるモデル、長すぎるプロンプト、GPU 未使用などでかなり遅くなります。

まず小さなモデルと小さなタスクで試してください。ollama run で短い質問が遅いなら、Codex でも遅くなります。

エラー：ツール呼び出しが不安定

ローカルモデルはコードを書けても、agentic tool use が安定しないことがあります。架空のコマンド、出力無視、壊れた JSON、ループが典型です。

ローカルモデルは小さな修正、説明、リファクタ、小さなバグ修正に向いています。大規模な調査やセキュリティレビューは強いモデルを使う方が安全です。

切り分けテンプレート

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


OS:
PowerShell or shell version:
Codex version:
Ollama version:
Model name:
Command used:
Exact error:
Does ollama run work:
Does curl http://localhost:11434/api/tags work:
Are you using WSL, Docker, or remote SSH:

まとめ

排障は、Ollamaプロセス、HTTP API、Codexのbase URL、APIモード、モデル名、コンテキスト、タスク範囲の順に確認します。ローカルモデルは小さく明確な作業で最も役に立ちます。