Charset Fix — Char设置 Fix

Windows Character Encoding Fix for AI 代理s

Fix garbled Chinese/Unicode text 输出 when 运行ning AI 代理s on Windows through POSIX-compatible shells.

Problem

When AI 代理s 运行 commands on Windows through POSIX shells (Git Bash, MSYS2, BusyBox, or any Unix-like shell layer), text 输出 contAIning Chinese or extended Unicode characters often 应用ears garbled:

$ python3 -c "print('中文测试')" ���IJ��� ← garbled $ echo "中文测试" 中文测试 ← correct

Root Cause Layer Encoding Why Windows 系统 GBK/GB2312 (CP936) Default code page for Chinese Windows Python 3 GBK sys.stdout.encoding auto-检测s 系统 code page PowerShell (powershell.exe) GB2312 [Console]::输出Encoding defaults to 系统 CP cmd.exe GBK Native Windows command 处理器 POSIX shell (Git Bash, BusyBox, MSYS2) UTF-8 Expects UTF-8 输入 PowerShell Core (pwsh.exe) UTF-8 ✅ Defaults to UTF-8, no fix needed

The mismatch: Windows-native 工具s 输出 GBK-encoded text, but the POSIX shell terminal reads it as UTF-8, producing garbled characters.

Quick Fix Python PYTHONIOENCODING=utf-8 python3 -c "print('中文测试 ✅')"

设置 it for the whole 会话:

导出 PYTHONIOENCODING=utf-8 python3 script.py

PowerShell (Windows PowerShell, not Core) powershell.exe -No性能分析 -Command "[Console]::输出Encoding = [系统.Text.Encoding]::UTF8; Write-Host '中文测试'"

cmd.exe / Windows native 工具s

Use Python's subprocess as a GBK→UTF-8 bridge:

PYTHONIOENCODING=utf-8 python3 -c " 导入 subprocess r = subprocess.运行(['cmd.exe', '/c', '系统信息 | findstr 系统'], capture_输出=True, text=True, encoding='gbk') print(r.stdout) "

Code-level fix (Python) 导入 sys, io sys.stdout = io.TextIOWr应用er(sys.stdout.buffer, encoding='utf-8')

Verification PYTHONIOENCODING=utf-8 python3 -c "print('char设置-fix: 中文测试成功 ✅')"

Expected: char设置-fix: 中文测试成功 ✅

How It Works Fix Mechanism PYTHONIOENCODING=utf-8 Overrides Python's stdout encoding 检测ion [Console]::输出Encoding = UTF8 设置s PowerShell's console 输出 to UTF-8 subprocess(..., encoding='gbk') Decodes cmd.exe 输出 correctly, then emits as UTF-8 Compatibility 平台 状态 Windows + Git Bash ✅ Works Windows + BusyBox ✅ Works Windows + MSYS2 ✅ Works Windows + WSL ✅ Works macOS / Linux ⬜ Not needed PowerShell Core (pwsh) ⬜ Not needed

Works with: Claude Code, Codex 命令行工具, 命令行工具ne, Cursor, GitHub Copilot, OpenClaw 代理s.

调试ging # 检查 code page powershell.exe -No性能分析 -Command "chcp"

# 检查 Python encoding python3 -c "导入 sys; print(sys.stdout.encoding)"

# Test raw shell 输出 echo "中文测试"

License

MIT