★ FEATURED ARTICLE 如果你最近用过 Codex估计心里多少有点别扭AI 生成的内容、对话逻辑都挺聪明可工具本身那套界面——命令提示、帮助文档、设置面板——全是英文。想改个配置先得搞懂这个单词是啥意思。说实话Codex 确实是个好用的编程助手但全英文界面这一关确实把不少中文用户挡在了门外所以社区里“Codex 汉化包”的搜索量一直居高不下。这篇博文就专门讲 Codex 汉化包怎么下载、怎么安装以及中文版设置的完整步骤重点说清楚汉化包导入的具体方法。我会把 CLI 版和 Windows 桌面版分开写因为两者改配置的位置不一样别混着来。文章面向的是已经装好 Codex、但被英文界面搞得头疼的开发者和爱好者目标是让你看完就能把界面切成中文顺带把几个高频报错也一起处理掉。1. 汉化方案的底层逻辑Codex 的界面文本到底在哪1.1 先分清你用的是哪种 Codex在开始下载汉化包之前必须要搞清楚一件事你现在用的 Codex 到底是哪个版本。因为不同的运行形态汉化包的导入路径和配置文件完全不一样混着用是肯定不会生效的。我实际接触下来现在用户手里的 Codex 主要有三种形态。第一种是命令行工具 Codex CLI。这是开源项目你在终端里输入codex回车就会进入一个全屏交互式的对话界面。这个界面支持你用自然语言描述需求它能直接读取项目代码、给出修改 diff、执行命令。它的核心代码用的是 Rust配置文件在用户主目录下的.codex目录里主要就是config.toml和auth.json这两个文件。第二种是 Windows 桌面版。这是图形界面程序外观上和普通聊天软件类似左边是会话列表右边是对话区域还内置了文件树和终端面板。它的引擎和 CLI 版是同一套但外壳增加了 GUI 层所以配置分两部分一部分沿用了 CLI 版的.codex目录另一部分在安装目录的resources文件夹里。第三种是编辑器插件最常见的是 VS Code 里的 Codex 扩展。它在 IDE 侧边栏或者编辑器区域显示一个对话面板让你直接在编辑器上下文里和 Codex 沟通。这种形态的界面文本取决于插件本身是否实现了国际化接口汉化方式和前两种差别较大。这三种形态网上的汉化教程经常混着写。你如果明明是桌面版却拿命令行版的教程去操作找半天目录也找不到对应的文件夹最后只能得出“教程有问题”的结论。所以第一步永远是确认形态。1.2 为什么社区普遍选择语言包方案确定了形态之后下一步就是选择汉化手段。有的人会问为什么不直接把整个程序界面截图丢给 AI让它对照翻译或者干脆用屏幕翻译软件我的回答是能应急但不好用。屏幕翻译在浏览器里确实方便一键划词翻译。但 Codex 的 CLI 界面里文本是滚动输出的终端流你没法像网页一样精准划词。桌面版虽然可以截屏但频繁切换窗口会让本来就高强度的编程工作变得支离破碎。更重要的是Codex 界面文本里有大量变量内容——token 数量、耗时、文件路径、错误代码——这些不是静态的菜单文字翻译软件很难还原成上下文明确的提示。所以社区的做法很统一工程化地处理做一个语言包把界面文案替换成整理好的中文 locale 文件。语言包方案的好处有三点第一可复现。语言文件是独立资源放进目录、改一行配置界面就切过来了随时可以回滚。第二可版本管理。社区汉化作者会跟着 Codex 版本更新语言包新增的菜单项会逐步补上。第三相对安全。语言包只做文本替换不修改可执行文件风险比所谓的“绿色汉化版”安装包低得多。注意不要下载来路不明的“Codex 中文完整版”安装包那类文件往往把汉化和破解捆绑在一起容易出安全问题。正确姿势始终是官方原版程序 社区语言包。2. 汉化包下载前的准备版本确认、渠道判断与备份2.1 用一条命令确认版本避免白忙一场进入下载环节之前先花一分钟确认版本。这步虽然简单但能避免大量无效操作。CLI 版在终端里执行codex --version能看到版本号的话记下来。比如输出0.34.0那你找汉化包时就要找适配 0.34.x 的文件至少大版本号要对上。如果执行之后提示找不到命令但桌面确实有一个 Codex 应用图标那说明你用的是桌面版。桌面版在界面的设置或关于页面里可以查到版本号同时注意看是 stable 还是 nightly。nightly 版的资源结构变化快社区汉化包未必能及时跟上我一般建议先切回 stable 版再汉化。VS Code 插件版的话在扩展市场里找到 Codex详情页上方会显示当前安装的版本号。插件版的汉化方式和前两者不同要看插件自身是否支持 locale 配置。有个细节容易坑人老版本的配置文件里用的是language字段新版本改成了locale你拿旧教程里的字段去改新版本根本不会生效。这又一次说明版本确认有多重要。2.2 汉化包去哪下载怎么判断靠不靠谱汉化包没有官方渠道官方只提供英文界面。所以你的来源基本是 GitHub 社区项目、开发者论坛、资源聚合站。我个人的下载优先级是GitHub Release 页面 知名开发者论坛 其他资源站。理由很简单GitHub 上的文件有版本记录、有 hash 校验值、有 issue 讨论区出了问题你能找到作者、能看别人踩坑的记录。资源站的东西虽然下载快但很多没有版本标注也没有校验信息来源不明。判断汉化包是否可信我一般看四个点有没有明确标注适配版本。只写“最新版通用”的多半是旧包改个名再发。有没有附安装说明和示例配置。靠谱的汉化包一定带 README里面会写清楚文件放哪、配置怎么改。文件类型合不合理。汉化包的本质是 JSON、YAML 这类语言资源文件如果给你的是 .exe、.msi不用想直接删掉。有没有附带校验值。有 SHA256 校验值的包至少说明作者是用心做的。下载到本地之后建议顺手做一次校验。macOS/Linux 用sha256sum 下载的文件名Windows 用Get-FileHash 下载的文件名把算出来的值和 Release 页面上公布的比对不一致说明文件被修改过别用。2.3 强制建议先备份再动手汉化操作本质是在 Codex 的配置和资源目录里写入新文件。虽然不碰程序本体但配置改错了轻则汉化不生效重则把登录态、模型配置一并弄丢。我自己的习惯是任何工具做这类操作前先把配置目录整个复制一份cp -r ~/.codex ~/.codex_backupWindows 用户用 PowerShellCopy-Item -Path $env:USERPROFILE\.codex -Destination $env:USERPROFILE\.codex_backup -Recurse备份之后你可以放心地改配置、删文件、反复尝试不同版本的汉化包。出了问题把备份目录覆盖回去就一切复原这个习惯能省掉大量不必要的焦虑。3. 中文版设置完整实操从下载到导入的五个步骤3.1 步骤一下载对应版本的汉化包并解压下载时注意命名规则。社区汉化包的命名一般是codex-locale-zh-CN-v版本号.zip或类似格式中间的版本号对应 Codex 主程序版本。你下载的文件版本和本地版本差太远就不要强行用界面会出现大量英文混杂原因就是语言包没收录新界面的文本。下载完成后先解压到一个临时目录。用 GUI 自带的解压工具或者命令行都行关键是看清解压出来的文件结构。常见结构有两种一个locale目录里面是zh-CN.json或类似名字的语言文件一个config目录里面放了部分配置片段用于增强汉化效果。只推荐导入语言文件这一部分配置片段是否使用取决于你的具体需求。如果不懂 config 片段里的字段含义就先不导入语言文件已经能覆盖 90% 的界面文案。3.2 步骤二找到 Codex 的资源目录别找错地方根据第一步确认的形态找到对应目录。CLI 版的配置目录WindowsC:\Users\你的用户名\.codexmacOS / Linux~/.codex这个目录下有几个关键内容要先认识下config.toml核心配置文件等下改语言配置就在这里auth.json登录凭据文件记录了你的认证信息locale/语言文件目录。有的版本不存在需要自己新建session/或projects/会话和项目数据。桌面版需要注意如果你是 Windows 桌面版安装目录通常在C:\Program Files\Codex或C:\Users\你的用户名\AppData\Local\Programs\Codex。在这个目录下找到resources文件夹社区汉化包一般要求把语言文件放到resources\locale下或者resources\app的子目录里具体以你下载的汉化包 README 为准。提示修改桌面版resources目录内的文件建议右键 Codex 图标选择“以管理员身份运行”否则权限不足时程序可能没有权限加载新语言文件。3.3 步骤三导入语言文件到指定位置CLI 版导入语言文件先创建 locale 目录再复制文件mkdir -p ~/.codex/locale cp zh-CN.json ~/.codex/locale/Windows 下New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex\locale Copy-Item zh-CN.json $env:USERPROFILE\.codex\locale\这里有一个极其常见的坑文件名。Codex 通常通过文件名里的语言代码识别语言包。简体中文必须是zh-CN如果你的汉化包解压出来叫zh_cn.json复制之前一定要重命名为zh-CN.json。我见过好几个人卡在这一步改了名字之后汉化立刻生效。桌面版导入路径不同把语言文件复制到resources\locale\下。如果目录不存在就自己新建一个命名规则相同。3.4 步骤四修改配置文件把语言切到中文语言文件到位后还需要让 Codex 加载它。这一步通过修改配置实现。CLI 版打开config.toml在文件顶层加一行locale zh-CN如果文件里已经存在locale字段直接改成这个值。如果你用的 Codex 版本较老可能用的是language字段遇到改了locale不生效的情况就改成language zh-CN桌面版如果读的是同一份 config.toml按同样方式处理如果 readme 要求改别的配置以 readme 为准。改完之后保存退出终端或桌面应用重新启动 Codex。这时候会重新加载配置和语言文件正常情况下界面就会切换为中文。3.5 步骤五重启验证与检查启动后的验证主要看两处。第一处是欢迎语和提示文本。CLI 版启动后如果界面顶部显示的是“输入你的需求输入 /help 查看帮助”这类中文提示那就是成功了。第二处是设置面板和菜单。桌面版可以在设置里找到语言相关选项如果显示的是“语言简体中文”说明汉化生效。如果启动后仍然是英文不要马上重装汉化包。按这个顺序排查先看语言文件是否在正确目录再看文件名是否为 zh-CN.json再看配置文件字段是否写对最后确认是否重启完整有些桌面版需要在任务管理器里结束进程再启动。4. 常见问题与高频报错排查实录4.1 cc switch local proxy failed 的完整排查思路这个报错出现频率很高很多用户把 Codex 接入第三方模型时都会撞上它。先解释它出现的场景。社区里很多用户会安装一个叫 ccswitch 的小工具用来在官方模型和第三方模型之间快速切换。ccswitch 的原理是在本地启动一个转发服务把 Codex 发出的 API 请求转发到你配置的模型服务地址上。这个报错表达的意思是这个本地转发服务在处理 Codex 的/responses接口请求时挂了。从实际排查经验来看最常见的原因有三个按出现频率排序endpoint 地址配置错误。很多人复制模型 API 地址时多带了空格、引号或者少写了路径里的某个斜杠。转发请求发出去之后直接失败反映出来就是 local proxy failed。本地转发服务没启动。ccswitch 配置文件改好了但启动命令没执行或者它设置成开机启动却被安全软件拦了。端口冲突。ccswitch 默认监听的本地端口被其他程序占用服务起不来或者起来之后被顶掉了。排错的步骤建议这样先把 ccswitch 控制台打开看本地转发服务是否处于运行状态然后检查 endpoint 地址最好重新从平台的 API 文档复制一遍不要手动敲最后检查端口占用情况Windows 下用netstat -ano | findstr 端口号macOS/Linux 用lsof -i:端口号。如果端口被占换一个端口重新配置。4.2 codex auth token is unavailable登录态与凭据问题“auth token is unavailable”是另一个高频报错字面意思是认证令牌不可用。从使用经验看这个错误基本都是三种情况第一从没登录过。CLI 版初次使用必须先运行codex login浏览器会弹出一个授权页面你登录账号并同意授权然后命令行拿到 token 存到auth.json。如果跳过这步直接使用就会提示 token 不可用。第二auth.json被删除或内容损坏。很多人汉化时在.codex目录里折腾文件不小心把auth.json删了或者覆盖了登录态就丢了。这就是前面强调备份的原因。第三接入第三方模型时没有填写 API key。如果你在config.toml里配置了第三方提供商的接入信息但没有填写对应的api_key字段Codex 也会认为“没有可用的认证令牌”。解决方法是按顺序排查先检查auth.json是否存在且内容非空然后执行一次codex login重新授权最后检查config.toml中对应 provider 的 API key 是否填写正确。如果你确实用的是第三方模型且不想用官方账号授权那就要确认接入工具的配置格式和你当前 Codex 版本匹配。4.3 exceeded retry limit, last status: 429 too many requests这个错误说明撞上的人不少。429 是 HTTP 状态码意思是“请求过多”服务器在限流。Codex 默认有重试机制发出去的请求如果遇到限流会自动重试几次。当重试次数超过阈值就会报“exceeded retry limit”同时给出最后一次的状态码429 too many requests。触发限流的原因我遇到过两种比较典型的一种是你在一个会话里疯狂回车。每按一次回车就发一次请求短时间请求量过大直接把额度打满。另一种是多个客户端共用一个 API key。比如 Codex CLI 开着一个会话VS Code 插件也挂着同一个账号两个程序都在发请求频率叠加后很快就触发限流。遇到 429最快的处理办法就是等一般等几十秒到几分钟限流窗口就会过去。如果频繁出现可以调低你的重试并发数或者在 config.toml 里设置更长的重试间隔。对第三方模型接入的场景还要去对应平台确认自己当前的速率限制和额度免费版通常比付费版更容易撞到 429。4.4 汉化后部分界面仍是英文甚至出现乱码汉化不彻底最直接的原因就是语言包和 Codex 版本不匹配。Codex 升级后界面新增了英文文本旧语言包没收录这些文本就会原样显示成英文。处理办法是等社区语言包更新或者自己往语言文件里补几条翻译。乱码问题则多半出在字体上。CLI 界面里的中文显示依赖终端字体的中文字符支持如果你用的终端字体不支持中文就会看到一堆方框或乱码。解决方法是把终端字体换成等距更纱黑体、JetBrains Mono、微软雅黑这类对中日韩字符支持完善的字体。还有一种情况是语言文件编码不对。JSON 语言文件必须使用 UTF-8 编码如果文件被某些 Windows 编辑器自动转成了 GBKCodex 解析时就容易出乱码。用 VS Code 打开文件看右下角编码显示确保是 UTF-8不是的话就另存为转码一次。4.5 Codex 打不开、一直转圈或卡在连接中“Codex 打不开”或者“正在重新连接”这类问题和汉化没有直接关系但汉化后初次重启时容易遇到可能是加载新语言文件时的异常表现。排查思路先杀掉所有 Codex 相关进程再重新启动。Windows 上按 CtrlShiftEsc 打开任务管理器把所有 Codex 进程结束掉macOS 上可以在活动监视器里搜 codex 结束进程。然后检查配置目录权限。如果.codex目录或resources目录的写入权限有问题程序启动时会卡住。最后清缓存。桌面版通常会在用户目录的AppData或~/Library/Caches下放缓存文件清掉缓存目录再启动一般能解决转圈问题。如果清缓存后问题依旧可以考虑把备份的.codex目录恢复回去确认是汉化导致的问题还是模型配置导致的问题再做下一步处理。4.6 常见报错速查表报错信息常见原因解决方向cc switch local proxy failedendpoint 写错 / 转发服务未启动 / 端口冲突核对 API 地址确认本地转发服务运行中更换端口auth token is unavailable未登录 / auth.json 丢失 / API key 缺失重新执行 codex login检查 auth.json 与 API key429 too many requests请求频率过高 / 多个客户端共用 Key等待限流窗口调大重试间隔确认额度部分英文 / 乱码语言包版本不匹配 / 字体不支持 / 编码错误更新语言包更换中文友好字体确认 UTF-8打不开或一直转圈进程残留 / 权限异常 / 缓存损坏结束进程、检查目录权限、清缓存5. 实操中容易被忽略的细节与扩展玩法5.1 终端字体与窗口宽度决定中文字体的最终观感汉化成功之后很多人的体验改善并不明显甚至觉得“还是英文界面好看”原因是终端渲染中文字体的效果差了。CLI 界面里的中文大多是全角字符如果终端字体不支持或者字体里的中文字形和中文字体不搭配就会出现对不齐、字距忽大忽小的问题。我自己踩过一次坑用的是某个纯英文字体汉化之后所有中文全是方框排查半天才发现是字体问题跟汉化包本身没关系。建议 Windows Terminal 用户把默认字体改为“微软雅黑”或“等距更纱黑体”iTerm2 用户把非拉丁字体设置为“PingFang SC”或“Noto Sans CJK SC”。同时把终端窗口宽度拉到 100 列以上给中文全角字符留足显示空间整个界面会清爽很多。5.2 汉化与模型接入并不冲突搭配使用时注意模型名参数最后聊一个热门话题Codex 接入 DeepSeek。汉化解决的是界面文字模型接入解决的是对话能力两者完全不冲突可以同时配置。接入 DeepSeek 时在 config.toml 里通常这样指定模型[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 api_key 你的key然后设置默认模型model deepseek-chat看到没这里面的model deepseek-chat就是模型名称参数。很多人在这一步报错the gpt-5.6-sol model is not supported when using codex with a...。这类“模型不受支持”的报错说白了就是model字段里写了一个 Codex 或当前接入工具不认识的模型名。解决办法很简单查一下当前接入方式支持的模型列表改成官方支持的名称。不要凭想象力写模型名也不要以为版本号越高越通用。模型名对不上Codex 转发的请求就会直接失败。接入第三方模型后对话内容本身会优先由模型决定语言风格你发中文问它就用中文答。但界面上的系统提示、菜单说明还是由 Codex 客户端本地文本决定的所以汉化包和模型接入正好是一对互补的配置缺一个体验都差一口气。按我的经验单独把一个 Codex 界面切成中文熟悉流程之后十分钟之内能搞定新手慢一点也不会超过半小时。真正影响长期体验的反而是字体、限流、模型配置这些容易忽略的细节。最后分享一个小经验Codex 升级大版本之后社区汉化包往往要过几天才会更新。如果你着急用中文界面可以先把旧版语言文件保留下来启动时用临时命令指定语言路径等方法适配好再切回正式配置。虽然这个方法只适用于 CLI 版但用熟了之后你会发现它比每次升级都干等汉化包省心得多。
阅读完成 · 觉得有帮助？
