Codex CLI 使用 Ollama 本地模型完整教程（2026）

AI 编程助手的兴起让越来越多的开发者开始关心一个问题：代码会不会被发送到云端？对于企业内网项目、含有敏感逻辑的代码库，或者仅仅是不想为 API 费用担忧的个人开发者，本地大模型是一个越来越成熟的替代方案。

Codex CLI 的设计非常灵活——它并不强绑 OpenAI 服务器，而是支持任何兼容 OpenAI Chat Completions API 格式的后端。Ollama 正好提供这个接口：它在本机启动一个轻量级 HTTP 服务，暴露 /v1/chat/completions 端点，让你像使用 OpenAI 一样使用本地模型。

本文将完整介绍从安装 Ollama、选择合适的编程模型，到配置 Codex CLI 接入本地服务的全部步骤，并附上常见问题排查和进阶用法。

1. 为什么选择 Ollama + Codex CLI

在决定投入时间配置本地模型之前，先了解清楚它的优势和局限，能帮你做出更合适的技术选型。

核心优势

• 隐私保护：代码完全在本机运行，不经过任何第三方服务器。适合金融、医疗、军工等对数据主权有严格要求的行业。
• 零 API 成本：不需要 OpenAI API Key，没有 token 计费。一次性购买 GPU 后，跑多少都不额外花钱。
• 离线可用：断网环境、飞机上、企业内网隔离区——只要本机有模型权重，Codex CLI 照样工作。
• 完全可控的系统 Prompt：通过 AGENTS.md 定制助手行为，不受平台策略限制。可以针对特定代码库、特定技术栈做深度定制。
• 无速率限制：OpenAI API 有 RPM/TPM 限制，本地服务没有。适合批量代码处理任务。

需要了解的局限

• 代码质量差距：即便是最强的 32B 本地模型，在复杂推理任务上与 OpenAI o4-mini 仍有明显差距，在多步骤代码修改、跨文件重构等场景尤为明显。
• 硬件门槛：运行 7B 模型需要 8GB 显存，32B 模型需要 24GB+。没有独显或苹果 M 系芯片的机器体验会很差。
• 上下文窗口较小：大多数本地模型支持 4K-32K 上下文，而 OpenAI o4-mini 支持 128K。大型项目的全局感知能力受限。
• 首次下载耗时：模型权重文件较大（7B 约 4-5GB，32B 约 20GB），首次拉取需要较长时间。

2. 安装 Ollama

Ollama 支持 macOS、Linux 和 Windows，安装过程非常简单。

macOS

推荐使用 Homebrew 安装，方便后续升级：

# 使用 Homebrew（推荐）
brew install ollama

# 或者直接下载 .dmg 安装包
# 访问 https://ollama.com/download/mac 下载并安装

macOS 上 Ollama 安装后会作为菜单栏应用运行，默认自动启动服务。Apple Silicon（M1/M2/M3/M4）芯片会自动使用 Metal GPU 加速，性能表现出色。

Linux

# 官方一键安装脚本
curl -fsSL https://ollama.com/install.sh | sh

# 安装完成后服务会自动注册为 systemd 服务
sudo systemctl enable --now ollama

Linux 用户需要确保已安装 NVIDIA 驱动（CUDA 12+）或 AMD ROCm 驱动，Ollama 会自动检测并使用 GPU。

Windows

访问 ollama.com/download/windows 下载 OllamaSetup.exe 安装包，双击安装即可。安装后 Ollama 会在系统托盘运行，支持 NVIDIA GPU 加速。

启动服务并验证

# 手动启动 Ollama 服务（macOS 菜单栏应用已自动启动则可跳过）
ollama serve

# 验证服务是否正常运行
curl http://localhost:11434/api/tags

# 正常响应示例（未下载任何模型时）
# {"models":[]}

如果 curl 命令返回 JSON 响应，说明 Ollama 服务已正常运行在 11434 端口。

3. 推荐模型及下载命令

并非所有 Ollama 模型都适合代码任务。以下是专门针对编程场景优化的主流模型，按综合性能排序：

下载模型

# 推荐：最佳代码质量（需要 24GB+ 显存）
ollama pull qwen2.5-coder:32b

# 推荐：平衡性能，16GB 显存可用
ollama pull deepseek-coder-v2:16b

# 低显存方案，8GB 显存可用
ollama pull qwen2.5-coder:7b

# 查看已下载的模型
ollama list

# 测试模型是否可用
ollama run qwen2.5-coder:7b "写一个 Python 冒泡排序"

4. 配置 Codex CLI 接入 Ollama

Codex CLI 提供三种方式接入 Ollama，分别适合不同使用场景。

方法一：环境变量（临时，适合快速测试）

在终端会话中设置环境变量，关闭终端后失效。适合临时切换或快速验证配置：

export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export CODEX_MODEL=qwen2.5-coder:32b

# 现在运行 Codex CLI 会自动使用本地模型
codex "重构 src/auth.ts，提取 JWT 验证逻辑到独立函数"

方法二：config.toml（持久，推荐）

将配置写入 ~/.codex/config.toml，每次启动 Codex CLI 都会自动加载：

# ~/.codex/config.toml
model = "qwen2.5-coder:32b"
provider = "ollama"

[providers.ollama]
name = "Ollama"
baseURL = "http://localhost:11434/v1"
envKey = "OPENAI_API_KEY"

同时在你的 shell 配置文件（~/.zshrc 或 ~/.bashrc）中添加：

# 添加到 ~/.zshrc 或 ~/.bashrc
export OPENAI_API_KEY=ollama

保存后执行 source ~/.zshrc 使配置生效。之后直接运行 codex 命令即可使用本地模型。

方法三：命令行参数（单次覆盖）

不修改配置文件，通过命令行参数临时指定模型和 provider，适合在已有配置基础上做单次切换：

codex --model qwen2.5-coder:32b \
      --provider ollama \
      "解释这段代码的时间复杂度"

多环境配置技巧

如果你需要在 Ollama 本地模型和 OpenAI 云端模型之间频繁切换，可以在 shell 配置文件中定义别名：

# ~/.zshrc

# 使用 Ollama 本地模型
alias codex-local='OPENAI_BASE_URL=http://localhost:11434/v1 OPENAI_API_KEY=ollama CODEX_MODEL=qwen2.5-coder:32b codex'

# 使用 OpenAI 云端模型（需要真实 API Key）
alias codex-cloud='OPENAI_BASE_URL="" OPENAI_API_KEY=$REAL_OPENAI_KEY CODEX_MODEL=o4-mini codex'

5. 验证配置是否生效

配置完成后，通过以下方式确认 Codex CLI 正确使用了本地模型：

# 查看版本和当前配置
codex --version

# 测试简单任务，观察响应速度（本地模型通常首 token 延迟 0.5-2s）
codex "用 Python 写一个快速排序函数，带类型注解"

# 检查 Ollama 请求日志（另开一个终端）
OLLAMA_DEBUG=1 ollama serve

# 查看 Ollama 当前正在运行哪些模型
ollama ps

# 查看 Ollama 服务健康状态
curl http://localhost:11434/api/tags | python3 -m json.tool

如果在 Ollama 的调试日志中看到类似 POST /v1/chat/completions 的请求记录，说明 Codex CLI 正在成功调用本地模型。

6. 与 OpenAI 云端模型对比

在选择使用本地模型还是云端模型时，以下对比表可以帮助你做出决策：

综合来看，如果你的项目对隐私要求高、网络条件受限，或者需要大量批量处理代码任务，本地模型是合理的选择。对于关键业务逻辑、需要高精度的代码重构，建议仍使用 OpenAI o4-mini。

7. AGENTS.md 本地模型专用配置

在项目根目录放置 AGENTS.md 文件，可以给 Codex CLI 提供项目上下文和行为约束。针对本地模型的特点（上下文较短、响应速度较慢），建议使用更精简的指令格式：

# AGENTS.md（项目根目录）

# Coding Assistant

You are a coding assistant running on a local Ollama model.

## Constraints
- Keep responses concise (local models have limited context)
- Prefer showing code over long explanations
- Use Chinese for comments unless asked otherwise
- Limit file reads to directly relevant files only
- When generating code, include type annotations by default

## Project Stack
- Backend: Python 3.12, FastAPI, SQLAlchemy 2.0
- Frontend: TypeScript, React 19, Tailwind CSS v4
- Database: PostgreSQL 17
- Test: pytest, vitest

## Allowed Operations
- Read any file in this project
- Write to src/, tests/, docs/
- Run: npm test, pytest, go test, make build

## Code Style
- Follow existing naming conventions in the codebase
- Do not introduce new dependencies without asking
- Always run formatter after editing: black (Python) / prettier (TS)

8. 常见问题排查

以下是接入 Ollama 时最常遇到的错误及解决方案：

调试技巧

# 检查 Ollama 服务详细日志
OLLAMA_DEBUG=1 ollama serve 2>&1 | tee /tmp/ollama.log

# 直接测试 API 接口（绕过 Codex CLI）
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ollama" \
  -d '{"model":"qwen2.5-coder:7b","messages":[{"role":"user","content":"hello"}]}'

# 检查 GPU 使用情况（NVIDIA）
watch -n 1 nvidia-smi

# 检查 GPU 使用情况（Apple Silicon）
sudo powermetrics --samplers gpu_power -n 1

9. 进阶：团队共享远程 Ollama 服务器

如果你的团队有一台配备高端 GPU 的工作站或服务器，可以让所有人共用一个 Ollama 实例，避免每人都需要高端显卡。

服务端配置

# 服务器端：允许来自任意 IP 的请求（默认只监听 127.0.0.1）
OLLAMA_HOST=0.0.0.0 ollama serve

# 或者通过 systemd 永久设置（Linux）
sudo systemctl edit ollama

# 在打开的编辑器中添加：
# [Service]
# Environment="OLLAMA_HOST=0.0.0.0"

sudo systemctl daemon-reload && sudo systemctl restart ollama

客户端配置

# 将 localhost 替换为服务器的局域网 IP
export OPENAI_BASE_URL=http://192.168.1.100:11434/v1
export OPENAI_API_KEY=ollama
codex "分析这个函数的性能瓶颈"

安全加固建议

• 通过防火墙限制访问端口，只允许公司内网 IP 段访问 11434 端口
• 使用 Nginx 反向代理并添加 Basic Auth，避免完全开放访问
• 考虑使用 Tailscale 或 WireGuard 建立安全隧道，而不是直接暴露端口
• 定期更新 Ollama 版本以获取安全补丁

性能调优

# 设置并发请求数（默认 1，增大可服务多个客户端）
OLLAMA_NUM_PARALLEL=4 ollama serve

# 设置模型在内存中保留时间（默认 5 分钟，设为 0 立即卸载）
OLLAMA_KEEP_ALIVE=30m ollama serve

# 限制最大加载模型数量
OLLAMA_MAX_LOADED_MODELS=2 ollama serve

10. 常见问题解答（FAQ）

Codex CLI 可以使用 Ollama 本地模型吗？

可以。Codex CLI 支持任何兼容 OpenAI API 格式的后端，包括 Ollama。核心原理是：Ollama 在 http://localhost:11434/v1 提供一个与 OpenAI Chat Completions 完全兼容的 HTTP 接口。只需设置 OPENAI_BASE_URL=http://localhost:11434/v1 和 OPENAI_API_KEY=ollama，Codex CLI 就会将所有请求发送到本地 Ollama 服务，而不是 OpenAI 的服务器。

Ollama 哪个模型最适合 Codex CLI？

取决于你的硬件配置：

• 24GB+ 显存（高端 NVIDIA 或 Apple M2 Ultra/M3 Max）：推荐 qwen2.5-coder:32b，目前开源代码模型中综合表现最佳。
• 16GB 显存（RTX 3080/4080 或 M2 Pro）：推荐 deepseek-coder-v2:16b，在代码生成质量和运行速度之间取得了很好的平衡。
• 8GB 显存（RTX 3060/4060 或 M1/M2 基础款）：推荐 qwen2.5-coder:7b，可以流畅运行，代码质量在 7B 级别中属于最强。
• 无独显 / 纯 CPU：推荐 deepseek-coder:6.7b 的 Q4 量化版本，虽然速度较慢，但内存占用仅约 4GB。

本地模型和 OpenAI o4-mini 哪个更好？

这个问题没有绝对的答案，取决于你的优先级。OpenAI o4-mini 在代码生成质量、多步骤推理、跨文件理解等方面明显优于本地 32B 模型，特别是 o 系列的专用推理能力是本地模型目前难以企及的。但本地模型的优势也很实在：零成本、完全离线、代码数据不出本地，对于隐私敏感的企业项目或想要节省 API 费用的个人开发者，本地模型是合理的权衡选择。实际上许多团队采用混合策略：日常快速任务用本地模型，关键代码审查和复杂重构调用 OpenAI。

Codex CLI 接入 Ollama 需要什么硬件？

最低配置：8GB 显存（或 Apple Silicon 16GB 统一内存）可以运行 7B 模型，能够完成基本的代码补全和简单重构。推荐配置：16GB 显存支持 14B-16B 模型，可以处理中等复杂度的编程任务。高端配置：24GB+ 显存可运行 32B 模型，代码质量接近云端服务。纯 CPU 运行也可以（任何 RAM 16GB+ 的机器），但速度会比 GPU 慢 5-10 倍，实际使用体验较差。