企业官网建设流程全解析

把 AI 编程助手 Codex 装在本地、接入自己下载的模型，这个组合我实际用了一个多月，越用越觉得顺手。这篇文章就从零开始，把 Codex 下载安装、本地部署、模型接入的完整过程拆开讲清楚，文里所有步骤我都亲自跑过，也会把踩坑的点单独列出来。适合想通过命令行真正掌握 AI 编程助手、又不愿意把数据和代码全部交给网页版工具的开发者，也适合那些打算把本地大模型和编程场景结合起来折腾的人。

1. Codex 到底是什么？先搞清楚要搭的是什么

1.1 Codex 与普通 AI 编程插件的区别

很多人第一反应是：Codex 不就是像 GitHub Copilot 那样的自动补全插件吗？我一开始也这么想，实际用下来发现完全不是一回事。Codex 更像是一个住在终端里的编程代理，你给它一句自然语言描述，比如“帮我写一个批量重命名图片文件的脚本”，它不只是给你一段代码，而是会在沙箱环境里真的去创建文件、安装依赖、运行命令、看报错、改代码，直到任务完成或者它自己觉得需要找你确认。

这种“代理式”的工作流，和我以前用的补全式插件有本质区别。自动补全解决的是“下一个字符是什么”，Codex 解决的是“接下来这个子任务怎么完成”。它会把一个大需求拆成多个步骤，每一步都尝试在本地执行并验证结果。这种模式最大的价值在于：它知道你写出来的代码能不能跑，而不是只帮你把代码“写完”。

1.2 本地部署的两层含义

说到“本地部署”，很多人会混淆两个完全不同的概念。第一层意思是：Codex 客户端本身跑在本地，命令行工具也好、桌面应用也好，都装在你自己的电脑上。第二层意思是：Codex 背后推理所用的大语言模型也跑在本地，常见方案就是搭配 Ollama 这类工具来跑开源模型。

我这次要讲的“从零搭建”，两层都覆盖。也就是说，你最终得到的效果是：终端里敲codex，就能启动一个 AI 编程助手，而它背后工作的模型，是你自己从模型仓库拉下来、跑在你自己机器上的。这样做的好处很明显，数据不出本机，不依赖外部 API 的额度，也不存在云端把代码拿去训练的问题。坏处也不是没有，本地模型的推理速度、复杂代码理解能力，跟顶级云端模型还是有差距。所以我把官方模型的接入方式也一并写了，方便你两种方案来回切换。

1.3 适合谁、不适合谁

以我这一个多月的使用体验来看，Codex 最适合的是这几类人：日常要写大量脚本的运维和开发、喜欢折腾工具链的技术爱好者、以及有隐私敏感代码需求但不想用网页版 AI 的开发者。不太适合的是：完全没接触过命令行的小白，以及只想要“一句话自动生成整个项目”的偷懒型用户。Codex 能帮你干活，但它不是魔法，它还是需要你理解自己要做什么，只是在“怎么写、怎么改、怎么验证”这些环节上替你省了大量体力劳动。

2. 部署前的环境盘点与方案选型

2.1 硬件配置：只跑 CLI 和同时跑本地模型的差别

先把结论放前面：如果只用 Codex CLI、不跑本地模型，对硬件几乎没有要求。我手上一台 8GB 内存的旧笔记本，跑 Codex CLI 加官方模型，终端操作完全流畅。因为生成代码的推理任务主要在云端完成，本机只是发送请求和展示结果。

但如果要把本地模型也跑起来，配置就要认真考虑了。以我常用的 qwen2.5-coder 7B 模型为例，量化版本占磁盘大概 4.7GB，运行时内存占用在 6GB 到 8GB 之间。想要跑 14B 模型，内存 32GB 起步。至于显卡，有 NVIDIA 显卡且显存在 6GB 以上，推理速度会明显提升；没有显卡，CPU 硬扛 7B 量化模型，生成速度大概是每秒 5 到 10 个 token，简单任务能忍，大段代码会等得比较焦躁。

我的建议是：如果你想长期把 Codex 当主力工具用，内存比显卡更重要。因为很多编码场景是多个会话并行，模型本身占内存，系统也要留余量。我试过在 16GB 内存的机器上同时开 Codex 会话和浏览器，已经能感到明显压力。32GB 内存加一张 8GB 显存的显卡，是比较舒服的分界线。

2.2 必备软件与基础环境

先把软件清单列出来，后面逐个讲怎么装：

这里有个优先级问题。Node.js 必须先装，因为 Codex CLI 最常用、最省事的安装方式就是npm install -g @openai/codex。如果你已经装了 Node.js，先检查一下版本：在终端里执行node --version，至少要在 18 以上，太老的版本会导致 npm 安装时直接报错。Git 在大多数场景下也是必需品，因为codex init会创建和读取项目配置，很多代码操作也天然依赖 Git 工作区。

2.3 CLI 和桌面客户端，到底怎么选

Codex 现在主要有两种形态：命令行工具和桌面客户端。我个人的使用习惯是主力用 CLI，因为它的工作流最透明，运行了什么命令、改了哪些文件、每一步经历了什么，都在终端日志里看得清清楚楚。桌面客户端胜在界面友好、安装门槛低，适合不习惯终端的用户。

需要特别提醒的是：桌面客户端和 CLI 在某些场景下的配置不一定互通。如果你先装了桌面版、登录了账号，再装 CLI，不要默认 CLI 就自动继承登录状态。实际情况是，两个工具各自独立维护配置，需要分别在各自界面里完成登录。所以我的建议是：先想清楚你的主要使用场景，再决定装哪一种，不要两种都装然后配置得云里雾里。如果拿不准，先装 CLI，它覆盖的场景更全面，也更容易排查问题。

3. Codex 下载安装与账号认证（新手照做版）

3.1 用 npm 安装 Codex CLI 的完整过程

安装过程其实只有四条命令，但每一步都可能出幺蛾子，我按顺序拆开讲。

第一步，确认 Node.js 环境：

node --version npm --version

如果系统提示“command not found”，就去 Node.js 官网下载 LTS 版本，一路下一步安装就好。装完再开一个新的终端窗口，否则 PATH 不会刷新。

第二步，全局安装 Codex CLI：

npm install -g @openai/codex

这一步如果网速慢，npm 会卡很久。建议先配置国内 npm 镜像源，或者耐心等它跑完。安装成功后会有类似“added X packages”的输出。如果出现权限报错，通常是因为全局目录没有写权限，不要在命令前盲目加sudo，更好的做法是检查 npm 的全局目录配置。

第三步，验证安装结果：

codex --version

能输出版本号，说明安装成功了。如果提示“codex: command not found”，大概率是 npm 的全局 bin 目录没有加入系统 PATH。用npm config get prefix查看全局目录，把它加到你的 shell 配置文件的 PATH 里。这个问题在 Windows 上尤其常见。

3.2 登录认证：三种方式选一种

Codex CLI 首次运行codex命令时，会引导你完成登录。我实际试过三种认证方式，各自的特点整理如下：

手动触发登录的方式也很简单：

codex login github

执行后终端会输出一个授权链接，复制到浏览器打开、确认授权，再回到终端看，登录就完成了。这里有个很容易踩的坑：如果在浏览器里授权之后终端一直没有反应，不要反复执行codex login，先等十几秒，授权回调可能需要一点时间；还是不行的话，检查一下系统默认浏览器是不是被某些策略拦截了弹窗。

API Key 方式相对简单粗暴。在环境变量里设置OPENAI_API_KEY，然后直接运行codex，它检测到有效 key 就会跳过交互式登录。这种方式我建议只在自动化脚本里用，本地日常开发还是用 GitHub 登录更省心。

3.3 登录状态与配置文件的生成

登录完成后，Codex 会在你的用户目录下生成配置文件目录。Linux 和 macOS 的路径是~/.codex/，Windows 是%USERPROFILE%\.codex\。在这个目录里，最核心的文件是config.toml，后面接本地模型、切换模型提供方都要改这个文件。首次运行后如果没找到这个文件，可以手动创建一个，不影响使用。

我想强调的是：这个配置文件是 Codex 本地部署真正的“总开关”。很多人登录都成功了，但接本地模型怎么也接不上，问题几乎都出在 config.toml 的字段写错了。下一章我把完整的配置模板给出来。

4. 把 Codex 接到本地模型：Ollama 实战

4.1 为什么要费劲接本地模型

有人可能会问：已经能正常用官方模型了，为什么还非要接本地模型？我的理由有三个。第一，隐私和合规。有些项目代码是客户资产，甚至签过保密协议，我不能把这些代码通过聊天工具发到外部服务去。接本地模型之后，整个 Codex 流程从头到尾都在本机完成，代码不出网。第二，成本可控。云端 API 是按 token 计费的，长时间开着会话、反复让 AI 改代码，token 消耗很快。本地模型是固定成本，电费加硬件折旧，怎么算都比 API 便宜。第三，断网可用的安全感。

当然，本地模型也有明显短板。最直观的差距是逻辑复杂的长链条任务，比如“重构这个模块并补充所有边界情况的单元测试”，本地 7B 模型生成的代码质量明显不如官方大模型，容易出现逻辑偏差。所以我的策略是：日常简单脚本、批量修改、代码解释这类任务用本地模型，复杂架构设计再切回云端模型。两者并不冲突。

4.2 安装 Ollama 并拉取代码模型

Ollama 是目前最简单好用的本地大模型运行工具，iOS 风格？不重要，关键是它把“下载模型、启动服务、提供接口”这三件事封装得非常干净。

安装方式很简单：去官网下载对应系统的安装包，或者用官方脚本安装。装完在终端里验证：

ollama --version

然后拉取一个适合编程的模型。我常用的是qwen2.5-coder，它在代码补全、代码解释、脚本生成方面表现均衡，而且有不同尺寸版本：

ollama pull qwen2.5-coder:7b

拉取模型的时候不用担心它会立刻占用大量内存，Ollama 是按需加载的。拉完之后可以确认一下：

ollama list

如果列表里能看到你拉取的模型，就说明模型就绪了。Ollama 启动服务一般不用手动管，安装后它通常已经在后台运行，默认监听 11434 端口。验证服务是否正常，直接请求它的 OpenAI 兼容接口：

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

能返回模型列表 JSON，就说明服务完全可用。

4.3 修改 config.toml，把 Codex 指向本地模型

这一步是本篇文章的核心。先找到用户的配置文件，Linux/macOS 在~/.codex/config.toml，Windows 在%USERPROFILE%\.codex\config.toml。我当前使用的配置模板如下：

# ~/.codex/config.toml model = "qwen2.5-coder:7b" model_provider = "ollama" [model_providers.ollama] name = "Ollama" base_url = "http://127.0.0.1:11434/v1" wire_api = "chat" env_key = "OLLAMA_API_KEY"

然后设置一个环境变量，随便填一个值即可，因为本地服务不做真实鉴权：

export OLLAMA_API_KEY="ollama"

完成之后，重新启动 Codex：

codex

如果能正常进入对话界面，说明本地模型已经接通。怎么确认当前生效的是本地模型而不是云端模型？两个方法：一是看对话的响应速度，本地模型生成代码时会有持续输出的感觉，而不是云端那种“等一会突然整段出现”；二是看 Ollama 的后台日志，当请求过来时，会有模型推理记录。

这里必须提醒几个常见坑。第一个坑：wire_api = "chat"是最重要的字段。Codex 原本用的是 responses 协议，但 Ollama 兼容的是 chat 协议，这个字段写错，请求会一直卡住或者报格式错误。第二个坑：base_url一定要写完整路径，有些教程写http://localhost:11434不带/v1，必挂。第三个坑：env_key对应的环境变量必须设置，虽然本地服务不校验 key，但 Codex 客户端会因为你没设置而直接拒绝启动请求。

4.4 补充方案：接入 OpenAI 兼容 API（以 DeepSeek 为例）

如果你的机器跑不动本地模型，或者想要比本地开源模型更强的推理能力，还有一条折中路线：把 Codex 接到其他兼容 OpenAI 接口的大模型服务上，DeepSeek 是目前很流行的选择。

在 config.toml 里增加一个模型提供方：

[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" wire_api = "chat" env_key = "DEEPSEEK_API_KEY"

然后设置环境变量：

export DEEPSEEK_API_KEY="sk-你的key"

启动时指定提供方：

codex --model-provider deepseek

这样做的本质，是利用 Codex 对 OpenAI 兼容接口的适配能力，让你在不用换工具的前提下，自由切换不同的模型后端。我把它放在“本地部署”的主题里说，是因为这套配置思路和本地模型完全一致，区别只是 base_url 指向的是外部 API 还是本地端口。理解了这个本质，以后无论出现什么新模型，你都可以用同样的方式接进来。

5. 实际项目里的用法：会话、审批与代码执行

5.1 用 codex init 初始化一个项目

Codex 不是那种让你在空目录里瞎问的聊天工具，更好的用法是先让它在项目里建立上下文。进入你的项目目录，执行：

cd my-project codex init

这个命令会在项目根目录生成配置文件，包括AGENTS.md之类用于告诉 AI 项目背景和约定的文件。初始化之后，Codex 会按照这个文件里的说明来理解项目结构、编码规范、构建方式。这一步很多人会跳过，但实际体验差别非常大。做过初始化的项目，Codex 生成的代码明显更贴近项目的既有框架和风格；没做的，它经常给出与项目结构格格不入的解决方案。

5.2 三种运行模式：全自动、逐条确认、只读

Codex 执行任务时有不同的权限模式，我用表格说明：

我强烈建议新手一开始不要用--full-auto，至少等到你把一个项目完整跑通过、知道它会在什么情况下执行什么命令再用全自动。我吃过一次亏：让它重构一个函数的调用方式，它为了验证结果，直接执行了测试脚本，结果测试脚本本身有副作用，把本地临时数据给清了。从那以后，我对全自动模式保持高度警惕。默认模式虽然每步都要确认，但那种“看它一步步干活”的掌控感，才是把 Codex 当伙伴而不是当工具的正确姿势。

5.3 多会话管理与日常使用细节

Codex 支持多个会话并行。这个功能非常实用，我通常一个项目开一个会话，互不干扰。常用命令：

codex "修复 README 里的所有死链" codex resume # 恢复最近一次会话 codex resume 2 # 恢复指定编号的会话

还有一个容易被忽略的细节：Codex 执行代码是在本地沙箱环境里进行的。默认情况下，它会限制对文件系统的写操作范围和命令执行权限。如果你确实需要它安装依赖、修改全局配置文件，可以通过--sandbox danger-full-access放开限制，但代价是它会完全以你的权限去执行命令。这个开关我建议只在临时需要时使用，用完就关。

6. 高频问题排查与避坑经验

6.1 问题速查表

这一节我把实际遇到过的、以及社区里高频出现的问题集中列出来。这些坑都是真金白银换来的经验。

关于最后一条“中文回复”，我多解释一句。Codex 的界面元素本身没有独立的中英文语言开关，但你可以通过两种方式让它用中文：一是在对话里直接说“之后请始终用中文回复”，这只会影响当前会话；二是把这一条写进项目指导文件里，这样每次新会话它都会读到中文要求。我见过有人在配置层面折腾语言开关，最后发现还是指导文件里写一句最靠谱。

6.2 几个值得长期记住的实操习惯

第一，全局模型配置尽量保持“默认官方模型为主，本地模型按项目切换”的方案。你可以在项目自己的配置文件里单独指定 model_provider，这样进不同项目自动用不同模型。第二，运行 Codex 前先看一遍它即将执行的命令列表，特别是删除和覆盖类操作，不要闭眼按回车。第三，本地模型拉取到新版本后，记得重启 Codex 会话，否则它可能还拿着旧模型的缓存上下文在跑。

最后分享一个我自己的使用心得。这套 Codex 加本地模型方案跑通之后，真正的收益不在于“免费”或者“不用上云”，而在于我开始重新审视 AI 编程助手到底应该怎么融入我的工作流。以前用网页版工具，我只敢把零碎的、不敏感的问题丢给它；现在本地部署之后，我敢把整个模块的雏形交给它写，因为我知道代码文件不会离开这台机器。这种心理上的安全感，带来的效率提升远比模型本身的能力差距重要。如果你也在纠结要不要折腾本地部署，我的建议很直接：先拿一台 16GB 内存以上的普通电脑，按这篇文章的步骤跑通一遍，你会很快判断出这套方案适不适合自己。