企业官网建设流程全解析

最近 GitHub 上热度最高的 AI 编程项目之一，就是 OpenAI 开源的 Codex CLI。简单说，它是一个跑在终端里的 AI 编程助手：能读你项目里的代码，按你的要求改文件、生成新功能、执行命令，甚至帮你跑测试。我最初是抱着尝鲜的心态下载的，结果用顺手之后，本地那台 Windows 电脑几乎被我当成了私人 AI 编程工位——把 Ollama 里的 DeepSeek 和 Qwen2.5-Coder 接进 Codex，彻底走上了“所有代码都在本地跑”的路子。这篇文章就是我的完整实战记录，从下载安装开始，到配置文件逐项解析、接入本地大模型、跑通第一个真实任务，再到各种报错的排查过程，通通写清楚。适合刚听说 Codex 的新手，也适合那些想把本地大模型真正用起来、不想再依赖网页聊天窗口的开发者。

1. Codex 到底是个什么东西，值得专门写一篇

1.1 一个住在终端里的 AI 结对程序员

很多朋友一听到“AI 编程助手”，第一反应是 GitHub Copilot 那种 IDE 插件：你在编辑器里敲代码，它帮你补全、生成函数、解释报错。Codex 不太一样，它更像一个住在终端里的结对程序员，你不光可以和它对话，它还能实际操作你的电脑。启动之后，它会扫描当前目录的文件结构，理解你手头这个项目的代码是怎么组织的，然后你要做的就是描述需求。比如“帮我把这个 Python 脚本改成异步版本”“给这段 TypeScript 加上单元测试”“查一下为什么 CI 构建老是失败”，它会自己翻代码、写补丁、执行命令、跑验证，然后把结果贴给你看。

在技术圈里，这种能调用工具、能执行动作的 AI 被称为 Agent，也就是“智能体”。Codex CLI 正是 OpenAI 把自家 Agent 能力开源落到终端里的产物。它在设计上非常克制，没有做一个花哨的 GUI，界面上就是一个命令行交互窗口，但恰恰是这种克制让它很适合真正干活的场景：它就在你的代码旁边工作，跟你的开发环境无缝衔接，而不是另开一个网页让你手动复制粘贴。

1.2 为什么本地部署这个思路突然火了

Codex 官方默认情况下是连接 OpenAI 的云端模型使用的，需要有 OpenAI 账号和对应的订阅额度。问题在于，很多人要么没有订阅，要么希望代码完全不离开自己的电脑，要么想用咱们自己在本地部署的大语言模型来驱动它。于是“本地部署 Codex”这个组合拳就开始流行了。

本地部署这个词听起来有点劝退，其实门槛没有想象中那么高。核心思路就一句话：Codex 自己不包含模型，它只是个壳，真正干活的是背后的 LLM。只要让这个壳“说”你本地模型的接口语言，它就能用本地模型干活。本地部署的好处非常明显：

• 隐私性拉满。代码文件、项目内容不会上传到任何云端，全在你的机器里。
• 没有按用量计费的焦虑。本地模型只要部署好，怎么调用都不心疼。
• 终端响应更可控。你可以完全掌控模型版本、参数，甚至定制 prompt 模板。
• 顺带把本地大模型的用途盘活了。很多人部署了 Ollama 之后发现除了聊天没有其他用武之地，接上 Codex 就等于给本地模型找了个正经工作。

说白了，Codex 本地部署不是让你搞一套多么复杂的工程，而是给“本地大模型到底能拿来干嘛”这个老问题提供了一个非常优质的答案：拿去写代码。

2. 动手之前：环境准备与三分钟安装

2.1 先看看你的电脑够不够格

Codex 本身非常轻量，它对电脑硬件的需求低到离谱，因为它只是一个 Node.js 写的命令行工具，不负责跑模型。真正的硬件要求来自模型那边，这部分我放到第四节细说。先说 Codex 本体需要的运行环境：

• Node.js 18 以上版本。官方建议用最新的 LTS，实测 20 和 22 都很稳。
• Git。它不是必选项，但 Codex 在操作 git 仓库时会调用系统 git，建议提前装好。
• macOS、Linux、Windows 都支持。Windows 上需要注意一点：虽然原生支持，但如果你要在终端里跑 bash 命令，建议装个 Git Bash，或者直接用 WSL，否则部分命令执行功能会受限。

我自己是在 Windows 11 上操作的，用的终端是 Windows Terminal 加 Git Bash，全程没有遇到什么环境上的大坑。如果你手头没有 Node.js，别用太旧的版本，去 nodejs.org 下一个 LTS 安装包，一路下一步装完就行。

2.2 三分钟安装，命令行搞定

安装方式很简单，npm 全局安装即可：

npm install -g @openai/codex

装完之后验证一下：

codex --version

如果能看到类似codex/0.2.2这样的输出，说明装好了。注意包名前面有@openai/这个命名空间，别敲成codex或者openai-codex。npm 上也有一个叫codex的老包，那是另一个项目的遗留名字，装错的话后面会非常混乱。

有一个比较实用的经验：如果 npm 下载速度很慢或者超时，可以把 npm 源切到国内镜像，比如npm config set registry https://registry.npmmirror.com，之后再执行安装命令就快多了。这一步纯属加速下载，不影响任何后续配置。

3. 配置文件是灵魂：手把手拆解 config.toml

3.1 配置文件到底放在哪里

Codex 的所有行为都由一个 TOML 格式的配置文件控制。这个文件路径很好记：

• macOS / Linux：~/.codex/config.toml
• Windows：%USERPROFILE%\.codex\config.toml
• 也就是用户主目录下的.codex文件夹里的config.toml。

第一次运行codex时，工具会自动创建这个目录。如果你找不到.codex文件夹，可以手动建一个，再新建一个config.toml文件，没问题的。这个文件的优先级非常高，启动时它会先读取这里的内容，再结合命令行参数决定最终行为。很多朋友说“Codex 登录不上”“Codex 打不开”，十有八九就是配置文件里某个字段写错了，不是软件坏了。

3.2 关键配置项逐个拆解

我把一个完整的、可以直接抄走的本地部署配置放在下面，然后逐个字段解释：

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

先看model字段。这个字段指定 Codex 默认使用的大模型名称。连接云端模型时，它的值是类似gpt-5-codex这种官方模型名；连接本地模型时，填你本地服务里的模型名，大小写要和模型服务返回的一致，否则会报“model not found”。

再看model_provider。这是最核心的配置，它决定了 Codex 把请求发到哪个“供应商”。Codex 支持一个[model_providers.xxx]的配置段，里面的xxx是你给供应商起的别名，然后在顶层model_provider = "xxx"引用这个别名。这种设计非常好理解：你可以在同一个配置文件里定义多个供应商，比如官方 OpenAI、DeepSeek API、本地 Ollama，然后随时切换默认值，不需要改来改去。

base_url就是供应商接口的地址。官方 OpenAI 的地址是https://api.openai.com/v1，本地 Ollama 就是http://127.0.0.1:11434/v1。注意 Ollama 的版本需要比较新，否则不提供/v1这个 OpenAI 兼容路径。env_key指定从哪个环境变量读取 API Key。本地模型通常不需要鉴权，但这个字段不写的话，有些版本会直接报“missing API key”，所以最好还是设置一个环境变量占位，比如LOCAL_API_KEY，随便给个值，或者干脆不填，取决于你的 Codex 版本。我在 0.2.x 版本上实测，不设置env_key也能正常跑本地模型，但设置一个也完全无害。

wire_api是一个非常容易被忽视的坑。OpenAI 的官方接口有/responses和/chat/completions两套协议，CODE CLI 不同版本对它们的支持不一样。本地模型服务，尤其是 Ollama，通常只实现了/chat/completions（也就是 chat 协议），所以这里要显式写wire_api = "chat"。如果你发现 Codex 连上了本地模型但每次请求都报“404 Not Found”或者“endpoint not found”，先来看这个字段，大概率它被默认设成了responses。

还有一个常用配置项：

auto_execute = false

这个控制 Codex 是否可以自动执行你同意过的命令。建议新手先保持false，每条命令执行前它都会问你一遍，等你熟悉它的行为习惯了，再改成true也不迟。后面我会专门讲这个的坑。

4. 接本地大模型：Ollama + DeepSeek/Qwen 实战

4.1 为什么我推荐 Ollama

让 Codex 用上本地模型，核心是给它接一个兼容 OpenAI 接口的本地推理服务。目前市面上可选的方案有 Ollama、LM Studio、vLLM、llama.cpp 等。我推荐 Ollama，原因有三个：

第一，安装极其简单。官网下一个安装包，双击装完，命令行直接能用，不用折腾 Python 虚拟环境、CUDA 依赖这些乱七八糟的东西。第二，它对显卡不挑剔。NVIDIA 显卡、AMD 显卡、核显、甚至纯 CPU 都能跑，只是速度问题，不像 vLLM 那样基本强制要求 NVIDIA GPU 且显存充足。第三，模型管理方便，ollama pull就能拉模型，类似 Docker 的使用体验，生态里的模型命名和版本管理都很清晰。

当然，LM Studio 也是个好选择，它的图形界面更友好，适合不想敲命令的朋友。但考虑到写代码的场景通常需要频繁调整参数、查看日志，我感觉还是 Ollama 更顺手。

4.2 拉模型、起服务、验证连通性

安装好 Ollama 之后，第一步先拉一个适合写代码的大模型。我的选择是qwen2.5-coder:14b，这个模型在代码生成、代码理解、代码补全方面的表现非常出色，是目前开源模型里最能打的代码模型之一。显存够大可以上 32b，显存只有 8G 就用 7b。拉取命令：

ollama pull qwen2.5-coder:14b

如果你想试试 DeepSeek 系列，可以拉deepseek-r1:14b或者deepseek-coder。DeepSeek 在数学和逻辑推理上很强，生成代码时也更注重解题思路，但响应速度比 Qwen 慢一些，实测在 Codex 场景下返回 token 数多，会显得“话痨”。我个人做常规开发任务更偏好 Qwen2.5-Coder。

模型拉好之后，确保 Ollama 服务在运行。命令行执行：

ollama serve

如果之前已经作为后台服务安装，这一步可以省略。然后另开一个终端，测试一下模型服务是否正常响应：

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

能返回一个 JSON 数组，说明服务起来了。再进一步，直接发起一次对话请求：

curl http://127.0.0.1:11434/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model":"qwen2.5-coder:14b","messages":[{"role":"user","content":"say hi"}]}'

如果返回了choices字段，说明兼容接口完全正常。这一步非常关键，它提前把网络层和服务层的问题隔离了，如果 curl 都拿不到正常响应，那问题一定出在 Ollama 这边，而不是 Codex 配置。

4.3 model_provider 配置与模型选型细节

在确保 Ollama 服务正常之后，把配置写成这样：

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

保存之后，进入一个测试目录，执行：

codex

进入交互界面后，随便问一句“用一个 Python 脚本计算斐波那契数列”。如果 Codex 返回了代码，那恭喜，整套本地部署链路已经跑通了。从下载安装到这一步，全程也就十几分钟。

关于模型选型，我给一个直观的参考表，是我在 16G 显存和 32G 内存的机器上实测的体感：

如果你的机器显存不足，又想体验本地部署，建议用 7b 模型，量化版本可以进一步降低显存占用。Codex 本身对模型大小并不敏感，它只会按配置发请求，模型小一点、响应慢一点，但不影响整套流程跑通。

5. 完整实操：让它帮你写个脚本

5.1 启动与第一次对话

环境都备齐之后，进入实战。我建议第一次不要直接在项目的根目录启动 Codex，因为如果代码量很大，它首次加载上下文会有点慢。先建一个空白目录，比如test-codex，在里面放一个简单的 Python 文件，随便写点啥，然后打开终端进入这个目录，执行：

codex

看到命令提示符就表示它已经就绪。注意它默认会先显示当前目录里的文件结构，这就是 Codex 的目录感知能力：它知道你在哪个项目里，能看到哪些文件。接下来的对话方式跟 ChatGPT 很像，但因为你是在终端里，建议你用更工程化的语言描述需求。

我测试时会让它做这么一件事：我写了一个 Python 脚本，功能是把一堆 CSV 文件合并成一个 Excel 文件，但并发一多就会内存溢出。我向 Codex 提出需求：“帮我重写这个脚本，用 pandas 的分块读取方式处理，避免一次把所有数据都加载到内存里。”

Codex 的回复通常分几步：先简要说明它的方案，然后直接给出修改后的代码块，再说明改动了哪些地方。如果你认可，它会问你“是否要写入文件”，选择确认后，它直接把代码写进你的文件，完全省去复制粘贴的环节。这个体验说实话，第一次用的人会很惊艳：它不只是“建议”，而是直接动手改。

5.2 让 Codex 真正理解项目上下文

很多人用 Codex 觉得效果一般，可能是因为只把它当聊天窗口用，没有充分利用它的目录感知能力。Codex 会看到当前目录的文件列表，但不会自动把每个文件的完整内容都硬塞进上下文。文件太多、太大时，它只会读取部分关键文件，或者等你在对话里提到某个文件时才去读。

所以最实用的技巧是：在提问时直接指明文件路径。比如“看下src/utils.py里的parse_date函数，为什么它处理 2024-02-30 这种日期会出错”。这样 Codex 会主动去读那个文件的对应部分，回答更精准。还有一个命令要记住：在 REPL 里输入!或/可以执行一些特殊指令。不同版本指令略有差异，但/help基本通用，可以随时查看当前版本支持哪些快捷操作。

实际用下来，我还有一个重要心得：把需求说得越接近“你在给同事派活”越好。比如，不要只说“优化一下这段代码”，而是说“这个函数在数据量超过 10 万行时会超时，帮我改成流式处理，并补一个简单的基准测试”。Codex 在这种具体任务上的完成度，比那种模棱两可的“帮我改改”要高好几个档次。

5.3 自动执行命令：好用但危险

Codex 最让我惊讶的功能是它能执行终端命令。比如它写了一个测试脚本，然后直接运行测试，把测试结果拿回来判断自己写的代码对不对。这个功能在auto_execute = true时非常丝滑，但风险也不小。

有一次它为了确认目录结构，打算执行rm -rf删除一个临时目录，虽然目标目录是我创建的，但它弹出确认框的时候我还是心头一紧。我的建议是：新手阶段保持auto_execute = false，让它每次执行命令前都征求你的同意，当你熟悉了它的行为模式，再逐步放开。尤其是在有 git 仓库的目录里，放开之前一定要确认git status是干净的，否则一旦它乱改文件，你回滚都麻烦。

6. 问题排查与避坑实录

6.1 安装与启动阶段的常见报错

先整理一份我遇到过的安装、启动阶段问题速查表：

登录问题是很多人卡住的第一道坎。Codex 默认逻辑是先走 OpenAI 账号 OAuth 登录，但如果你根本不想用云端账号，直接配置一个本地或第三方 provider，就不会触发登录流程。我自己在 Windows 上遇到过 OAuth 页面打不开、回调链接无法处理的情况，最后就是用本地 provider 绕开的，干净利落。

6.2 接口对接阶段的常见报错

接入本地模型时的报错，绝大多数都指向同一个根源：base_url 或 wire_api 配置不正确。这里列三个最典型的：

第一个，请求 404。如果你在日志里看到类似 “failed while handling codex endpoint /responses” 的报错，多半是 Codex 把请求发到了/responses端点，而你的本地服务只支持/chat/completions。解决办法就是在 provider 配置里显式加wire_api = "chat"。这个坑非常隐蔽，因为 base_url 看起来完全正常，很多教程也不会特意提。

第二个，401 / 403 鉴权失败。本地 Ollama 默认不鉴权，如果你在 base_url 后面多写了一些路径，或者 Ollama 开启了 token 校验，就会出现这种情况。先确认 curl 直连是通的，再排查配置。

第三个，模型返回空内容。常见原因是模型上下文窗口太小，Codex 一次性塞给模型太多内容，模型直接吐空。这时候要么换一个上下文窗口更大的模型，要么在项目目录里减少无关文件，降低上下文压力。

6.3 本地模型效果与性能优化建议

最后说说效果。必须承认，本地模型写代码的能力和 OpenAI 官方模型有差距，特别是在复杂架构设计、跨文件重构这种需要很强“全局观”的任务上，本地模型会显得保守，生成的代码偶尔有啰嗦和重复。但在日常任务上，比如写单元测试、写 SQL、做数据清洗、修 bug、解释代码，Qwen2.5-Coder 系列的完成度已经非常高。我的经验是：把任务拆细，一次只让 Codex 做一件事，本地模型的效果会明显提升。

性能方面也有一些优化空间。Ollama 默认会占用一部分内存做 KV cache，如果你的模型运行不稳定，可以调整 Ollama 的环境变量控制并发和缓存占用。CPU 推理的朋友建议选量化模型，比如qwen2.5-coder:7b-q4_K_M，速度会快很多。另外，Codex 的交互默认是流式输出的，如果你觉得终端滚动太快，可以在配置里调整输出方式，但这只是观感问题，不影响最终结果。

最后分享一个我个人用得最舒服的小技巧：把 Codex 的配置文件里同时保留官方云端 provider 和本地 provider，日常用本地模型省钱省心，偶尔碰到特别棘手的难题，临时切回云端模型救场。两个 provider 在同一个 config.toml 里互不干扰，切换只需要改一行model_provider。这个思路可能是 Codex 本地部署最大价值所在——你既拥有了完全本地、隐私可控的开发助手，又没有放弃随时调用更强模型的能力。整个体验下来，我觉得 Codex 加上本地大模型这套组合，已经是当前开源工具链里最接近“私人编程搭子”的方案了，非常值得你花一个下午把它跑通。