很长时间里终端里的 AI 编程工具要么绑定 ChatGPT 账号要么只能调用 OpenAI 官方模型接口。Codex CLI 的出现改变了这种局面它既可以使用 ChatGPT 账号登录也可以通过config.toml配置自定义模型服务商。对国内开发者来说更有吸引力的用法是把 DeepSeek、通义千问、Kimi、智谱 GLM 等国产大模型的 OpenAI 兼容接口配置到 Codex 中这样不需要 ChatGPT Plus 订阅也不需要为网络连接操心。这篇文章面向刚接触 Codex 的开发者目标是让你完成三件事第一安装并正确配置 Codex CLI第二把国产大模型的兼容接口接入 Codex第三理解并编写 Codex skill让模型按固定流程完成重复性任务。文章最后还会整理常见报错的排查路径包括cc switch local proxy failed、config.toml无法加载、model not supported这类高频问题。1. 先弄清楚 Codex、Skill 和国产大模型之间的关系1.1 Codex 是什么从模型名到终端编程代理Codex 最早是 OpenAI 推出的代码模型名专门用于理解代码并生成代码。后来这个名字被沿用到终端 AI 编程代理产品上也就是 Codex CLI。通俗地讲Codex CLI 是一个跑在终端里的 AI 开发者。它不是简单聊天窗口而是可以读取当前项目里的文件。根据自然语言指令修改代码。执行 shell 命令比如运行测试、安装依赖。生成补丁让你在应用前审查改动。结合 Git 工作流辅助提交代码。Codex CLI 本身负责调度和工具调用真正回答问题、写代码的是背后的模型。这意味着 Codex 可以搭配不同模型使用只要模型服务商提供兼容接口。这里有一个容易混淆的点Codex CLI 不是某个固定大模型的别名。你可以在config.toml里指定model字段让 Codex 使用deepseek-chat、qwen-plus、glm-4-plus等模型。Codex 变成了一个壳模型服务可以来自任何兼容服务商。1.2 Skill 机制解决什么问题Skill 是 Codex 里用来固化工作流的能力。通俗理解是给 AI 准备了几份“操作手册”。假设团队经常要做 SQL 审查。每次都在对话里重新描述审查规则很费劲而且容易漏掉细节。Skill 可以把审查步骤写成固定文件模型遇到 SQL 审查任务时按文件里的流程执行。这样输出更稳定规则也能随文件一起维护和评审。从技术角度看Skill 通常是一个包含 Markdown 指令的文件文件里会描述这个 skill 的触发场景。执行任务时应该遵循的步骤。输出结果时应该包含哪些信息。Skill 和普通 prompt 的区别在于复用性。普通 prompt 只存在于某一次对话里而 Skill 可以长期存放在项目或用户目录中团队共享版本管理随时修改。1.3 为什么可以把国产大模型接入 Codex核心原因是越来越多的国产模型服务商提供了 OpenAI 兼容接口。OpenAI 兼容接口的意思是HTTP 路径、请求 JSON 结构、响应格式大致和 OpenAI 官方 API 保持一致。Codex 通过base_url访问模型服务所以只要把base_url指向对应服务商就能把模型服务切换过去。Codex 在config.toml中提供了model_providers配置段用于定义自定义模型服务商。这里有几个关键字段name服务商名称只用于显示。base_urlOpenAI 兼容接口地址。env_key从哪个环境变量读取 API Key。wire_api接口协议类型常用chat或responses。需要注意OpenAI 原生 Codex 可能会使用/v1/responses接口而很多第三方模型服务商只实现了/v1/chat/completions。因此接国产大模型时wire_api通常要设置为chat。如果设置错误请求会返回 404 或model not found。在认证方面Codex 支持 ChatGPT 账号登录也支持 API Key 方式。使用国产模型服务商时推荐走 API Key 方式。你只需要在环境变量里配置服务商提供的密钥不需要 ChatGPT 订阅也不需要使用任何额外的网络转发组件。2. 安装 Codex CLI 并完成基础配置2.1 环境准备先检查 Node.js、npm 和 GitCodex CLI 基于 Node.js 开发安装前先确认本机环境。打开终端执行node -v npm -v git --version建议 Node.js 使用 18 以上的 LTS 版本。如果还没有安装 Node.js推荐用 nvm 管理版本避免 npm 全局目录权限问题。在 Linux 环境中安装 nvm 的基本方式是curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后执行nvm install 20 nvm use 20Windows 用户可以使用 Windows Terminal 配合 nvm-windows 或官方安装包。安装完成后确认node -v能正常输出版本号。注意安装 Codex 之前不要急着配置模型。先确保 Node.js 和 npm 可用否则后续不管怎么改config.toml都会卡在第一步。2.2 安装 Codex CLI使用 npm 全局安装npm install -g openai/codex安装完成后检查版本codex --version如果 npm 官方源下载速度不理想可以临时切换镜像源npm config set registry https://registry.npmmirror.com安装完成后改回来或者保持镜像源都可以取决于你的项目环境。镜像源只影响 npm 包下载不影响 Codex 的模型接口配置。升级 Codex 时使用相同命令npm install -g openai/codexlatestCodex 更新频率较快生产环境中建议固定版本号避免升级后配置语法变化导致异常。2.3 认证方式选择ChatGPT 账号还是 API KeyCodex 有两种常见使用路径第一种是 ChatGPT 账号登录。在终端执行codex login登录后 Codex 会使用 ChatGPT 账号的会话能力。这种方式适合已经订阅 ChatGPT 的用户但模型选择受账号等级限制。热搜里出现的the gpt-5.6-sol model is not supported when using codex with a chatgpt acc正是这种认证方式下指定了账号不支持模型时的报错。第二种是 API Key 方式。这种情况下不需要codex login直接通过配置指定模型服务商和密钥。更推荐第二种方式尤其是接入国产大模型时。因为 API Key 方式把模型选择权完全交给开发者你可以在不同服务商之间切换不受 ChatGPT 账号体系限制。2.4 用 config.toml 管理配置Codex 的主配置文件位于用户目录下的.codex文件夹中Linux/macOS~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml如果文件不存在可以手动创建。第一次运行 Codex 时也会自动生成默认配置。一个面向 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这段配置做了以下几件事model指定 Codex 默认使用deepseek-chat。model_provider指定使用自定义 provider 中名为deepseek的那一项。[model_providers.deepseek]定义一个名为 deepseek 的服务商。base_url指向 DeepSeek 的 OpenAI 兼容接口。env_key告诉 Codex 从DEEPSEEK_API_KEY环境变量读取密钥。wire_api使用 chat 协议因为 DeepSeek 兼容的是聊天补全接口。启动前设置环境变量export DEEPSEEK_API_KEYsk-你的密钥 codex之后 Codex 就会以deepseek-chat模型运行。这个流程是理解国产大模型接入的关键后续所有服务商配置都遵循同样的模式。3. 接入国产大模型在 config.toml 中配置自定义 model_provider3.1 model_providers 配置结构model_providers可以同时定义多个服务商。每个服务商有独立的name、base_url、env_key和wire_api。结构如下model qwen-plus model_provider dashscope [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat [model_providers.dashscope] name DashScope base_url https://dashscope.aliyuncs.com/compatible-mode/v1 env_key DASHSCOPE_API_KEY wire_api chat切换模型服务商时只需要修改两处model改成目标模型名。model_provider改成对应的 provider 名称。这种设计让开发者可以同时保留多个模型服务商按任务类型切换。比如日常简单任务用deepseek-chat复杂推理需求用deepseek-reasoner或更强模型。3.2 DeepSeek 接入示例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获取密钥后在终端验证接口连通性curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果返回模型列表 JSON说明密钥和接口正常。Codex 接入后可以使用deepseek-chat作为默认模型也可以切换到deepseek-reasoner处理需要多步推理的编码任务。3.3 通义千问、Kimi、智谱等模型接入示例不同服务商的接口地址和模型名不同但配置模式一致。以下是一个多服务商配置模板model qwen-plus model_provider dashscope [model_providers.dashscope] name DashScope base_url https://dashscope.aliyuncs.com/compatible-mode/v1 env_key DASHSCOPE_API_KEY wire_api chat [model_providers.moonshot] name Moonshot base_url https://api.moonshot.cn/v1 env_key MOONSHOT_API_KEY wire_api chat [model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4/ env_key ZHIPU_API_KEY wire_api chat通义千问的兼容地址位于阿里云百炼控制台。开通百炼服务后创建 API Key然后在环境变量中设置DASHSCOPE_API_KEY。模型名按百炼平台提供的最新模型列表填写常见的有qwen-plus、qwen-turbo、qwen-max。Moonshot 的 Kimi 模型同样提供 OpenAI 兼容接口。不同阶段模型名变化较大配置前先到官方文档确认当前模型名和接口地址。智谱 GLM 使用/api/paas/v4/地址。模型名通常以glm-开头具体模型名以官方文档为准。下表整理了常见服务商的参考信息服务商base_url 示例模型名示例备注DeepSeekhttps://api.deepseek.com/v1deepseek-chat、deepseek-reasonerOpenAI 兼容接口成熟阿里云百炼https://dashscope.aliyuncs.com/compatible-mode/v1qwen-plus、qwen-turbo、qwen-max使用百炼平台的兼容模式地址Moonshot Kimihttps://api.moonshot.cn/v1kimi-k2等模型名随时变化以官网为准智谱 GLMhttps://open.bigmodel.cn/api/paas/v4/glm-4-plus、glm-4-flashv4 接口地址火山方舟https://ark.cn-beijing.volces.com/api/v3推理接入点 ID通常不直接使用模型名表格里的信息和地址只是参考。模型服务商调整接口地址、模型名、计费规则都很常见落地前一定要到目标服务商文档里确认最新值。3.4 密钥管理的安全建议不要在config.toml中直接写入api_key字符串。原因很简单配置文件可能被同步到团队仓库、粘贴到工单、留在测试服务器上。一旦泄露密钥可能被滥用并产生费用。推荐的密钥管理方式使用env_key让 Codex 从环境变量读取密钥。在 shell profile 中设置环境变量例如~/.bashrc、~/.zshrc。生产环境中可以使用密钥管理服务把密钥注入到进程环境变量。如果当前版本的 Codex 不支持env_key需要把密钥写入auth.json时至少要注意文件权限chmod 600 ~/.codex/auth.json设置权限后只有当前用户能读取该文件降低泄露风险。4. 编写并使用 Skill让 Codex 形成稳定能力4.1 skill 的目录结构和文件格式Skill 本质上是可复用的指令文件。Codex 会通过约定目录加载 skill不同版本对目录名的兼容性存在差异。下面是一种常见组织方式~/.codex/ config.toml AGENTS.md skills/ sql-review/ SKILL.md git-commit/ SKILL.md log-analysis/ SKILL.md每个 skill 子目录下有一个SKILL.md文件。文件头部使用 YAML frontmatter 声明元信息正文描述执行步骤。如果你使用的 Codex 版本对 skill 目录有不同约定优先查看codex --help和官方文档。不要因为配置路径不生效就放弃 skill多数情况下只是目录名或加载方式不同。4.2 最小 skill 示例SQL 审查创建一个 SQL 审查 skill 文件~/.codex/skills/sql-review/SKILL.md--- name: sql-review description: 当用户要求审查 SQL 语句、排查慢查询或评估查询性能时使用。 --- # SQL 审查流程 1. 先定位 SQL 涉及的表和字段确认表结构是否已知。 2. 检查 WHERE、JOIN、ORDER BY 中出现的字段是否可能缺少索引。 3. 检查是否存在 SELECT *并说明是否真的需要全字段。 4. 检查是否存在隐式类型转换例如字符串字段与数字直接比较。 5. 检查是否有 LIMIT尤其是生产环境查询。 6. 输出风险清单按影响程度排序并给出改写建议。这个 skill 做了什么它把一个有经验的 DBA 审查 SQL 时的检查顺序写成了固定流程。以后在 Codex 会话中只要出现 SQL 审查需求模型就会按这个顺序输出结构化建议。4.3 如何让 skill 生效和触发修改 skill 文件后建议重启 Codex 会话。因为部分版本的 Codex 在会话启动时才会加载 skill 文件运行中修改不一定立即生效。触发方式有两种第一种是显式触发。在对话中直接输入使用 sql-review 技能审查下面这条 SQL SELECT * FROM users WHERE phone 13800001111;第二种是隐式触发。如果 skill 文件的description写得足够清晰模型会在合适的场景自动加载。比如用户直接说“帮我看看这条查询是不是有性能问题”模型可能自动匹配到sql-reviewskill。想要隐式触发更准确description要写清楚触发场景不能写得太宽泛。例如“当用户要求审查 SQL 时使用”比“一个 SQL 分析工具”更容易让模型正确匹配。4.4 可复用 skill 场景Skill 适合固化的任务通常具备两个特征步骤稳定、重复频率高。以下场景比较适合写 skill场景skill 应包含的步骤效果SQL 审查索引、隐式转换、SELECT *、LIMIT输出稳定的性能风险评估代码评审检查错误处理、边界条件、安全风险减少评审遗漏Git 提交信息生成读取 diff按规范生成 commit message提高提交信息一致性依赖升级检查列出变更、识别破坏性更新降低升级风险日志分析提取异常类型、时间线、关联错误加快问题定位不要把所有任务都写成 skill。如果某个任务每次处理时情况差异很大写成 skill 反而会限制模型。Skill 适合的是“规则明确、输出格式可预期”的任务。5. 运行验证与效果分析5.1 验证基础对话是否走通配置完成后在项目目录下执行export DEEPSEEK_API_KEYsk-你的密钥 codex进入 Codex 交互界面后输入一个简单的编码任务例如请用 Python 写一个脚本读取 data.csv统计每列的非空数量并输出到 summary.txt。正常情况下Codex 会生成代码文件并尝试在当前目录写入summary.txt。如果能生成文件说明模型调用、工具执行、文件读写这条链路已经走通。如果任务只是返回文本而没有操作文件说明当前模型可能不支持工具调用或者 provider 的接口没有正确暴露工具能力。Codex 这类终端编程代理依赖模型具备工具调用能力模型选型时要确认服务商支持 OpenAI 兼容的工具调用。5.2 验证请求确实发送到了自定义 provider很多开发者配置完发现自己实际用的还是另一个模型但没有察觉。验证方法很简单让请求走一个肯定会报错的错误地址。例如把base_url临时改成base_url https://api.deepseek.com/wrong-path重启 Codex 后发起对话如果报错里出现了/wrong-path说明请求确实发到了自定义地址。确认后再改回正确地址。更直接的方式是查看 Codex 日志。在 Linux/macOS 中日志通常位于~/.codex/log/目录。打印最近的日志ls -lt ~/.codex/log/ | head日志中会出现请求的目标 URL。检查其中的域名和路径就能确认实际生效的 provider 是哪一个。5.3 验证 skill 是否生效在 Codex 会话中显式触发一个 skill使用 sql-review 技能审查这条 SQL SELECT * FROM orders WHERE create_time BETWEEN 2025-01-01 AND 2025-02-01;如果 Codex 开始按SKILL.md中的步骤输出索引检查、类型转换检查、LIMIT 建议等内容说明 skill 已经加载。如果输出仍是普通问答风格说明 skill 没有加载成功优先检查目录路径和 frontmatter 格式。注意不要只验证“能聊天”。对于 Codex 这类 agent 工具要验证文件读写、命令执行、skill 触发、错误分支是否都符合预期。只有完整链路验证过才能进入生产使用。5.4 学习环境与生产环境的差异学习环境里怎么方便怎么来生产环境则需要严格控制。两者的主要差异如下表所示维度学习环境生产环境模型选择默认模型即可成本优先复杂任务用更强模型简单任务用低成本模型API Key可以使用测试 Key独立生产 Key设置调用限额配置来源直接写在 config.toml环境变量或密钥管理服务注入权限控制本机实验权限随意限制文件读写范围避免高危命令自动执行日志可关闭或忽略收集日志关注异常和敏感信息升级策略直接升级到最新版固定版本验证后再升级如果团队要求数据不出内网还可以考虑本地部署模型推理服务例如通过 vLLM 或 Ollama 暴露 OpenAI 兼容接口然后同样用model_providers接入 Codex。本地部署需要确认设备算力是否满足需求7B 级模型在量化后可以运行在部分配置较高的 arm64 设备上但实际效果取决于内存、带宽和显卡规格。6. 常见报错与排查路径6.1 报错cc switch local proxy failed while handling codex endpoint /responses现象描述终端中出现了类似这样的错误cc switch local proxy failed while handling codex endpoint /responses. provider...这个错误通常出现在使用 cc-switch 这类配置切换工具的环境中。cc-switch 会通过在本机启动一个本地转发端点把 Codex 的请求改写到目标模型服务。当端点没有正常启动或者目标 provider 配置不完整时Codex 请求/responses就会失败。排查步骤先确认当前是否使用了配置切换工具。如果没有使用检查是否残留了旧的本地转发配置。检查目标 provider 的base_url是否能直接访问。可以用 curl 测试接口。关闭配置切换工具直接在config.toml中配置 provider让 Codex 直连模型服务。确认wire_api设置正确。如果模型服务只支持/chat/completions而 Codex 请求的是/responses同样会报错。处理方式不建议在同一台机器上叠加多层转发配置。Codex 本身已经支持通过model_providers自定义服务商直接配置base_url和env_key是最简单、最不容易出错的路径。6.2 报错the gpt-5.6-sol model is not supported when using codex with a chatgpt account现象描述使用 ChatGPT 账号登录 Codex 后启动或切换模型时出现the gpt-5.6-sol model is not supported when using codex with a chatgpt account这个报错里的模型名不是关键。关键是你使用了 ChatGPT 账号认证却指定了一个当前账号不支持的模型名。这里的gpt-5.6-sol可以替换成任何账号不允许的模型名称。原因分析ChatGPT 账号登录模式下的模型列表是受限的。Codex 会校验当前账号可用模型当config.toml中的model字段指定了账号之外的模型名时就会报错。解决方式不要使用 ChatGPT 账号登录改用 API Key 方式接入自定义 provider。将配置改为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这样模型选择完全由 provider 配置决定与 ChatGPT 账号无关。6.3 报错无法加载 config.toml现象描述执行 Codex 时提示无法加载config.toml日志中会包含具体行号和字段信息例如无法加载 config.toml: model常见原因包括TOML 语法错误例如括号不匹配、缺少引号。字段名拼写错误例如把model_provider写成model_provide。配置文件路径不对Codex 没有读取到预期文件。某个 provider 引用了未定义的环境变量。排查方式先检查文件路径ls -l ~/.codex/config.toml然后校验 TOML 格式。Python 3.11 以上版本可以直接使用 tomllibpython3 -c import tomllib; tomllib.load(open(/root/.codex/config.toml,rb))如果输出异常说明文件格式有问题。根据报错行号修复。Windows 用户检查%USERPROFILE%\.codex\config.toml。如果配置文件放在项目目录需要确认运行时的工作目录。6.4 请求超时、401、429 等 API 错误接入国产大模型时最常见的几类错误可以用下表快速定位现象常见原因检查方式处理建议请求超时base_url 不可达或域名解析失败用 curl 测试接口地址确认服务商文档地址更换可访问地址401 UnauthorizedAPI Key 错误或未设置检查环境变量是否生效重新生成 Key确认没有空格或换行429 Rate limit触发调用限额登录服务商控制台查看用量提升限额或改用低频率调用404 Not Found接口路径错误或 wire_api 不正确确认 base_url 后是否包含/v1修正 base_url检查 wire_apimodel not found模型名不对查询服务商模型列表换成文档中列出的模型名这里要强调一个容易忽略的点base_url末尾是否包含/v1每个服务商习惯不同。DeepSeek 的地址是https://api.deepseek.com/v1Moonshot 是https://api.moonshot.cn/v1智谱则可能是https://open.bigmodel.cn/api/paas/v4/。配置前最好用 curl 实测curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY如果返回 JSON 数据说明地址正确。如果返回 404去掉或补上路径中的/v1再试。7. 最佳实践与可复用清单7.1 配置管理清单接入 Codex 并不难难的是让配置在团队中稳定可维护。以下是每次修改前建议对照的清单确认config.toml中model和model_provider指向同一服务商。确认base_url能以 curl 正常访问。确认密钥通过环境变量注入而不是写在配置文件里。确认wire_api与接口协议匹配。确认修改后重启了 Codex 会话。确认当前 Codex 版本支持所写的配置字段。Codex 更新频繁某些字段名可能在升级后改变。生产环境做好版本固定升级前先在测试环境验证配置兼容性。7.2 skill 编写规范编写 skill 时建议遵循以下原则第一一个 skill 只解决一类任务。同一个文件里既写 SQL 审查又写日志分析会让模型难以判断什么时候触发。第二description写清楚触发场景。描述应该包含关键词和边界条件例如“当用户要求审查 SQL 语句、排查慢查询或评估查询性能时使用”。第三步骤要具体到可执行。不要只写“检查 SQL 性能”要写清楚检查哪些方面例如 WHERE 条件字段、JOIN 字段、隐式类型转换、LIMIT。第四指定输出格式。如果希望输出风险清单就明确写“输出风险清单按影响程度排序”。第五避免让 skill 依赖模型的记忆。模型不会记住上一次对话的内容每个 skill 文件都要独立完整。7.3 成本与安全建议接入国产大模型后成本和安全主要从三个角度控制。第一个是成本控制。在模型服务商控制台设置调用限额避免单个任务反复重试产生高额费用。 Codex 可能因为工具调用失败多次重试必要时在交互中限制重试次数。第二个是权限控制。不要让 Codex 在不知道的情况下执行高风险命令。进入生产环境前审查它的执行权限必要时通过配置限制可写目录和可执行命令。第三个是敏感信息保护。Codex 会把代码片段和上下文发送到模型服务商。涉及商业机密、个人隐私、密钥鉴权信息的项目不要直接使用外部 API。此时优先考虑本地部署模型或者通过企业私有的模型网关接入。7.4 建议的上手路径对于刚接触 Codex 的开发者不建议一上来就配置大量 skill 和多个 provider。推荐按以下顺序逐步推进安装 Codex CLI确认codex --version正常。配置一个国产大模型 provider完成基础对话。跑通文件读写任务确认工具调用链路正常。为最高频的重复任务写一个最小 skill。验证 skill 触发和输出格式。熟悉日志和报错排查方式。再考虑切换多个 provider、配置团队级AGENTS.md、接入本地模型。Codex 的价值不在于能跑多少命令而在于能否稳定地嵌入你的开发流程。让模型在一条可验证、可回滚、可观察的链路下辅助编码比追求新功能和复杂配置更有意义。