1. はじめに：Codex CLIはローカルモデルでも動かせる
Codex CLIはOpenAIのクラウドモデルだけでなく、OllamaまたはLM Studioで提供するローカルモデルにも接続できます。基本形は次のとおりです。
codex --oss --local-provider ollama --model <MODEL_NAME>codex --oss --local-provider lmstudio --model <MODEL_NAME>ただし、モデル単体で会話できることと、ファイルを正しく読み、ツールを呼び出し、編集後にテストまで完了できることは別問題です。本記事では接続方法だけでなく、小規模リポジトリで編集とテストを安全に試す方法、失敗の切り分け方、クラウドモデルへ切り替える判断基準まで扱います。
2. 通常利用とローカルモデル利用の違い
通常利用では、Codex CLIがプロンプトや必要なコンテキストをOpenAIのモデルへ送り、返された判断に従ってローカルのファイル操作やコマンド実行を仲介します。
--ossを付けると、このうち推論先がOllamaまたはLM Studioへ切り替わります。リポジトリを読み、パッチを適用し、シェルを起動する主体は引き続きCodex CLIです。つまり、ローカルになるのは主にモデル推論であり、ファイル権限まで無害になるわけではありません。
flowchart LR
accTitle: Codex CLIの推論経路
accDescr: Codex CLIはクラウド利用ではOpenAIモデルへ接続し、ローカル利用ではOllamaまたはLM Studioを経由してローカルモデルへ接続する。ファイル操作とコマンド実行はどちらもCodex CLIが仲介する。
Repo[作業リポジトリ] <--> CLI[Codex CLI]
CLI -->|通常利用| OpenAI[OpenAIモデル]
CLI -->|--oss| Provider[Ollama または LM Studio]
Provider --> Local[ローカルモデル]
CLI --> Tools[ファイル編集・コマンド実行]ローカル推論とクラウド推論の構成
ローカル利用には、推論APIへコードを送らない構成を作りやすい、従量課金を気にせず反復できる、量子化やモデルを選べるという利点があります。一方で、速度、コンテキスト長、指示追従、Tool Callingの品質は手元のモデルとハードウェアに強く依存します。
なお、--ossだけで完全なオフライン性が保証されるわけではありません。Ollamaの:cloudモデル、LM Linkのリモート実行、Codexのネットワーク機能などを併用すれば通信は発生します。機密コードを扱う場合は、モデル名、サーバーの接続先、ネットワーク設定、ログやテレメトリーの方針も確認してください。
3. 事前準備と検証環境
必要なのは、Codex CLI、OllamaまたはLM Studio、ローカルで動くモデル、テスト可能な小規模Gitリポジトリです。最初から業務リポジトリへ書き込み権限を与えず、次のような検証環境を用意します。
local-codex-demo/
├── src/
│ └── calculator.py
├── tests/
│ └── test_calculator.py
├── README.md
└── AGENTS.md検証は「モデル単体で会話する」「読み取りだけ任せる」「変更案を出させる」「1ファイルだけ編集させる」「テストを実行させる」の順に進めます。段階を分けることで、接続障害とエージェント能力不足を混同しにくくなります。
4. コーディング向けローカルモデルの選び方
チャット性能だけでは選べない
Codexで重要なのは、コード生成能力だけではありません。複数ファイルの関係把握、制約への追従、ツール呼び出し、構造化された引数の生成、コマンド結果を踏まえた再判断が必要です。利用候補について、少なくとも次を確認します。
- 必要なRAM・VRAMと量子化
- 最大および実際に割り当てるコンテキスト長
- Tool Callingと構造化出力への適性
- コード理解・生成能力
- チャットテンプレート
- OllamaまたはLM Studio上の正確なモデル識別子
小型モデルは、1ファイルの説明、型ヒントやコメントの追加、単純なテスト生成、局所的なリファクタリングから試すのが現実的です。大規模な設計変更や曖昧な要件からの長時間自律実装は、接続に成功しても安定するとは限りません。
コンテキスト長が重要な理由
モデルへ渡るのはユーザーの依頼だけではありません。システム指示、AGENTS.md、読み込んだファイル、ツール引数、コマンド出力、テスト結果、会話履歴が積み上がります。
Ollamaはエージェントやコーディングツールに少なくとも64Kトークンを設定するよう案内しています。一方、LM StudioのCodex連携ガイドは約25Kを超える設定を推奨しています。ただし、コンテキストを増やすほどKVキャッシュなどに必要なメモリも増えます。最大値を機械的に選ぶのではなく、速度とメモリ使用量を観察してください。
5. Ollamaを準備する
Ollamaサーバーを起動し、使用するモデルを取得します。アプリ版では、すでにサーバーが動いている場合があります。
ollama serve
ollama pull <MODEL_NAME>
ollama ls
ollama run <MODEL_NAME>ollama lsに表示される名前をCodexの--modelへ渡します。まずollama runで、コード生成と説明が単体で成立するか確認してください。
64Kコンテキストを割り当ててサーバーを起動する例は次のとおりです。
OLLAMA_CONTEXT_LENGTH=64000 ollama serveメモリ不足や速度低下が起きたら、実際の割り当てとCPUへのオフロードを確認します。
ollama psOllamaにはCodex用の設定を生成して起動するコマンドもあります。
ollama launch codex設定だけ行う場合は次を使用できます。
ollama launch codex --config本記事では接続先を明確にするため、以降はCodex側で--local-provider ollamaを指定します。
6. LM Studioを準備する
LM Studioでは、モデルをダウンロードしてメモリへロードし、GPU Offloadとコンテキスト長を設定します。チャット画面で単体動作を確認したら、Developer画面またはCLIからローカルサーバーを起動します。
lms server start --port 1234LM Studioの既定ポートは1234です。Codexとの接続にはOpenAI互換のPOST /v1/responsesが使われます。問題が起きたら、サーバーの起動、モデルのロード、APIリクエストの受信、指定したモデル識別子の一致をDeveloper画面で確認します。
項目 | Ollama | LM Studio |
|---|---|---|
主な操作 | CLI中心 | GUIとCLI |
モデル確認 |
| My Models／Developer |
サーバー | アプリまたは | Developerまたは |
向いている人 | ターミナル中心で管理したい | ロード状態やメモリを画面で確認したい |
7. CodexをOSSモードで起動する
プロバイダーとモデルを明示して起動します。
codex --oss --local-provider ollama --model <MODEL_NAME>codex --oss --local-provider lmstudio --model <MODEL_NAME>--modelは-mへ短縮できます。
codex --oss --local-provider ollama -m <MODEL_NAME>OpenAIの現行ドキュメントでは、対話モードで--ossだけを指定し、プロバイダーの既定値がない場合は選択を促されます。一方、codex execはプロバイダーを決定できないとエラー終了します。再現可能な手順やスクリプトでは--local-providerを明示するのが安全です。
モデルが見つからない場合は、表示名ではなくAPIが認識する識別子を指定しているか確認します。Ollamaではollama ls、LM StudioではDeveloper画面のモデル識別子が基準です。
8. config.tomlへ既定値を保存する
ユーザー設定は~/.codex/config.tomlに保存します。
oss_provider = "ollama"
model = "<MODEL_NAME>"
approval_policy = "on-request"
sandbox_mode = "workspace-write"これで起動コマンドを短縮できます。
codex --ossLM Studioを既定にする場合はoss_provider = "lmstudio"へ変更します。コマンドライン引数は設定より優先されるため、一度だけ切り替えることも可能です。
codex --oss --local-provider lmstudio --model <OTHER_MODEL>クラウド用とローカル用を分けるなら、$CODEX_HOME/local.config.tomlを作成し、次のように選択します。
codex --profile local --oss現行のプロファイルは$CODEX_HOME/<profile-name>.config.tomlという独立ファイルです。プロバイダーを切り替えるたびに主設定を書き換える必要はありません。
9. 実践：ローカルモデルにリポジトリを操作させる
読み取りから始める
検証用リポジトリで、最初は変更を禁止します。
このリポジトリの構成を確認してください。
まだファイルは変更せず、各ファイルの役割と改善点だけを説明してください。存在しないファイルを作り上げていないか、変更禁止を守ったか、対象を正しく把握したかを確認します。
1ファイルだけ編集する
src/calculator.pyだけを対象にしてください。
目的:
- 型ヒントを追加する
- docstringを追加する
禁止事項:
- 関数名と処理内容を変更しない
- 外部ライブラリを追加しない
- 他のファイルを変更しない
変更後:
- 差分を確認する
- pytestを実行する
- 変更点とテスト結果を報告する小型モデルには、対象、目的、禁止事項、完了条件を分けて伝えます。「いい感じに改善して」のような広い依頼は、不要な変更やループを起こしやすくなります。
テストを追加させる場合も範囲を限定します。
現在の実装を確認し、tests/test_calculator.pyに境界値テストを追加してください。
既存テストは削除しないでください。
失敗した場合は原因を説明してから修正し、再試行は2回までにしてください。最後はCodexの説明だけを信用せず、人間側でも確認します。
git status
git diff
pytest10. codex execで非対話実行する
codex execは対話画面を開かず、明確な1タスクを実行するモードです。スクリプトやCI形式の処理に向きます。
codex exec \
--oss \
--local-provider ollama \
--model <MODEL_NAME> \
"リポジトリの構成を説明してください"LM Studioの場合もプロバイダーを置き換えるだけです。
codex exec \
--oss \
--local-provider lmstudio \
--model <MODEL_NAME> \
"テストコードを確認し、不足しているケースを列挙してください"標準入力も利用できます。
cat prompt.txt | codex exec \
--oss \
--local-provider ollama \
--model <MODEL_NAME> \
-方法 | 向いている場面 |
|---|---|
| 途中で判断や差分を確認する |
| 境界の明確な単発処理 |
シェル＋ | 同じ読み取り処理を反復する |
CI＋ | 十分検証済みの自動チェック |
ローカルモデルの挙動を把握するまでは対話モードを使い、無人実行は読み取り中心から始めます。
11. 承認ポリシーとサンドボックス
サンドボックスは「技術的にどこまで操作できるか」、承認ポリシーは「どの操作で人間へ確認するか」を制御します。推論先がローカルでも、この2層は必要です。
最初は読み取り専用で確認します。
codex \
--oss \
--local-provider ollama \
--model <MODEL_NAME> \
--sandbox read-only \
--ask-for-approval on-request編集を許可する段階では、書き込み範囲をワークスペース内に限定します。
codex \
--oss \
--local-provider ollama \
--model <MODEL_NAME> \
--sandbox workspace-write \
--ask-for-approval on-request主なサンドボックスモードはread-only、workspace-write、danger-full-accessです。承認ポリシーにはuntrusted、on-request、neverがあります。neverは「安全な操作だけを行う」という意味ではなく、承認を対話的に求めない設定です。
codex --dangerously-bypass-approvals-and-sandboxこのオプションは承認とサンドボックスを迂回します。公式資料も隔離されたランナー内だけで使うよう警告しています。特にツール呼び出しが不安定なローカルモデルとは組み合わせないでください。
12. ローカルモデルで起こりやすい問題
問題を「Codex CLI」「APIサーバー」「モデル」「コンテキスト／メモリ」に分けると、モデル交換だけを繰り返さずに済みます。
flowchart TD
accTitle: ローカルCodexの障害切り分け
accDescr: Codexの失敗を、APIへ到達しない接続問題、モデル識別子やロードの問題、コンテキストとメモリの問題、ツール呼び出しや指示追従の問題へ順番に切り分ける。
Start[失敗を再現] --> Request{APIサーバーへ
到達したか}
Request -->|いいえ| Server[ポート・サーバー・プロバイダーを確認]
Request -->|はい| Loaded{指定モデルが
ロードされたか}
Loaded -->|いいえ| Model[モデル識別子とロード状態を確認]
Loaded -->|はい| Resource{遅延・停止・
コンテキスト不足か}
Resource -->|はい| Memory[コンテキスト・RAM・VRAM・オフロードを確認]
Resource -->|いいえ| Tool{ツール引数や
指示を守れないか}
Tool -->|はい| Capability[タスクを縮小しモデルやテンプレートを変更]
Tool -->|いいえ| Logs[Codex出力・テスト・差分を調査]ローカル実行の障害切り分け
Tool Callingが壊れる
ファイルを読まずに読んだと回答する、ツール呼び出しを通常テキストとして出す、不正なJSON引数を生成するといった症状です。Tool Callingに適したモデルを使い、1回の依頼を1〜3ファイル程度へ絞り、JSON生成とファイル編集を別タスクにします。
指示を忘れる、同じ処理を繰り返す
制約を依頼の末尾でも繰り返し、AGENTS.mdへ恒久的なルールを書きます。「テスト失敗時の再試行は2回まで。解決できなければ停止して報告」と終了条件を与えることも有効です。
大きなリポジトリを扱えない
--cdで作業ルートを限定し、最初に構成だけを説明させ、必要なファイルを人間が指定します。巨大なテストログはコンテキストを急速に消費するため、対象テストを絞ってください。
メモリ不足または極端に遅い
Ollamaではollama psでコンテキスト割り当てとCPUオフロードを確認します。LM Studioではロード設定、GPU Offload、推定メモリを確認します。別モデルの同時ロードを避け、必要ならコンテキストまたはモデルサイズを下げます。
13. クラウド版Codexとの比較
比較項目 | ローカルモデル | クラウドモデル |
|---|---|---|
推論場所 | 手元のPCまたは自前サーバー | クラウド |
従量課金 | 通常は外部API従量課金なし | 契約・利用方法による |
ハードウェア依存 | 大きい | 比較的小さい |
Tool Calling | モデル次第で不安定 | 高性能モデルを選びやすい |
長いコンテキスト | メモリ負荷が大きい | サービス仕様の範囲で利用 |
大規模リポジトリ | 苦手になりやすい | 対応しやすい |
オフライン構成 | 可能 | 基本的に不可 |
運用負荷 | モデルとサーバーを管理 | 比較的小さい |
二者択一にする必要はありません。機密性、難易度、変更リスク、調査にかかる人間の時間で使い分けるのが現実的です。
14. ローカルモデルに向いているタスク
向いているのは、コード説明、コメントや型ヒントの追加、命名改善、小規模リファクタリング、単純なテスト生成、READMEの下書き、1〜2ファイルの差分レビュー、定型変換です。
認証・認可、DBマイグレーション、依存関係の大規模更新、本番デプロイ、インフラ変更、削除操作、セキュリティ修正、複数サービスを横断する変更は慎重に扱います。実行する場合も、読み取り、計画、編集、検証を別セッションに分け、人間が各段階を確認してください。
15. クラウドモデルへ切り替える判断基準
同じ失敗を2〜3回繰り返す、対象ファイルを特定できない、Tool Callingエラーが続く、制約を保持できない、設計判断や複雑なデバッグが必要、人間の修正コストがAI利用前より増えた場合は切り替え時です。
flowchart TD
accTitle: モデル選択の判断フロー
accDescr: 低リスクで範囲が小さいタスクはローカルモデルで試し、人間が差分を確認する。複雑、高リスク、大規模、または失敗を繰り返すタスクはクラウドモデルへ切り替える。
Task[タスクを定義] --> Risk{高リスクな変更か}
Risk -->|はい| Cloud[クラウドモデルと厳格なレビュー]
Risk -->|いいえ| Scope{対象は少数ファイルで
要件が明確か}
Scope -->|いいえ| Cloud
Scope -->|はい| Local[ローカルモデルで実行]
Local --> Review[人間が差分とテストを確認]
Review --> Success{妥当か}
Success -->|はい| Done[採用]
Success -->|いいえ| Retry{失敗は2回未満か}
Retry -->|はい| Narrow[タスクと制約を縮小]
Narrow --> Local
Retry -->|いいえ| Cloudローカルとクラウドの使い分け
実用的な役割分担は、ローカルモデルに調査、説明、小さな変更、下書きを任せ、人間が確認し、複雑な実装や最終レビューをクラウドモデルへ渡す形です。
16. まとめ
Codex CLIは--ossでローカルモデルモードを有効化し、--local-providerでollamaまたはlmstudioを選択できます。--modelには各サーバーが認識するモデル識別子を指定し、oss_providerを設定すれば毎回の指定を省略できます。codex execではプロバイダー未設定がエラーになる点にも注意が必要です。
ローカル推論は、権限管理が不要になることを意味しません。最初はread-onlyとon-requestで観察し、対象と完了条件を小さく保ち、差分とテストを人間が確認してください。簡単で反復的な処理はローカル、複雑または高リスクな判断はクラウドという使い分けが、現時点では最も現実的です。