企业官网建设流程全解析

Codex 这名字这两年折腾 AI 编程的人都绕不开，但很多人冲到下载页装完，发现它默认跑的是一套云端模型服务，本地环境完全没利用起来。我花了大半天时间把 Codex 从安装、配置到接入本地大模型完整跑了一遍，最后整出了一个能脱网状态下继续干活的 AI 编程助手。这篇就从头讲讲我是怎么做的，适合正在评估 Codex 或者想把 AI 编程能力搬进本地环境的朋友参考。

先说清楚，Codex 是 OpenAI 出的一个 AI 编程代理工具，它不是一个聊天窗口，而是能直接在你项目目录里读代码、改代码、跑命令的那种。你可以把它理解成一个“住在终端里的结对工程师”。默认情况下，它走的是在线模型接口，依赖网络、依赖平台账号。而我这次做的本地部署，核心思路很简单：把模型这一环从云端换成本地或可自控的模型服务，让 Codex 的客户端能力继续保留，但推理后端由自己掌控。

1. Codex 到底是什么？为什么值得本地部署

1.1 先理解 Codex 的定位

Codex 在外观上确实只是个命令行程序，装好后你在终端敲codex就能交互。但它的内核是一个“代理式”编程助手，跟那些只做补全的代码插件不是一类东西。它可以：

• 扫描你的整个项目结构，理解上下文；
• 按你的自然语言指令修改多个文件；
• 自动执行测试、lint、构建命令；
• 在沙箱环境里试验代码，给出运行结果。

实际上，Codex 的工程化能力来自“模型推理 + 工具调用”的闭环。它会先拆解你的需求，生成步骤，然后逐步调用终端工具、读写文件，每一步都回到模型重新评估。这也是为什么它比“复制粘贴问答”要复杂得多。

1.2 做本地部署解决的几个问题

我选择本地部署，不是因为 Codex 默认体验不好，而是有现实痛点：

• 数据敏感：公司项目或者个人私有代码不适合丢给外部服务；本地部署意味着代码只在本地进出，推理也在本机或内网完成。
• 依赖外部服务的不稳定：网络抖动、服务限流、登录失效都会打断工作流。本地模型跑起来之后，这些因素基本被隔离了。
• 成本与配额：云端模型服务按 token 计费，高强度使用一上午可能就消耗不少额度。本地模型只要硬件扛得住，想跑多少跑多少。
• 可定制性：想要给模型加特定系统提示、微调行为、限定工具权限，本地部署能完全掌控。

这里要提醒一下：Codex 本身是开源 CLI，但“本地部署”不等于彻底离线。如果你要用 OpenAI 官方模型，依然需要网络；如果你想完全走本地模型，就需要像 Ollama 这样的大模型运行环境来提供推理服务。所谓“本地部署”，正确理解是把 Codex 客户端和模型服务都装在自己可控的环境里。

2. 下载与安装：开发机环境准备

2.1 环境要求与检查

Codex 官方对操作系统有明确支持范围：macOS、Ubuntu 这类主流 Linux 发行版、Windows 桌面版是最近才补上的。不同平台安装方式略有差别，但核心依赖是一样的。

我这次是在 Ubuntu 22.04 上操作的，硬件配置是 i7-12700K + 32GB 内存 + RTX 3060 12GB。如果你的机器配置偏低，后面跑本地模型时建议选小参数模型，或者直接用 API 兼容服务。

环境检查主要看三样：

• 系统版本：lsb_release -a确认系统发行版和版本；
• Node.js：Codex 的 npm 包是官方主推安装方式，需要 Node.js 18 或更高版本，node -v查看；
• 网络连通：确认能访问需要访问的模型服务域和 GitHub（如果要从源码仓库获取东西）。

注意：如果你的机器上 Node 版本太老，建议先用 nvm 装一个新版 Node，不要直接改系统默认 Node，避免影响其他项目。

2.2 三种安装方式

第一种是最常见的 npm 方式：

npm install -g @openai/codex

这个包名是@openai/codex，别漏了 scope。装完会在全局 bin 目录生成codex可执行文件。优点是简单、自动处理依赖，缺点是 Codex 发布新版本时，需要手动执行同样的命令来升级。

第二种是官方原生安装脚本。它的好处是不依赖 Node.js 环境，适合想隔离环境的人。在官方发布页能找到指向对应 tar.gz 包的下载链接，解压后把二进制放进$PATH即可。你可以手动下载适合自己平台的包，然后执行：

tar -xzf codex-x86_64-linux.tar.gz sudo mv codex /usr/local/bin/ codex --version

第三种是从源码编译。如果你要修改或者魔改 Codex 的行为，这种最合适。需要先git clone官方仓库，然后npm install和npm run build，最终产物同样是一个 CLI。对于大多数使用者，第一、二种足够。

Windows 桌面版的话，官方有安装包，下载后一路下一步就行。但要注意：Windows 桌面版本质是图形外壳加 Codex CLI 内核，如果你习惯终端工作流，还是建议用 WSL 2 跑 Linux 版，整体体验更顺。

2.3 验证安装与初始化配置

装完先验证：

codex --version

能输出版本号说明核心可用。但此时你还不能直接开工，因为它没有任何账号或 API 登录信息。官方支持两种登录方式：一种是直接用 ChatGPT 账号做 OAuth 登录，适合有订阅的用户；另一种是配置 OpenAI API Key，适合想按量计费或者走兼容 API 的用户。

执行登录：

codex login

会弹出一个浏览器窗口，完成授权后 CLI 会拿到本地凭据。如果你的环境没有浏览器，也可以用设备码流程，终端会给出一个链接和一个验证码，在另一台设备上访问并输入即可。

如果不想用官方账号，直接在环境变量里配置：

export OPENAI_API_KEY="你的密钥"

这样 Codex 会自动读取该变量。对我来说，直接配了密钥，省去 OAuth 的折腾。需要留意的是，密钥不要写进 shell 历史或者项目配置文件里，最好放在.env或者密钥管理器里。

3. 本地大模型接入：让 Codex 跑在本地模型上

3.1 用 Ollama 部署本地模型

Codex 本身不带模型，它只负责“干活”。要让 Codex 使用本地模型，最省事的方案是 Ollama。Ollama 是一个大模型本地运行框架，支持从拉取模型到启动服务的完整闭环，而且它会暴露一个 OpenAI 兼容接口，端口默认是11434，这就让 Codex 可以像对接标准 API 一样对接本地模型。

安装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh

或者 Windows 直接下载安装包。装完启动服务：

ollama serve

然后拉取模型。以我常用的 qwen2.5-coder 为例：

ollama pull qwen2.5-coder:32b

这一步耗时会比较久，取决于网络和模型大小。32b 模型光参数文件就十几个 G，你机器只有 12GB 显存的话，就跑不动 32B 全精度了。我实际选用的是qwen2.5-coder:14b，量化后大概 9GB 多一点，能塞进显存并且留出上下文空间。

经验之谈：本地部署大模型，不要盲目追求大参数。显存不够导致部分层跑在 CPU 上，推理速度会掉到没法用的程度，而且大模型还容易超出上下文限制直接报错。先在ollama run里单聊几句，确认响应速度和上下文窗口都正常，再约到 Codex 里面。

3.2 在 Codex 配置里接入本地端点

Ollama 就绪后，Codex 并不知道它的存在。Codex 的配置需要改config.toml，这个文件默认在~/.codex/config.toml。如果没有就手动创建。

配置核心思路是新增一个自定义模型提供商，指向http://localhost:11434/v1，并指定一个模型名称：

model = "local/qwen2.5-coder:14b" [model_providers.local] name = "Local Ollama" base_url = "http://localhost:11434/v1" env_key = "LOCAL_API_KEY" wire_api = "chat"

如果你愿意，也可以不自定义 provider，直接把 base_url 指向 Ollama 的/v1路径，再设置model为 Ollama 里的模型名。Codex 兼容 OpenAI 的 chat completions 接口，所以用wire_api = "chat"这一项即可。

env_key表示从环境变量里读取的 API Key 名称。Ollama 默认不校验 Key，但 Codex 依然会尝试读取一个值。你可以在 shell 里随便设置一个：

export LOCAL_API_KEY="ollama"

然后在~/.codex/config.toml里指定模型后，进入 Codex 交互会话，输入!model可以查看当前模型；如果显示的是你配置的本地模型名，说明已经被正确加载。

3.3 本地模型该怎么选

这是很多人最容易踩坑的地方。Codex 这种代理型工具对模型的“指令遵循”“工具调用”能力要求很高，不是所有本地模型都能胜任。太小参数的模型经常会犯两个毛病：

• 看不懂工具调用格式，回复的是纯文本而不是结构化动作；
• 拆解任务时过于简单，几步就走偏。

按我的实测，7B 级别的量化模型在 Codex 里基本不能用，它连“读完文件再修改”这种嵌套指令都容易翻车；14B 级别的中端模型能在简单任务里胜任，例如改一个函数、补一个测试；32B 级别明显更稳，能处理跨文件的改动，但显存要求水涨船高。

这里贴一个我实测过的基础对比表：

如果你既想保住成本又想提升能力，还可以用支持外部 API 的兼容服务，把本地模型换成云上的大模型。YAML 配置里把base_url替成对应服务地址，model换成对应模型名，Codex 照样能用。好处是无需重新安装，坏处是又回到了“依赖网络”的状态。这完全看你自己的选择。

4. 日常实操与核心环节实现：跑通一次真实修复任务

4.1 启动 Codex 和两种交互姿势

一切就绪后，进入一个真实项目目录，直接敲：

codex

进入交互模式。此时它会读取当前目录的上下文。如果你想要更明确的工程上下文，可以先跑：

codex "解释这个项目的架构"

这是单轮模式，跑完自动退出，适合快速问答。而交互模式下，你可以连续发指令，Codex 会一边读文件一边处理，不断跟你确认下一步。

我建议你在已有 git 的项目里测试，因为 Codex 会自动看 diff，你很容易确认它改了哪些文件。如果没有 git，先git init并提交一个初始快照，否则改错了想回滚就很麻烦。

4.2 掌握审批模式和沙箱

Codex 默认不是“直接乱改”模式，它会向你请求确认每一步操作。这个设计很关键，尤其是当它准备执行有副作用的命令时。

启动时可以指定审批级别，常用这几个：

• --full-auto：全自动，不询问，适合完全信任的场景；
• --ask：每次执行工具前询问，适合日常使用；
• --sandbox：启用沙箱隔离，限制它对系统的访问范围。

我在实际操作中喜欢用--ask加--sandbox组合，即便偶尔放空了，也不会因为一次错误的rm -rf把项目搞坏。沙箱不是万能的，Codex 在沙箱里依然能访问项目目录的所有文件，只是对项目之外的文件系统访问更受限。

4.3 演示一次完整修复流程

我手头一个 Python 项目里有个小 bug：一个函数在输入为空列表的时候会抛IndexError。我直接在 Codex 里下指令：

项目里 `parse_config` 在 config 列表为空时会抛 IndexError，帮我修复，并补一个单测。

Codex 的行动路径大概是：

1. 先列出项目目录，定位parse_config所在文件；
2. 读取该函数源码，理解异常触发点；
3. 修改函数，增加空列表保护；
4. 找到测试文件，补一个空列表的用例；
5. 运行 pytest 验证，确认测试通过。

期间它会多次停下来问我是否允许读取某个目录、是否运行 pytest。等它跑完，我git diff查看改动，基本都是预期代码。这就是一个典型的本地模型闭环工作流：理解需求、修改代码、执行验证、汇报结果。

要注意一点：Codex 在本地模型下跑任务，速度感知会跟云端模型不一样。云上模型推理快，交互像聊天；14B 模型跑一步可能要等十几秒，多文件任务可能会有明显等待。这不是故障，是本地推理的正常节奏。建议在指令里把需求写得更明确，减少来回试错的轮次。

5. 常见问题与排查技巧实录

5.1 登录不上、组织设置加载不出来

遇到codex login之后一直转圈、或者提示“无法加载组织设置”，先分两种情况看。一种是网络不通畅，这种情况检查域名可达性即可；另一种是浏览器授权回调端口被占用或防火墙拦截，可以尝试换个网络环境或者干脆用 API Key 方式绕过 OAuth 登录。

我自己的经验是：如果只是要在本地折腾 Codex，API Key 方式远比其他登录方式省心，因为不依赖浏览器授权流程。设置好OPENAI_API_KEY后，Codex 会自动跳过登录步骤。

5.2 配置不生效和奇怪的配置告警

Codex 在启动时如果检测到config.toml里有它不认识的字段，会提示：

codex is ignoring 1 unrecognized configuration setting. Check for typos or deprecated options.

我确实遇到过一次，原因是我把某个 provider 的api_key_env_var写错成了env_var，Codex 不认识这个字段就直接忽略了，结果模型请求一路上没有 key。解决办法是先用codex --version确认版本，再去官方文档对照字段名，尽量不要靠记忆写配置。

另一个隐蔽问题：config.toml里如果同时设置了多个 provider，Codex 默认只认model字段指向的 provider。你在model_providers里写了半天配置，但顶层model没改，那一切都不会生效。改完配置后，进入交互模式执行!model是最快的验证方式。

5.3 模型不支持或报错

当你让 Codex 使用某个模型，但它明确提示该模型不受支持时，通常是模型名不匹配。Codex 有自己的模型白名单，哪怕它是一个本地模型名，你也必须在model_providers里注册，并且顶层model要写成provider名/模型名这种形式。直接填一个裸模型名，它可能拿这个去探测官方端点，当然会失败。

我遇到过类似这样的报错，老版本 Codex 会对某些新模型名直接拒绝，处理办法是先用一个小模型测试你的 provider 配置是否可用，确认连通后再替换模型名，避免模型名错误和配置错误混在一起排障。

5.4 请求超时和响应缓慢

本地模型推理慢是常态，但 Codex 侧有默认超时时间。如果你跑的是 32B 大模型，一个生成请求经常超过几十秒，Codex 就会中断。我的解决方法是：

• 尽量启动前热一次模型，ollama run qwen2.5-coder:14b "你好"，让它把权重加载进显存；
• 如果还是频繁超时，换更小模型或量化版本；
• 在 Ollama 侧调整环境变量，比如增加空闲时保持模型加载的时间。

排查超时问题时，建议开两个终端。一个跑 Codex，另一个随时用nvidia-smi或者ollama ps观察显存和模型状态，这能直观看出到底是模型没加载还是推理卡住了。

5.5 Windows 上的特殊问题

Windows 桌面版最常见的两个问题：一是安装包下完后安装向导卡住，通常是系统缺少 VC++ 运行库；二是桌面版登录完成但无法进入主界面，可能是因为它内置的 Node 服务和系统代理冲突。我的建议是：如果你在 Windows 上工作，优先用 WSL 2 + Linux 版 Codex，很多奇怪问题可以天然绕开。桌面版作为尝鲜可以，但做严肃项目还是 CLI 顺手。

另外，在 Windows 上用 WSL 跑 Ollama 时注意一个坑：WSL 默认只会分配部分内存给 Linux，如果跑模型经常被系统杀进程，去.wslconfig里给memory设一个合适的上限，比如 24GB。别把整个物理内存全给 WSL，Windows 宿主机也需要余量。

6. 一点个人总结和后续扩展思路

折腾完这一整套，我最大的体会是：Codex 的价值不只在“它很聪明”，更多是在“它能自己动手”。而本地部署让这种动手能力有了自主可控的底座。你不用再担心项目代码被第三方拿去训练，也不用掐着手指算 token 成本。代价是你得自己维护模型、调参、处理环境问题，这本质上是在用工程时间换资源和隐私。

如果你打算长期用，我想额外推荐两个扩展方向。一个是把 Codex 和 Dify 这类工作流平台结合，让代理任务可以挂到更大的自动化链条里去；另一个是把代码仓库迁移到 Gitea 这类本地托管服务，配合 Codex 形成内网可用的研发闭环。我自己已经把本地 Git 仓库的古早项目逐渐迁移到 Gitea 上，配合 Codex 用起来非常顺。后续我还会继续尝试给 Codex 配置不同的模型和工具链，有值得分享的再单独写一篇。