摘要：在软件开发中，API Token 的消耗往往是一笔不小的开支。随着 OpenAI Codex 开始全面支持本地推理引擎，开发者可以通过 Ollama或 llama.cpp搭建本地大模型服务，将 Codex CLI / Desktop 的后台模型无缝替换为本地运行的开源模型。本文将详细讲解配置流程，带你打造一个无需联网、隐私安全且彻底免费的本地 AI Coding Agent。
> 
一、 为什么选择“Codex + 本地模型”架构？
OpenAI Codex 提供了出色的终端工具调用、多文件重构及代码库感知能力。但在处理大型项目或频繁重构时，云端 API 容易遇到调用限额及高昂的 Token 费用。
通过将 Codex 的后端 Endpoint 绑定至本地运行的推理框架，可以实现：
 Token 自由：无调用次数限制，彻底摆脱计费焦虑。
 数据安全与隐私：核心业务代码完全驻留在本地局域网，不经过第三方服务器。
 离线自主 Agent：配合本地模型，Codex 能在无网环境下独立完成文件读取、修改及本地脚本执行。
二、 准备工作
在配置前，请确保系统已安装以下基础环境：
 1. Node.js（用于安装 Codex CLI）
 2. Ollama 或 llama.cpp（用于提供 OpenAI 兼容接口）
 3. 推荐显存：8GB 以上（运行 7B~14B 量化模型）或 16GB 以上（运行更大参数模型）。
 三、 实战教程：接入本地推理引擎
方案 A：使用 Ollama 快速接入
Ollama 提供了极为简便的命令行交互，能自动配置 Codex 所需的 API 映射。
1. 安装 Codex CLI
```bash
npm install -g @openai/codex

```

 2. 拉取适合代码生成的开源模型
推荐使用对工具调用（Function Calling）与代码逻辑支持较好的开源模型（如 Qwen2.5-Coder、DeepSeek-Coder 或 Llama 3 系列）：
```bash
ollama pull qwen2.5-coder:14b

```
3. 启动并绑定 Codex
直接在终端通过 --oss 模式启动，并指定本地模型：
```bash
codex --oss -m qwen2.5-coder:14b

```
*如果使用的是 Codex Desktop App，也可以通过以下命令实现持久化绑定：*
```bash
ollama launch codex-app --model qwen2.5-coder:14b

``` 方案 B：使用 llama.cpp 实现极限性能优化
对于追求更高推理吞吐量或使用 GGUF 格式自定义量化权重的场景，可以直接使用 llama-server 暴露标准 /v1 接口。
1. 启动 llama.cpp API 服务
指定模型路径与稳定别名，确保开启工具调用模板与本地监听：
```bash
llama-server -m ~/Models/Qwen2.5-Coder-7B-Instruct-Q4_K_M.gguf \
  --alias qwen2.5-coder \
  --host 127.0.0.1 \
  --port 8080 \
  --jinja

```

2. 配置 Codex 局部 Profile
在 Codex 的配置目录中创建本地 Provider 配置文件 ~/.codex/llamacpp.config.toml：
```toml
model_provider = "llamacpp"
model = "qwen2.5-coder"

[model_providers.llamacpp]
name = "llama.cpp"
base_url = "http://127.0.0.1:8080/v1"
wire_api = "responses"
requires_openai_auth = false

```
 3. 环境变量与启动
在终端中设置虚拟 Key，并指定该 Profile 运行：
Linux / macOS:
```bash
export LLAMA_CPP_API_KEY=sk-no-key-required
codex exec --profile llamacpp -C ./your-project-dir "重构 src/utils.py 中的异常处理逻辑"

```
Windows PowerShell:
```powershell
$env:LLAMA_CPP_API_KEY="sk-no-key-required"
codex exec --profile llamacpp -C .\your-project-dir "检查当前目录下的单元测试并修复"

```
 四、 运行效果与体验建议
 1. 上下文窗口配置：Agent 模式会对上下文长度提出较高要求，建议在 Ollama / llama.cpp 中将上下文大小（num_ctx / -c）设置在 32768（32K）或更高，防止长代码截断。
 2. 显存优化：若显存有限，可开启 --lowvram 参数或使用 Q4_K_M / IQ4_XS 等高性能量化级别，优先保证长上下文推理速度。
通过上述配置，不仅摆脱了付费 API 的依赖，还建立了一套完全受控、支持自动干活的本地 AI Agent 运行环境。