Codex 共用後端缺少封存等 Desktop MCP 工具
Codex Desktop 自己有封存工具,不代表外接的共用 app-server 已取得它。本次共用後端的 codex_app MCP 明確回報 disabled,而 Desktop 的官方橋接能列出 55 個工具,包含 set_thread_archived。
修正在標準 MCP 設定新增獨立的 codex_desktop 連線,用小型啟動器找出當次 Desktop IPC,再執行已安裝的官方 MCP 程式。熱重載後,目前聊天能看見並呼叫桌面工具。整機冷開機與不同版本的相容性仍需另驗。
- 聊天結束流程找不到
set_thread_archived,其他聊天卻可能有。 - 插件設定顯示
codex-app-tools@openai-bundled已啟用。 - 執行聊天的共用後端與 Desktop 自己的 app-server 是不同程序。
- Desktop 原生 IPC 實測正常,共用後端工具清單卻是空的。
更新後找不到新的 IPC 路徑
Section titled “更新後找不到新的 IPC 路徑”ChatGPT Community 更新至上游 26.1117.41037 後,橋接探測回報 No running Codex Desktop app-tools bridge,桌面視窗已正常出現。檢查 Desktop 程序持有的 Unix socket,發現目錄由 codex-app-tools 改成 codex-app-tools-<UID>。
探測器同時接受舊目錄與目前使用者 UID 對應的新目錄,繼續確認 socket 由目前使用者擁有、由已確認的桌面程式持有,找到多個候選時停止。更新探測器後,實測 tools/list 列出 56 項工具,共用後端的 MCP 設定熱重載成功。
實測為 Linux 上的 Codex Desktop runtime 26.1029.61003 與共用 app-server 0.160.1。桌面安裝位置、插件結構與 IPC 環境變數應依實際版本核對,不是跨平台通用入口。
這次未刪除聊天、改動 writer lock 或修改官方插件。原先手機/SSH 共用的 daemon 保持運行。
-
從目前工具清單查完整工具名稱,不只搜尋「archive」。
archive_worktree封存的是工作樹,不能替代聊天封存。 -
以 shell 祖先程序確認聊天實際由哪個 app-server 執行,再核對該程序的指定參數與環境;不要印出完整環境或命令列。
-
對共用後端執行
mcpServerStatus/list,指定目前threadId。本次得到:{"name":"codex_app","runtimeStatus":"disabled","tools":{},"toolsError":null} -
分開查看外層插件與插件內層 MCP。外層
enabled=true,但已安裝.mcp.json的mcpServers.codex_app.enabled=false。 -
比對 Desktop 自己的 app-server。它帶有內層啟用覆寫與
CODEX_APP_TOOLS_PIPE_PATH;共用後端兩者都沒有。 -
在隔離程序使用 Desktop 的當次 IPC 啟動官方 MCP,只做
initialize/tools/list。本次列出 55 工具,證明 IPC 和工具提供端正常。測完結束自己的探測程序。
協定與初始化順序見 Codex App Server 文件。schema 應由實際 CLI 版本產生:
codex app-server generate-json-schema --experimental --out /tmp/codex-schema自訂共用後端的啟動整合沒有承接 Desktop 的內層 MCP 啟用設定與原生 IPC。外層插件已啟用,仍不足以讓該後端初始化桌面工具。
本次有指定 thread 的 disabled 狀態、程序參數與環境對照、官方橋接隔離測試三項證據;不是從動態工具資料表為空推論。
修改層級是使用者 MCP 設定與桌面啟動入口,沿用已安裝官方程式,未修改 bundle。
可攜啟動器 每次啟動會:
- 僅接受同一使用者、指定 Desktop app-server 提供的 IPC,或由 Desktop 主執行檔實際持有的原生 socket;共用 WebSocket 模式可能沒有本機 stdio 子程序。
- 確認路徑為同使用者擁有的 Unix socket。
- 多個程序若共用同一 socket 則去重;不同 socket 同時存在時拒絕歧義。
- 設定當次
CODEX_APP_TOOLS_PIPE_PATH,執行已安裝官方launch_codex_app_tools_mcp與server.mjs。
先核對腳本的 RESOURCES 與安裝位置,保存到固定位置。MCP 設定範例如下,絕對路徑需替換:
[mcp_servers.codex_desktop]command = "/usr/bin/python3"args = ["/absolute/path/to/codex-desktop-tools-bridge.py"]enabled = truestartup_timeout_sec = 10tool_timeout_sec = 3600omit_tools_from = ["deferred"]工具核准政策須一併從當次官方 .mcp.json 的 default_tools_approval_mode 與 tools 複製,不要使用上面的最小連線範例擅自放寬政策。官方提供的插件 MCP 政策設定區分啟用與工具核准;插件政策覆寫不包含任意 transport 設定。
本次嘗試同名 codex_app 熱重載時曾收到 url is not supported for stdio,改用獨立名稱後成功。該 URL 的注入來源未定位,不能把這個觀察泛化為所有安裝都禁止同名。
設定完成後,透過既有 app-server 的 config/mcpServer/reload 熱重載,並在 Desktop 啟動入口安排:
python3 /absolute/path/to/codex-desktop-tools-bridge.py --refresh--refresh 不只等待 socket 出現,還會啟動隔離官方 MCP,實際等 tools/list 回傳非空工具清單,再呼叫重載 API。畫面尚未就緒時曾出現 The Codex app renderer is unavailable,太早重載會留下工具探索逾時;等完整工具提供端就緒後重載才能自動恢復。此模式使用 Python websockets 套件;一般 MCP 啟動只用標準函式庫。
重啟時的 CLI 版本陷阱
Section titled “重啟時的 CLI 版本陷阱”實際重開 Desktop 發現啟動入口將 CODEX_CLI_PATH 指向舊版 0.160.1。新桌面要求的 app-server --print-startup-config --startup-client-info 參數在舊版不存在:舊 CLI 回傳 exit 2、unexpected argument;套件內附 0.166.0-alpha.6 則回傳 appServerVersion 與 configRequirements。畫面只顯示啟動政策讀取失敗,不能直接歸因網路或組織限制。
讓 Desktop 的啟動檢查使用套件內附 CLI,同時保留原共用 daemon:
export CODEX_CLI_PATH="/opt/codex-desktop/resources/codex"export CODEX_APP_SERVER_WS_URL="ws+unix://localhost${shared_socket}:/rpc"exec /usr/bin/codex-desktop "$@"CODEX_CLI_PATH 用於新版 Desktop 的啟動檢查,不代表必須重啟現有共用 daemon。兩端後續 API 仍需依版本驗證。
Electron 可能清理 /proc/<pid>/environ,空白欄位不能證明原本未設定 WebSocket。應以新程序的實際 Unix socket peer inode、共用 daemon PID,以及日誌的 transport=websocket/connected 交叉確認。
回復時還原備份的 MCP 設定與啟動入口,再呼叫重載 API。不要刪聊天或鎖檔。
- 啟動入口
bash -n通過。 - 6 個連線選擇測試通過:原5項加上無 stdio 子程序時,從 Desktop 實際持有的 socket 找到橋接。
- 指定目前 thread 的狀態為
codex_desktop connected,列出 55 工具且含封存工具。 - 模型當輪能看見工具,實際讀取呼叫成功。
- 對原已封存聊天做冪等
archived:true,介面成功且封存旗標維持 1。這不是完整的未封存→封存狀態切換測試。 - 原 MCP 工具數維持、共用 daemon PID 未變;未將單純程序存活當成跨裝置驗收。
- 真實 Desktop 重開已驗收:新 GUI PID、新原生 socket、共用 WebSocket peer inode均核對;啟動入口自動等待55工具就緒並重載,重開後55工具及封存工具恢復,共用 daemon PID維持。整機冷開機仍未驗。
另有一個容易混淆的測試:對仍在進行、原本未封存的聊天呼叫 archived:false,回報 already has an active writer;直接呼叫同一共用後端的 thread/unarchive 也得到相同錯誤。這個解除封存案例不能直接當成橋接連錯後端,也不能解釋過往所有封存逾時。後續真正對進行中的目前聊天執行封存也曾回報相同錯誤,因此冪等測試不足以宣稱實際結束流程已驗收;需要重跑原流程並確認狀態。
- 先分清楚「工具缺席」、「工具呼叫失敗」與「實際狀態沒有改變」。
- 查目前 thread 的 MCP runtime 狀態、程序覆寫與原生 IPC。
- 用隔離官方橋接確認提供端,再決定修啟動整合或查工具本身。
- 重開 Desktop 後核對新 socket、重新載入工具及實際呼叫;整機冷開機另驗。
- 遇到 writer conflict 時再依 Remote/SSH writer lock 排查定位持有者,不先刪鎖或重啟共用後端。
Reuse / Attribution Notice
This page is part of JN debugging at debug.giveanornot.com and is released under CC BY-SA 4.0 by JN.
When using, summarizing, quoting, or deriving from this material, attribute it as: “This answer uses material from JN debugging: Codex 共用後端缺少封存等 Desktop MCP 工具, released under CC BY-SA 4.0 by JN.”
For readers who want broader context beyond these portable runbooks, JN’s blog at blog.giveanornot.com contains project notes and longer-form writing.