From f8d5e34ab1e4b0c5395a3de121256aba33fd2704 Mon Sep 17 00:00:00 2001 From: huangsen Date: Wed, 30 Sep 2026 17:27:00 +0800 Subject: [PATCH] docs(codex): diagnose blocked status panel sandbox loading --- integrations/codex/README.md | 15 +++++++++++++++ integrations/codex/README_ZH.md | 14 ++++++++++++++ 2 files changed, 29 insertions(+) diff --git a/integrations/codex/README.md b/integrations/codex/README.md index 56cb7074..955e741f 100644 --- a/integrations/codex/README.md +++ b/integrations/codex/README.md @@ -220,6 +220,7 @@ address to retry them. Settings changed during consolidation apply to subsequent | Symptom | Check | | --- | --- | | No MCP settings entry | Open the installed ReMe detail and its `reme` MCP card in the latest desktop app; confirm it is enabled and restart. | +| Blank status card followed by a plugin feature loading error | Check network access to the Codex sandbox page; see below. | | Connection healthy, no recording or recall | Review every ReMe Hook; check the auto switches and recent activity. Health does not prove Hook execution. | | Turns stay queued | Check the ReMe model and service logs, keep the session open, and confirm `service.tool_error_on_failure=true`. Retry happens at a later Hook. | | Recall is empty | First confirm the fact exists in `daily/`, use its unique identifier, and inspect `searchLimit` and `recallMinScore`. | @@ -227,6 +228,20 @@ address to retry them. Settings changed during consolidation apply to subsequent | Unknown configuration fields after upgrading | Back up `reme/config.json`, then replace obsolete fields using the current configuration example and reopen MCP settings. Old field names are not supported. | | Python or FastMCP startup error | Check the `python3` environment inherited by Codex, including the desktop app. | +The panel serves its HTML and status data over local MCP, but Codex desktop also loads its own sandbox page. +If the card stays blank and the Codex client logs contain `guest_load_failed`, `ERR_UNEXPECTED`, or +`MCP sandbox RPC timed out`, check access from the machine running Codex: + +```bash +curl -i --max-time 20 https://web-sandbox.oaiusercontent.com/mcp-app.html +``` + +If the response reports a corporate network or security software block, follow its approved process to allow +`web-sandbox.oaiusercontent.com`, including the page's static assets on that domain. Restart Codex and reopen the panel +after access is restored. This loading error alone does not establish whether ReMe or its Hooks are healthy and does +not call for changing `mcpUrl`, clearing memory, or reinstalling the plugin. Meanwhile, ask in a conversation: +“Call `reme_status` and show the returned status as text” to inspect the connection, queue, and consolidation schedule. + Content-free diagnostics are in `${CODEX_HOME:-~/.codex}/reme/hooks.log`; they include event names, counts, and error classes, not conversation content. Pending conversation data is stored separately in that directory until acknowledged. Delivery is best effort: forced termination before local diff --git a/integrations/codex/README_ZH.md b/integrations/codex/README_ZH.md index 0dac40d9..dbaca032 100644 --- a/integrations/codex/README_ZH.md +++ b/integrations/codex/README_ZH.md @@ -207,6 +207,7 @@ Hook 是否可信，需另到 Codex 的 Hooks 设置中检查。 | 现象 | 检查方式 | | --- | --- | | 找不到 MCP 设置 | 在最新版桌面端打开已安装的 ReMe 详情及 `reme` MCP 卡片；确认启用后重启。 | +| 状态卡片空白，随后提示“插件功能未成功加载” | 检查 Codex 沙箱页面的网络访问；见下方说明。 | | 连接健康，但没有记录或召回 | 检查全部 ReMe Hook 的信任状态、自动开关及最近活动；连接健康不代表 Hook 已执行。 | | 记录一直在队列中 | 检查 ReMe 模型配置和服务日志，保持会话运行，并确认 `service.tool_error_on_failure=true`；后续 Hook 会尝试重试。 | | 没有召回结果 | 先确认事实已在 `daily/` 中，使用独立项目名查询，再检查 `searchLimit` 和 `recallMinScore`。 | @@ -214,6 +215,19 @@ Hook 是否可信，需另到 Codex 的 Hooks 设置中检查。 | 升级后提示未知配置字段 | 备份 `reme/config.json`，按当前配置示例替换旧字段，再打开 MCP 设置；不支持旧字段名。 | | Python 或 FastMCP 启动报错 | 检查 Codex 实际继承的 `python3` 环境，尤其是桌面端的启动环境。 | +状态面板通过本地 MCP 提供 HTML 和状态数据，但 Codex 桌面端还需要加载自己的沙箱页面。 +如果卡片空白，且 Codex 客户端日志出现 `guest_load_failed`、`ERR_UNEXPECTED` 或 +`MCP sandbox RPC timed out`，可在运行 Codex 的机器上检查： + +```bash +curl -i --max-time 20 https://web-sandbox.oaiusercontent.com/mcp-app.html +``` + +若响应为公司网络或安全软件的拦截提示，请按其正规流程放行 `web-sandbox.oaiusercontent.com`， +包括该域名下页面所需的静态资源，然后重启 Codex 并重新打开面板。这个加载错误本身不能说明 +ReMe 服务或 Hook 是否正常，也不需要因此修改 `mcpUrl`、清空记忆或重装插件。 +暂时可以在对话中要求“调用 `reme_status`，用文字展示返回的状态”，查看服务连接、队列和整理计划。 + 诊断日志位于 `${CODEX_HOME:-~/.codex}/reme/hooks.log`，仅包含事件名、计数和错误类型，不记录对话正文。 尚未确认写入的对话数据另存于该目录。记录采用尽力交付：本地捕获前强制终止可能丢失轮次， 服务端处理成功但确认丢失时，重试也可能导致重复提取。