Codex本地部署完全指南

agoutongxie

952人浏览 · 2026-09-10 10:35:23

agoutongxie · 2026-09-10 10:35:23 发布

OpenAI Codex 本地部署完全指南：从本机安装到企业私有化

文档版本：v1.0
更新时间：2026-09-10
适用范围：个人开发者、技术团队、企业架构师，目标是把 Codex（OpenAI 开源的终端编程智能体）以本地化/私有化方式部署并投入使用
说明：文中版本号与命令以撰写时官方文档为准，部署前请核对最新 Release

1. 概述：Codex 是什么，为什么本地部署

1.1 Codex 的定位

Codex 是 OpenAI 开源的终端编程智能体（Agentic Coding Agent），以命令行工具（Codex CLI）和桌面应用（Codex App）两种形态交付。它不是一个"代码补全插件"，而是一个能读取代码库、规划任务、执行命令、修改文件、运行测试、提交变更的自主执行体——与 Claude Code 同类定位。

到 2026 年，Codex 的关键特性包括：

特性	说明
Rust 原生构建	启动快、内存占用低，终端体验流畅
完全开源	代码透明可审计，社区驱动迭代
多模型支持	原生支持 OpenAI、Anthropic、Ollama、LM Studio、Amazon Bedrock，可自定义任意 OpenAI 兼容 API
多级沙箱	macOS Seatbelt、Linux bubblewrap、Windows 原生沙箱，平台级安全隔离
MCP 协议	通过 Model Context Protocol 连接任意外部工具和服务
多智能体协作	内置 Subagent 系统，支持并行任务委派
OSS 模式	2026 年 6 月重大更新，可接入任意开源大模型实现完全本地化

1.2 为什么需要"本地部署"

本地部署的核心驱动力有四类：

数据安全与合规：代码是企业最敏感资产。把代码库发往云端模型服务，对金融、政务、军工、医疗等受监管行业是硬红线。本地部署让"代码不出内网"成为可能；
成本可控：云端 agentic 编码按 token 计费，一个高频使用工程师月成本可能数百到上千元；本地模型（尤其 7B~32B 开源模型）一次硬件投入、长期零边际成本；
离线与稳定：内网隔离环境、无外网机房、出差断网场景，本地模型是唯一可行解；
可控与可审计：本地化后可以统一配置、统一审计、按需升级模型，不依赖外部服务的稳定性与限流策略。

1.3 本文的三种部署形态

本文按"数据与模型在哪里"划分三种形态，全篇围绕它们展开：

2. 部署形态与选型

2.1 三种形态对比

维度	形态一：云端模型	形态二：本地模型	形态三：企业私有化
模型能力	最强（GPT/Claude 旗舰）	中等（取决于开源模型）	中等~强（取决于集群规模）
代码数据去向	出网（有合规风险）	不出网	不出内网
成本结构	按 token 计费	硬件一次性 + 电费	集群投入 + 运维
部署复杂度	低	中	高
典型用户	个人、合规宽松团队	个人/小团队、离线环境	中大型企业、受监管行业
适合起步	✅ 最快见效	✅ 成本敏感	❌ 需评估后推进

2.2 决策逻辑

建议：绝大多数团队从形态一或形态二开始——先用云端模型验证 Codex 工作流是否适合团队，再用本地模型替换模型后端，最后按合规要求演进到形态三。不要一开始就上形态三，编码智能体的价值验证应当先于基建投入。

2.3 一个典型的演进案例

某中型 SaaS 公司的实际路径（示意）：

第 1 月（形态一）：3 人试点用云端模型跑 Codex，验证"修 bug、补测试、小功能开发"三类任务的效果，沉淀 AGENTS.md 与黄金任务集；
第 2 月（形态二）：采购一台 4090 双卡服务器，部署 Qwen2.5-Coder-32B，试点成员切换本地模型，对比完成率——本地模型覆盖了约七成日常任务，云端模型仅用于深度重构；
第 3 月（形态三）：合规部门要求代码不出内网，团队上线内网模型网关 + vLLM 集群，全员接入，云端通道仅保留为容灾降级；
第 4 月起：按黄金任务集每月回归，模型升级与提示词迭代纳入常规版本管理。

这个案例的关键不是"最终上了形态三"，而是每一步都有明确的验证出口：效果不达标就停在该形态，而不是盲目追加基建投资。

3. 环境准备与安装

3.1 系统要求

项	要求	说明
操作系统	macOS 12+ / Linux / Windows 10+	三平台均官方支持
运行环境	Node.js 18+（npm 安装方式）	也可用 Homebrew、curl 脚本或源码编译
终端	支持 TUI 的现代终端	Windows 推荐 Windows Terminal
沙箱依赖	macOS 内置 / Linux 需 bubblewrap / Windows 内置	见 5.3 沙箱章节
磁盘	500MB 以上	CLI 本体很小，模型另计
网络	视形态而定	形态二/三可完全离线

3.2 安装方式

方式一：npm（最通用）

npm install -g @openai/codex
codex --version   # 验证安装

方式二：Homebrew（macOS）

brew install codex

方式三：官方安装脚本（Linux/macOS）

curl -fsSL https://codex.openai.com/install.sh | bash

方式四：源码编译（需要 Rust 工具链）

git clone https://github.com/openai/codex.git
cd codex
cargo build --release

升级：npm 方式 npm update -g @openai/codex；brew 方式 brew upgrade codex。Codex 迭代非常快，建议团队固定版本并统一升级窗口，避免行为漂移。

3.3 桌面应用（Codex App）

除了 CLI，OpenAI 还提供 Codex App（桌面应用），提供图形化会话界面。其配置与 CLI 共享同一套 config.toml 与认证体系，且同样支持指向任意 OpenAI 兼容 API（包括本地模型）。偏好图形界面的用户可以直接用 App，命令行自动化场景用 CLI。

3.4 安装期常见问题

现象	原因	解决
npm 安装权限报错	全局安装需要写系统目录	用 `sudo` 或配置 npm 全局前缀到用户目录
`codex: command not found`	PATH 未包含 npm 全局 bin	执行 `npm config get prefix`，把对应目录加入 PATH
源码编译报 Rust 错误	工具链版本过旧	`rustup update stable` 后重试
企业内网无法下载	网络受限	走内部 npm/制品镜像，或离线安装包分发
安装成功但启动闪退	终端/系统组件兼容	换 Windows Terminal / iTerm2，检查系统版本满足最低要求

批量安装建议（团队场景）：把 @openai/codex 固定版本号打进内部制品库，用一条脚本统一安装，避免成员各自装不同版本导致行为不一致。

4. 配置与认证

4.1 配置文件：config.toml

Codex 的配置集中在 ~/.codex/config.toml（macOS/Linux）或 %USERPROFILE%\.codex\config.toml（Windows）。核心结构：

# 全局模型配置
model = "gpt-5.2-codex"
model_provider = "openai"

# 认证（二选一）
[openai_auth]
  # 方式一：API Key（从环境变量读取更安全）
  # 方式二：ChatGPT OAuth 登录（codex login 自动写入）

# 自定义模型提供方（profile）
[model_providers.ollama]
  name = "Ollama"
  base_url = "http://localhost:11434/v1"
  wire_api = "responses"
  env_key = "OLLAMA_API_KEY"   # 本地模型可省略

配置红线（社区高频踩坑）：

不要把凭证写进项目级配置：项目目录的 codex/config.toml（如 AGENTS.md 旁的配置）会被提交进 Git，密钥可能泄露。用户级凭证放 ~/.codex/，项目级配置只放行为类设置；
profile 写法：新版用 [model_providers.xxx] 定义提供方、用 [profiles.xxx] 定义命名组合，旧文章里的混写方式已失效，对照官方文档写；
环境变量优先：OPENAI_API_KEY、ANTHROPIC_API_KEY 等由环境变量注入，比写死在配置里安全得多。

4.4 多 Profile 与团队配置分发

Profile 机制：Codex 支持用 [profiles.xxx] 定义多套命名配置（如 work 走内网网关、local 走 Ollama、cloud 走 OpenAI），切换命令如 codex --profile local。典型用法：

# ~/.codex/config.toml
[profiles.local]
  model = "qwen2.5-coder:32b"
  model_provider = "ollama"

[profiles.work]
  model = "codex-local"
  model_provider = "internal-gateway"

团队分发建议：

个人凭证（API Key、登录态）留在用户级 ~/.codex/，绝不进仓库；
团队级行为配置（profile 定义、模型选择、沙箱默认值）放仓库内 codex/config.toml 或由内部配置系统下发；
每次升级后统一回归：先在一台机器验证新版本与团队配置兼容，再全员更新；
项目级配置（AGENTS.md）随仓库走，与代码一起评审、一起版本化。

4.2 认证方式对比

方式	适用	优点	注意
OpenAI API Key	形态一（OpenAI）	简单直接	按用量计费，妥善保管
ChatGPT OAuth 登录	有 ChatGPT Plus/Pro 订阅	复用订阅额度，无需单独开 API	`codex login` 交互式完成
Anthropic API Key	形态一（Claude 模型）	可切 Claude 系模型	需另配
本地模型（无认证）	形态二/三	零外部依赖	base_url 指向本地服务即可

4.3 最小配置示例

对接 OpenAI 云端（形态一）：

export OPENAI_API_KEY="sk-..."
codex

对接本机 Ollama（形态二，核心配置）：

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

[model_providers.ollama]
  name = "Ollama"
  base_url = "http://localhost:11434/v1"
  wire_api = "responses"

重要：Codex 对本地模型要求至少 64k 上下文窗口，选模型时必须确认其 context length 达标（如 Qwen2.5-Coder 32B 的 128k、DeepSeek-Coder 系 128k 等均满足）。

5. 核心功能与安全模型

5.1 交互模式

交互式（默认）：进入 TUI，与 Agent 多轮对话，实时看到工具执行与文件变更；
非交互式：codex exec "修复 README 中的拼写错误"，单条指令执行后退出，适合脚本与 CI；
恢复会话：codex resume 继续上次会话，会话按项目持久化，重启不丢上下文；
纯聊天：codex chat，不带工具权限，只问答。

5.2 工具集

Codex 内置的核心工具（随版本演进，以 codex --help 与官方文档为准）：

工具	作用	风险等级
Shell 命令执行	运行测试、构建、Git 操作等	高（可执行任意命令）
文件读写/编辑	修改代码文件	中
搜索（grep/glob）	定位代码	低
Web 检索	联网查资料（需放行）	低
MCP 工具	外部系统能力	视工具而定

5.3 安全审批模型（Sandbox）

Codex 的安全模型是三平台原生沙箱 + 审批分级：

模式	行为	适用
untrusted（默认）	工具操作前逐项询问，高风险命令需确认	日常使用
workspace	仅限当前工作目录内操作，目录外需确认	单项目聚焦开发
full-auto	全自动执行，不逐项询问	CI、可信环境、明确授权

沙箱实现：macOS 用 Seatbelt、Linux 用 bubblewrap、Windows 用原生沙箱——即使 Agent 被诱导执行恶意命令，也会被限制在沙箱边界内。

最佳实践：日常开发用 untrusted 或 workspace；只有明确授权的自动化场景（CI 流水线、一次性迁移脚本）才用 full-auto，且最好在隔离容器/虚拟机里跑。

5.4 MCP 与 Subagent

MCP：在配置中声明 MCP server，即可让 Codex 调用任意外部工具（数据库、浏览器、内部系统）。MCP 是 Codex 从"写代码"扩展到"操作系统"的关键；
Subagent：Codex 内置多智能体系统，可把子任务委派给并行 Subagent 执行（如同时排查两个模块），再汇总结果——大任务拆解时吞吐显著提升。

5.5 常用命令速查

codex                          # 交互式会话
codex exec "描述任务"           # 非交互式执行
codex resume                   # 恢复最近会话
codex login                    # ChatGPT OAuth 登录
codex logout                   # 登出
codex --oss                    # 以 OSS 模式启动（对接本地模型）
codex --help                   # 查看全部选项

5.6 会话与上下文管理

Codex 的上下文管理是本地部署效果的关键，三个要点：

AGENTS.md 是第一优先级的上下文：Codex 每次会话自动读取仓库根目录（及子目录）的 AGENTS.md，把项目结构、构建命令、编码规范、禁止事项写进去，能显著减少 Agent 的无效探索。它的作用大于任何技巧性提示词；
会话按项目隔离：会话上下文与项目绑定，切换项目不会串上下文；codex resume 恢复时按项目列出历史会话，长任务建议拆成多个短会话推进，避免上下文被历史垃圾占满；
上下文预算：本地模型上下文窗口有限（64k 起步），大仓库必须主动控制：用 AGENTS.md 指路、要求 Agent 先检索再回答、避免"把整个文件贴进对话"的用法；必要时在任务描述中限定文件范围。

6. 对接本地模型（核心章节）

6.1 OSS 模式

2026 年 6 月起，Codex 全面支持 OSS 模式（Open-Source Mode）：codex --oss 启动，即可对接任意 OpenAI 兼容 API——包括本机 Ollama、LM Studio、OpenRouter，以及自建网关。Codex App、CLI、SDK 三者均可指向任意兼容端点，不限于 GPT 系列。

这意味着本地部署的技术路径完全打通：Codex 本体是开源 Rust 程序，模型后端换成开源模型，整条链路可完全自主可控。

6.2 方案 A：Ollama（个人与小团队首选）

安装与启动：

# 安装 Ollama（官方脚本，或下载对应平台安装包）
curl -fsSL https://ollama.com/install.sh | sh

# 拉取适合编码的模型（按硬件选择规模）
ollama pull qwen2.5-coder:32b

# 启动服务（默认 11434 端口）
ollama serve

Ollama 官方还提供一键集成：

ollama launch codex

该命令自动完成 Codex 安装与 Ollama 对接配置。

Codex 侧配置（见 4.3）：base_url = "http://localhost:11434/v1"，wire_api = "responses"，模型选已拉取的编码模型。

6.3 方案 B：LM Studio

LM Studio 提供图形化管理本地模型的能力（下载模型、启动本地 OpenAI 兼容服务）：

在 LM Studio 中下载编码模型（如 Qwen2.5-Coder）；
启动 Local Server，默认端口 http://localhost:1234/v1；
Codex 配置 base_url = "http://localhost:1234/v1"。

6.4 方案 C：自建 OpenAI 兼容服务（vLLM）

企业/高性能场景用 vLLM 部署模型，吞吐与并发远优于 Ollama：

# 以 vLLM 启动 OpenAI 兼容服务（示例：Qwen2.5-Coder-32B）
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-Coder-32B-Instruct \
    --served-model-name codex-local \
    --tensor-parallel-size 4 \
    --max-model-len 65536

Codex 配置 base_url = "http://<内网IP>:8000/v1" 即可。

6.5 推荐模型清单

模型	参数量	上下文	编码能力	硬件建议
Qwen2.5-Coder-7B	7B	128k	基础可用	8GB VRAM（量化）
Qwen2.5-Coder-14B	14B	128k	良好	16GB VRAM
Qwen2.5-Coder-32B	32B	128k	强（社区常用首选）	24~48GB VRAM（量化/A100）
DeepSeek-Coder-V2 系列	16B~236B	128k	强	按规模配置
GLM-4 系列	9B~32B	128k	良好	按规模配置

模型榜单迭代快，部署前以最新评测与自身任务实测为准。工具调用（function calling）能力是 Codex 正常运行的前提，选模型时必须确认其支持 OpenAI 兼容的 function calling 格式。

6.6 工具调用协议兼容性问题（重要避坑）

本地部署最大的技术坑不在"能不能对话"，而在工具调用协议兼容性。一个真实案例：Ollama 的 /v1/responses 端点与 Codex 对接时，存在工具调用语义不兼容——HTTP 层返回 200、语法看似正常，但函数调用的参数结构错位，导致所有工具调用静默失败。社区已有协议桥接（bridge）方案解决此问题。

实践建议：

对接后必须先做工具调用冒烟测试：让 Codex “运行 ls 并告诉我结果”，确认工具链路通；
优先选择被社区验证过与 Codex 兼容的模型/端点组合（Ollama 官方文档的 Codex 集成页是首要参考）；
遇到"Agent 一直说但从不执行工具"的现象，优先怀疑协议兼容性，而不是模型能力；
备选 wire_api 值（responses / chat）在配置中可切换，不同端点行为不同，逐个试。

6.7 本地模型的限制与预期管理

限制	说明	应对
长任务稳定性	本地小模型多步推理易走偏	任务拆小、频繁确认
上下文管理	64k 起步，超大仓库仍需压缩	用 AGENTS.md 给 Agent 指路、限制检索范围
多语言弱项	中文代码注释理解弱于 GPT 系	提示词明确语言
工具调用率	部分小模型不肯/不会调工具	选 function-calling 强化的模型
速度	单 GPU 生成速度远低于云端	可接受则用，否则上多卡/量化

预期管理：本地模型（尤其 7B~14B）适合常规编码任务、增量修改、测试补全；对需要深度推理的大型重构，云端旗舰模型仍有明显优势。形态二的实际定位是"成本与隐私优先的日常主力"，不是"全场景替代"。

6.8 本地模型的选型与验收方法

本地模型不能只看榜单分数，必须在 Codex 真实工作流里验收。建议按三步走：

工具调用冒烟测试（必做）：接入后立刻执行三类指令——“列出当前目录文件”（shell 工具）、“在 X 文件中新增一行注释并保存”（文件工具）、“搜索包含关键字 Y 的代码”（检索工具）。三类全过，工具链路才算通；
黄金任务集回归：挑选 10~20 个团队真实任务（修 bug、补测试、加小功能、重构片段），记录每个任务的完成率与人工修正量，形成基线；换模型、改参数都跑同一套，用数据说话；
长期稳定性观察：连续使用一周，关注三类现象——多步推理是否走偏、工具调用是否退化（前期通后期不通通常是上下文累积问题）、生成速度是否随会话变长明显下降。

选型原则：优先选"社区验证过与 Codex 兼容"的模型（参考 Ollama 官方 Codex 集成文档与社区兼容清单），而不是参数最大的模型；同一规模下，function calling 能力比通用能力更重要——编码 Agent 的命脉是"会调工具"，不是"会聊天"。

7. 企业私有化部署方案

7.1 总体架构

7.2 组件职责

组件	选型	职责
模型网关	One-API / New API / LiteLLM（开源）	统一 OpenAI 兼容入口、多模型路由、密钥托管、限流配额
推理引擎	vLLM（首选）/ Ollama / TensorRT-LLM	模型推理，多卡并行
认证	对接企业 SSO / LDAP	网关层统一鉴权
审计	网关访问日志 + 模型调用日志	按人、按模型、按 token 计量
终端配置	团队统一下发 `config.toml`	统一 base_url、模型、沙箱策略

7.3 落地步骤

硬件评估：按并发用户数 × 单请求 token 估算吞吐，确定 GPU 规模（见第 8 章）；
推理层：部署 vLLM/Ollama，启动 OpenAI 兼容端点，做压测；
网关层：部署模型网关，接入推理端点与统一认证，配置模型路由与配额；
终端层：统一下发配置模板，Codex 指向内网网关地址；
审计与监控：接入既有监控体系（日志、指标、告警）；
灰度：先试点小组使用，验证效果与成本后再全员铺开。

7.4 网络与安全加固

内网隔离：模型网关与推理集群只暴露内网/专线，禁止公网直连；
最小权限：Codex 终端的沙箱默认 untrusted，写操作逐项确认；
审计留痕：每次会话记录用户、模型、token 消耗、文件变更摘要（可由网关日志 + Codex 会话记录联合完成）；
模型安全：本地模型同样存在提示注入与输出风险（仓库内恶意代码诱导 Agent 执行），沙箱 + 审批是最终防线；
供应链：Codex 与模型的升级走内部镜像/制品库，防止供应链投毒。

7.5 与 CI/CD 集成

# CI 中运行 Codex 非交互模式（示例：自动修复 lint 并提交）
codex exec "修复代码中的 lint 错误并提交变更" \
  --sandbox workspace \
  --model-provider internal-gateway

CI 场景注意：不要在 CI 里用 full-auto 且不审计，至少保留日志与变更 diff 评审。

7.6 多模型路由与容灾

企业网关的核心价值之一是多模型路由，把不同任务分给不同模型：

路由策略	规则示例	目的
按任务类型	简单问答 → 小模型；深度重构 → 大模型	成本优化
按团队/项目	核心项目 → 旗舰模型；外围项目 → 小模型	预算控制
按优先级	高优任务 → 独占队列	质量保障
按可用性	主模型故障 → 自动切换备用模型	容灾

容灾设计：推理集群至少两套模型（如 32B 主力 + 7B 备用），网关探测到主模型异常（超时率、错误率超阈值）自动降级；同时保留云端 API 作为终极降级通道（合规允许时）——Codex 侧只需切换 profile，业务不停。

8. 硬件与性能

8.1 模型规模与硬件对照

模型规模	显存需求（FP16）	量化后（Q4/Q8）	建议硬件
7B	~14GB	₅8GB	RTX 4060/4070（量化）
14B	~28GB	₁₀14GB	RTX 4090 / 3090×2
32B	~64GB	₂₀28GB	A100 40G / 4090×2（量化）
70B+	~140GB	~40GB+	A100/H100 多卡集群

8.2 量化与优化

AWQ / GPTQ / GGUF 量化：显存不够时优先量化，32B Q4 在消费级双卡上可跑；
KV Cache 优化：大上下文场景 KV cache 显存占用可观，用 vLLM 的 PagedAttention 可显著降低；
长上下文取舍：Codex 要求 64k 起，但并非越大越好——max-model-len 设得越大，显存占用与生成延迟越高，按仓库实际规模配置；
并发：单用户交互式使用一卡即可；团队并发需按"并发数 × 单请求峰值 token"扩容。

8.3 CPU 部署（兜底方案）

无 GPU 时可用 Ollama CPU 模式跑 7B~14B 量化模型，速度慢（每分钟数 token 到数十 token），但对轻度问答可用。作为团队主力不推荐，作为验证/离线兜底可行。

8.4 性能指标参考

指标	云端旗舰	本地 32B（A100）	本地 14B（4090）
首 token 延迟	~0.5s	_0.51s	_0.30.8s
生成速度	50~150 tok/s	30~80 tok/s	50~120 tok/s
工具调用可靠性	高	中~高	中

9. 常见问题与排障

现象	根因	解决
`codex` 命令不存在	未安装或 PATH 未配置	重装；npm 全局 bin 加入 PATH
认证失败	API Key 错误/过期，或未登录	检查环境变量；`codex login` 重新登录
连不上本地模型	Ollama/LM Studio 未启动或端口不对	`ollama serve`；检查 base_url 与端口
上下文不足报错	模型 context length < 64k	换长上下文模型，或改 `max-model-len`
Agent 不执行工具	工具调用协议不兼容	按 6.6 检查 wire_api、换兼容端点/模型
中文乱码	终端编码或模型输出编码问题	终端切 UTF-8；模型提示词指定中文
沙箱拦截过多	untrusted 模式询问频繁	按场景切 workspace；安全可信时再放宽
响应极慢	模型太大/未量化/CPU 推理	量化、换小模型、加 GPU
Windows 沙箱异常	Windows 沙箱依赖未满足	检查系统版本与沙箱组件，必要时降级非沙箱模式（慎用）
升级后行为变化	版本迭代快	固定版本、看 Release Notes 再升级

9.2 日志与调试

问题定位的三条通道：

Codex 自身日志：~/.codex/log/ 下保留会话与请求日志，遇到"行为异常但说不出原因"时，先看日志里模型返回的原始内容与工具调用结果；
模型侧日志：本地推理服务（Ollama/vLLM）的访问日志能看到每次请求的模型、token 数、耗时——排查"慢"和"贵"的第一现场；
网关日志（形态三）：记录每个用户每次请求的路由、模型、配额消耗，是审计与容量规划的权威来源。

调试技巧：给 Codex 一个最小复现任务（如"只运行 pwd 并输出"），逐步缩小问题范围——先确认 CLI 本身正常，再确认模型链路，再确认工具链路，最后才是具体业务问题。避免一上来就在复杂任务里排查。

10. 安全与合规

10.1 不可信代码执行风险

Codex 会执行命令、修改文件，本质上是一个"能跑代码的 Agent"，必须按"不可信代码执行"的安全等级对待：

默认 untrusted 沙箱 + 逐项审批，不用 full-auto 跑未审计任务；
关键操作（删库、push、部署、密钥相关命令）在审批层面强制人工确认；
在高危环境（生产服务器）运行前，先在容器/虚拟机里验证；
仓库内的恶意指令（README 里写"运行 rm -rf"）属于提示注入，沙箱与审批是防线。

10.2 数据与合规

形态一（云端模型）会向第三方发送代码内容，涉密项目必须走形态二/三；
本地部署不自动等于合规——仍需完成数据分类、访问控制、审计、删除策略；
深度合成/生成内容管理类合规要求按业务场景评估（编码工具一般仅涉及代码，风险低，但输出引入开源代码时需检查许可证合规）。

10.3 供应链安全

从官方渠道安装，校验发布签名/哈希；
企业内使用内部制品库缓存，锁版本；
模型权重从可信源（官方 Hub/内网镜像）拉取，校验哈希，防止投毒模型。

10.4 本地部署合规自查清单

检查项	要求
数据分级	明确哪些代码/数据可入 Codex 链路，涉密资产不进云端
网络隔离	本地模型链路是否仅内网可达
访问控制	谁可以用哪个模型，配额与审批
审计	会话、工具调用、文件变更、token 消耗是否留痕
模型许可	开源模型许可证（如 Qwen 系 Apache-2.0）是否满足商用要求
依赖许可	Agent 生成的代码引入的开源依赖是否符合团队许可证策略
密钥管理	API Key、网关凭证是否托管在密钥管理系统
备份恢复	会话记录、配置、模型部署脚本是否可恢复

自查清单应由安全团队定期复核，部署形态越重（形态三），清单越要制度化。

11. 最佳实践与工作流

11.1 日常开发工作流（推荐）

AGENTS.md 是本地部署的关键资产：在仓库根目录写清项目结构、构建命令、测试命令、编码约定，Codex 每次会话自动读取——这比任何提示词工程都更有效。

11.2 任务拆分原则

单次任务边界清晰（“修复 X 模块的 Y 缺陷"优于"优化整个系统”）；
让 Agent 先给方案再动手（高成本操作前要求"先说明计划"）；
长任务拆成多个短会话，每段验证后再继续。

11.3 团队协作规范

统一版本与配置（仓库内放团队级 codex/config.toml 行为配置，不含密钥）；
统一模型与参数（成本与效果可预期）；
会话记录与审计留痕（合规团队必做）；
建立"Agent 改动评审"流程：Agent 提交的代码走与人工代码相同的 Review 门禁。

11.4 成本对比（量级）

方案	成本结构	月成本量级（单活跃用户）
云端旗舰模型	按 token	数百元~数千元
本地 32B（租用 GPU）	云 GPU 租赁	数百~千元/卡
本地 14B（自购 4090）	一次性 ~1.5 万 + 电费	摊薄后很低
本地 7B（CPU 兜底）	极低	忽略不计

本地部署的"回本逻辑"是高频使用 + 长期使用：用量越大、周期越长，本地模型越划算；低频试用期先用云端更省。

11.5 AGENTS.md 模板示例

一份可复用的 AGENTS.md 骨架（放仓库根目录，随代码版本化）：

# 项目指南（Codex 自动读取）

## 项目结构
- src/main/java/：业务代码（Maven 多模块）
- src/test/：单元测试，运行 `mvn test`
- docs/：设计文档与接口说明

## 常用命令
- 构建：`mvn -q compile`
- 测试：`mvn -q test -Dtest=<类名>`
- 启动：`mvn spring-boot:run -Dspring-boot.run.profiles=dev`

## 编码约定
- Java 17，代码风格遵循 .editorconfig；
- 数据库访问走 MyBatis Mapper，禁止在 Service 里写原生 SQL；
- 新增公共方法必须补单元测试；
- 日志使用 slf4j，业务关键节点打 info，禁止打印敏感字段。

## 禁止事项
- 不要修改 pom.xml 的依赖版本（除非任务明确要求）；
- 不要直接改生产配置（application-prod.yml）；
- 不要删除其他模块的测试用例。

写好 AGENTS.md 后，用 codex exec "总结一下这个项目的构建方式" 验证 Agent 是否读到——读到了，后续任务质量会有立竿见影的提升。

12. 总结与展望

Codex 本地部署的本质，是把"OpenAI 的编码智能体"改造成"你的编码智能体"：代码不出内网、模型按需替换、行为完全可控。2026 年的技术现状是：

工具侧已成熟：Codex CLI/App 开源、Rust 原生、三平台沙箱、MCP、Subagent，OSS 模式打通了任意模型后端；
模型侧已可用：Qwen2.5-Coder、DeepSeek-Coder 等开源模型配合 64k+ 上下文与 function calling，已能满足常规编码任务；
工程侧要补课：本地部署的难点从"装不装得上"转移到"协议兼容、硬件规划、安全审计、团队规范"——这才是本文想传递的核心。

给不同角色的落地建议：

个人开发者：形态二起步，Ollama + 14B/32B 编码模型，一条命令跑通；
小团队：形态二或三简化版（一台带 GPU 的服务器 + Ollama/vLLM + 团队统一配置）；
中大型企业：按合规要求直接规划形态三（网关 + 推理集群 + 审计），试点小组验证后铺开；
所有人：无论哪种形态，先确认工具调用链路通畅（6.6 冒烟测试），再谈效果——这是本地部署 80% 问题的根源。

展望：随着开源编码模型与本地推理框架的迭代，终端编程智能体"本地化运行"会从"可行"走向"默认"。Codex 这层开源底座的意义，是让每个团队都能在这一天到来之前，就先把自己的 AI 编程能力握在手里。

修订记录

版本	日期	修订说明
v1.0	2026-09-10	初版发布，覆盖三种部署形态、本地模型对接、企业私有化与安全规范

本文档基于 2026 年 9 月生态现状撰写，Codex 版本迭代频繁，命令与配置以官方 GitHub 仓库与文档为准。

码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

不想先学一堆 React？用 Codex 帮你完成第一支 Remotion 动效视频

码道开发者社区

突发！英伟达限制员工使用Claude；程序员一条代码删掉89TB数据获刑：被判五年十个月；曝iPhone Duo有望支持微信双开 | 极客头条

码道开发者社区

每日热评｜学术牛马的救星还是幻觉放大器？47k星学术研究Agent技能包深度评测

码道开发者社区

所有评论(0)

查看更多评论

agoutongxie

@agoutongxie

已为社区贡献2条内容

Codex本地部署完全指南

agoutongxie

OpenAI Codex 本地部署完全指南：从本机安装到企业私有化

目录

1. 概述：Codex 是什么，为什么本地部署

1.1 Codex 的定位

1.2 为什么需要"本地部署"

1.3 本文的三种部署形态

2. 部署形态与选型

2.1 三种形态对比

2.2 决策逻辑

2.3 一个典型的演进案例

3. 环境准备与安装

3.1 系统要求

3.2 安装方式

3.3 桌面应用（Codex App）

3.4 安装期常见问题

4. 配置与认证

4.1 配置文件：config.toml

4.4 多 Profile 与团队配置分发

4.2 认证方式对比

4.3 最小配置示例

5. 核心功能与安全模型

5.1 交互模式

5.2 工具集

5.3 安全审批模型（Sandbox）

5.4 MCP 与 Subagent

5.5 常用命令速查

5.6 会话与上下文管理

6. 对接本地模型（核心章节）

6.1 OSS 模式

6.2 方案 A：Ollama（个人与小团队首选）

6.3 方案 B：LM Studio

6.4 方案 C：自建 OpenAI 兼容服务（vLLM）

6.5 推荐模型清单

6.6 工具调用协议兼容性问题（重要避坑）

6.7 本地模型的限制与预期管理

6.8 本地模型的选型与验收方法

7. 企业私有化部署方案

7.1 总体架构

7.2 组件职责

7.3 落地步骤

7.4 网络与安全加固

7.5 与 CI/CD 集成

7.6 多模型路由与容灾

8. 硬件与性能

8.1 模型规模与硬件对照

8.2 量化与优化

8.3 CPU 部署（兜底方案）

8.4 性能指标参考

9. 常见问题与排障

9.2 日志与调试

10. 安全与合规

10.1 不可信代码执行风险

10.2 数据与合规

10.3 供应链安全

10.4 本地部署合规自查清单

11. 最佳实践与工作流

11.1 日常开发工作流（推荐）

11.2 任务拆分原则

11.3 团队协作规范

11.4 成本对比（量级）

11.5 AGENTS.md 模板示例

12. 总结与展望

修订记录

所有评论(0)

温馨提示：您尚未绑定手机号

agoutongxie