Skip to content

[codex] Add desktop reconnecting proxy troubleshooting #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
toby-bridges wants to merge 1 commit into
base: main
Choose a base branch
from
+85 −0
Draft

[codex] Add desktop reconnecting proxy troubleshooting #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions docs/configuration/config-file.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,25 @@ description: "Codex config.toml 配置指南，说明模型、沙盒、审批、

项目长期规则建议写到仓库内的 `AGENTS.md`，个人偏好放到本机 `config.toml`。这样团队成员能共享项目规则，又能保留自己的 CLI 使用习惯。

## `.env` 和 `config.toml` 不要混用

`config.toml` 保存 Codex 的持久配置，例如模型、沙盒、审批、profiles 和 MCP server。`~/.codex/.env` 更适合放 Desktop app 或 IDE extension 启动时需要读取的环境变量，例如 provider 需要的区域变量，或排障时临时验证过的代理变量。

OpenAI [Amazon Bedrock provider 文档](https://developers.openai.com/codex/amazon-bedrock)提醒：Desktop app 和 VS Code extension 可能不会继承当前 shell 里的环境变量；如果这些入口需要某些变量，可以把值放进 `~/.codex/.env`，然后重启 app 或 extension。

写入前先确认两件事：

- 变量确实是当前入口需要的，不要把所有 shell 变量都复制进去。
- 文件里可能包含 secret，截图、发 issue 或提交仓库前必须脱敏。

例如代理排障时，不要先猜端口。先用系统代理设置和 `curl -x` 确认端口可用，再写：

```bash
export HTTP_PROXY="http://127.0.0.1:<PORT>"
export HTTPS_PROXY="http://127.0.0.1:<PORT>"
export NO_PROXY="localhost,127.0.0.1,::1,*.local"
```

::: info 截图占位
请补充本机 `~/.codex/config.toml` 文件位置截图，注意遮挡敏感路径和 token。建议文件：`docs/.vuepress/public/screenshots/config/02-config-location.png`。
:::
Expand Down Expand Up @@ -231,6 +250,7 @@ codex-provider restore <backup-dir>
| Codex 权限超出预期 | 检查 `sandbox_mode` 和 `approval_policy` |
| 某个命令一直被拒绝 | 检查沙盒限制、网络权限和组织策略 |
| MCP 无法连接 | 检查服务命令、环境变量、端口、认证方式 |
| Desktop 不继承代理变量 | 先验证真实代理端口和协议，再把最小变量放进 `~/.codex/.env` 并重启 |
| 切换 provider 后旧会话不可见 | 先判断是否是 Desktop 最近 50 条显示限制，再检查 provider metadata 是否需要同步 |
| 团队成员行为不一致 | 把项目共同规则写进 `AGENTS.md` |

Expand All @@ -239,4 +259,6 @@ codex-provider restore <backup-dir>
- [Config basic](https://developers.openai.com/codex/config-basic)
- [Config advanced](https://developers.openai.com/codex/config-advanced)
- [Config reference](https://developers.openai.com/codex/config-reference)
- [Environment variables](https://developers.openai.com/codex/environment-variables)
- [Use Codex with Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock)
- [openai/codex config docs](https://github.com/openai/codex/blob/main/docs/config.md)
63 changes: 63 additions & 0 deletions docs/guide/18-troubleshooting.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,69 @@ redirectFrom:
- 检查当前账号计划和组织策略。
- 查看官方 Help Center 的 Codex 相关文章。

## Desktop 一直显示 Reconnecting

`Reconnecting` 不是一个具体根因。它可能是主连接、会话恢复、WebSocket / SSE 流、代理协议、MCP worker 或服务端临时问题。不要一开始就重装 Codex、覆盖 `config.toml`，或者直接换账号。

::: tip 最后核对
官方资料和 GitHub issue 最后核对日期：2026-06-14。本文参考 OpenAI [Codex app troubleshooting](https://developers.openai.com/codex/app/troubleshooting)、[Environment variables](https://developers.openai.com/codex/environment-variables)、[Use Codex with Amazon Bedrock](https://developers.openai.com/codex/amazon-bedrock)、[Model Context Protocol](https://developers.openai.com/codex/mcp)，以及社区排障库 [Desktop Reconnecting / Proxy Triage](https://github.com/toby-bridges/community-codex-windows-troubleshooting/blob/main/DESKTOP-RECONNECTING-PROXY-GUIDE.md)。
:::

先按三层判断：

| 层级 | 现象 | 先做什么 |
| --- | --- | --- |
| 主连接 | 新线程也一直 `Reconnecting` | 验证 Codex 进程能不能走到正确代理 |
| 会话流 | 偶发 `stream disconnected before completion` | 看是否是旧会话、WebSocket/SSE 或服务端连接问题 |
| 工具 worker | 主界面恢复，但 MCP、Browser、node_repl 仍失败 | 再查 `config.toml` 里的 MCP 环境变量 |

如果你使用 macOS 代理：

```bash
scutil --proxy
launchctl getenv HTTP_PROXY
launchctl getenv HTTPS_PROXY
curl -sS --max-time 10 -x "http://127.0.0.1:<PORT>" "https://api.ipify.org?format=json"
```

端口和协议都验证通过后，再把最小代理变量放进 `~/.codex/.env`，然后完全退出并重新打开 Codex Desktop：

```bash
export HTTP_PROXY="http://127.0.0.1:<PORT>"
export HTTPS_PROXY="http://127.0.0.1:<PORT>"
export ALL_PROXY="http://127.0.0.1:<PORT>"
export NO_PROXY="localhost,127.0.0.1,::1,*.local"
```

网上有 macOS 一键脚本会自动读取 `scutil --proxy` 并更新 `~/.codex/.env`。可以把这类脚本当模板，但运行前至少确认它会备份原 `.env`、用 `curl -x` 验证代理协议、不会覆盖其他 secret，并且明确只适用于 macOS。

如果你使用 Windows 或 WSL：

- Windows 原生 Desktop 优先检查 Windows 用户环境变量。
- WSL 模式不要只写 `~/.bashrc`，因为 Desktop 启动 WSL 进程时不一定经过 login shell。
- 修改环境变量后完全重启 Codex。

```powershell
[Environment]::SetEnvironmentVariable("HTTP_PROXY", "http://127.0.0.1:<PORT>", "User")
[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:<PORT>", "User")
```

如果主界面已经恢复，但 MCP 或 node_repl 仍然断，再检查 MCP server 是否需要单独配置环境变量：

```toml
[mcp_servers.node_repl.env]
HTTP_PROXY = "http://127.0.0.1:<PORT>"
HTTPS_PROXY = "http://127.0.0.1:<PORT>"
NO_PROXY = "localhost,127.0.0.1,::1,*.local"
```

日志位置：

- macOS app logs：`~/Library/Logs/com.openai.codex/YYYY/MM/DD`
- 会话记录：`$CODEX_HOME/sessions`，默认 `~/.codex/sessions`

发 issue 或群里求助时，只贴脱敏后的错误字符串、时间点、Codex 版本、平台和网络拓扑。不要公开完整日志、邮箱、account id、conversation id、session id、真实出口 IP、本机路径、私有仓库名或 token。

## Windows 桌面 App / CLI 专项排障

如果问题发生在 Windows 桌面 App、Microsoft Store / winget 安装、Windows sandbox、Worktree、Browser / Computer Use 插件、WSL 混合路径或 PowerShell 环境，可以参考社区维护的 Windows 专项排障库：
Expand Down