企业官网建设流程全解析

Codex 是 OpenAI 推出的命令行 AI 编程 Agent，在终端里启动后，它能读取项目结构、自动生成修改方案、执行命令、修改文件，甚至完成从需求到提交的完整开发任务。这类工具默认绑定 OpenAI 官方模型，对国内开发者来说，账号、网络和费用都有一定门槛。好在 Codex CLI 从设计上保留了模型提供方（model provider）的扩展能力，通过修改配置文件，就能把底层模型替换为 DeepSeek、本地 Ollama 或者第三方中转模型，在普通网络环境下以很低成本获得可用的 Agent 体验。本文会从安装、配置、运行到排错，完整走一遍这个过程。

1. 先理解 Codex CLI 的模型接入机制：为什么能换成 DeepSeek 和 Ollama

1.1 Codex CLI 不是只能调用 OpenAI：model provider 的作用

Codex CLI 的默认配置指向 OpenAI 官方接口，模型也是官方模型。但它的架构不是写死的，而是通过配置文件~/.codex/config.toml来声明模型提供方。每个提供方（provider）包含四个关键信息：名称、请求地址、API Key 的环境变量名、请求协议格式。

model = "gpt-5" model_provider = "openai" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

实际请求时，Codex CLI 会把model_providers里配置的base_url作为接口根地址，把model作为模型名，从env_key指定的环境变量中读取密钥。只要第三方服务提供 OpenAI 兼容接口，就能通过这套机制接入。

wire_api字段决定 Codex CLI 使用哪种请求格式。responses对应 OpenAI 较新的 Responses API，chat对应更普及的 Chat Completions API。DeepSeek、Ollama、绝大多数中转服务目前都兼容 Chat Completions，因此配置时一般写chat。

1.2 云端 API、本地模型和中转模型分别适合什么场景

三种接入方式各有定位，不能简单说谁更好。

1.3 自定义 provider 的字段说明

在 config.toml 中新增 provider 时，需要正确理解以下字段：

注意：配置base_url时，到底带不带/v1，取决于服务商文档。DeepSeek 官方接口是https://api.deepseek.com，它的/v1路径可以兼容；Ollama 的 OpenAI 兼容端点则是http://127.0.0.1:11434/v1。

2. 安装 Codex CLI 桌面端：Node.js、npm 镜像与版本确认

2.1 环境准备

Codex CLI 是 Node.js 命令行工具，先确认本机有 Node.js 和 npm。

node --version npm --version

建议使用 Node.js 18 或更高版本。版本过老时，Codex CLI 安装过程中可能出现语法兼容问题。这里不写死具体版本，以 Codex 仓库和 npm 包的实际要求为准。

安装前重点确认 npm 源。国内默认从 npm 官方源拉包，速度不稳定，建议先切换到国内镜像：

npm config set registry https://registry.npmmirror.com

设置完成后可以验证：

npm config get registry

2.2 安装 Codex CLI

使用全局安装方式：

npm install -g @openai/codex

安装过程中如果长时间卡在下载阶段，优先检查 npm 源是否生效，而不是反复重试。安装完成后，查看命令是否可用：

codex --version

能输出版本号，说明安装成功。此时如果直接运行codex，它会引导登录 OpenAI 账号。这一步可以暂时跳过，因为本文后面的 DeepSeek 和 Ollama 接入方式不依赖 OpenAI 登录。

2.3 首次启动时如何处理登录

Codex CLI 启动时会判断当前模型提供商。如果使用默认 OpenAI provider，则必须先完成 ChatGPT 登录或配置 OpenAI API Key。如果配置文件已经写好了第三方 provider，启动时就不用登录，Codex 会直接从你指定的环境变量中读取密钥。

这是国内开发者能顺利使用 Codex 的关键：不登录 OpenAI，不访问 OpenAI 控制台，只通过配置指定国内可访问的模型服务。

3. 接入 DeepSeek：OpenAI 兼容 API 的最小配置

3.1 准备 DeepSeek API Key

在 DeepSeek 开放平台注册账号，创建 API Key。创建后页面只会完整显示一次，要立即复制保存。DeepSeek API 采用按量计费，新用户通常有一定免费额度，具体以官网说明为准。

API Key 属于敏感凭证，不要写进代码仓库，也不要直接写进 config.toml。推荐先设置为环境变量：

export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx

Windows PowerShell 使用对应语法：

$env:DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxx"

3.2 修改 Codex 配置文件

编辑~/.codex/config.toml，如果目录不存在则先创建。下面是接入 DeepSeek 的完整配置：

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

这里选择deepseek-chat作为默认模型。它对应 DeepSeek-V3 系列，适合日常对话和代码生成。如果需要更强的推理能力，可以改成deepseek-reasoner，但推理模型的响应时间更长，费用也可能更高。

关键点：

• wire_api = "chat"必须写，因为 DeepSeek 的 OpenAI 兼容端点实现的是 Chat Completions 协议。
• base_url的/v1路径不能随便删，Codex 会在后面拼接/chat/completions或/responses。
• 如果希望永久保存 API Key，可以把它放在 config.toml 中通过env_key指定，也可以在 shell 配置文件中写入 export 命令。

3.3 启动 Codex 并验证

启动时指定 provider：

codex --model-provider deepseek

进入交互界面后，输入一个简单任务验证链路：

你：用 Python 写一个函数，读取当前目录下所有 .txt 文件并统计总行数

如果配置正确，Codex 会进入 Agent 流程：先生成实现方案，再调用模型生成代码，必要时直接修改文件或执行命令。只要模型能返回内容且 Codex 能继续追问，就说明 DeepSeek 接入成功。

还可以在交互会话中使用/model命令切换同一 provider 下的其他模型，比如在deepseek-chat和deepseek-reasoner之间切换。

3.4 这一节最常见的坑

4. 接入本地 Ollama：不依赖外部服务的 Agent 体验

4.1 安装 Ollama 并下载模型

Ollama 是本地模型运行工具，安装后可以把 Qwen、Llama、DeepSeek 等开源模型跑在本机。Codex CLI 通过 Ollama 提供的 OpenAI 兼容接口访问本地模型，整个过程不经过外部 API。

Ollama 官方下载速度不稳定时，可以尝试从 GitHub Releases 获取安装包，或者使用其他国内镜像加速方式。模型拉取变慢也常见，通常是因为默认下载源带宽有限。实际工程中建议先确认磁盘空间，再选择合适大小的模型。

安装完成后，启动 Ollama 服务并拉取一个模型：

ollama pull qwen3:8b

拉取结束后查看本机已有模型：

ollama list

输出类似：

NAME ID SIZE MODIFIED qwen3:8b 8d6d2cbb7a3e 5.5 GB About a minute ago

这里输出的模型名，就是 Codex 配置中要填写的model值。

4.2 验证 Ollama 的 OpenAI 兼容接口

Ollama 默认监听127.0.0.1:11434。先用 curl 检查接口是否可用：

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

如果返回包含模型列表的 JSON，说明兼容接口正常。如果请求失败，排查 Ollama 服务是否启动，端口是否被占用。

4.3 配置 Ollama provider

在~/.codex/config.toml增加以下内容：

model = "qwen3:8b" model_provider = "ollama" [model_providers.ollama] name = "Ollama Local" base_url = "http://127.0.0.1:11434/v1" env_key = "OLLAMA_API_KEY" wire_api = "chat"

本地模型不需要真实密钥，但 Codex 会读取env_key指向的环境变量。如果该变量不存在，Codex 可能提示缺少 API Key。解决办法是设置一个非空占位值：

export OLLAMA_API_KEY=ollama

然后启动：

codex --model-provider ollama

4.4 本地模型在 Codex 里的表现与限制

本地模型体验和云端模型有明显区别：

• 响应速度取决于 CPU/GPU，8B 级别模型在纯 CPU 环境中可能比较慢。
• 代码生成能力弱于 DeepSeek 和 GPT 系列，复杂项目理解能力有限。
• 完全离线，不会把代码片段发送到外部服务，适合敏感环境。
• 不需要网络，也不会因为外部接口波动而失败。

学习阶段建议从 4B 或 8B 模型开始，先把链路跑通，再根据本机算力调整模型大小。

4.5 本地接入的常见坑

5. 通过中转模型接入更多模型，并用 CC Switch 管理切换

5.1 中转模型是什么

中转模型通常指第三方模型服务商提供的中转接口。这类服务会把多家模型统一成 OpenAI 兼容格式，用户只需要一个 API Key 和一个 base_url，就能访问多种模型。

中转服务的优势是接入简单，不用分别注册多个平台；劣势是服务稳定性依赖第三方，模型版本、价格和接口策略都可能变化。选择中转服务时，要自行确认服务方是否合规、稳定，避免把重要代码发给不可信的服务。

5.2 手动配置中转 provider

中转服务的具体 base_url、模型名、API Key 都由服务商提供。配置结构是一样的：

model = "gpt-4o-mini" model_provider = "relay" [model_providers.relay] name = "My Relay" base_url = "https://your-relay.example.com/v1" env_key = "RELAY_API_KEY" wire_api = "chat"

wire_api要优先看中转服务商文档。大多数中转实现 Chat Completions，但也有部分宣称支持 Responses 协议。如果请求失败或返回仅支持chat的报错，就改成chat。

5.3 CC Switch 的核心作用

CC Switch 是社区里的 Codex 配置切换工具。它解决的问题是：当你有 DeepSeek、Ollama、多个中转服务时，每次改 config.toml 都很麻烦。CC Switch 可以在界面上维护多套 provider 配置，一键切换当前生效的模型。

这类工具通常会自动写入~/.codex/config.toml，并在切换时重启或触发 Codex 重新读取配置。具体界面和命令以项目 README 为准，本文不展开操作细节，只讲清原理。

5.4 切换 provider 时本地转发失败的处理思路

使用 CC Switch 类工具时，有一个典型报错：切换 provider 后，Codex 请求失败，错误信息提示本地转发服务启动失败，同时指出请求到达的是/responses接口，并带上 provider 名称。

这个场景背后通常有三种原因：

1. CC Switch 的本地转发服务没有正常启动，Codex 请求访问不到本机监听端口。
2. 当前 provider 的模型名不被 Codex 支持，Codex 尝试用默认的 responses 协议请求，服务端不支持。
3. 配置文件被覆盖，base_url 或 env_key 指向了不可用的服务。

排查顺序如下：

• 先看 CC Switch 的本地服务进程是否存在。
• 检查本机端口监听情况，确认转发服务端口是否正常。
• 查看 config.toml 当前 provider 的实际内容，确认 base_url 和模型名没有被工具改错。
• 不启动 CC Switch，直接用命令行指定 provider，绕过工具排查：

codex --model-provider relay

如果绕过 CC Switch 后正常，问题就在工具本身；如果仍然失败，问题在 provider 配置。

6. 常见错误排查链路：从现象定位到根因

6.1 网络连接失败或超时

现象：Codex 启动后卡住，随后提示无法连接。

检查顺序：

1. 确认 base_url 是否可达，用 curl 直接测试接口。
2. 检查系统环境变量中是否有会改变请求路径的配置，比如 HTTP 相关环境变量被设置到某个不可达地址。
3. 确认代码项目目录是否在网络映射盘或特殊权限目录中，Codex 执行命令时可能受目录权限影响。

curl -I https://api.deepseek.com/v1

6.2 模型名不支持：the '...' model is not supported when using codex

现象：启动 Codex 时直接报错，提到某个模型名不支持。例如：

the 'gpt-5.6-sol' model is not supported when using codex with a provider...

这个错误说明 Codex 对模型名做了校验，或者当前 provider 的协议能力与 Codex 期望不匹配。

处理方式：

• 使用该 provider 官方文档明确支持的模型名，不要随意使用奇怪的别名。
• 检查wire_api是否设置正确。中转服务只支持 chat 时，Codex 内部如果走了 responses 流程，就会因为模型能力不匹配报错。
• 升级 Codex 版本，部分模型名校验在旧版本中更严格。

6.3 缺少 API Key

现象：Codex 提示找不到 API Key。

排查：

1. 确认 config.toml 里env_key写的变量名正确。
2. 确认环境变量已经 export，并且新开了终端让变量生效。
3. 本地 Ollama 场景需要设置一个非空占位值，不能留空。

6.4 Ollama 服务正常但 Codex 请求失败

现象：curl 接口正常，Codex 仍然失败。

可能原因：

• Ollama 和 Codex 运行在不同网络命名空间，比如 WSL 访问 Windows 本机端口时，127.0.0.1指向不同。
• 模型没有完全加载，第一次请求需要等待。
• Ollama 版本过老，OpenAI 兼容接口存在兼容性问题。

处理方式：先升级 Ollama 到最新版本，再检查网络地址。WSL 场景需要把 base_url 改成宿主机 IP 或使用host.docker.internal这类特殊地址。

6.5 错误排查速查表

7. 从学习环境到生产环境：配置安全与管理建议

7.1 不要把 config.toml 提交到 Git

.codex目录下的配置文件可能包含敏感信息。即使没有直接写 API Key，env_key字段也会暴露你正在使用的服务商。建议把~/.codex/目录加入 Git 忽略规则，并在团队项目中统一用环境变量注入密钥。

.codex/

7.2 用环境变量分层管理密钥

不同项目可以使用不同的 API Key，实现成本隔离和权限控制。启动 Codex 前先设置当前项目所需变量：

export DEEPSEEK_API_KEY=$(cat ~/.secrets/deepseek.key) codex --model-provider deepseek

这样可以把密钥从配置文件中剥离，降低泄露风险。

7.3 生产环境还要关注日志、权限和成本

学习环境只要跑通即可，生产环境还需要额外考虑：

• 日志：Codex 执行命令时会修改项目文件，生产场景建议在单独分支或容器中运行，避免误改线上代码。
• 权限：不要给 Codex 提供过大的文件系统权限，限定在项目目录内更安全。
• 成本：云端模型按 token 计费，长对话或大仓库扫描会快速消耗额度。建议设置模型用量提醒，并定期清理历史会话。
• 更新：Codex 和 Ollama 迭代较快，每次升级后重新验证一次配置，防止字段变动导致原配置失效。

7.4 可复用的接入检查清单

每次新增模型服务商，按照下面清单确认，可以避免大部分问题：

1. 服务商的 OpenAI 兼容接口地址是什么，是否包含/v1。
2. 服务商支持chat还是responses协议。
3. 官方推荐的模型名是什么，是否带版本后缀。
4. API Key 已经设置为环境变量，且终端已刷新。
5. 在 config.toml 中新增了独立的 provider 段落。
6. 用curl先测通接口，再启动 Codex。
7. 以codex --model-provider <provider>启动验证。
8. 会话中用/model切换模型确认可用。
9. 检查配置文件中没有明文 API Key。
10. 升级 Codex 或模型服务版本后重新跑一次最小验证任务。

这套流程既适用于 DeepSeek，也适用于任何 OpenAI 兼容服务。Codex 的扩展能力决定了接入方式高度统一，真正需要花时间理解的是 base_url、wire_api、模型名和密钥管理这四个部分。把这几块搞清楚之后，无论是接 DeepSeek、本地 Ollama，还是任何中转模型，都只是换一套参数的问题。