Troubleshooting
Find the next step from an error message or symptom.
When something goes wrong, run gcodex status first; most problems are visible in its output. gcodex prints its messages in Chinese, so the original text is quoted below with a translation.
Install & sign-in
Open a new terminal window, or run . "$HOME/.recodex/env" in the current one (source "$HOME/.recodex/env.fish" for fish). On Windows, open a new PowerShell window.
Use https://recodex.cc/install.sh (install.ps1 on Windows). Don't use script links from GitHub.
gcodex needs the official Codex CLI installed first. Install it the official way, or run gcodex update to download it. If it lives somewhere unusual, set the RECODEX_CODEX_PATH environment variable to the full path of codex.
The link is valid for 5 minutes and works only once. Go back to the terminal and run gcodex login again.
Only subscriptions that have an assigned account and are neither paused nor expired can be selected. A new subscription also shows Timer paused until its account is assigned; wait for the Account assigned message, then sign in. For other paused or expired subscriptions, sort them out in the console first (see subscription status).
"Device binding conflict, please retry": this subscription has reached its device limit. Revoke a computer you no longer use on the Devices page in the console, then run gcodex login again. Signing in again on the same computer doesn't take another slot.
Run gcodex login --no-browser, then open the printed authorization link in a browser on any device and approve it.
"…is a real sign-in written after ReCodex took over; stopped to avoid overwriting it": while ReCodex was managing Codex, you signed in to your own account directly in the official Codex, and gcodex stopped so it wouldn't overwrite that. To keep using ReCodex, back up and move ~/.codex/auth.json yourself as the message suggests, then try again.
Subscription & usage
"Timer paused": gcodex won't start Codex while the subscription is paused. The reason follows the colon and is also shown on the console's Overview:
- 等待人工分配账号 (awaiting account assignment): a new subscription waiting for an administrator. The timer isn't running and there's nothing for you to do.
- 账号封禁 (account banned): open a support ticket and choose Account issue.
- Authorization expired, upstream plan expired, account paused, etc.: an administrator will handle it, and the timer is paused meanwhile. If it takes long, ask through a support ticket.
See subscription status.
The subscription has ended, and requests are rejected even mid-session. Redeem a code for the same plan to renew; the account and signed-in devices are kept.
"Code can't be redeemed or was already used". Common causes:
- the code has already been used;
- when renewing, the code is for a different plan than the subscription (for example a Pro 200 code on a Pro 100 subscription);
- the code was already redeemed successfully but you submitted it again with a different target; refresh the Subscriptions page to confirm;
- the code has passed its validity period.
Running out of the upstream 5-hour / 7-day quota is normal, not a fault. Quota windows on the console's Overview, or /status in Codex CLI, show when it resets.
To avoid interrupting sessions in progress, gcodex never force-restarts the background service. Save and finish your current CLI and Desktop work, run gcodex stop, then run gcodex again.
ReCodex only supports the official Codex CLI and Codex Desktop. Don't modify the client's request headers or call the service directly from other tools.
Inside Codex launched through gcodex, and on the whole computer while a ReCodex-managed Desktop is running, api.openai.com is rejected. Quit Desktop completely when you need it, and run your program outside gcodex.
ReCodex does not support Realtime Voice yet.
Network
Run gcodex config network current to see the network in use. After switching VPNs, run gcodex config network reload in a terminal that has the new settings. See VPN & proxies.
If gcodex status shows 本机网络不可用: localnet: system PAC/WPAD is enabled… ("local network unavailable"), Windows' “Automatically detect settings” is usually on. If you use a proxy, set its address with gcodex config network set; if you don't, turn off “Automatically detect settings” under Settings → Network & internet → Proxy, then run gcodex config network auto.
Desktop
Always open Desktop with gcodex desktop run. Opening it from the Dock or Start menu, or letting it restart itself after an auto-update, doesn't go through ReCodex. Quit Desktop completely, then run gcodex desktop run.
The message reads This account's Chat is in use on another device. Wait for its lease to expire. Web chat can only be used on one device at a time, and each use on the original device extends its hold. Go back to the original device, or switch about 30 minutes after it stops using web chat.
If Desktop was installed as an MSIX package (for example from the Microsoft Store), enable Codex's alias under Settings → Apps → Advanced app settings → App execution aliases, then try again.
This usually happens after upgrading from an older version. Quit Desktop completely, then:
gcodex repair --dry-run # preview what will be repaired
gcodex repair # repair; the original files are backed up automaticallyStill stuck?
Open a ticket under Support in the console (descriptions are limited to 4,000 characters, without attachments; if you have no subscription yet or can't sign in, contact us on QQ: 1393688344) and include:
- when the problem happened and the exact error message;
- the output of
gcodex status, plusgcodex desktop statusfor Desktop problems; - the Tracking ID of the affected request (in Request details under Usage in the console);
- any relevant log lines:
gcodex logs -n 200shows the last 200 lines of the background service log, and the Desktop log is at~/.recodex/logs/desktop.log. Paste only the lines related to the error.