最近好多人在问“Codex怎么设置中文”尤其是从 VSCode、Cursor 生态转过来的朋友装上 Codex 之后第一反应就是界面全是英文模型回复默认也是英文终端里中文还老显示成方块好不容易跑起来又给你来一句cc switch local proxy failed while handling codex endpoint /responses。这篇文章就把“Codex 中文设置”这件事从界面、模型回复、终端显示到报错排查整个流程掰开揉碎讲一遍国内用户照着做就行。先明确一个核心认知Codex 的“中文设置”不是一个开关能搞定的它涉及四个层面——界面语言、模型回复语言、终端显示环境、以及国内环境下常见的端点配置问题。很多人折腾半天没弄好就是因为只盯着界面语言忽略了后面三件事。1. 先搞清楚你的 Codex 是哪个形态再谈后续设置1.1 Codex 常见的三种使用形态Codex 现在有好几种用法不同形态对应的中文设置方法完全不一样第一步就是先分清你用的是哪种。第一种是CLI 命令行版通过npm install -g openai/codex或者brew install codex安装平时在终端里输入codex进入交互式对话或者用codex 你的问题直接问。这是最接近“命令行 AI 助手”的形态也是目前国内开发者用得最多的一种。第二种是桌面版 App官方推出的独立客户端Windows、macOS 都有安装包界面是图形化窗口操作逻辑类似 ChatGPT 客户端只是把对话场景换成了编码场景。第三种是网页版直接通过浏览器访问使用不需要安装任何东西适合临时体验。三种形态的中文设置难度从低到高排列网页版最简单在浏览器翻译插件或者对话指令里解决桌面版次之CLI 版最复杂——因为它牵涉终端编码、字体、配置文件等多个环节。1.2 为什么安装版本不同设置入口完全不同原因很简单CLI 版没有传统意义上的“设置界面”所有行为靠配置文件控制桌面版虽然有图形界面但官方目前没有提供完整的中文界面语言包网页版则受限于浏览器环境。所以你在网上搜“Codex 中文设置”会看到各种互相矛盾的答案——有人告诉你改AGENTS.md有人告诉你在终端里设置字体还有人让你改配置文件。其实他们说的都对只是针对的形态不同。我的建议是先运行codex --version确认版本再看自己在哪个界面里用。如果你用的是桌面版优先考虑对话指令和项目规则文件方案如果你用的是 CLI那终端环境的准备工作是绕不开的。2. 界面层面的中文设置三个形态分别该怎么处理2.1 VSCode 内嵌 Codex 扩展的中文化思路很多人在 VSCode 里装 Codex 插件结果发现插件面板的按钮、提示全是英文。这里有个容易混淆的点VSCode 本身可以通过安装“Chinese (Simplified) (简体中文) Language Pack”扩展来汉化但 Codex 插件面板内部是独立渲染的不一定会跟随 VSCode 的语言切换。实测下来的经验是Codex 插件的大部分文字跟随系统语言但少数按钮和错误提示仍然是英文。对于这种情况没有“一键汉化”的官方方案我的做法是记住几个高频按钮的含义其余靠上下文推断。本质上Codex 是编码助手不是界面软件把界面汉化的收益其实很低——真正影响效率的是它回复你的语言。真正值得花时间的是让 Codex 的输出语言变成中文这属于模型回复层面的设置我在第 3 节会详细讲。2.2 桌面版 App 的中文界面思路桌面版 Codex 目前没有官方的中文界面切换选项这点和很多 AI 编程工具一样。想用中文界面目前只有两个变通思路第一个是借助系统层面的全局翻译工具。Windows 上可以给应用窗口开翻译macOS 上可以用系统自带的一些辅助功能但这类工具对动态渲染的界面效果一般经常出现“翻译了半边”的情况体验不稳定。第二个思路是干脆不做界面汉化把精力放在让回复变成中文上。如果你只是为了看懂操作桌面版的操作路径其实不长常用的就是新建会话、输入指令、查看 diff、接受或拒绝改动这几个动作记住了英文界面影响不大。个人建议不要为了界面汉化去装来路不明的汉化补丁或修改版安装包。Codex 需要登录自己的账号第三方修改版存在凭证泄露风险没必要让界面汉化的问题变成一个安全隐患。2.3 CLI 终端环境的中文字体与编码准备CLI 版要显示中文第一个坑就是字体。终端默认的等宽字体如果不支持中文字形中文就会显示成方框或者乱码。Windows 上推荐使用 Windows Terminal 中文字体组合。字体方面实测比较靠谱的是“Sarasa Mono SC”更纱黑体、“微软雅黑 JetBrains Mono”之类的混合字体或者直接选择字体设置里的“Microsoft YaHei Mono”。在 Windows Terminal 的设置界面里把字体改成上述字体之一中文基本就能正常显示。macOS 上终端默认的 Menlo 字体在中文显示上表现一般建议在 Terminal 偏好设置里把字体换成“Sarasa Mono SC”或者“PingFang SC”。Linux 上比如各种云服务器需要确认系统里有没有中文字体没有的话执行sudo apt install fonts-noto-cjk安装 Noto 中文字体然后在终端的配置文件里指定这个字体。编码问题通常是另一个坑。Windows 下老版 CMD 的代码页导致中文乱码解决办法是把系统区域设置里的“Beta 版使用 Unicode UTF-8 提供全球语言支持”勾上或者改用 Windows Terminal。Linux 下检查echo $LANG确保是zh_CN.UTF-8而不是C。3. 让 Codex 说中文的核心配置AGENTS.md config.toml3.1 项目级规则文件 AGENTS.md 的正确用法Codex CLI 和桌面版都会自动读取当前项目目录下的AGENTS.md文件把它作为项目级指令注入到每次对话的上下文里。这个文件是官方支持的约定作用就是告诉模型“在这个项目里你要遵守什么规则”。所以想让 Codex 用中文回复最简单有效的方法就是新建一个AGENTS.md文件内容写成这样# 项目规则 - 无论用户使用什么语言提问一律使用简体中文回复。 - 代码注释和 Git 提交信息使用中文。 - 生成的文档、说明性文字使用中文。 - 代码逻辑命名保持英文但解释性文本必须中文。这个文件放在项目根目录即可Codex 启动时会自动识别并加载。它的优先级很高相当于每次对话都附加了一段系统指令比你在对话里反复强调“请说中文”要可靠得多。如果你的多个项目都希望 Codex 说中文可以考虑在用户主目录下创建全局的AGENTS.md这样所有项目都会继承这个规则。全局文件的位置一般是~/.codex/AGENTS.md没有就手动创建。3.2 全局配置文件 config.toml 的 instructions 字段除了 AGENTS.mdCodex CLI 还有一个全局配置文件~/.codex/config.toml里面的instructions字段专门用来添加全局指令。这个字段的优先级低于项目级 AGENTS.md 还是高于它实测中主要看模型自己怎么理解但从“双保险”的角度考虑两个地方都写上没问题。一个参考配置# ~/.codex/config.toml model gpt-5.6-sol model_provider openai instructions [ 你必须始终使用简体中文回复用户。, 回答尽量简洁先给结论再给详细说明。, 代码示例中的注释使用中文。, ]这里面的model和model_provider按你的实际情况写instructions数组里的每条指令都会被加到系统提示中。设置完成后重启 Codex让配置生效。另一个常用的指令是把回复风格也一并定下来。比如要求“问题拆解清晰”“步骤编号”等这样每次对话不用重新交代背景Codex 的输出质量会稳定很多。3.3 对话内指令与使用习惯的补充配置文件负责“长期生效”但有些场景需要在对话里单独指定。比如你只希望当前这次会话用中文回复不想改任何配置直接在输入时加一句“本次会话全程使用简体中文回复代码注释也用中文”也能达到效果。个人经验是只写“请用中文回复”太模糊模型有时候照样在关键地方蹦英文。更有效的说法是“所有面向用户的文本输出必须使用简体中文包括解释、总结、报错分析、注释和提交信息”。把“所有面向用户的文本”这个范围框出来模型的理解会更准确。还有个细节如果你让 Codex 生成代码代码本身的标识符变量名、函数名要保持英文但注释和文档类输出用中文。这个混合策略能保证代码可维护性又满足中文阅读需求。实测中直接把“标识符用英文注释和输出用中文”写进 AGENTS.md效果很稳定。4. 国内用户高频踩坑端点切换工具报错和模型名不匹配4.1 “cc switch local proxy failed while handling codex endpoint /responses” 到底是什么问题这个词条在热搜里出现频率非常高很多配了本地端点切换工具的人都会遇到。先说结论这个报错并不是 Codex 本身的问题而是切换工具没把本地转发服务正确启动起来导致 Codex 在请求/responses接口时连不上本地端点。这类切换工具的作用是在多个 API 配置之间切换。它一般会修改~/.codex/config.toml和~/.codex/auth.json同时通过本地端口做转发。报错里的local proxy指的就是这个本地转发服务。常见的触发原因有三个第一个是端口被占用。切换工具默认监听的端口如果被其他程序占用转发服务起不来后面所有请求都会失败。排查方法是在命令行里查端口占用情况找到对应进程后关掉它再重新启动切换工具。第二个是配置文件被写坏了。切换工具在切换配置时如果中途退出、断电或者手动编辑了配置文件导致 JSON 或 TOML 格式错误Codex 启动时会加载不了配置。排查思路是把这个工具的配置重置或者手动检查~/.codex/config.toml的语法。第三个是切换工具版本与 Codex 版本不兼容。Codex 更新频率比较快接口也经常变老版本的切换工具生成的配置可能已经过期。这种情况只能升级切换工具或者放弃切换工具手动改config.toml恢复官方配置。4.2 “model is not supported” 的修正方法另一种高频报错长这样the gpt-5.6-sol model is not supported when using codex with a...。前半段可能因人而异但核心逻辑是一致的你在配置里指定的模型名在对应服务商或本地服务上不存在。这个问题的根源在于 Codex 的model字段和model_provider是解耦的。你把model_provider指向第三方兼容端点但model字段仍然填的是官方模型名第三方服务又根本不提供这个模型自然报错。解决办法就是进入config.toml把model改成目标服务实际支持的模型标识。比如某个纯文本对话服务支持的是deepseek-chat那配置就应该是model deepseek-chat model_provider openai-compatible这个案例在社区里很常见很多人照着网上的教程把model_provider改成第三方服务后忘了同步改model字段结果一直报错。记住换 provider 和换 model 是两件事必须一起改。另外要注意wire_api的差异。Codex 默认走的是 Responses API而很多兼容服务只提供 Chat Completions API。以接入某些 OpenAI 兼容服务为例config.toml里需要把wire_api设置对否则请求格式不匹配也会报错。4.3 自定义 provider 的完整配置参考分享一个实际可用的自定义 provider 配置结构方便你对照排查model deepseek-chat model_provider custom [model_providers.custom] name Custom Provider base_url https://api.example.com/v1 env_key CUSTOM_API_KEY wire_api chat对应地在 shell 配置文件比如.bashrc或.zshrc里设置好环境变量export CUSTOM_API_KEY你的密钥设置完成后在终端里运行codex启动用一句“你好请用中文回复”测试链路是否通了。如果仍然报错先看base_url是否正确拼接到了/v1层再看wire_api是否匹配最后确认环境变量是否被正确加载。从个人经验看这类报错 90% 是配置细节问题不是 Codex 本身有故障。我建议排查时用codex --verbose模式启动或者直接查看切换工具生成的配置文件通常一眼就能发现问题。5. 登录与认证问题的排查auth token 不可用、桌面版打不开5.1 “auth token is unavailable” 的常见原因与处理报错codex auth token is unavailable意味着 Codex 在读取登录凭证时失败了。国内用户遇到这个报错优先从三个方向排查。第一登录状态失效。运行codex login重新登录一次它会重新走一遍认证流程。如果登录过程一直没有完成检查终端里是否弹出了需要确认的链接以及浏览器是否正常打开了授权页面。第二认证文件缺失或损坏。Codex 的登录凭证默认存在~/.codex/auth.json如果这个文件被手动物理删除了或者因为切换工具改写导致内容不完整就会出现“凭证不可用”的提示。备份好现有配置后删除auth.json重新执行codex login让工具重新生成凭证文件。第三系统时间错误。这个原因非常隐蔽却是我实际遇到过的。系统时间与真实时间偏差太多时认证请求的签名校验会失败表现为反复登录不成功或者拿到 token 后被立刻判定无效。排查方法很简单看系统时间的秒数是否与现实时间一致差几分钟以上就需要校准时间。5.2 桌面版安装失败或者打不开的应急处理Windows 桌面版安装卡在“正在安装”是常见问题。先检查磁盘空间是否充足很多时候装到一半卡住是因为磁盘写不进去了。其次检查杀毒软件有没有拦截安装程序可以把安装目录加入信任列表然后重新运行安装包。如果安装完成后 Codex 打不开表现为点击图标没反应可以尝试清理旧版本残留配置再启动。Windows 下一般是%LocalAppData%\Programs\codex目录里的文件冲突macOS 下则是/Applications/Codex.app的权限问题右键选择“打开”绕过系统限制。5.3 终端环境下的登录状态管理经验多套配置切换时登录状态的管理很容易乱。有些切换工具会同时改写auth.json导致你切回官方账号后发现凭证也不可用。我的习惯是用固定的命名规则管理多份凭证文件切换时手动备份和恢复而不是完全依赖工具。具体来说我会把正常可用的auth.json备份成auth.json.official.bak和auth.json.custom.bak每次切换就手动替换文件。这样做虽然原始但可控性最高很少再出现“凭证被覆盖但说不清为什么”的问题。6. 常见问题速查表与我的实操心得6.1 Codex 中文设置与报错排查速查表现象核心原因解决方向终端里中文显示成方块终端字体不支持中文换 Sarasa Mono SC / Noto CJK 字体终端里中文显示成乱码编码不是 UTF-8Windows 开 UTF-8 选项Linux 设 LANGCodex 回复全是英文缺少语言指令写 AGENTS.md / config.toml 的 instructions切换工具报 local proxy failed端口占用或配置损坏查端口占用重置切换工具配置报 model is not supportedmodel 和 provider 不匹配修改 model 为服务商实际支持的模型报 auth token is unavailable凭证文件损坏或失效重新 codex login重置 auth.json桌面版安装卡住磁盘空间不足或杀毒拦截清理磁盘加白名单重装Codex 桌面版打不开安装残留或权限问题清理旧版本macOS 右键打开6.2 我在实际配置过程中的几点体会Codex 的中文设置折腾过一遍之后我的体会是三层渐进第一层是界面语言这个最不重要能看懂常用的几个按钮就行第二层是回复语言这个最重要直接决定使用体验通过 AGENTS.md 和 instructions 就能很好解决第三层是终端环境属于“基础不牢地动山摇”的类型字体和编码问题不解决中文显示永远有问题。另外一个小技巧配置完成后先用“请总结一下你现在需要遵守的规则。”这句话来验证。如果 Codex 能准确说出“需要用中文回复、注释用中文”这些规则说明你的配置文件加载成功了如果它答不上来那配置文件大概率没生效回去检查路径和格式。最后再提醒一句Codex 更新很快每次升级后最好重新看一下codex --version确认配置文件和新版本仍然兼容。毕竟这类工具的中文设置从来不是一劳永逸的事但只要掌握了排查的底层逻辑无论以后怎么更新你都能快速找到对应的解决方案。
Codex中文设置指南：界面、回复、终端与报错排查全解析
最近好多人在问“Codex怎么设置中文”尤其是从 VSCode、Cursor 生态转过来的朋友装上 Codex 之后第一反应就是界面全是英文模型回复默认也是英文终端里中文还老显示成方块好不容易跑起来又给你来一句cc switch local proxy failed while handling codex endpoint /responses。这篇文章就把“Codex 中文设置”这件事从界面、模型回复、终端显示到报错排查整个流程掰开揉碎讲一遍国内用户照着做就行。先明确一个核心认知Codex 的“中文设置”不是一个开关能搞定的它涉及四个层面——界面语言、模型回复语言、终端显示环境、以及国内环境下常见的端点配置问题。很多人折腾半天没弄好就是因为只盯着界面语言忽略了后面三件事。1. 先搞清楚你的 Codex 是哪个形态再谈后续设置1.1 Codex 常见的三种使用形态Codex 现在有好几种用法不同形态对应的中文设置方法完全不一样第一步就是先分清你用的是哪种。第一种是CLI 命令行版通过npm install -g openai/codex或者brew install codex安装平时在终端里输入codex进入交互式对话或者用codex 你的问题直接问。这是最接近“命令行 AI 助手”的形态也是目前国内开发者用得最多的一种。第二种是桌面版 App官方推出的独立客户端Windows、macOS 都有安装包界面是图形化窗口操作逻辑类似 ChatGPT 客户端只是把对话场景换成了编码场景。第三种是网页版直接通过浏览器访问使用不需要安装任何东西适合临时体验。三种形态的中文设置难度从低到高排列网页版最简单在浏览器翻译插件或者对话指令里解决桌面版次之CLI 版最复杂——因为它牵涉终端编码、字体、配置文件等多个环节。1.2 为什么安装版本不同设置入口完全不同原因很简单CLI 版没有传统意义上的“设置界面”所有行为靠配置文件控制桌面版虽然有图形界面但官方目前没有提供完整的中文界面语言包网页版则受限于浏览器环境。所以你在网上搜“Codex 中文设置”会看到各种互相矛盾的答案——有人告诉你改AGENTS.md有人告诉你在终端里设置字体还有人让你改配置文件。其实他们说的都对只是针对的形态不同。我的建议是先运行codex --version确认版本再看自己在哪个界面里用。如果你用的是桌面版优先考虑对话指令和项目规则文件方案如果你用的是 CLI那终端环境的准备工作是绕不开的。2. 界面层面的中文设置三个形态分别该怎么处理2.1 VSCode 内嵌 Codex 扩展的中文化思路很多人在 VSCode 里装 Codex 插件结果发现插件面板的按钮、提示全是英文。这里有个容易混淆的点VSCode 本身可以通过安装“Chinese (Simplified) (简体中文) Language Pack”扩展来汉化但 Codex 插件面板内部是独立渲染的不一定会跟随 VSCode 的语言切换。实测下来的经验是Codex 插件的大部分文字跟随系统语言但少数按钮和错误提示仍然是英文。对于这种情况没有“一键汉化”的官方方案我的做法是记住几个高频按钮的含义其余靠上下文推断。本质上Codex 是编码助手不是界面软件把界面汉化的收益其实很低——真正影响效率的是它回复你的语言。真正值得花时间的是让 Codex 的输出语言变成中文这属于模型回复层面的设置我在第 3 节会详细讲。2.2 桌面版 App 的中文界面思路桌面版 Codex 目前没有官方的中文界面切换选项这点和很多 AI 编程工具一样。想用中文界面目前只有两个变通思路第一个是借助系统层面的全局翻译工具。Windows 上可以给应用窗口开翻译macOS 上可以用系统自带的一些辅助功能但这类工具对动态渲染的界面效果一般经常出现“翻译了半边”的情况体验不稳定。第二个思路是干脆不做界面汉化把精力放在让回复变成中文上。如果你只是为了看懂操作桌面版的操作路径其实不长常用的就是新建会话、输入指令、查看 diff、接受或拒绝改动这几个动作记住了英文界面影响不大。个人建议不要为了界面汉化去装来路不明的汉化补丁或修改版安装包。Codex 需要登录自己的账号第三方修改版存在凭证泄露风险没必要让界面汉化的问题变成一个安全隐患。2.3 CLI 终端环境的中文字体与编码准备CLI 版要显示中文第一个坑就是字体。终端默认的等宽字体如果不支持中文字形中文就会显示成方框或者乱码。Windows 上推荐使用 Windows Terminal 中文字体组合。字体方面实测比较靠谱的是“Sarasa Mono SC”更纱黑体、“微软雅黑 JetBrains Mono”之类的混合字体或者直接选择字体设置里的“Microsoft YaHei Mono”。在 Windows Terminal 的设置界面里把字体改成上述字体之一中文基本就能正常显示。macOS 上终端默认的 Menlo 字体在中文显示上表现一般建议在 Terminal 偏好设置里把字体换成“Sarasa Mono SC”或者“PingFang SC”。Linux 上比如各种云服务器需要确认系统里有没有中文字体没有的话执行sudo apt install fonts-noto-cjk安装 Noto 中文字体然后在终端的配置文件里指定这个字体。编码问题通常是另一个坑。Windows 下老版 CMD 的代码页导致中文乱码解决办法是把系统区域设置里的“Beta 版使用 Unicode UTF-8 提供全球语言支持”勾上或者改用 Windows Terminal。Linux 下检查echo $LANG确保是zh_CN.UTF-8而不是C。3. 让 Codex 说中文的核心配置AGENTS.md config.toml3.1 项目级规则文件 AGENTS.md 的正确用法Codex CLI 和桌面版都会自动读取当前项目目录下的AGENTS.md文件把它作为项目级指令注入到每次对话的上下文里。这个文件是官方支持的约定作用就是告诉模型“在这个项目里你要遵守什么规则”。所以想让 Codex 用中文回复最简单有效的方法就是新建一个AGENTS.md文件内容写成这样# 项目规则 - 无论用户使用什么语言提问一律使用简体中文回复。 - 代码注释和 Git 提交信息使用中文。 - 生成的文档、说明性文字使用中文。 - 代码逻辑命名保持英文但解释性文本必须中文。这个文件放在项目根目录即可Codex 启动时会自动识别并加载。它的优先级很高相当于每次对话都附加了一段系统指令比你在对话里反复强调“请说中文”要可靠得多。如果你的多个项目都希望 Codex 说中文可以考虑在用户主目录下创建全局的AGENTS.md这样所有项目都会继承这个规则。全局文件的位置一般是~/.codex/AGENTS.md没有就手动创建。3.2 全局配置文件 config.toml 的 instructions 字段除了 AGENTS.mdCodex CLI 还有一个全局配置文件~/.codex/config.toml里面的instructions字段专门用来添加全局指令。这个字段的优先级低于项目级 AGENTS.md 还是高于它实测中主要看模型自己怎么理解但从“双保险”的角度考虑两个地方都写上没问题。一个参考配置# ~/.codex/config.toml model gpt-5.6-sol model_provider openai instructions [ 你必须始终使用简体中文回复用户。, 回答尽量简洁先给结论再给详细说明。, 代码示例中的注释使用中文。, ]这里面的model和model_provider按你的实际情况写instructions数组里的每条指令都会被加到系统提示中。设置完成后重启 Codex让配置生效。另一个常用的指令是把回复风格也一并定下来。比如要求“问题拆解清晰”“步骤编号”等这样每次对话不用重新交代背景Codex 的输出质量会稳定很多。3.3 对话内指令与使用习惯的补充配置文件负责“长期生效”但有些场景需要在对话里单独指定。比如你只希望当前这次会话用中文回复不想改任何配置直接在输入时加一句“本次会话全程使用简体中文回复代码注释也用中文”也能达到效果。个人经验是只写“请用中文回复”太模糊模型有时候照样在关键地方蹦英文。更有效的说法是“所有面向用户的文本输出必须使用简体中文包括解释、总结、报错分析、注释和提交信息”。把“所有面向用户的文本”这个范围框出来模型的理解会更准确。还有个细节如果你让 Codex 生成代码代码本身的标识符变量名、函数名要保持英文但注释和文档类输出用中文。这个混合策略能保证代码可维护性又满足中文阅读需求。实测中直接把“标识符用英文注释和输出用中文”写进 AGENTS.md效果很稳定。4. 国内用户高频踩坑端点切换工具报错和模型名不匹配4.1 “cc switch local proxy failed while handling codex endpoint /responses” 到底是什么问题这个词条在热搜里出现频率非常高很多配了本地端点切换工具的人都会遇到。先说结论这个报错并不是 Codex 本身的问题而是切换工具没把本地转发服务正确启动起来导致 Codex 在请求/responses接口时连不上本地端点。这类切换工具的作用是在多个 API 配置之间切换。它一般会修改~/.codex/config.toml和~/.codex/auth.json同时通过本地端口做转发。报错里的local proxy指的就是这个本地转发服务。常见的触发原因有三个第一个是端口被占用。切换工具默认监听的端口如果被其他程序占用转发服务起不来后面所有请求都会失败。排查方法是在命令行里查端口占用情况找到对应进程后关掉它再重新启动切换工具。第二个是配置文件被写坏了。切换工具在切换配置时如果中途退出、断电或者手动编辑了配置文件导致 JSON 或 TOML 格式错误Codex 启动时会加载不了配置。排查思路是把这个工具的配置重置或者手动检查~/.codex/config.toml的语法。第三个是切换工具版本与 Codex 版本不兼容。Codex 更新频率比较快接口也经常变老版本的切换工具生成的配置可能已经过期。这种情况只能升级切换工具或者放弃切换工具手动改config.toml恢复官方配置。4.2 “model is not supported” 的修正方法另一种高频报错长这样the gpt-5.6-sol model is not supported when using codex with a...。前半段可能因人而异但核心逻辑是一致的你在配置里指定的模型名在对应服务商或本地服务上不存在。这个问题的根源在于 Codex 的model字段和model_provider是解耦的。你把model_provider指向第三方兼容端点但model字段仍然填的是官方模型名第三方服务又根本不提供这个模型自然报错。解决办法就是进入config.toml把model改成目标服务实际支持的模型标识。比如某个纯文本对话服务支持的是deepseek-chat那配置就应该是model deepseek-chat model_provider openai-compatible这个案例在社区里很常见很多人照着网上的教程把model_provider改成第三方服务后忘了同步改model字段结果一直报错。记住换 provider 和换 model 是两件事必须一起改。另外要注意wire_api的差异。Codex 默认走的是 Responses API而很多兼容服务只提供 Chat Completions API。以接入某些 OpenAI 兼容服务为例config.toml里需要把wire_api设置对否则请求格式不匹配也会报错。4.3 自定义 provider 的完整配置参考分享一个实际可用的自定义 provider 配置结构方便你对照排查model deepseek-chat model_provider custom [model_providers.custom] name Custom Provider base_url https://api.example.com/v1 env_key CUSTOM_API_KEY wire_api chat对应地在 shell 配置文件比如.bashrc或.zshrc里设置好环境变量export CUSTOM_API_KEY你的密钥设置完成后在终端里运行codex启动用一句“你好请用中文回复”测试链路是否通了。如果仍然报错先看base_url是否正确拼接到了/v1层再看wire_api是否匹配最后确认环境变量是否被正确加载。从个人经验看这类报错 90% 是配置细节问题不是 Codex 本身有故障。我建议排查时用codex --verbose模式启动或者直接查看切换工具生成的配置文件通常一眼就能发现问题。5. 登录与认证问题的排查auth token 不可用、桌面版打不开5.1 “auth token is unavailable” 的常见原因与处理报错codex auth token is unavailable意味着 Codex 在读取登录凭证时失败了。国内用户遇到这个报错优先从三个方向排查。第一登录状态失效。运行codex login重新登录一次它会重新走一遍认证流程。如果登录过程一直没有完成检查终端里是否弹出了需要确认的链接以及浏览器是否正常打开了授权页面。第二认证文件缺失或损坏。Codex 的登录凭证默认存在~/.codex/auth.json如果这个文件被手动物理删除了或者因为切换工具改写导致内容不完整就会出现“凭证不可用”的提示。备份好现有配置后删除auth.json重新执行codex login让工具重新生成凭证文件。第三系统时间错误。这个原因非常隐蔽却是我实际遇到过的。系统时间与真实时间偏差太多时认证请求的签名校验会失败表现为反复登录不成功或者拿到 token 后被立刻判定无效。排查方法很简单看系统时间的秒数是否与现实时间一致差几分钟以上就需要校准时间。5.2 桌面版安装失败或者打不开的应急处理Windows 桌面版安装卡在“正在安装”是常见问题。先检查磁盘空间是否充足很多时候装到一半卡住是因为磁盘写不进去了。其次检查杀毒软件有没有拦截安装程序可以把安装目录加入信任列表然后重新运行安装包。如果安装完成后 Codex 打不开表现为点击图标没反应可以尝试清理旧版本残留配置再启动。Windows 下一般是%LocalAppData%\Programs\codex目录里的文件冲突macOS 下则是/Applications/Codex.app的权限问题右键选择“打开”绕过系统限制。5.3 终端环境下的登录状态管理经验多套配置切换时登录状态的管理很容易乱。有些切换工具会同时改写auth.json导致你切回官方账号后发现凭证也不可用。我的习惯是用固定的命名规则管理多份凭证文件切换时手动备份和恢复而不是完全依赖工具。具体来说我会把正常可用的auth.json备份成auth.json.official.bak和auth.json.custom.bak每次切换就手动替换文件。这样做虽然原始但可控性最高很少再出现“凭证被覆盖但说不清为什么”的问题。6. 常见问题速查表与我的实操心得6.1 Codex 中文设置与报错排查速查表现象核心原因解决方向终端里中文显示成方块终端字体不支持中文换 Sarasa Mono SC / Noto CJK 字体终端里中文显示成乱码编码不是 UTF-8Windows 开 UTF-8 选项Linux 设 LANGCodex 回复全是英文缺少语言指令写 AGENTS.md / config.toml 的 instructions切换工具报 local proxy failed端口占用或配置损坏查端口占用重置切换工具配置报 model is not supportedmodel 和 provider 不匹配修改 model 为服务商实际支持的模型报 auth token is unavailable凭证文件损坏或失效重新 codex login重置 auth.json桌面版安装卡住磁盘空间不足或杀毒拦截清理磁盘加白名单重装Codex 桌面版打不开安装残留或权限问题清理旧版本macOS 右键打开6.2 我在实际配置过程中的几点体会Codex 的中文设置折腾过一遍之后我的体会是三层渐进第一层是界面语言这个最不重要能看懂常用的几个按钮就行第二层是回复语言这个最重要直接决定使用体验通过 AGENTS.md 和 instructions 就能很好解决第三层是终端环境属于“基础不牢地动山摇”的类型字体和编码问题不解决中文显示永远有问题。另外一个小技巧配置完成后先用“请总结一下你现在需要遵守的规则。”这句话来验证。如果 Codex 能准确说出“需要用中文回复、注释用中文”这些规则说明你的配置文件加载成功了如果它答不上来那配置文件大概率没生效回去检查路径和格式。最后再提醒一句Codex 更新很快每次升级后最好重新看一下codex --version确认配置文件和新版本仍然兼容。毕竟这类工具的中文设置从来不是一劳永逸的事但只要掌握了排查的底层逻辑无论以后怎么更新你都能快速找到对应的解决方案。
