Codex接入GLM-5.3全流程：config.toml配置与Codex++工具实战

先说说我为什么折腾这事吧。Codex 这工具本身挺好用尤其是它的命令行交互和自动改代码的能力写点脚本、重构逻辑、补测试都很顺手。但我手上的账号在某些环境里访问官方模型总是不太稳定而 GLM-5.3 这代模型的代码能力和上下文长度又确实能打尤其是 GLM-5.3-flash 那个性价比简直是为高频调用量身定做的。问题就卡在怎么把这两者接起来。官方文档只给了 OpenAI 自家模型的配置方式第三方模型接入得自己拼 config.toml网上资料又零散踩坑踩得脑壳疼。这篇文章就把我折腾出来的全流程整理一遍重点讲 config.toml 怎么改、Codex 这个工具怎么用以及那些你十有八九会碰到的报错怎么解。想省事的照着走一遍基本十分钟能搞定。1. 为什么要把 GLM-5.3 接进 Codex1.1 Codex 到底是什么Codex 是 OpenAI 出的一个命令行 AI 编程助手本质是一个基于对话的 Agent你给它一个任务它会在你的项目目录里自主地读文件、写代码、执行命令、看报错、再改代码直到任务完成为止。它和我们常用的那种复制粘贴代码进聊天框完全不一样它真的长在你的终端里直接操作你的仓库。它的配置核心是config.toml这里面定义了模型、API 地址、权限、日志级别等参数。而~/.codex/auth.json则负责存 API Key。这两个文件是 Codex 的命门所有接入第三方模型的问题最后都会落在这两个文件上。1.2 GLM-5.3 和 GLM-5.3-flash 怎么选GLM-5.3 是智谱那边的新一代模型代码生成和逻辑推理能力提升明显尤其长上下文场景下表现很稳。GLM-5.3-flash 则是轻量版速度快、价格低适合日常的代码补全、简单重构、跑测试这些高频操作。我的建议是日常开发用 GLM-5.3-flash遇到复杂需求比如跨文件重构、新架构设计切到 GLM-5.3 完整版。两个模型在 Codex 里的接入方式完全一样只是model字段的值不同。这也意味着如果你希望一个 Codex 实例能随时切换模型你就需要一个方便的管理工具——这就是 Codex 出场的地方。1.3 接入方案选型为什么用 config.toml Codex先说结论我给的三套方案对比会直观一点方案优点缺点手动改 config.toml最底层完全可控切换模型要手动编辑文件麻烦用 cc-switch轻量社区常用不少人反馈切换后历史对话串会失效用 Codex有图形界面/CLI支持配置模板和快速切换需要额外安装多一个工具要学习我最终选的是config.toml Codex。原因很简单Codex 能帮你管理多套模型配置切换时直接改~/.codex/config.toml里的model字段同时还能备份和恢复历史配置。我之前用 cc-switch 踩过坑——切换模型 provider 之后历史对话直接没法打开报错信息是provider custom不存在之类的问题后来换成 Codex 之后再没出过这种状况。2. 动手前的准备基础环境搭建2.1 安装 Codex CLICodex 官方支持 macOS、Linux 和 WindowsWindows 上有桌面版和 CLI 两种形态。最省事的方式是用 npm 安装npm install -g openai/codex装完后验证一下codex --version如果你看到版本号输出说明 Codex CLI 已经就绪。这里有个小提示安装后最好先跑一次codex init或者随便执行一次codex exec hello让它生成默认的配置目录~/.codex/。很多新手直接去改 config.toml结果发现文件都不存在就是因为还没初始化过。Windows 用户如果不想折腾 npm可以直接下官方桌面版安装包装完会有图形界面。但我个人建议既然要走配置流CLI 版本反而更干脆因为桌面版很多配置选项被界面封住反而不如直接改 toml 灵活。2.2 Codex 是什么以及怎么安装Codex 是一个社区维护的 Codex 增强管理工具核心能力有三个提供可视化的模型供应商配置管理你不需要手写 JSON 或 toml支持把多套config.toml配置保存成模板随时一键切换内置常见大模型厂商的参数预设包括智谱 GLM、DeepSeek、通义等安装方式也简单以 macOS/Linux 为例# 使用 Homebrew 安装如果官方仓库里有 brew install codexpp # 或者使用 npm 全局安装社区版 npm install -g codex-pp安装完成后运行codex --version验证。如果一切正常你会看到类似于Codex v1.x.x的输出。这个工具不会覆盖你的~/.codex/目录它默认只是读取和写入同一套配置文件所以你完全可以放心地用。提示如果你在网络上搜索 Codex 发现有很多同名变体认准以下几个特征支持命令行、能配置第三方base_url、提供切换配置命令。凡是只能做聊天不能用 CLI 的大概率不是你要找的东西。2.3 获取 GLM API Key在智谱的开放平台注册一个账号创建 API Key。这一步需要说一下权限如果你是个人开发者创建一个普通 Key 就够了如果团队协作建议用团队 Key 并设置好额度上限防止某个同学把余额跑光。拿到 Key 之后记得它长这样xxxxxxxx.xxxxxxxx一串以点号分隔的字符串。把 Key 存好待会儿要写进auth.json。3. config.toml 核心配置逐行拆解3.1 配置文件的位置和整体结构Codex 的默认配置目录是~/.codex/核心文件就两个config.toml主配置模型、供应商、权限、日志全在这里auth.json认证信息存 API Key打开你的config.toml如果你之前初始化过里面应该会有一堆默认内容。第三方接入时你其实只需要关注几个关键字段其他的保持默认即可。一个典型的config.toml接入 GLM-5.3长这样model glm-5.3 model_provider zhipu [model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4 env_key ZHIPU_API_KEY [model_providers.zhipu.extra_body] extra_headers { x-request-id codex }这里有几个关键点model字段表示你要调用的模型名称。GLM-5.3 就填glm-5.3flash 版就填glm-5.3-flash。model_provider字段表示你走哪个供应商配置对应下方[model_providers.zhipu]这段的键名。base_url是关键中的关键。Codex 是 OpenAI 协议客户端它默认请求https://api.openai.com/v1你改成智谱的兼容地址它就会把请求发到智谱那边去。env_key表示从环境变量里读取 API Key。你也可以不设env_key而是在auth.json里直接写 Key两种方式我会在 3.4 节详细讲。3.2 model_provider 配置的细节很多人在[model_providers]这一段上摔跟头因为网上教程五花八门什么[model_providers.zhipu]、[model_providers.glm]、[model_providers.custom]都有。其实这个括号里的名字是你自定义的关键是后续model_provider 这里要和它一致。更规范的写法是给它加一个wire_api字段告诉 Codex 用哪种 API 协议。智谱的开放接口兼容 OpenAI 格式所以写成[model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4 wire_api chat env_key ZHIPU_API_KEYwire_api支持chat和responses两种。默认 Codex 官方模型用的是responses也就是新版的 Responses API但第三方厂商大多兼容的是chatChat Completions API。如果你的请求一直报 404 或者 model not found先检查这里是不是填的chat。3.3 model 字段和 model_reasoning_effortmodel字段决定具体跑哪个模型。GLM-5.3 和 GLM-5.3-flash 都可以用但注意Codex 的某些功能比如内置的系统提示词可能会要求模型具备特定的工具调用能力。GLM-5.3 是支持工具调用function calling的所以接进去后读写文件、执行命令这些动作都能正常用。如果你用的是 GLM-5.3-flash还想调一下模型的思考深度可以加一行model_reasoning_effort medium可选的值为minimal、low、medium、high。我的实测经验是日常改 bug 用low或medium就够只有在写核心架构时才需要high因为high的响应时间明显变长token 消耗也更大。3.4 auth.jsonAPI Key 放哪里有两个地方可以放 API Key方式一环境变量推荐在.bashrc、.zshrc或 Windows 的环境变量里设置export ZHIPU_API_KEY你的智谱API Key然后在config.toml的 provider 配置里写env_key ZHIPU_API_KEY。这样 Key 不会明文出现在 Codex 的配置文件里安全性更好。方式二auth.json打开~/.codex/auth.json初始内容可能是{ OPENAI_API_KEY: sk-xxx }你需要改成{ OPENAI_API_KEY: 你的智谱API Key, ZHIPU_API_KEY: 你的智谱API Key }这里有个坑Codex 读取 key 时会先看config.toml里的env_key如果环境变量不存在再去看auth.json。如果你两个地方都填了Codex 会优先用环境变量里的值。所以遇到明明改了 auth.json 怎么还是老 Key这类问题时先去检查环境变量是不是还留着旧值。4. 实操过程用 Codex 完成一键接入4.1 Codex 图形化配置最快路径如果你装了 Codex最直接的方式是启动它的管理界面codex ui界面里会有模型供应商管理入口点进去新增一个供应商供应商名称填zhipu或任意名字Base URL填https://open.bigmodel.cn/api/paas/v4API Key粘贴你在智谱平台拿到的 Key默认模型填glm-5.3或glm-5.3-flash协议类型选Chat Completionschat保存之后它会自动帮你把内容写入~/.codex/config.toml和~/.codex/auth.json。这一步做完理论上就已经接好了。然后你在终端里执行codex exec 写一个 Python 脚本计算斐波那契数列前20项如果看到 Codex 正常调用、正常返回结果说明对接成功。4.2 命令行配置脚本化/无界面环境图形界面不是什么时候都有服务器上通常只有命令行。Codex 也提供了 CLI 方式codex provider add zhipu \ --base-url https://open.bigmodel.cn/api/paas/v4 \ --api-key 你的智谱API Key \ --model glm-5.3执行后Codex 会做三件事在config.toml里追加[model_providers.zhipu]配置把model和model_provider字段更新为 GLM 相关的值在auth.json里写入对应的 API Key你也可以随时切换模型# 切换到 GLM-5.3 完整版 codex use zhipu/glm-5.3 # 切换到 GLM-5.3-flash codex use zhipu/glm-5.3-flash这个命令的本质就是修改config.toml里的model字段顺手把model_provider也切到对应供应商。好处是你不用手动打开文件编辑也不怕改错格式——Codex 会做一次校验如果 toml 语法有问题它会报错并回滚。4.3 手动改配置文件如果你想完全掌控虽然用 Codex 很方便但我还是建议每个人都学会手动改一遍config.toml因为你总有一天要折腾不在 Codex 预设列表里的奇怪配置。打开~/.codex/config.toml做三件事第一步确认文件顶部有model和model_provider两个字段model glm-5.3-flash model_provider zhipu第二步在文件末尾添加 provider 配置[model_providers.zhipu] name Zhipu GLM base_url https://open.bigmodel.cn/api/paas/v4 wire_api chat env_key ZHIPU_API_KEY第三步确保auth.json里有对应的 Key。如果走环境变量记得source ~/.zshrc让新变量生效。然后执行codex exec 11等于几理论上你会在终端里看到模型它自己想了一会儿然后给出答案。如果这里能通后面就都是顺水推舟。4.4 配置完成的验证方法要说我真的接好了只看一次成功返回还不够。我的完整验证清单是这样的用codex exec 在当前目录创建 test.py内容为 print(hello)然后执行它观察 Codex 是否真的能创建文件并执行。打开项目的.codex/目录如果有的话确认 Codex 是否正确记录了对话历史。用codex --debug跑一条简单命令检查日志里请求的base_url是不是指向智谱地址。这一步很关键能直接看出是不是还在走默认的 OpenAI 地址。5. 高频报错与排障实录5.1 cc-switch 切换后历史对话打不开、报 providercustom不存在这个问题在社区里很常见。典型报错chatgpt cant load config.toml, so this thread cant resume. fix config.toml: model provider custom not found为什么会出这个问题因为 cc-switch 这类工具在切换供应商时会在config.toml里生成model_provider custom然后在[model_providers.custom]下写一堆配置。但当你切走再切回来时它有时没把[model_providers.custom]整段恢复完整导致 Codex 加载配置文件时找不到对应的 provider。解决办法有两个第一直接编辑config.toml把model_provider改成你自己的供应商名字比如zhipu并确保下面有对应的[model_providers.zhipu]配置。第二用 Codex 重建配置。执行codex provider fix它会自动扫描config.toml里所有 provider 定义缺失的问题并尝试用默认模板补齐。注意不要轻易删除历史对话目录。Codex 的历史会话存在~/.codex/sessions/下删了就真的没了。遇到打不开的情况先改配置再重启 Codex90% 都能恢复。5.2 model not supported 报错报错长这样the gpt-5.6-sol model is not supported when using codex with a chatgpt account或者model glm-5.3 does not exist这有两种情况。情况一你还在用 ChatGPT 账号的登录态跑 Codex。Codex 默认走 ChatGPT 账号体系时只允许官方模型第三方模型一律不给用。解决方法是走 API Key 模式也就是在auth.json里填第三方 API Key而不是用codex login登录。如果你是先登录了 ChatGPT 再想接 GLM建议先codex logout清理登录态再改配置。情况二model字段的模型名填错了。不同平台对模型名的写法有差异。智谱平台在 OpenAI 兼容接口里通常直接用glm-5.3或glm-5.3-flash。但如果你是通过某些中转服务可能要加版本后缀比如glm-5.3-250828假设有这种日期版本。正确做法是去智谱开放平台的文档或控制台确认当前可用的模型 ID。5.3 config.toml 加载失败Codex 根本起不来报错一般是error loading config: parse error这种 90% 是 toml 语法问题。最常见的原因有两个第一个字符串没加引号。base_url的地址必须用双引号包起来name字段同理。第二个provider 配置写在了错误的层级。有些新手把[model_providers.zhipu]写在了别的地方导致缩进和层级不对。TOML 对段落归属要求很严格一旦嵌套错了就解析失败。我的建议是拿不准的时候就备份原文件然后重新写一份最小化配置model glm-5.3 model_provider zhipu [model_providers.zhipu] name Zhipu base_url https://open.bigmodel.cn/api/paas/v4 wire_api chat先让 Codex 跑起来再逐步加其他配置。5.4 请求超时或连接失败报错可能是connection refused、timeout、proxy error等。这里有几个排查方向第一步确认base_url是否可达。智谱的接口地址通常支持浏览器直接访问你可以在浏览器打开https://open.bigmodel.cn/api/paas/v4/models如果能看到返回信息说明接口正常。第二步检查本地代理。Codex 会读取系统的 HTTP_PROXY/HTTPS_PROXY 环境变量。如果你之前设置过代理而又不想走代理访问可以在运行 Codex 时清掉env -u HTTP_PROXY -u HTTPS_PROXY codex exec test第三步看日志。用codex --debug跑一次它能打印每次请求的 URL、状态码和响应正文报错原因一目了然。注意这里提到的代理是正常的网络调试手段比如公司内网代理、本地调试代理请确认你的使用场景符合当地法规和平台规则。我不展开任何涉及绕过网络限制的内容。5.5 Codex 相关的小坑用 Codex 的时候我遇到过两个问题第一个Codex 写入 auth.json 时覆盖了原有内容。如果你同时用多个模型的 API Key建议先手动备份auth.json。Codex 的新版本有合并逻辑但旧版本是直接覆写。第二个Codex 的配置模板和你的项目级配置冲突。Codex 支持在项目目录下放一个.codex/config.toml如果项目级配置存在它会覆盖~/.codex/config.toml里的同级选项。也就是说你在全局配置里接了 GLM但某个项目里又有单独的配置跑起来可能还是用的项目配置。遇到这种情况优先看项目目录下有没有.codex/目录。6. 把思路再往外扩一扩接完 GLM-5.3 之后Codex 的玩法其实还能再翻出不少花样。我就顺着这段时间折腾的经验分享几个我觉得最实用的方向。第一多模型并存。config.toml支持配置多个model_providers你完全可以在同一份配置里同时写上智谱、DeepSeek、还有 OpenAI 官方。日常用 Codex 直接切换哪个便宜用哪个哪个跑不通用哪个。这不是花活而是实打实省成本的手段。我自己的习惯是写业务代码时用 GLM-5.3-flash快、省做代码评审和重构时切 GLM-5.3稳、准偶尔用其他模型做交叉验证。切换只需要一条命令成本几乎为零。第二善用 Codex 的--sandbox和--dangerously-bypass-approvals-and-sandbox参数。默认情况下 Codex 每次执行命令都要你确认很烦。但直接在沙箱模式里跑又容易误操作因为 AI 可能会执行你没有仔细看的命令。我的折中方案是默认保持确认模式只在跑测试、格式化、静态检查这种低风险操作时临时加一个--sandbox让它自动执行。这个思路和模型接入无关但对 Codex 的实际体验提升巨大。第三定期清理 session 文件。Codex 的会话历史文件会越积越多占磁盘空间是小事关键是会话多了之后codex启动时加载列表会变慢。我一般每个月清理一次只保留最近一周的会话find ~/.codex/sessions -type f -mtime 7 -delete这个命令在 macOS 和 Linux 上都能跑Windows 用户可以在 PowerShell 里用对应的Get-ChildItem | Where-Object LastWriteTime逻辑。第四把 Codex 的配置模板纳入版本管理。我在自己的 dotfiles 仓库里维护了一份.codex/config.toml模板换新机器时直接用codex import config.toml导进来再填一下各家的 API Key 就完事。不用每次花十分钟重新敲配置。7. 踩过坑之后的几条实在经验最后聊几个我自己的习惯谈不上标准答案但至少能让你少走弯路。第一改配置之前永远先备份。无论是config.toml还是auth.json改动之前先复制一份带日期后缀的备份文件。别嫌麻烦我因为 cc-switch 的坑写过一次整个配置从那以后这个备份习惯再没断过。第二不要用记事本改 config.toml。Windows 用户尤其注意记事本保存的文件默认是带 BOM 的 UTF-8TOML 解析器碰上 BOM 头就容易报错。推荐用 VS Code 或者直接vim/nano改。第三环境变量的优先级经常坑人。如果你的config.toml里写了env_key ZHIPU_API_KEY那么即使你在auth.json里填了新 KeyCodex 也只会读环境变量的值。很多你已经改了 Key 但还在报认证失败的人先排查环境变量别盯着 auth.json 死磕。第四尽量用最新版 Codex。老版本的 Codex 对自定义 provider 的支持不够完善有些 API 字段比如wire_api是后加的。如果你用的版本过老可能不支持chat协议的某些行为。定期npm update -g openai/codex是个好习惯。这次把 GLM-5.3 接入 Codex 的过程说到底就是搞清楚三个文件的关系config.toml告诉 Codex 去哪找模型auth.json告诉它你是谁Codex 则是帮你管理这两个文件的遥控器。把这三者的关系理顺之后后面再接任何新模型都是复制粘贴的事。