diff --git a/docs/configuration/config-file.md b/docs/configuration/config-file.md index 04d2160..cebd090 100644 --- a/docs/configuration/config-file.md +++ b/docs/configuration/config-file.md @@ -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:" +export HTTPS_PROXY="http://127.0.0.1:" +export NO_PROXY="localhost,127.0.0.1,::1,*.local" +``` + ::: info 截图占位 请补充本机 `~/.codex/config.toml` 文件位置截图，注意遮挡敏感路径和 token。建议文件：`docs/.vuepress/public/screenshots/config/02-config-location.png`。 ::: @@ -231,6 +250,7 @@ codex-provider restore | Codex 权限超出预期 | 检查 `sandbox_mode` 和 `approval_policy` | | 某个命令一直被拒绝 | 检查沙盒限制、网络权限和组织策略 | | MCP 无法连接 | 检查服务命令、环境变量、端口、认证方式 | +| Desktop 不继承代理变量 | 先验证真实代理端口和协议，再把最小变量放进 `~/.codex/.env` 并重启 | | 切换 provider 后旧会话不可见 | 先判断是否是 Desktop 最近 50 条显示限制，再检查 provider metadata 是否需要同步 | | 团队成员行为不一致 | 把项目共同规则写进 `AGENTS.md` | @@ -239,4 +259,6 @@ codex-provider restore - [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) diff --git a/docs/guide/18-troubleshooting.md b/docs/guide/18-troubleshooting.md index 1db4ca5..f174ebc 100644 --- a/docs/guide/18-troubleshooting.md +++ b/docs/guide/18-troubleshooting.md @@ -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:" "https://api.ipify.org?format=json" +``` + +端口和协议都验证通过后，再把最小代理变量放进 `~/.codex/.env`，然后完全退出并重新打开 Codex Desktop： + +```bash +export HTTP_PROXY="http://127.0.0.1:" +export HTTPS_PROXY="http://127.0.0.1:" +export ALL_PROXY="http://127.0.0.1:" +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:", "User") +[Environment]::SetEnvironmentVariable("HTTPS_PROXY", "http://127.0.0.1:", "User") +``` + +如果主界面已经恢复，但 MCP 或 node_repl 仍然断，再检查 MCP server 是否需要单独配置环境变量： + +```toml +[mcp_servers.node_repl.env] +HTTP_PROXY = "http://127.0.0.1:" +HTTPS_PROXY = "http://127.0.0.1:" +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 专项排障库：