企业官网建设流程全解析

最近我把 Codex 从单纯的网页聊天界面搬到了本地终端里，折腾了一圈才发现，真正意义上的“ Codex 本地部署”其实包含两件事：一是把 Codex 这个编程助手本体装到你自己的机器上，二是让它能调用本地的大语言模型。这两件事分开做都不难，合在一起就容易踩坑。这篇文章把我从下载安装、配置本地模型，到排查各种报错的完整经历写出来，给想搭一个不依赖云端、随时能改代码的 AI 编程助手的读者一个可以直接照做的方案。

先说明一下我这边的基本情况：主力机是 Windows，还有一台装 Ubuntu 的旧笔记本专门负责跑模型。所以下面的步骤兼顾 Windows 和 Linux/macOS 两种路径，能覆盖大多数人的使用场景。如果你只是想尽快跑通，那我建议你直接按第 2 节的安装步骤走，然后在第 3 节把本地模型接上，基本 20 分钟就能看到一个能干活的 Codex。

1. 为什么要本地化部署 Codex，而不是只用网页版

1.1 Codex 在开发链路里到底解决什么问题

Codex 不是传统意义上的“帮你补全代码”的插件，它更像是一个住在终端里的智能体：你给它一个任务描述，它会自己去读项目文件、执行命令、编辑代码，然后把改动结果告诉你。这和平时我们在 IDE 里按 Tab 补全、或者复制报错信息去问聊天机器人完全不是一回事。

我最早用 Codex 是让它帮我重构一个 Python 的报表模块。那模块有 2000 多行，逻辑散落在三四个文件里。我给的指令是“把数据库连接抽出来，统一走连接池，同时把查询里所有硬编码的表名改成配置读取”。Codex 不是只给我一段建议代码，而是真的把文件打开、逐段改完、再跑了一遍测试命令，最后把 diff 摆在我面前。这种“会动手”的工作方式，才是最吸引我把它部署到本地的核心原因。

1.2 本地部署换来的三项实际收益

把 Codex 从云端聊天界面搬到本地终端，不只是“换了个入口”，它实际改写了三条使用逻辑：

• 数据和代码不出内网。你可以直接让它处理有保密要求的业务代码，无需担心代码文本被发送到云端模型服务做上下文分析。只要模型运行在本地，代码流全程在自己机器上，这对企业项目和技术预研来说尤其重要。
• 切断对单一云端服务的依赖。Codex 默认会走 OpenAI 的接口，但本地部署后可以接 Ollama、DeepSeek 或者其他兼容接口。也就是说，你可以在断网环境、内网隔离环境，甚至只有 CPU 的机器上继续用“会动手”的编程助手。
• 更细的调试粒度。终端版本的输出、日志、配置文件都是明文，我能清楚地看到它每一步调了哪个模型、传了哪些参数、在哪个环节报错。相比之下，网页版更像一个黑盒，出了问题只能干瞪眼。

1.3 什么情况不适合本地部署

我不太建议完全零基础的读者一上来就搞纯本地部署。原因不是安装多难，而是后面“调模型”这件事很吃经验：本地模型选小了，Codex 会表现得像个刚学编程的新手；选大了，显存不够又卡成幻灯片。

如果只是想在 IDE 里体验 AI 编程，直接用官方已经封装好的桌面版就好。本地部署更适合这三类人：一是对数据出境敏感的开发者，二是想把编程助手集成到 CI/CD 或内网环境里的运维工程师，三是想深入研究 Codex 智能体机制、搞清楚模型调用链路的爱好者。你属于哪一类，就去选对应的路线，别硬扛。

2. 下载安装：从零到能跑通一条命令的完整过程

2.1 先把 Node、Git 和环境变量理顺

Codex 的 CLI 主要走 npm 分发，所以第一步是把 Node.js 装好。注意版本要求，Codex 对 Node 版本有硬性下限，我建议装 Node.js 20 LTS 以上，因为部分依赖在新版本里才会正常加载。装完后打开终端，依次确认三个命令能正常回显版本号：

node -v npm -v git --version

如果git没有安装，也用下面的命令补上。Windows 用户建议用 winget，macOS 用户建议用 Homebrew：

# Windows winget install Git.Git # macOS brew install git

这里面有一个很容易被忽略的点：安装完 Node 和 Git 后必须重新打开一个新的终端窗口。因为 PATH 环境变量不会在已经打开的窗口里自动刷新，我和不少人都栽在这一步——装完一切正常，但新终端里一敲node就提示“不是内部或外部命令”，白白浪费十几分钟。

2.2 用 npm 安装 Codex CLI

环境确认无误后，执行全局安装命令：

npm install -g @openai/codex

装完以后验证版本：

codex --version

正常情况下你会看到类似codex/0.1.0的版本输出。安装后，Codex 会在用户目录下创建一个.codex文件夹，用来放配置、日志和会话数据。Windows 上这个路径是C:\Users\你的用户名\.codex，Linux/macOS 是~/.codex。

注意：如果你的npm全局包安装目录不在 PATH 里，命令行会提示找不到codex。Windows 上可以通过npm config get prefix查看路径，然后把那个目录加到用户 PATH；Linux/macOS 一般不用额外设置，但如果用的是 nvm，需要确保软链正常。

如果你想用官方桌面版而不是纯命令行，可以去 Codex 官网下载 Windows 桌面安装包。桌面版的底层和 CLI 是同一套运行时，只是外面包了一层图形界面，适合喜欢窗口操作的读者。

2.3 登录与授权：个人账号、组织账号怎么选

安装只是开始，要让 Codex 真正连上 OpenAI 的服务，还需要完成身份认证。在终端输入：

codex login

此时终端会打开一个浏览器页面，让你选择登录方式。日常玩玩的个人用户，直接用你的 ChatGPT 账号授权就行，这种方式的优点是会自动刷新令牌，你不需要自己管 API Key。如果是企业里用，那就用组织账号登录，Organization ID 会在登录后自动关联。

需要注意：如果你用的是 API Key 方式，就不要把 Key 写在任何命令行参数里，正确的做法是把它放到环境变量中：

# Windows PowerShell $env:OPENAI_API_KEY="sk-你的key" # Linux/macOS export OPENAI_API_KEY="sk-你的key"

我把一次真实的报错经历放在这里作提醒：我第一次登录时用的是个人账号，但在公司电脑上又绑定了组织账号，结果 Codex 始终提示“无法加载组织设置”。后来才发现是因为~/.codex/auth.json里同时存在两套凭据，Codex 默认取了旧的那一套。处理办法是把 auth.json 备份后删掉，重新执行codex login，让它只保留一份校验信息。

2.4 安装阶段最容易出的三个错

按我帮同事排查的经验，安装阶段的高频错误基本就是三类：

• certificate verify failed或网络证书报错。这是本地网络环境跟 npm 源的 TLS 握手出了问题。如果是公司内网，先问清楚网管有没有专用的 npm 私服地址，有就把 registry 切到私服；如果只是家用网络偶发不稳定，重试一般就能恢复，不要盲目去加strict-ssl=false。
• npm 安装超时。Codex 的依赖包不少，网络不好时很常见 5 分钟还没装完。可以先把 npm 的超时时间适当调大，或者换一个非高峰时段再跑。我不建议为了图快而用那些来路不明的加速工具，安全风险大于收益。
• PowerShell 脚本执行策略限制。Windows 上如果报“无法加载文件，因为在此系统上禁止运行脚本”，需要用管理员身份打开 PowerShell 执行一次Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。这一步没有副作用，是 Windows 官方推荐的安全策略调整方式。

安装这块没什么玄学，核心就一句话：环境变量、网络连通性、脚本执行权限，三样理顺了，codex命令必然能起来。

3. 接入本地模型：让 Codex 调用 Ollama 与 DeepSeek

3.1 Codex 的模型路由机制和执行流程

很多读者搜索“Codex 接入 DeepSeek”或“Ollama 本地部署”，其实想要的是同一个结果：让 Codex 这个智能体外壳，驱动本地的大模型来干活。要做到这一点，先要理解 Codex 的模型路由逻辑。

Codex 的所有模型请求，都会经过一个叫model_providers的配置区。Codex 的配置中心是~/.codex/config.toml，默认情况下它只有一个指向 OpenAI 官方服务的 provider。你可以在这个文件里追加一个本地 provider，指向 Ollama 或者任何兼容 OpenAI API 格式的本地服务。之后在启动 Codex 时，用一个--model参数指定“用哪个 provider 下的哪个模型”即可。

不同模型提供者还有一个关键区别：wire_api。Codex 官方默认用的是 Responses API，对应/responses端点；Ollama 和一些私有化部署模型用的是 Chat Completions 模式，对应/v1/chat/completions。你在配置里必须明确告诉 Codex 用哪种协议，否则请求会全部打到错误的路径上。

3.2 config.toml 关键字段逐一解释

我用一份实际可用的配置做例子，不展开高大上的概念：

model = "ollama/qwen2.5-coder:14b" model_provider = "ollama" [model_providers.ollama] name = "Ollama Local" base_url = "http://127.0.0.1:11434/v1" wire_api = "chat" env_key = "NO_KEY"

逐行解释一下：

• model：默认使用的模型标识。格式是provider名称/模型名称，这里指 ollama provider 下面名为qwen2.5-coder:14b的模型。
• model_provider：指定默认 provider，和上面的 model 前缀对应。
• [model_providers.ollama]：定义名为 ollama 的 provider。
• name：显示名称，随意取。
• base_url：本地模型服务的地址。Ollama 默认监听 11434，OpenAI 兼容接口要加/v1后缀。注意我用的是127.0.0.1而不是localhost，因为有些系统会把 localhost 解析成 IPv6 的::1，而 Ollama 只监听了 IPv4，导致连接被拒绝。
• wire_api：设为chat，表示走 Chat Completions 协议。如果保留默认的responses，Codex 请求时会出现路由错误。
• env_key：告诉 Codex 读取哪个环境变量作为 API Key。本地 Ollama 不需要钥匙，填一个不存在或无所谓的值比如NO_KEY，Codex 就会跳过鉴权。

如果你需要通过兼容 OpenAI API 的 DeepSeek 官方接口，而不是本地 Ollama，那么配置思路完全一样，只是把base_url换成服务商提供的地址，env_key换成你自己的密钥变量名。

3.3 本地模型下载与会话联调

写完配置文件，接下来启动本地模型服务。先在 Ollama 官网下载对应系统的安装包装好，然后拉取你想要的代码模型。这里给几个经过我验证的推荐：

# 代码能力较强的通用模型 ollama pull qwen2.5-coder:14b # 逻辑推理型，适合代码 review 和架构分析 ollama pull deepseek-r1:14b

拉取完成后，在另一个终端里启动服务（新版 Ollama 装完会自动常驻，但手动启动更直观）：

ollama serve

然后验证一下本地接口是否真的通了：

curl http://127.0.0.1:11434/v1/models

能看到模型列表 JSON，就说明服务正常。最后，回到 Codex 终端，敲下面这行命令进入会话：

codex --model ollama/qwen2.5-coder:14b

进去后随便让它写一段冒泡排序，如果能正常生成代码并保存成文件，就说明本地链路完全打通了。我第一次打通的时候，还特意把网线拔了测试，Codex 依然能完成代码修改，那一刻才真正感觉到“本地部署”四个字的分量。

3.4 常见本地组合的性能对比

本地模型不是越大越好，得看你机器的配置。我把自己试过的几组组合放进表格，方便你做选择：

如果你只是想体验“会动手的 AI 编程助手”，先用 qwen2.5-coder:7b 打通流程就够了；如果是要真正用于项目开发，我建议至少上 14b。再往上，除非你手头有不错的 GPU 资源，否则等待时间会让写代码的流畅感大打折扣。

4. 真实使用中的高频故障与完整排查链路

跑通不代表能稳定用，这一段写的是我实际使用两周后遇到的高频故障和完整排查链路。我不会只给你结论，而是把排查思路也一并写出来，遇到类似问题时你可以顺着走。

4.1 cc switch 报本地链路切换失败，导致 /responses 端点阻塞

先描述症状：装了 cc switch 这类本地切换工具的用户，在 Codex 使用过程中会突然看到类似cc switch ... local ... failed while handling codex endpoint /responses的错误。这个错误的字面意思是：本地切换工具在处理 Codex 的 /responses 请求时，没能成功完成链路切换，所以请求被中断。它通常不是 Codex 本身的问题，而是本地多服务并发时，端口或宿主解析被抢占导致的。

我的排查链路如下：

1. 先看 Codex 能不能独立运行。把 cc switch 退掉，单独启动 Codex，如果能正常请求，说明冲突源来自切换工具残留。
2. 检查本地端口监听状态。用netstat -ano | findstr 11434（Windows）或netstat -an | grep 11434（Linux），确认本地模型服务的端口只被一个进程占用。
3. 清理 cc switch 的缓存和日志。这类工具一般会在用户目录下保存历史会话状态，把它的缓存目录改名后重启，让工具重新初始化。
4. 最后再重新执行codex login，让 Codex 重新走一遍 token 校验。

注意：遇到这类错误时不要反复重试，很容易把本地会话文件写坏。正确操作是先退出所有第三方工具，再启动 Codex 验证，最后再逐步把工具加回来。

4.2 模型不支持提示“gpt-5.6-sol”时该怎么解

有读者私信问：我在配置里填了gpt-5.6-sol，Codex 报the 'gpt-5.6-sol' model is not supported when using codex with a ...。这个问题分两层看。第一层，Codex 在通过本地 provider 走 Chat 接口时，会检查模型名称是否在其支持前缀列表内，防止有人胡乱指定模型导致协议不匹配。第二层，gpt-5.6-sol根本不是当前 Codex 内置的模型标识，可能是你从某个渠道看到了未发布的模型名，或者单纯笔误。

正确解法是用codex models命令列出当前可用的模型标识：

codex models

看到输出后，选择其中带ollama/前缀的本地模型，或用codex --help查看当前版本支持的默认模型。如果你确定要用某个不在列表里的模型，正确做法是在本地 provider 的配置里给它取一个别名，让 Codex 认为它是合规模型，具体字段是：

[model_providers.ollama] name = "Ollama Local" base_url = "http://127.0.0.1:11434/v1" wire_api = "chat" env_key = "NO_KEY" includes_model_ids = ["qwen2.5-coder:14b"]

给 provider 加上includes_model_ids白名单后，Codex 就会把这个模型视为可用项，不再报 not supported。

4.3 Windows 桌面版设置一直转圈 / “设置未完成”

Windows 桌面版有它自己的脾气。最常见的是安装完打开设置，页面一直转圈，或者显示“设置未完成”。这个问题的根因通常不是软件坏了，而是桌面版在初始化时依赖的三个基础项没对齐：

• 用户目录下的.codex文件夹首次创建失败；
• Windows 没有开启开发者模式（影响符号链接创建）；
• 终端模拟器的权限不足。

排查顺序是：

1. 打开设置 -> 隐私和安全性 -> 开发者选项，确认“开发人员模式”开关是打开的，这一步影响 Codex 在 Windows 上创建模拟终端和链接的能力。
2. 手动进入%USERPROFILE%\.codex，确认目录存在且不是被同步盘（如 OneDrive）重定向的路径。有很多人把用户目录同步到了云盘，结果 Codex 写配置时被云盘锁定，设置页就永远转圈。
3. 右键桌面版图标，选择“以管理员身份运行”，等设置页正常后再退出，以后用普通方式启动即可。

如果你遇到的是“无法加载组织设置”，处理思路也在这附近：删掉~/.codex下的会话缓存后重启。注意删之前把config.toml和auth.json备份出来，只清缓存文件。

4.4 组织设置加载失败的处理

组织设置加载失败，我遇到过两种形态。一种是登录后 Codex 完全读不到组织的任何配置，另一种是能读到一部分，但模型列表和权限策略缺失。

第一种形态的根源通常是登录凭据混乱。我前面说过，~/.codex/auth.json里如果有多份凭据，Codex 会优先读取错误的那个。处理办法只有一个：备份后清掉，执行codex login重新登录，登录时注意在浏览器里切换到目标组织身份。

第二种形态多半是企业自己搭了模型网关，组织管理员把模型列表下发逻辑改了。这个你本地没法绕，只能找到管理员，让网关接口返回完整的模型清单。如果你只是自己搭着玩，遇到组织设置加载错误，直接忽略组织相关的设置项，用--model参数显式指定模型即可，这个参数优先于所有组织策略。

5. 把本地 Codex 用好的经验与底线

5.1 密钥与凭据管理

本地部署最大的风险不是模型跑得慢，而是凭据泄露。特别是接远程服务商的 API 时，Key 一旦被误传到代码仓库或者日志系统里，损失很难估。我给自己定了几条死规矩：

• 环境变量优先，配置文件尽量不写env_key对应的明文值。
• auth.json和所有含密钥的文件，加入.gitignore，并单独备份到一个离线位置。
• 定期检查~/.codex/logs目录，确认没有把模型的 system prompt 或 API Key 打印在日志里。

如果你要给团队用，建议不要把配置文件直接发给每个人，而是用环境变量注入的方式，让每个人的 token 都保持独立，出问题也方便单独回收。

5.2 沙箱边界与权限收敛

Codex 既然能自己执行命令，就意味着它有“破坏性”的一面。我看过有人在生产服务器上直接把--sandbox参数关掉，让它以完全权限运行，结果 Codex 一个误操作把构建目录清空了。正确的做法是：

• 本地测试时保留 Codex 默认的沙箱模式，甚至故意给它一个只读的测试目录，让它在里面跑破坏性命令。
• 必须执行高风险命令（如git push）时，先按Esc中断自动执行，手工确认命令内容后再放行。
• 不要用 root 或管理员账号跑 Codex，给它建一个低权限用户，哪怕它把项目删了，也不至于伤到系统。

我这里特别强调这一点，是因为“会动手”的智能体比“只会聊天”的机器人危险得多，权限边界是你能控制它的最后一道闸门。

5.3 日志、缓存与日常清理

Codex 的日志和缓存会随着使用迅速膨胀，尤其是跑长会话时，切换过多个模型的话，日志里会积累大量请求详情。我建议每周做两次清理：

rm -rf ~/.codex/logs/* 2>/dev/null rm -rf ~/.codex/sessions/*.json 2>/dev/null

注意 sessions 文件里有全部对话上下文，如果你有需要保留的项目，建议先单独导出备份再清理，否则一个误删就直接丢掉了历史思考链路。

清理完记得重启 Codex。如果后续出现莫名其妙的内存飙升，先看看日志文件是不是撑爆了磁盘，再怀疑模型本身的问题。这个顺序别搞反，我排那个内存问题时，一直怀疑是本地模型加载了太多参数，最后发现是日志积累了 6 个 G，浪费了两个小时。

我个人现在的习惯是：日常写业务代码用 Ollama 的 qwen2.5-coder:14b，碰到底层逻辑分析和架构设计时，临时切到 DeepSeek 系列模型。整个过程都是在这台本地机器上完成的，不拖云端，不打断思路，改代码就像跟一个坐在旁边的同事协作。如果你也想试，我建议你从最小的模型开始跑通流程，再逐步换大模型，这条路走一遍，后面所有报错你都能自己判断是模型问题、配置问题还是网络问题。