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は接続エラーやタイムアウトになります。

まとめ

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