【Bug已解决】codex: output encoding garbled / UTF-8 mojibake — CodeX CLI 输出乱码解决方案

1. 问题描述

CodeX CLI 的输出中出现乱码或编码问题：

# 中文输出乱码
$ codex "用中文解释代码"
# 输出: è¿™æ˜¯ä¸€æ®µä»£ç  （应为: 这是一段代码）

# 或终端显示乱码
$ codex
> hello
# 输出: â"œå"œå­—符

# 或文件内容乱码
$ codex "创建中文 README.md"
# 文件中: 正常（应为: 正常）

# 或 Windows 上乱码
$ codex "task"
# 输出: τÖç«á内容

这个问题在以下场景中特别常见：

• 终端编码不是 UTF-8
• Windows 使用 GBK/CP936
• SSH 连接编码不匹配
• 文件编码不一致
• 管道/重定向丢失编码
• 环境变量 LANG/LC_ALL 未设置

2. 原因分析

核心原理拆解

CodeX 输出 UTF-8 → 终端/文件/管道使用不同编码
        ↓
编码不匹配 → 乱码

原因分类表

原因分类	具体表现	占比
终端编码	非 UTF-8	约 35%
Windows	GBK/CP936	约 25%
SSH 编码	远程编码不匹配	约 15%
文件编码	非 UTF-8 写入	约 15%
环境变量	LANG 未设	约 5%
管道丢失	重定向编码丢失	约 5%

3. 解决方案

方案一：设置终端为 UTF-8（最推荐）

# 步骤 1：设置 LANG 和 LC_ALL
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# 步骤 2：永久设置
echo 'export LANG=en_US.UTF-8' >> ~/.zshrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.zshrc
source ~/.zshrc

# 步骤 3：验证
locale
# 应显示 UTF-8

# 步骤 4：重启 CodeX
codex

方案二：macOS 终端设置

# 步骤 1：终端偏好设置
# Terminal → Preferences → Profiles → Text
# 确保 "Unicode (UTF-8)" 编码

# 步骤 2：iTerm2 设置
# Preferences → Profiles → Terminal → Terminal Emulation
# 确保 "Unicode Version 9 Widths" 和 UTF-8

# 步骤 3：验证
echo "中文测试"
codex "用中文回答"

方案三：Windows 设置

# 步骤 1：更改代码页为 UTF-8
chcp 65001

# 步骤 2：或设置 PowerShell
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
[Console]::InputEncoding = [System.Text.Encoding]::UTF8

# 步骤 3：永久设置
# Settings → Time & Language → Language → Administrative
# → Change system locale → 勾选 "Beta: Use Unicode UTF-8"

# 步骤 4：验证
codex "task"

方案四：SSH 编码修复

# 步骤 1：在 SSH 配置中设置
# ~/.ssh/config
Host *
  SendEnv LANG LC_ALL
  SetEnv LANG=en_US.UTF-8

# 步骤 2：远程服务器设置
ssh user@server
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
codex

# 步骤 3：验证
locale
codex "task"

方案五：文件编码修复

# 步骤 1：检查文件编码
file README.md
# 应该是 UTF-8

# 步骤 2：转换编码
iconv -f GBK -t UTF-8 README.md > README_utf8.md
mv README_utf8.md README.md

# 步骤 3：确保 CodeX 以 UTF-8 写入
export LANG=en_US.UTF-8
codex "创建中文 README.md"

# 步骤 4：验证
file README.md
cat README.md

方案六：管道/重定向编码

# 步骤 1：管道中保持 UTF-8
export LANG=en_US.UTF-8
codex --print "task" | cat

# 步骤 2：重定向到文件
codex --print "task" > output.txt
file output.txt  # 应为 UTF-8

# 步骤 3：使用 iconv 确保编码
codex --print "task" | iconv -f UTF-8 -t UTF-8 > output.txt

# 步骤 4：验证
cat output.txt

4. 各方案对比总结

方案	适用场景	推荐指数	难度
方案一：设置 LANG	通用	⭐⭐⭐⭐⭐	低
方案二：macOS	macOS	⭐⭐⭐⭐⭐	低
方案三：Windows	Windows	⭐⭐⭐⭐⭐	低
方案四：SSH	远程	⭐⭐⭐⭐	中
方案五：文件编码	文件乱码	⭐⭐⭐⭐	低
方案六：管道	重定向	⭐⭐⭐	低

5. 常见问题 FAQ

5.1 如何检查当前编码

locale
echo $LANG

5.2 UTF-8 和 GBK 的区别

• UTF-8: 国际通用，支持所有语言
• GBK: 中文编码，不支持其他语言

5.3 Windows 默认编码

Windows 控制台默认使用 CP936（GBK）或 CP437。需要 chcp 65001 切换到 UTF-8。

5.4 如何查看文件编码

file filename
# 或
hexdump -C filename | head -3
# UTF-8 文件通常以 EF BB BF 开头（BOM）

5.5 SSH 乱码怎么办

确保本地和远程都设置 LANG=en_US.UTF-8，SSH 配置中 SendEnv LANG LC_ALL。

5.6 iconv 是什么

编码转换工具：

iconv -f GBK -t UTF-8 input.txt > output.txt

5.7 管道导致乱码

确保管道两端都使用 UTF-8。设置 LANG=en_US.UTF-8。

5.8 Docker 中乱码

docker run -e LANG=en_US.UTF-8 -e LC_ALL=en_US.UTF-8 codex-env

5.9 VS Code 终端乱码

VS Code 设置: terminal.integrated.encoding: "utf8"

5.10 排查清单速查表

□ 1. export LANG=en_US.UTF-8
□ 2. export LC_ALL=en_US.UTF-8
□ 3. locale 验证编码
□ 4. macOS: 终端偏好设置 UTF-8
□ 5. Windows: chcp 65001
□ 6. SSH: SendEnv LANG LC_ALL
□ 7. file 命令检查文件编码
□ 8. iconv 转换非 UTF-8 文件
□ 9. Docker: -e LANG=en_US.UTF-8
□ 10. 管道/重定向保持 UTF-8

6. 总结

1. 根本原因：输出乱码最常见原因是终端编码非 UTF-8（35%）和 Windows GBK 编码（25%）
2. 最佳实践：设置 export LANG=en_US.UTF-8 和 export LC_ALL=en_US.UTF-8，永久写入 .zshrc
3. Windows 修复：使用 chcp 65001 切换到 UTF-8，或在系统设置中启用 Unicode UTF-8
4. SSH 修复：在 SSH 配置中 SendEnv LANG LC_ALL，确保远程也设置 UTF-8
5. 最佳实践建议：所有环境统一使用 UTF-8 编码——终端、文件、管道、Docker，避免编码不匹配

故障排查流程图

flowchart TD
    A[输出乱码] --> B[locale 检查编码]
    B --> C{LANG=UTF-8?}
    C -->|否| D[export LANG=en_US.UTF-8]
    C -->|是| E{Windows?}
    D --> F[source ~/.zshrc]
    F --> G[codex 验证]
    E -->|是| H[chcp 65001]
    E -->|否, macOS| I[终端设置 UTF-8]
    E -->|否, SSH| j[SSH SendEnv LANG]
    H --> K[PowerShell UTF-8]
    K --> G
    I --> G
    j --> L[远程也设 UTF-8]
    L --> G
    G --> M{还乱码?}
    M -->|否| N[✅ 问题解决]
    M -->|是, 文件| O[file 检查编码]
    M -->|是, 管道| P[管道保持 UTF-8]
    O --> Q[iconv 转换编码]
    P --> R[确保 LANG 设置]
    Q --> G
    R --> G
    N --> S[Docker: -e LANG=UTF-8]
    S --> T[✅ 长期方案]