最近有不少做 AI 编程工具研究的朋友问我Codex 是不是必须要 ChatGPT 订阅是不是必须依赖境外网络环境本地那些 skill 技能又是怎么一回事先说结论Codex 本身是可以脱离 ChatGPT 订阅使用的。通过 Codex CLI 的模型提供商配置机制我们可以把模型切换成国产大模型 API比如 DeepSeek效果基本能满足日常代码生成、代码审查、Commit Message 生成等需求。加上 skill 技能机制Codex 还能变成一个具备“领域知识”的本地编码助手。这篇文章我会结合自己的实操过程从安装、配置、编写 skill 到报错排查完整走一遍。文中所有内容都基于普通网络环境即可完成不需要额外开通 ChatGPT 付费订阅也不需要复杂网络设置。如果你是刚接触 Codex 的小白或者已经装了 Codex 但一直没跑通这篇教程可以帮你一次性解决。1. Codex 与 Skill 到底是什么1.1 Codex 是什么Codex 是 OpenAI 推出的人工智能编程工具系列常见形态包括网页版、IDE 插件和命令行工具 Codex CLI。很多教程里提到的“Codex”其实有两种理解一种是早期专门用于写代码的 Codex 模型另一种是现在的 Codex CLI 工具。本文主要讨论的是Codex CLI。Codex CLI 是一个运行在终端里的编程代理它可以根据你的指令读取项目目录、分析代码、修改文件、执行命令甚至调用外部工具。和简单聊天窗不同它更接近一个“住在终端里的结对编程搭档”。这里要区分几个概念ChatGPT通用对话产品面向普通用户需要登录网页或 App 使用。Codex CLI开发工具面向开发者提供命令行交互界面可以通过 API 或模型提供商配置连接不同模型。skillCodex CLI 中的技能扩展机制类似于给助手预设的专业能力包让它能按固定流程完成某一类任务。对国内开发者来说直接使用 Codex CLI 时如果绑定的是 ChatGPT 账号可能需要考虑账号类型、订阅状态、模型支持范围等问题。更好的做法是把 Codex CLI 的模型切换成国产大模型服务这样既绕开了订阅门槛又能使用国内网络环境直接访问。1.2 为什么要接入国产大模型接入国产大模型不是“退而求其次”而是很多开发者的现实需求。原因主要有三点。第一成本更灵活。ChatGPT 订阅是包月制部分用户可能只是偶尔用一下包月并不划算。而 DeepSeek 等国产大模型采用按量计费注册后充值少量金额就能用很久对个人开发者更友好。第二网络访问简单。Codex CLI 如果走官方 ChatGPT 账号通道会涉及境外服务访问问题对国内用户不一定是稳定体验。而 DeepSeek、通义千问等模型的 API 域名都在国内普通网络环境下直接调用即可不需要额外配置网络链路。第三数据合规更有把握。企业项目中对代码外发非常敏感。接入国产大模型时可以选择与内部合规要求匹配的服务商签署相应协议数据管控路径更清晰。个人开发者也能根据自己的信任度选择服务商。要注意接入国产大模型以后Codex CLI 的定位就变了它不再是一个“只能连 ChatGPT 的客户端”而是一个“支持 OpenAI 兼容接口的编码代理终端”。我们只需要在配置文件中声明模型提供商就能自由切换模型。1.3 skill 技能机制是什么skill 是 Codex CLI 近期版本引入的扩展机制借鉴了 Agent Skills 的设计思路。简单说你可以在本地创建一组技能文件告诉 Codex CLI“当用户要求做某件事时按这套规范和脚本去执行。”一个 skill 通常包含一份描述文件说明技能的用途、适用场景和使用步骤。可选的一组脚本用来完成具体操作。可选的参考资料用来给模型提供领域知识。可选的规则清单约束模型的行为方式。举个例子。团队希望 Codex 生成的 Commit Message 必须遵循 Conventional Commits 规范你就可以写一个commit-message技能描述里写明“根据 git diff 生成符合 Conventional Commits 规范的提交信息类型只允许使用 feat/fix/docs 等枚举值”。之后 Codex 执行相关任务时就会自动带上这套约束。skill 的价值在于把可复用的经验和规范沉淀成文件而不是每次都在对话里重复输入。下面我们会从安装配置开始一步步搭建一个可用的 Codex 环境。2. 环境准备与安装2.1 环境要求概览在开始之前先确认你的电脑满足基本条件。Codex CLI 是一个 Node.js 命令行工具所以系统里需要安装 Node.js 运行环境。操作系统方面Windows、macOS、Linux 都可以。本文示例以 Windows 11 PowerShell 为主如果你用的是 macOS 或 Linux命令差异主要是环境变量设置方式后面会单独说明。版本方面建议 Node.js 使用 18 或更高版本。太旧的 Node.js 可能导致 Codex CLI 安装失败或运行时出现依赖兼容问题。如果你拿不准自己的版本可以在终端执行node -v npm -v如果命令能够正常输出版本号说明 Node.js 环境基本可用。如果没有安装 Node.js可以去 Node.js 官网下载 LTS 版本安装完成后重新打开终端再检查一遍。这里需要说明一下Codex CLI 更新速度比较快不同版本在配置字段、命令参数上可能略有差异。本文以常见版本为例重点演示配置思路遇到具体字段变化时请以你安装版本的官方文档为准。2.2 安装 Codex CLI安装 Codex CLI 最直接的方式是使用 npm 全局安装。打开终端执行下面的命令npm install -g openai/codex如果你的 npm 在国内网络环境下下载比较慢可以临时切换到国内镜像源例如使用淘宝镜像npm config set registry https://registry.npmmirror.com npm install -g openai/codex安装完成后验证一下命令是否可用codex --version正常情况下会输出版本号类似codex 0.x.x。如果你的电脑上同时安装了 pnpm 或 yarn也可以使用对应的包管理器安装例如pnpm add -g openai/codex。选择哪个包管理器主要看你的使用习惯没有本质区别。安装时如果提示权限不足在 macOS/Linux 下可以尝试sudo npm install -g openai/codex在 Windows 下可以确认终端是否以管理员身份运行。注意使用 sudo 安装全局包会带来权限风险如果项目环境允许建议先配置 npm 全局目录为当前用户目录再重新安装。2.3 安装后的目录结构Codex CLI 安装成功后会在用户目录下生成一个配置目录。在 Windows 上通常是C:\Users\你的用户名\.codex在 macOS/Linux 上是~/.codex。这个目录里最核心的文件是config.tomlCodex CLI 读取这个文件来决定连接哪个模型服务商、使用哪个模型、以及一些运行参数。如果文件不存在可以手动创建。另外skill 技能文件通常也放在这个目录下的skills子目录中结构类似~/.codex/ ├── config.toml ├── skills/ │ ├── commit-message/ │ │ ├── SKILL.md │ │ └── scripts/ │ └── code-review/ │ └── SKILL.md └── logs/先记住这个目录结构后面配置时会反复用到。2.4 是否需要登录 ChatGPT很多人的困惑是安装 Codex CLI 后会不会强制要求登录 ChatGPT 账号如果是第一次启动 Codex CLI它可能会提示你选择登录方式常见的有“使用 ChatGPT 账号登录”和“使用 API Key”。如果你不打算使用 ChatGPT 官方模型就不需要走登录流程。我们可以通过修改config.toml把模型提供商指定为 DeepSeek 等国产大模型服务这样 Codex CLI 就不会要求绑定 ChatGPT 账号了。需要注意的是不同版本 Codex CLI 在首次启动时的交互逻辑不一样。如果你安装的版本强制要求先登录可以在配置好国产模型后再启动或者在初始化界面选择“跳过 / Skip”。本文模型配置部分会给出完整的config.toml配置完成后Codex CLI 会直接走自定义提供商路线。3. 配置国产大模型以 DeepSeek 为例3.1 获取 DeepSeek API Key接下来把 Codex CLI 切换到国产大模型。目前社区里比较常见的接入对象是 DeepSeek因为它的 API 兼容 OpenAI 接口格式配置起来很顺而且模型能力在编程场景中表现不错。首先打开 DeepSeek 开放平台官网注册并登录账号。进入控制台后找到“API Keys”菜单创建一个新的 API Key。创建完成后系统会显示一串类似sk-xxxxxxxx的密钥复制并保存好。关于 API Key 的安全性有几点必须提醒API Key 相当于你的账号凭证不要提交到 Git 仓库。不要写在博客、群聊或任何公开地方。建议把 Key 放到环境变量里Codex CLI 从环境变量读取这样配置文件里就不会出现明文密钥。如果你希望限制风险可以在平台里设置消费额度上限防止 Key 泄露后被恶意调用。DeepSeek 平台的模型分为deepseek-chat和deepseek-reasoner两个常见模型标识。前者适合常规对话和代码生成后者适合需要深度推理的复杂任务。具体以你注册时服务商提供的模型列表为准。3.2 编写 config.toml找到~/.codex/config.toml文件如果不存在就新建一个。使用 VS Code 或你喜欢的文本编辑器打开写入以下内容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 CLI 默认使用的模型名称。model_provider指定模型提供商对应下面定义的deepseek配置块。[model_providers.deepseek]是一个配置块描述 DeepSeek 服务商的连接信息。env_key告诉 Codex CLIAPI Key 从名为DEEPSEEK_API_KEY的环境变量中读取。这里有一个容易踩坑的地方不同版本 Codex CLI 的配置字段不完全一样。有的版本使用model_provider有的版本使用model_providers下的id字段还有的版本对wire_api的取值要求不同。如果你在启动时发现提示“无法识别配置项”请打开 Codex CLI 的帮助文档按照官方示例调整字段名。3.3 配置环境变量接下来把 API Key 写入环境变量。在 Windows PowerShell 中执行$env:DEEPSEEK_API_KEYsk-你的密钥这种方式只对当前终端窗口有效关闭终端后会失效。如果你希望永久生效可以通过 Windows 系统设置里的“环境变量”配置界面添加。在 macOS / Linux 下可以在~/.bashrc或~/.zshrc中追加一行export DEEPSEEK_API_KEYsk-你的密钥然后执行source ~/.bashrc配置完成后在终端里启动 Codex CLIcodex如果一切正常Codex CLI 会使用 DeepSeek 模型开始会话。你可以输入一句“你好请介绍一下这个项目”验证是否能正常返回结果。3.4 其他国产大模型的可选配置除了 DeepSeek市面上还有其他 OpenAI 兼容接口的服务商可选。比如通义千问的阿里云百炼平台、智谱 AI 等。它们的配置思路完全一样只是base_url和env_key不同。以通义千问为例参考配置如下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注意base_url必须按服务商文档填写不同平台的兼容路径差异很大。如果填写错误Codex CLI 会报 404 或 401 错误。选择哪个模型主要看三点服务商是否提供 OpenAI 兼容接口。模型在代码生成、代码理解上的能力表现。API 价格和限流策略是否符合你的使用强度。建议先从 DeepSeek 开始因为社区里配置案例多遇到问题容易搜到解决方案。4. 编写与加载 Skill 技能4.1 skill 的典型目录结构配置好模型以后Codex CLI 已经可以正常工作了。接下来我们给它增加“专业技能”让它能按照团队规范完成特定任务。skill 的本质是一组文件放在~/.codex/skills/目录下。每个技能一个子目录子目录里必须有一个SKILL.md文件。典型结构如下~/.codex/skills/ └── commit-message/ ├── SKILL.md ├── scripts/ │ └── suggest_commit.py └── references/ └── conventional-commits.mdSKILL.md技能的主描述文件告诉 Codex 这个技能是做什么的、什么时候使用、怎么使用。scripts/存放可执行脚本Codex 在完成任务时可以调用。references/存放参考资料Codex 读取这些内容来补充领域知识。如果你的技能不需要脚本和参考资料只创建SKILL.md就够了。最重要的还是把描述写得足够清晰因为模型会依靠这份描述来决定是否启用该技能。4.2 编写第一个 SKILL.md下面以“生成 Commit Message”为例创建一个简单实用的技能。先创建目录mkdir -p ~/.codex/skills/commit-message然后在该目录下新建SKILL.md内容如下--- name: commit-message description: 根据当前 Git 变更生成符合 Conventional Commits 规范的提交信息。当用户要求“生成提交信息”“写 commit message”时使用。 --- # Commit Message 生成技能 ## 目标 根据 Git 仓库的暂存区变更生成一条符合 Conventional Commits 规范的提交信息。 ## 使用步骤 1. 运行 git status 查看当前变更状态。 2. 运行 git diff --cached 查看暂存区具体内容。 3. 根据变更内容判断提交类型可选类型包括 - feat: 新功能 - fix: 修复 Bug - docs: 文档变更 - style: 格式调整 - refactor: 重构 - test: 测试 - chore: 构建或辅助工具变更 4. 生成标题格式为 类型(可选范围): 简要描述例如 feat(auth): 增加验证码登录接口。 5. 如果变更内容复杂在标题下补充正文说明改动原因和影响范围。 ## 注意事项 - 标题不超过 72 个字符。 - 第一行首字母小写。 - 不要使用 AI 腔调词汇例如“优化”“完善”“提升”。 - 如果暂存区没有变更先提醒用户执行 git add。文件开头使用了 YAML 格式的 frontmatter其中name是技能名称description是触发条件描述。description写得好不好直接决定 Codex 能不能在合适的时候自动找到这个技能。建议把常见的触发说法都写进去比如“生成提交信息”“写 commit message”“帮我提交一下”。后面的正文部分采用 Markdown 格式模型会把它当作执行指南。可以在其中约定严格的输出格式也可以加入负面清单避免模型自由发挥。4.3 在 Codex 中加载和使用 skillskill 写好后Codex CLI 并不一定会自动加载。你需要确认当前版本支持 skill 机制并且启动了对应功能。不同版本 Codex CLI 对 skill 的启用方式不同。常见做法包括在对话中输入/skills查看可用的技能列表。使用参数指定技能目录例如codex --skills或类似命令。在配置文件中声明skills_enabled true。如果以上方式在某个版本中不可用建议先执行codex --help查看帮助确认该版本支持什么命令。也可以到官方 GitHub 仓库的 Release Notes 里查看功能变更说明。在支持 skill 的版本里加载效果是当你输入“帮我把这些改动生成 commit message”时Codex 会自动检索匹配的技能描述发现commit-message技能的description与需求吻合于是加载并遵循技能中的步骤执行。4.4 进阶让 skill 结合脚本有些任务光靠文字描述不够还需要脚本参与。比如生成 Commit Message 时可以让 Python 脚本先解析 git diff输出变更文件列表和代码摘要再让模型基于摘要生成规范化的提交信息。在commit-message技能目录下创建scripts/suggest_commit.py内容如下import subprocess import sys def get_staged_diff(): result subprocess.run( [git, diff, --cached, --stat], capture_outputTrue, textTrue, checkFalse, ) return result.stdout def main(): diff_stat get_staged_diff() if not diff_stat.strip(): print(暂存区没有变更请先执行 git add 将文件加入暂存区。) sys.exit(1) print(以下文件已暂存) print(diff_stat) if __name__ __main__: main()然后在SKILL.md的使用步骤里补充一句如果用户允许运行脚本先执行 python ~/.codex/skills/commit-message/scripts/suggest_commit.py 查看暂存文件概况再生成提交信息。这样就把“静态技能描述”升级成了“可执行技能”。Codex CLI 在沙箱环境中执行脚本时可能受到权限限制如果脚本无法执行需要检查命令行工具的权限配置。其他领域的技能也可以采用同样思路。比如代码审查技能可以先用脚本统计改动文件、圈复杂度再把分析结果交给模型生成审查意见。技能的核心价值不是把模型变聪明而是把流程规范化和可重复化。5. 常见报错与排查思路5.1 config.toml 无法加载或内容解析失败如果你在启动 Codex CLI 时看到类似“无法加载 config.toml”的提示通常有三个原因。第一配置文件路径不对。Codex CLI 的配置目录按系统和版本不同会有差异默认是用户目录下的.codex但如果你设置了CODEX_HOME环境变量实际读取的是指定目录。排查时可以执行echo $CODEX_HOME确认配置目录到底指向哪里。第二TOML 语法错误。TOML 对格式要求严格如果少了引号、多了一个括号或者把注释符号写错解析就会失败。建议复制一段官方示例在示例基础上修改不要手工敲写复杂结构。第三配置了不存在的字段。某些网络教程会在配置里添加了很多高版本才支持的字段旧版本 Codex CLI 读到这些字段时会直接报错。最稳妥的做法是保留最小配置逐步增加字段每次改完都启动一次验证。5.2 模型不受支持gpt-5.6-sol 这类报错热词里有一个典型报错the gpt-5.6-sol model is not supported when using codex with a chatgpt account。这个报错的根本原因很简单config.toml里model字段写了一个服务商根本不存在的模型名或者你用了 ChatGPT 账号认证却指定了一个自定义模型。Codex CLI 会严格校验模型名模型不支持就直接拒绝。解决办法分两步确认你使用的是自定义模型提供商而不是 ChatGPT 账号登录。把model字段改成服务商真实提供的模型名。以 DeepSeek 为例可以先用deepseek-chat测试再去平台文档查看最新可用列表。类似的还有把模型名写成gpt-5、gpt-4-xxx等旧版或虚构名称的情况。建议修改配置后先运行一个最简对话测试。5.3 请求 /responses 接口失败或网络连接失败Codex CLI 在处理请求时会向模型服务商的接口发送数据。如果你看到类似“switch local proxy failed while handling codex endpoint /responses”的报错或者直接提示网络连接失败大概率是请求链路出了问题。这里要分两类情况看待。一类是使用国产大模型 API正常情况下普通网络访问国内服务商不会有问题如果报错优先检查base_url是否填错是否多了空格或尾部斜杠。环境变量是否在当前终端中生效。服务商控制台是否开启了接口白名单。另一类是用户本机存在网络转发工具或全局网络拦截软件且未对命令行工具放行导致请求被强制转发到非法路径。这类场景不属于正常开发配置如果遇到建议关闭无关工具或者只在必要且合规的前提下调整系统设置。国内用户使用国产模型时没有必要配置额外的网络链路。5.4 中文输出乱码或内容截断Codex CLI 默认在终端输出内容部分终端对中文字符支持不好会出现乱码。排查时先确认终端编码为 UTF-8Windows 下可以在 PowerShell 里设置$OutputEncoding [System.Text.Encoding]::UTF8 [Console]::OutputEncoding [System.Text.Encoding]::UTF8另外模型输出的长度受上下文窗口和参数限制。如果对话过长可以开启新会话如果模型回答到一半就停可以检查是否设置了过小的输出 token 上限或者换用支持更长上下文的模型。5.5 排查清单问题现象常见原因解决思路config.toml 无法加载路径错误 / TOML 语法错误 / 未知字段检查路径用最小配置启动逐步增加字段model not supported模型名不存在或认证方式不匹配使用自定义提供商确认模型真实存在请求接口失败base_url 错误 / Key 无效 / 网络链路问题核对接口地址检查环境变量确认服务商状态401 鉴权失败API Key 错误或未读取到环境变量重新生成 Key确认 env_key 名称一致中文乱码终端编码不是 UTF-8设置终端编码后重试skill 无法生效版本不支持 / 描述不匹配查看帮助命令完善 description 触发词排查时不要一次性改多个变量。记住一个原则每次只改一个配置项然后启动验证这样出现问题时能快速定位。6. 最佳实践与工程建议6.1 API Key 安全与成本控制接入国产大模型后API Key 的安全就是一等一的大事。建议把所有 Key 都通过环境变量注入而不是写进config.toml或项目目录下的.env文件。即便使用.env也要确保该文件被.gitignore忽略。成本控制方面可以在服务商控制台设置月度消费上限还可以设置每分钟请求数限制防止脚本异常循环导致费用激增。日常使用中优先选择价格较低的对话模型处理简单任务只有在复杂重构、架构分析时才切换推理模型。另外不要把个人 Key 分享给团队使用。多人协作时应该由团队统一申请服务商账号按成员分配独立的 Key方便审计和回收权限。6.2 skill 文件与版本管理skill 是纯文本文件非常适合用 Git 管理。建议为 skill 单独建一个仓库团队成员 clone 到各自~/.codex/skills/目录后即可使用。skill 的命名和更新也有讲究名称使用小写中划线风格例如commit-message、code-review。每个 skill 只做一件事职责单一。修改 skill 描述时注意同步更新description中的触发词。技能设计严格遵循最小权限原则只申请执行所需的最小权限。如果发现某个技能经常不被触发问题通常出在description写得不够明确。可以多收集团队实际对话中的说法把它们补充到触发词里。6.3 生产环境使用注意事项如果你的团队准备把 Codex CLI 接入到正式项目流程中有几个问题需要提前决策。第一代码是否允许发送到第三方模型服务。企业项目常常有保密要求需要先和法务、安全团队确认数据边界选择支持私有化部署或签订数据保护协议的服务商。第二生成的代码怎么审查。Codex 生成的代码不能直接合入主干必须走人工 Code Review。建议让 Codex 生成建议补丁由开发者确认后再落盘而不是让 AI 自动修改所有文件。第三自动化脚本要控制影响范围。Codex CLI 有能力执行终端命令如果不加限制它可能执行任意指令。团队可以在配置中关闭危险操作或者只允许在指定目录内执行命令。生产环境中变更代码、操作数据库等行为必须走审批和备份流程。6.4 与 IDE 和日常流程结合Codex CLI 适合重度终端用户但如果你更习惯用 VS Code可以安装 Codex 插件把同样的能力集成到 IDE 侧边栏。IDE 版本和 CLI 版本在配置上是互通的共用~/.codex/config.toml里的模型提供商配置。日常使用中我也建议把 Codex 的定位想清楚它适合辅助生成脚手架、写单元测试、解释陌生代码、生成提交信息、做基础代码审查。它不适合在无人复核的情况下直接修改生产代码。把它当成“高级自动补全 可编程助手”比当成“全自动程序员”更现实。6.5 保持工具链更新Codex CLI、skill 机制、国产大模型 API 都在快速迭代。每过一段时间配置项就可能变化。建议关注两部分信息源一是 Codex CLI 官方 GitHub Release 页面二是你所用服务商的模型列表和接口变更公告。升级工具前先在测试环境验证核心技能是否还能正常工作。尤其是SKILL.md的 frontmatter 字段如果新版不兼容旧版格式可能导致所有技能失效。备份好~/.codex目录是成本最低的保险手段。7. 总结与落地建议7.1 回顾关键链路整篇文章的核心链路其实很短安装 Codex CLI在配置文件中声明 DeepSeek 模型提供商把 API Key 放到环境变量里然后开始使用。如果想让它在项目中发挥更大作用再为它编写自定义 skill把团队的规范沉淀成描述文件。我在本地实际使用的过程中最明显的一个感受是把模型从 ChatGPT 官方通道切换到国产大模型后Codex CLI 的可用性反而更高了因为它不再受网络环境和账号类型的制约同时还能按量计费用多少花多少心理负担也小很多。文中提到的config.toml和SKILL.md都是最简示例。你完全可以根据自己的项目特点扩展比如为 Python 项目写一个“依赖安全检查”技能为前端项目写一个“组件规范生成”技能为数据库操作写一个“SQL 审查”技能。7.2 进一步学习的方向如果你已经跑通本文的环境下一步可以深入这几个方向学习 Codex CLI 的权限模型尝试在沙箱环境中限制命令执行范围。研究 skill 机制的进阶写法包括多脚本协作、动态读取项目上下文。比较 DeepSeek、通义千问等模型在代码任务上的差异选出最适合个人场景的默认模型。尝试把 Codex 能力接入团队 CI 流程比如用它在提交前自动生成变更说明。最后给一个实操建议不要在第一次启动时就折腾复杂的技能和配置。先把codex跑起来用一个简单问题验证链路再逐步增加技能文件、环境变量和脚本。每一步验证通过后再进入下一步这样排查问题时思路会清晰很多。如果你在配置过程中遇到了文中没有提到的报错欢迎在评论区留言带上你的 Codex 版本号和完整报错信息我们可以一起分析。