之前不少朋友在体验 Codex CLI 时被安装方式、模型接入和本地服务配置这几个环节反复卡住。尤其是想把 Codex 接到第三方兼容模型社区里常提到的“GPT-5.6”其实是这类模型的昵称时资料东一块西一块很难一次跑通。本文整理了一份从零开始的 Codex 安装与接入教程覆盖环境准备、CLI 安装、第三方模型配置、CC Switch 本地端点排错和最佳实践不管你是想本地玩一玩还是在真实项目里把它用起来都可以直接参考这套流程。1. Codex 是什么为什么要接入第三方模型1.1 Codex 的定位Codex 是 OpenAI 推出的编码智能体。它不是一个单纯的代码补全插件而是一个能在命令行会话里理解任务、生成代码、执行命令、读取文件、甚至自动修复报错的工作流工具。简单说你可以把 Codex 理解成一个“住在终端里的 AI 程序员搭档”。Codex CLI 是 Codex 的命令行客户端。它把代码生成、代码审查、Shell 命令执行和 Git 操作整合在一起通过自然语言交互完成开发任务。常见使用方式包括用自然语言描述需求让 Codex 生成完整模块。让 Codex 阅读项目源码解释某个逻辑。让 Codex 检查代码中的潜在问题。让 Codex 执行测试、运行命令并分析输出。这种工作方式适合追求高效编码的开发者也适合想要学习 AI 编程实践的新手。相比在网页对话框里复制粘贴代码Codex 的优势是能直接操作本地文件系统有上下文感知能力能持续完成一个完整的开发小闭环。1.2 为什么要接入第三方模型Codex CLI 默认情况下会优先使用官方模型和官方 API 服务。但很多开发者会遇到三种情况希望使用已有的其他大模型服务商账号节省额外成本。希望体验社区版本中被称为“GPT-5.6”的模型能力。希望把 Codex 接入内网统一模型网关方便团队管理。Codex CLI 提供了比较灵活的模型提供方配置机制只要目标服务是 OpenAI API 兼容协议就能通过修改配置文件接入。这样我们就不必被默认的模型和鉴权方式锁死可以自由切换多个服务商甚至能做到“一个 Codex多个模型”。1.3 关于“GPT-5.6”需要先说明本文标题里的“GPT-5.6”并不是一个严谨的官方模型名称。你在社区看到的“白嫖 GPT-5.6 接入 Codex”通常指的是通过第三方兼容服务把 Codex CLI 连接到一个模型名包含gpt-5.6的模型端点或者连接到一个被服务商包装成该名字的模型。使用这类模型时请务必注意三点以服务商文档给出的模型名称为准不要在配置里凭记忆填写。不要使用非正规渠道获取的 API Key避免账号安全和数据泄露。需要留意服务商的收费规则和免费额度避免在不知情的情况下产生高额费用。2. 环境准备与版本说明2.1 需要准备的环境在安装 Codex CLI 之前先确认本机环境满足以下条件操作系统Windows 10/11、macOS 或主流 Linux 发行版均可。Codex CLI 是跨平台工具但不同系统的安装命令有差异。终端Windows 推荐 PowerShell 7 或 Windows TerminalmacOS 推荐 iTerm2 或系统自带终端Linux 使用 bash 或 zsh。Node.js如果选择 npm 方式安装需要 Node.js 16 及以上版本。你可以用node -v检查。Git部分 Codex 流程会调用 Git建议提前安装并配置好用户信息。API Key准备一个可用的第三方模型服务商 API Key或者官方 API Key。这些不是硬性门槛但提前准备好会让后续步骤更顺畅。特别是 API Key建议放在独立的环境变量里不要直接写在配置文件中提交到 Git。2.2 当前版本说明Codex CLI 版本迭代比较快本文示例以社区常见的 npm 安装方式为主。如果你在安装时发现命令或参数有差异请优先参考当前版本的codex --help输出不要照搬旧文档。版本相关建议不要盲目安装最新测试版如果你的项目比较重要建议使用 stable 版本。安装完成后用codex --version记录当前版本后续排查问题会方便很多。不同操作系统的安装方式可能不同优先参考官方 README 和 release 说明。2.3 配置文件位置Codex CLI 的配置会存放在用户目录下不同系统默认路径如下系统配置文件路径Linux~/.codex/config.tomlmacOS~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml如果文件夹不存在可以手动创建。下面所有配置示例都以 Linux/macOS 路径为例Windows 用户把路径替换为主用户目录下的.codex文件夹即可。3. 安装 Codex CLI 的完整步骤3.1 安装前检查打开终端先确认 Node.js 和 npm 是否可用node -v npm -v如果系统提示命令不存在需要先安装 Node.js。建议使用 LTS 版本避免出现兼容性问题。然后检查是否已经安装过 Codexcodex --version如果已经安装过低版本可以先卸载旧版本再重新安装npm uninstall -g openai/codex卸载后再次执行codex --version看到“command not found”说明环境已经干净。3.2 使用 npm 安装 Codex CLI大多数情况下推荐使用 npm 进行全局安装npm install -g openai/codex安装过程会输出依赖信息等待一段时间后再用codex --version验证。如果网络下载比较慢可以换用国内 npm 镜像但要注意镜像源的更新频率npm config set registry https://registry.npmmirror.com安装完成后再把镜像源改回官方源也可以具体取决于你的实际网络环境。3.3 使用 Homebrew 安装macOS 可选macOS 用户如果已经安装 Homebrew也可以使用 brew 安装 Codex。不同版本对应的 brew 仓库名称可能不同建议先用以下方式搜索brew search codex找到对应包名后再安装brew install codex使用 Homebrew 的好处是与系统包管理统一升级方便。但需要注意 brew 仓库中的 Codex 版本可能与 npm 版本不一致功能差异不大按个人习惯选择即可。3.4 验证安装结果安装完成后执行以下命令codex --help如果能看到类似Usage: codex [OPTIONS] COMMAND的帮助信息说明安装成功。接着查看版本号codex --version3.5 登录与鉴权方式Codex CLI 支持多种登录方式。如果你使用官方 API Key可以执行codex login在弹出的页面完成授权Codex 会自动保存凭证。如果使用第三方模型服务商通常不需要codex login而是通过 API Key 注入方式鉴权。这点会在第 4 章详细说明。4. 配置第三方模型接入 Codex4.1 理解 OpenAI 兼容端点很多模型服务商都会提供 OpenAI 兼容的 API 格式。这意味着只要 Codex 发送的请求遵循 OpenAI 的规范服务商就能正常响应。于是我们只需要在 Codex 配置文件中指定base_url服务的 API 地址。env_key存放 API Key 的环境变量名。model服务商支持的模型名称。model_provider默认使用的模型提供方。这种设计把“模型服务商”和“Codex 工作流”解耦了。你甚至可以同时配置 DeepSeek、Moonshot、通义千问等多个服务商按需切换。4.2 获取 API Key 与 Base URL在配置之前先到对应服务商的控制台创建 API Key。创建后不要直接复制到配置文件里推荐放到环境变量中。以 DeepSeek 为例假设你的 API Key 是sk-xxxxexport DEEPSEEK_API_KEYsk-xxxx如果你使用的是 Windows PowerShell可以执行$env:DEEPSEEK_API_KEYsk-xxxx同时记录服务商提供的 API Base URL。通常形如https://api.deepseek.com/v1不同服务商的 Base URL 可能不一样以服务商文档为准。4.3 编写 config.toml 配置编辑~/.codex/config.toml添加一个自定义模型提供方# 定义模型提供方 model_providers [ { name deepseek, base_url https://api.deepseek.com/v1, env_key DEEPSEEK_API_KEY } ] # 设置默认提供方和默认模型 model_provider deepseek model deepseek-chat配置完成后保存文件。下次终端里运行 Codex 时它会自动读取这个配置。如果你使用的服务商模型名是社区常说的gpt-5.6可以把model修改为服务商给出的实际模型名。但务必确认服务商确实支持这个模型否则会报 “model not found” 之类的错误。4.4 使用 CC Switch 管理多模型可选CC Switch 是社区常用的模型切换工具。它的作用是集中管理多个模型服务商的 API Key并在本地启动一个统一端点让 Codex、IDE 插件等工具通过这个端点访问不同模型。接入逻辑是在 CC Switch 中填写多个服务商的 API Key。启动 CC Switch 的本地服务。把 Codex 的base_url指向 CC Switch 本地地址。Codex 通过本地地址发送请求CC Switch 再转发到对应模型服务商。比如常见本地地址格式可能是http://127.0.0.1:8000/v1具体端口号以 CC Switch 界面显示为准。配置文件可写成model_providers [ { name ccswitch, base_url http://127.0.0.1:8000/v1, env_key CCSWITCH_API_KEY } ] model_provider ccswitch model gpt-5.6这种方式的优势是你不需要反复修改 Codex 配置只需要在 CC Switch 中切换模型。适合经常在多个模型之间切换测试的开发者。4.5 鉴权方式的区别如果你使用第三方模型服务商通常仍然需要一个 API Key 才能通过鉴权。Codex 会根据env_key读取对应的环境变量然后把 Key 放入请求头。使用 CC Switch 时API Key 可以设置在 CC Switch 中Codex 端只需要随便填一个环境变量占位即可。关键点是Codex 和 CC Switch 之间必须能够建立本地连接。5. 实战让 Codex 完成一个小任务5.1 初始化项目先新建一个测试目录mkdir codex-demo cd codex-demo git init创建一个空的 README 文件方便 Codex 理解项目上下文echo # Codex Demo README.md5.2 使用交互模式在项目目录下直接运行codex进入交互会话后输入如下命令创建两个文件main.py 和 utils.py。main.py 从命令行接收一个数字 n调用 utils.py 中的 fibonacci 函数打印斐波那契数列前 n 项。Codex 会读取项目结构编写代码并显示变更内容。如果你同意它会直接写入文件。5.3 使用非交互模式如果你希望用一条命令完成任务可以使用非交互方式codex exec 在 main.py 中实现一个判断素数的函数并输出测试示例Codex 会在执行后返回结果。这种方式适合在自动化脚本中调用。5.4 让 Codex 审查代码当 Codex 生成代码后可以继续让它检查请检查 utils.py 是否有边界问题并给出优化建议。Codex 会读取文件内容输出可执行建议。如果它发现 bug也可以直接让它修改。5.5 预期输出说明不同模型、不同服务商对同一段自然语言的理解可能存在差异最终生成的代码不会完全一样。只要文件内容符合任务要求就说明 Codex 工作流已经打通。如果遇到响应超时、模型不支持、API Key 鉴权失败等情况优先参考第 6 章的排查清单。6. 常见问题与排查思路6.1 常见报错速查表问题现象常见原因解决思路codex: command not foundnpm 全局安装路径不在 PATH 中重新安装检查 npm 全局路径并加入 PATHmodel not found模型名称与服务商实际支持不一致去服务商文档确认模型名Unauthorized/401API Key 错误或环境变量未生效检查 env_key 和 API Key 是否正确请求一直超时网络不通或 Base URL 错误确认 Base URL查看服务商状态页本地端点处理请求失败CC Switch 未启动、端口占用或配置不符确认 CC Switch 状态检查 base_url 端口local endpoint failed本地与管理工具之间请求格式不兼容升级 CC Switch检查模型名和 API KeyPython 代码未生成Codex 对任务理解偏差或服务商模型限制细化任务描述换更合适的模型6.2 CC Switch 本地服务问题很多人在配置 CC Switch 后Codex 请求本地端点时报错。根据经验常见原因有三个CC Switch 没有真正启动服务只打开了桌面窗口。Codex 配置中的base_url端口和 CC Switch 实际监听端口不一致。请求的模型名称没有被 CC Switch 映射到后端服务。排查顺序建议为先确认 CC Switch 服务状态再检查配置文件最后测试模型名是否可在服务商后台调用。6.3 环境变量无效问题在 Windows 上如果你在终端里设置了环境变量但 Codex 是在另一个终端窗口启动的它读取不到当前设置。建议把 API Key 写入系统环境变量或者统一放到.env文件并由启动脚本导出。在 Linux/macOS 上可以把导出命令加到~/.bashrc或~/.zshrcexport DEEPSEEK_API_KEYsk-xxxx修改后执行source ~/.bashrc再启动 Codex环境变量就能生效了。6.4 配置文件格式错误config.toml对格式比较敏感。常见错误包括缺少逗号。字符串中文引号混入。env_key名称和实际环境变量不一致。多个model_providers数据表没有用列表格式。修改后可以先运行不起动 Codex用codex --help或直接运行codex看是否报配置错误。配置文件里不要包含多余空行和注释符号问题但常规注释是允许的。7. 最佳实践与工程建议7.1 API Key 安全不要将 API Key 写入config.toml更不要提交到 Git 仓库。推荐使用环境变量或密钥管理工具。即使只是本地开发也要养成最小权限原则给 API Key 设置可用额度上限。如果怀疑 Key 泄露第一时间到服务商控制台吊销并重新生成。团队协作时建议每个成员使用自己的 Key方便追踪用量。7.2 版本锁定与升级Codex CLI 更新速度比较快新版本可能改变参数、配置格式或交互方式。建议在项目中使用稳定的 CLI 版本升级前先阅读 changelog。如果你在团队中推广 Codex可以把配置文件和常用命令整理成文档包含版本号、模型提供方和常见故障说明这样新人上手会轻松很多。7.3 模型选择策略不是所有任务都适合用同一个模型。日常小任务可以选响应更快的模型代码生成复杂任务可以选能力更强的模型。通过模型提供方配置你可以在 Codex 中快速切换不同服务商但也要注意不同模型对上下文长度和工具调用的支持不同。如果遇到“当前模型不支持此操作”的提示替换成其他兼容模型再试是很常见的解法。7.4 与编辑器结合Codex CLI 适合终端流但很多人也喜欢在 VS Code 中使用 Codex 插件。插件的配置逻辑与 CLI 类似需要指定 API 地址和模型名称。建议先在 CLI 中验证完整流程再去配置编辑器插件这样排错时能隔离问题。7.5 注意数据安全Codex 会读取工作目录内的文件并发送给模型服务商。对于包含敏感信息的仓库建议不要直接使用第三方模型或者先在干净分支上测试。生产环境代码的提交、修改和执行命令仍然需要人工 reviewAI 工具只能辅助不能完全替代人类的工程判断。7.6 从一个小任务开始不要第一次使用就要求 Codex 生成整个微服务项目。建议从一个函数、一个脚本、一个单元测试开始逐步熟悉它的工作节奏和输出风格。当你清楚它在哪些场景下可靠、哪些场景下需要人工介入才能真正把 Codex 变成日常开发的高效助手。配置完成后先打开终端给 Codex 一个最简单的任务让它生成hello.py并运行。看到输出结果的那一刻你已经完成了从安装到接入的完整闭环。后续无论是接入更多模型还是让 Codex 参与代码审查都可以在这套基础上继续扩展。希望这份教程能帮你少踩一些坑把时间花在真正有价值的代码上。