WebSocket fails with non-ASCII workspace paths (UTF-8 in x-codex-turn-metadata header)

Codex CLI UTF-8 Path Bug — Bug Report Draft

Bug version: codex-cli 0.125.0-alpha.3
Date discovered: 2026-04-25
Reproducer: Kamer (kamercanizvermez@gmail.com)

Summary

Codex CLI fails to establish WebSocket connection when the workspace path contains non-ASCII Unicode characters (specifically tested with Turkish characters: ı, ğ, ş). The HTTP header x-codex-turn-metadata requires ASCII-only values per RFC 7230, but the workspace path is included unencoded in the workspaces field of the JSON metadata.

Reproduction

# Setup: directory with Turkish characters
mkdir ~/Agentlarım && cd ~/Agentlarım
git init && git commit --allow-empty -m "test"

# Trigger
echo "hello" | codex exec -

# Expected: response from Codex
# Actual: 5x reconnect attempts, fallback succeeds but slow

Error Output

ERROR codex_api::endpoint::responses_websocket: failed to connect to websocket:
UTF-8 encoding error: failed to convert header to a str for header name
'x-codex-turn-metadata' with value: "{\"session_id\":\"...\",\"thread_source\":\"user\",
\"turn_id\":\"...\",\"workspaces\":{\"/Users/kamer/Agentlar\xc4\xb1m\":{...}},
\"sandbox\":\"seatbelt\"}"
url: wss://chatgpt.com/backend-api/codex/responses

The \xc4\xb1 is the UTF-8 byte sequence for ı (U+0131 LATIN SMALL LETTER DOTLESS I).

Workaround

Run Codex outside the affected workspace:

cd /tmp && codex exec --skip-git-repo-check

This avoids triggering git workspace discovery which embeds the path in the WebSocket header.

Suggested Fix

In the x-codex-turn-metadata header serialization code, percent-encode the workspace path values per RFC 3986, or use a separate header that supports UTF-8 (e.g., x-codex-turn-metadata-b64 with base64-encoded JSON).

Alternative: use a body field or HTTP/2 trailer instead of a header for binary-safe metadata.

Impact

• Affects all users with non-ASCII characters in workspace paths
• Common in non-English locales (Turkish, German, French, Japanese, Chinese, etc.)
• WebSocket connection fails; Codex falls back to HTTP polling (slower, less efficient)
• Each turn includes 5x reconnect retry overhead

Repository

OpenAI Codex CLI: https://github.com/openai/codex (or wherever issue tracker is)

Status

• [ ] Issue submitted to GitHub
• [ ] Workaround documented in araclar/codex.sh ✅ (Kamer's system)
• [ ] Fix verified on patched version