前言：为什么要在本地运行 Codex？
用 Codex CLI 调用 OpenAI API 是最简单的方式——GPT-5.5 的 400K 上下文窗口、服务端压缩、提示词缓存都很强。但以下几种场景，本地推理是更好的选择：
- 数据敏感：金融、医疗、军工代码不能离开内网
- 成本可控：长期运行不想烧 API 额度
- 离线环境：隔离网络或弱网条件
- 自主可控：模型版本、限流规则完全由你决定
本文将教你用 Docker Model Runner (DMR) 在本地运行 Codex，并搭建本地 + 云端混合工作流——简单任务本地跑，复杂任务云端跑，兼顾隐私与性能。
一、前置条件：检查你的环境
1. Docker 是否已安装
打开终端运行：
docker --version
如果显示 Docker version XX.XX.X，跳过下一步。如果没有，去 docker.com/products/docker-desktop 下载并安装 Docker Desktop（Windows/Mac）或 Docker Engine（Linux）。
2. GPU 支持（可选但推荐）
本地运行大模型，GPU 能让速度提升 10 倍以上。DMR 支持： - NVIDIA GPU：需安装 CUDA 驱动，在 Docker Desktop 设置中开启 GPU 加速 - AMD GPU：Linux 下支持 ROCm，Windows 下暂不支持 - Intel 集成显卡：通过 Vulkan 后端支持 - Apple Silicon：Mac 上自动使用 Metal，无需额外配置
二、启用 Docker Model Runner
Docker Desktop（macOS / Windows / Linux）
- 打开 Docker Desktop
- 进入 Settings → AI
- toggling Docker Model Runner 开关为 On
- 如果是 NVIDIA GPU，同时开启 GPU-backed inference
Docker Engine（Linux 无头服务器）
# Ubuntu / Debian
sudo apt-get install docker-model-plugin
# RHEL / Fedora
sudo dnf install docker-model-plugin
验证安装：
docker model version
看到版本号即表示安装成功。
三、拉取编码专用模型
DMR 推荐使用 GPT-OSS 系列模型——专为 Codex CLI 的工具调用协议优化。
全尺寸模型（适合 16GB+ RAM 或独立显卡）
docker model pull ai/gpt-oss:120b
轻量模型（适合 8GB 内存或无独立显卡）
docker model pull ai/gpt-oss:20b
也可以拉取 Hugging Face 上的第三方模型
docker model pull hf.co/bartowski/Qwen3-Coder-Next-30B-GGUF
查看已下载的模型：
docker model ls
四、测试模型是否正常工作
docker model run ai/gpt-oss:120b
进入交互式聊天后，输入一个编程问题测试，例如：
写一个 Python 函数，计算斐波那契数列第 n 项
收到正确回复后按 Ctrl+C 退出。
五、安装 Codex CLI 技能包
DMR 自带一套 Codex CLI 技能，教会 Codex 如何管理本地模型：
docker model skills --codex
这会安装技能文件到 ~/.codex/skills/。你可以同时为多个 AI 助手安装：
docker model skills --codex --claude
升级时用 --force 覆盖旧版本：
docker model skills --codex --force
六、配置 Codex CLI 连接本地模型
编辑或创建 ~/.codex/config.toml，添加 DMR 作为模型提供商：
[model_providers.docker-runner]
name = "Docker Model Runner"
base_url = "http://localhost:12434/engines/v1"
无需 env_key——DMR 本地运行，不需要认证。
七、创建 Profile：定义不同场景下的推理策略
在同一个 config.toml 中添加多个 Profile：
# 本地全尺寸模型：深度代码重构
[profiles.docker-local]
model_provider = "docker-runner"
model = "ai/gpt-oss:120b"
reasoning_effort = "medium"
# 本地轻量模型：快速迭代测试
[profiles.docker-fast]
model_provider = "docker-runner"
model = "ai/gpt-oss:20b"
reasoning_effort = "low"
# 云端模型：复杂长周期任务
[profiles.cloud]
model = "gpt-5.5"
reasoning_effort = "high"
切换 Profile 使用
# 敏感代码本地跑，不离开机器
codex --profile docker-local "重构认证模块，改用 RBAC"
# 快速本地迭代，零成本
codex --profile docker-fast "给 parseConfig 函数加单元测试"
# 复杂迁移，需要云端大上下文
codex --profile cloud "将代码库从 Express 迁移到 Fastify"
⚠️ 注意：
--oss快捷参数只针对 Ollama 和 LM Studio，DMR 请使用上面的--profile方式显式切换。
八、混合工作流：何时用本地，何时用云端？
核心决策变量：上下文窗口大小。
| 场景 | 推荐 Profile | 理由 |
|---|---|---|
| 专有算法重构 | docker-local |
代码不出机器 |
| 快速测试生成 | docker-fast |
低延迟，零成本 |
| 多文件迁移（>20 个文件） | cloud |
需要大上下文窗口 |
| 物理隔离环境 | docker-local |
无需网络 |
| 安全审计 | cloud (GPT-5.2-Codex) |
专用安全模型 |
| 周末个人项目 | docker-fast |
零 API 花费 |
本地模型的局限：大多数消费级硬件上，本地模型的有效上下文上限约为 64K tokens。超过这个量，质量会下降，或者你需要切换到云端。GPT-5.5 云端可提供 400K tokens（API 调用可达 1M）。
九、性能调优技巧
1. 调整上下文窗口
# 查看当前配置
docker model inspect ai/gpt-oss:120b
Codex CLI 建议至少 64K tokens 才能有效运行 Agent。64GB 统一内存的 Apple Silicon Mac 上，120B 模型可舒适地服务 64K 上下文；32GB 机器建议用 20B 模型。
2. GPU 后端选择
- Apple Silicon：Metal 自动启用，无需配置
- NVIDIA：确保 CUDA 驱动已安装，Docker Desktop 设置中开启 GPU 推理
- AMD：Linux 下支持 ROCm，需要兼容驱动
- 其他 GPU：Vulkan 后端提供广泛兼容
3. 模型自动卸载
DMR 会在空闲时自动从内存卸载模型，释放资源。切换本地/云端 Profile 时，本地模型不会持续占用 VRAM。
十、安全注意事项
CVE-2026-33990（重要）
2026 年 4 月，Docker 修复了 DMR 的 OCI Registry Client SSRF 漏洞。请立即更新 Docker Desktop 到最新版本：
docker model version # 确认已在修复版本之上
网络隔离
DMR 默认只在 localhost 提供服务，TCP 端口 12434 不会暴露到外部网络。如需额外加固：
[model_providers.docker-runner]
name = "Docker Model Runner (local only)"
base_url = "http://127.0.0.1:12434/engines/v1"
代码隐私
本地推理的核心价值就是代码不出机。DMR 在推理过程中不会向 Docker 或模型发布者发送任何遥测数据。
十一、完整配置文件示例
一份可直接使用的 ~/.codex/config.toml：
# 默认使用云端模型
model = "gpt-5.5"
# Docker Model Runner 提供商
[model_providers.docker-runner]
name = "Docker Model Runner"
base_url = "http://localhost:12434/engines/v1"
# 三个 Profile
[profiles.private]
model_provider = "docker-runner"
model = "ai/gpt-oss:120b"
reasoning_effort = "medium"
[profiles.quick]
model_provider = "docker-runner"
model = "ai/gpt-oss:20b"
reasoning_effort = "low"
[profiles.deep]
model = "gpt-5.5"
reasoning_effort = "high"
日常使用示例
# 早上：本地快速生成测试用例
codex --profile quick "为 src/billing/ 生成边界情况测试"
# 下午：本地处理敏感代码重构
codex --profile private "将支付网关提取为独立模块"
# 复杂迁移：切换到云端
codex --profile deep "将 REST API 从 v2 迁移到 v3 规范"
十二、与 Ollama 的对比
| 特性 | Docker Model Runner | Ollama |
|---|---|---|
| 安装方式 | 内置 Docker Desktop | 独立二进制 |
| 模型格式 | OCI artifacts (GGUF, Safetensors) | Modelfile + GGUF |
| API 端点 | localhost:12434 |
localhost:11434 |
| 推理引擎 | llama.cpp, vLLM, Diffusers | llama.cpp 仅 |
| GPU 支持 | CUDA, ROCm, Vulkan, Metal | CUDA, ROCm, Metal |
| Codex 技能 | docker model skills --codex |
无官方技能 |
两者可以共存，在 config.toml 中分别定义 Provider 并通过 Profile 切换即可。
来源
来源：Daniel Vaughan，《Codex CLI and Docker Model Runner: Containerised Local Inference for Private, Cost-Free Coding Agents》，Codex Knowledge Base，2026-04-29 发布，2026-08-31 更新。原文详细介绍了 DMR 的完整部署流程、Profile 配置、混合工作流策略及性能调优方法。
资料最后核对日期：2026-08-31 · 内容整理自 CodexGuide 社区公开教程