企业官网建设流程全解析

最近好多人在问“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.toml

3.1 项目级规则文件 AGENTS.md 的正确用法

Codex CLI 和桌面版都会自动读取当前项目目录下的AGENTS.md文件，把它作为项目级指令注入到每次对话的上下文里。这个文件是官方支持的约定，作用就是告诉模型“在这个项目里你要遵守什么规则”。

所以，想让 Codex 用中文回复，最简单有效的方法就是新建一个AGENTS.md文件，内容写成这样：

# 项目规则 - 无论用户使用什么语言提问，一律使用简体中文回复。 - 代码注释和 Git 提交信息使用中文。 - 生成的文档、说明性文字使用中文。 - 代码逻辑命名保持英文，但解释性文本必须中文。

这个文件放在项目根目录即可，Codex 启动时会自动识别并加载。它的优先级很高，相当于每次对话都附加了一段系统指令，比你在对话里反复强调“请说中文”要可靠得多。

如果你的多个项目都希望 Codex 说中文，可以考虑在用户主目录下创建全局的AGENTS.md，这样所有项目都会继承这个规则。全局文件的位置一般是~/.codex/AGENTS.md，没有就手动创建。

3.2 全局配置文件 config.toml 的 instructions 字段

除了 AGENTS.md，Codex 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 中文设置与报错排查速查表

6.2 我在实际配置过程中的几点体会

Codex 的中文设置折腾过一遍之后，我的体会是三层渐进：第一层是界面语言，这个最不重要，能看懂常用的几个按钮就行；第二层是回复语言，这个最重要，直接决定使用体验，通过 AGENTS.md 和 instructions 就能很好解决；第三层是终端环境，属于“基础不牢地动山摇”的类型，字体和编码问题不解决，中文显示永远有问题。

另外一个小技巧：配置完成后，先用“请总结一下你现在需要遵守的规则。”这句话来验证。如果 Codex 能准确说出“需要用中文回复、注释用中文”这些规则，说明你的配置文件加载成功了；如果它答不上来，那配置文件大概率没生效，回去检查路径和格式。

最后再提醒一句，Codex 更新很快，每次升级后最好重新看一下codex --version，确认配置文件和新版本仍然兼容。毕竟这类工具的中文设置从来不是一劳永逸的事，但只要掌握了排查的底层逻辑，无论以后怎么更新，你都能快速找到对应的解决方案。