Skip to content

👾 Open Computer Use – Open-Source Alternative to Codex Computer Use

chore: improve codex debugging workflow docs

Leo7f742488c82d
diff --git a/README.md b/README.md
index 73178e6..b4fa6f8 100644
--- a/README.md
+++ b/README.md
@@ -94,7 +94,7 @@ go run . call list_apps
如果你想用 `mitmproxy` / `mitmweb` 观察 Codex 自己打到上游的请求,仓库内提供了一个默认脱敏的 addon:
-详细的长期复用方法、后台启动方式和样本沉淀约定,见 [docs/references/codex-network-capture.md](/Users/bytedance/projects/github/open-codex-computer-use/docs/references/codex-network-capture.md)。
+详细的长期复用方法、后台启动方式和样本沉淀约定,见 [docs/references/codex-network-capture.md](./docs/references/codex-network-capture.md)。
如果你只是想快速后台启动一份抓包并让后续 Agent 复用,优先直接用:
@@ -136,6 +136,12 @@ https://chatgpt.com/backend-api/codex/responses
它会先做 `101 Switching Protocols`,随后在 WebSocket 帧里承载 `response.create`、`response.output_text.delta` 等消息。`scripts/codex_dump.py` 会把这些帧按 JSONL 持久化到 `websocket/` 目录里,同时把匹配到的 HTTP 请求写到 `http/` 目录。
+现在脚本还会把当前抓包 `session_id` 对应的 `~/.codex/sessions/rollout-*.jsonl` 摘要一起写到 `local-sessions/`,所以同一个实验目录里可以直接对照看:
+
+- 模型侧的 tool decision
+- Codex 宿主侧的 `function_call`
+- 本地 tool 的 `function_call_output`
+
仓库默认已经把 `artifacts/codex-dumps/` 加进 `.gitignore`,适合把真实抓包样本留在 repo 目录里反复分析,而不误提交到 Git。
## 工程结构
diff --git a/docs/REPO_COLLAB_GUIDE.md b/docs/REPO_COLLAB_GUIDE.md
index b484a15..414841b 100644
--- a/docs/REPO_COLLAB_GUIDE.md
+++ b/docs/REPO_COLLAB_GUIDE.md
@@ -15,6 +15,7 @@
- `AGENTS.md` 只做路由,不要在里面堆一大坨规则。
- `docs/` 是仓库级知识的正式来源。
- 行为一旦变化,对应文档就要在同一次改动里同步更新。
+- 仓库内文件、目录、脚本入口和文档链接一律使用相对路径,不要写任何机器相关的绝对路径。
- 比起继续往大文档里堆内容,更推荐新增一份边界清楚的小文档。
## Git 与评审
diff --git a/docs/histories/2026-04/20260417-1510-nonintrusive-computer-use.md b/docs/histories/2026-04/20260417-1510-nonintrusive-computer-use.md
index 1599a3c..e438317 100644
--- a/docs/histories/2026-04/20260417-1510-nonintrusive-computer-use.md
+++ b/docs/histories/2026-04/20260417-1510-nonintrusive-computer-use.md
@@ -50,3 +50,17 @@
- `plugins/open-computer-use/.codex-plugin/plugin.json`
- `docs/ARCHITECTURE.md`
- `docs/references/codex-network-capture.md`
+
+### 🔬 Follow-up (2026-04-17 17:20)
+
+在继续做 Codex 宿主侧调试时,把“隔离另一套 plugin 再跑 case”正式收进仓库流程:
+
+- **[Isolated Exec Helper]**: 新增 `scripts/run-isolated-codex-exec.sh`,把 `computer-use` / `open-computer-use` / `all` 三种模式收成统一入口,底层通过单次 `codex exec -c 'plugins."...".enabled=false'` 做临时覆写,不改全局 `~/.codex/config.toml`。
+- **[A/B Routing Guidance]**: 在 `docs/references/codex-network-capture.md` 增补“隔离 plugin 路径”章节,明确当需要比较官方和仓库插件时,默认应该关掉另一套,避免 prompt 锚点和共存插件一起污染结论。
+- **[Verification Outcome]**: 这台机器上的隔离验证结果是:只开官方 `computer-use` 时 `list_apps` 正常;只开 `open-computer-use` 时 `list_apps` 仍然返回 `user cancelled MCP tool call`;而 direct JSON-RPC 调用仓库插件 launcher 是正常的,因此当前主瓶颈不是两套 plugin 互相干扰,而更像是 Codex host 对第三方 plugin 调用的 gate。
+
+这一步的价值不只是“跑通一个 shell alias”。之前调试里,`prompt` 文案、插件共存状态和宿主策略混在一起,很容易把路由偏差误判成 runtime 行为差异。把隔离入口收进仓库后,后续做焦点行为对比、MITM 抓样本和 eval 时,至少能先把“到底调用的是谁”固定下来。
+
+**Isolation Files:**
+- `scripts/run-isolated-codex-exec.sh`
+- `docs/references/codex-network-capture.md`
diff --git a/docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md b/docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md
index ff7bffb..d0bc49a 100644
--- a/docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md
+++ b/docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md
@@ -30,3 +30,35 @@ Codex 当前主模型调用走 `chatgpt.com/backend-api/codex/responses` WebSock
- `docs/references/README.md`
- `docs/references/codex-network-capture.md`
- `docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md`
+
+## [2026-04-17 17:50] | Task: 改进 Codex dump script,补充本地 session 摘要
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `GPT-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 改进 `codex_dump.py`,让抓包目录里更容易直接看到正常请求、MCP tool 调用和 tool result。
+
+### 🛠 Changes Overview
+**Scope:** `scripts`、`README.md`、`docs/references`、`docs/histories`
+
+**Key Actions:**
+- **[本地摘要导出]**: 扩展 `scripts/codex_dump.py`,在保留 HTTP / WebSocket dump 的同时,把当前 websocket `session_id` 对应的 `~/.codex/sessions/rollout-*.jsonl` 导出成 `local-sessions/*.json`。
+- **[结构化结果]**: `local-sessions/*.json` 只保留高信号字段,包括 `user_prompts`、`tool_calls`、`function_call_output` 解析结果和 `final_answer`,避免直接复制原始 session JSONL。
+- **[精确匹配]**: 优先用 websocket 握手头里的 `session_id` 精确关联本地 session,避免把同时间窗口内的旧 session 一起扫进当前 dump 目录。
+- **[启动健壮性]**: `scripts/start-codex-mitm-dump.sh` 现在会确认端口真的开始监听后才返回,并把 mitmdump 的 stdin 重定向到 `/dev/null`。
+- **[文档顺序更新]**: 更新 runbook,明确新的默认排查顺序是 `websocket/` -> `local-sessions/` -> `logs_2.sqlite`。
+
+### 🧠 Design Intent (Why)
+用户真正要分析的通常不是“模型决定调用了哪个 tool”这一半,而是“宿主最终把什么 `function_call` 下发给本地 MCP、又收到了什么 `function_call_output`”。把这层摘要直接落进同一个 dump 目录,能显著降低来回切换 `mitm` 样本和 `~/.codex/sessions` 的成本,也更适合做长期 eval 留档。
+
+### 📁 Files Modified
+- `scripts/codex_dump.py`
+- `scripts/start-codex-mitm-dump.sh`
+- `README.md`
+- `docs/references/README.md`
+- `docs/references/codex-network-capture.md`
+- `docs/references/codex-local-runtime-logs.md`
+- `docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md`
diff --git a/docs/histories/2026-04/20260417-1812-normalize-repo-path-links.md b/docs/histories/2026-04/20260417-1812-normalize-repo-path-links.md
new file mode 100644
index 0000000..b601fd8
--- /dev/null
+++ b/docs/histories/2026-04/20260417-1812-normalize-repo-path-links.md
@@ -0,0 +1,25 @@
+## [2026-04-17 18:12] | Task: 清理仓库内绝对路径链接
+
+### 🤖 Execution Context
+* **Agent ID**: `Codex`
+* **Base Model**: `GPT-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 把仓库里写成仓库根绝对路径的目录引用清理掉,改成相对路径,并在 `AGENTS.md` 对应的文档里强调后续只能写相对路径。
+
+### 🛠 Changes Overview
+**Scope:** `README.md`、`docs/REPO_COLLAB_GUIDE.md`、`docs/histories`
+
+**Key Actions:**
+- **[清理链接]**: 把 `README.md` 中指向仓库内 reference 文档的两处绝对路径链接改成相对路径。
+- **[补充约束]**: 在 `docs/REPO_COLLAB_GUIDE.md` 的文档纪律里新增规则,明确仓库内路径引用不得使用机器相关的绝对路径。
+- **[留存变更]**: 新增本次 history,记录路径规范清理的目的和范围。
+
+### 🧠 Design Intent (Why)
+仓库内文档如果写死本机绝对路径,会让链接不可移植,也会把环境偶然性带进仓库知识。把 repo-local 引用统一成相对路径,才能保证换机器、换用户目录、换协作者后仍然稳定可用。
+
+### 📁 Files Modified
+- `README.md`
+- `docs/REPO_COLLAB_GUIDE.md`
+- `docs/histories/2026-04/20260417-1812-normalize-repo-path-links.md`
diff --git a/docs/references/README.md b/docs/references/README.md
index b5a28da..8da9630 100644
--- a/docs/references/README.md
+++ b/docs/references/README.md
@@ -16,8 +16,8 @@
- `codex-computer-use-reverse-engineering/`
- 官方 `Codex Computer Use.app` / `SkyComputerUseClient` 的持续逆向分析资料。
- `codex-network-capture.md`
- - 用 `mitmdump` + `scripts/codex_dump.py` 抓 Codex 上游 HTTP / WebSocket 流量,并把样本沉淀到 `artifacts/codex-dumps/` 做持续分析。
+ - 用 `mitmdump` + `scripts/codex_dump.py` 抓 Codex 上游 HTTP / WebSocket 流量,并把对应 `session_id` 的本地 `function_call` / `function_call_output` 摘要一起沉淀到 `artifacts/codex-dumps/` 做持续分析。
- `codex-local-runtime-logs.md`
- - 当上游 LLM dump 不足以解释本地 tool / MCP 行为时,补查 Codex 本地 `logs_2.sqlite`;默认顺序仍然是先看上游抓包,再看本地日志。
+ - 当抓包目录里的 `websocket/` + `local-sessions/` 仍不足以解释本地 tool / MCP 行为时,再补查 Codex 本地 `logs_2.sqlite`。
- `codex-computer-use-cli.md`
- 仓库内 `scripts/computer-use-cli/` 的用途、使用方法,以及为什么探测官方 bundled `computer-use` 时要优先走 `codex app-server` 代理而不是 direct stdio。
diff --git a/docs/references/codex-local-runtime-logs.md b/docs/references/codex-local-runtime-logs.md
index 97c9d99..f0b4d1e 100644
--- a/docs/references/codex-local-runtime-logs.md
+++ b/docs/references/codex-local-runtime-logs.md
@@ -5,10 +5,11 @@
默认排查顺序应该是:
1. 先看 `docs/references/codex-network-capture.md` 对应的上游 HTTP / WebSocket dump。
-2. 只有当上游样本不足以解释本地 tool 行为时,再查 Codex 本地日志。
-3. 只有当本地日志仍然不够,且确实需要原始 `stdio` JSON-RPC 字节流时,才考虑 wrapper / shadow plugin / 更底层 hook。
+2. 再看同一个 dump 目录里的 `local-sessions/*.json`,这里已经会把当前 `session_id` 对应的 `function_call` / `function_call_output` 摘要一起导出来。
+3. 只有当这两层仍然不足以解释本地 tool 行为时,再查 Codex 本地日志。
+4. 只有当本地日志仍然不够,且确实需要原始 `stdio` JSON-RPC 字节流时,才考虑 wrapper / shadow plugin / 更底层 hook。
-大多数情况下,第 1 步已经足够;这份文档是补充路径,不是默认入口。
+大多数情况下,前 2 步已经足够;这份文档是更深一层的补充路径,不是默认入口。
## 适用场景
@@ -19,19 +20,21 @@
## 为什么需要这条补充路径
-`mitmdump` 抓到的是 Codex 到上游模型服务的 HTTP / WebSocket 流量。它很适合回答:
+`mitmdump` 抓到的是 Codex 到上游模型服务的 HTTP / WebSocket 流量;仓库内增强后的 `scripts/codex_dump.py` 还会顺手把同一个 `session_id` 的本地 session 摘要落到 `local-sessions/*.json`。这两层很适合回答:
- 模型看到了什么上下文。
- 模型何时决定调用某个 tool。
- tool call 在模型协议层长什么样。
+- Codex 宿主最终把什么 `function_call` 分发给了本地 MCP。
+- 本地 tool 返回了什么 `function_call_output`。
-但对于官方 `computer-use` 这种本地 `stdio` MCP,网络抓包看不到:
+但如果你要看的问题更偏宿主内部日志视角,这两层仍然看不到:
-- Codex 宿主与本地 MCP server 的 `stdio` 交换细节。
-- 本地 tool 的宿主侧落盘结果。
-- 某些本地 tool 调用后的完整输出摘要。
+- Codex 宿主与本地 MCP server 的完整 `stdio` 交换字节流。
+- `logs_2.sqlite` 里额外的 host 级事件、错误分类和埋点字段。
+- 某些不在 session JSONL 摘要里的上下文。
-这时补看 Codex 自己的本地日志,通常就足够了。
+这时补看 Codex 自己更底层的本地日志,通常就足够了。
## 主要日志位置
@@ -217,8 +220,9 @@ LIMIT 100;
## 推荐工作流
1. 先按 `docs/references/codex-network-capture.md` 抓上游样本。
-2. 如果上游样本已经能回答问题,就直接在仓库文档里沉淀结论。
-3. 如果问题落在本地 `stdio` MCP / `computer-use` 行为上,再查 `logs_2.sqlite`。
-4. 只有当本地日志仍然不够,才考虑 wrapper / shadow plugin 方案。
+2. 先看同一个 dump 目录里的 `local-sessions/*.json`,确认 `function_call` 和 `function_call_output`。
+3. 如果前两层样本已经能回答问题,就直接在仓库文档里沉淀结论。
+4. 如果问题仍然落在本地 `stdio` MCP / `computer-use` 更深一层的宿主行为上,再查 `logs_2.sqlite`。
+5. 只有当本地日志仍然不够,才考虑 wrapper / shadow plugin 方案。
这个顺序能避免一上来就走高侵入、难维护的拦截路径。
diff --git a/docs/references/codex-network-capture.md b/docs/references/codex-network-capture.md
index ee4ff52..98be13d 100644
--- a/docs/references/codex-network-capture.md
+++ b/docs/references/codex-network-capture.md
@@ -5,9 +5,10 @@
默认排查顺序里,这份文档应该优先于 `docs/references/codex-local-runtime-logs.md`:
- 先看上游 LLM call dump。
-- 只有当上游样本不足以解释本地 tool / MCP 行为时,才补查 Codex 自己的本地日志。
+- 再看同一个 dump 目录里的 `local-sessions/*.json`,确认本地 `function_call` / `function_call_output`。
+- 只有当这两层仍然不足以解释本地 tool / MCP 行为时,才补查 Codex 自己更底层的本地日志。
-尤其是官方 `computer-use` 这类本地 `stdio` MCP,网络抓包通常只能回答“模型侧发生了什么”,不能完整回答“本地 tool 最终收到了什么参数、回了什么结果”;这类问题再切到本地日志路径更合适。
+现在的 `scripts/codex_dump.py` 会利用 websocket 握手里的 `session_id`,把对应的 `~/.codex/sessions/rollout-*.jsonl` 摘要一起落到当前 session 目录里,所以很多关于官方 `computer-use` 的问题,已经不需要第一时间跳去查 `logs_2.sqlite`。
## 适用场景
@@ -95,12 +96,12 @@ codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
session_dir="artifacts/codex-dumps/$(date +%Y%m%d-%H%M%S)-basic-ok"
mkdir -p "$session_dir"
-nohup mitmdump \
+nohup setsid mitmdump \
--listen-host 127.0.0.1 \
--listen-port 8082 \
-s scripts/codex_dump.py \
--set codex_dump_dir="$session_dir" \
- >"$session_dir/mitmdump.log" 2>&1 &
+ </dev/null >"$session_dir/mitmdump.log" 2>&1 &
echo $! >"$session_dir/mitmdump.pid"
```
@@ -163,6 +164,7 @@ https://chatgpt.com/backend-api/codex/responses
artifacts/codex-dumps/<session-name>/
http/
websocket/
+ local-sessions/
```
其中:
@@ -171,11 +173,22 @@ artifacts/codex-dumps/<session-name>/
保存匹配到的 HTTP 请求和响应。
- `websocket/*.jsonl`
按事件逐行保存 WebSocket 开始、消息和结束。
+- `local-sessions/*.json`
+ 从 `~/.codex/sessions/rollout-*.jsonl` 导出的结构化摘要,只保留当前抓包 `session_id` 命中的 user prompt、tool call、tool result 和 final answer。
- `mitmdump.log`
如果用后台方式启动,会包含 mitmdump 自身日志。
- `mitmdump.pid`
如果用后台方式启动,会保存后台进程 PID。
+把这三层串起来看,通常就能直接回答:
+
+- `websocket/`
+ 模型何时决定调用哪个 tool,以及调用参数是什么。
+- `local-sessions/`
+ Codex 宿主实际把哪个 `function_call` 分发给了本地 MCP,以及 `function_call_output` 返回了什么。
+- `http/`
+ 非 websocket 的补充请求,例如 `wham/apps`、plugin/config 初始化等。
+
## 脱敏默认值
仓库内的 `scripts/codex_dump.py` 默认会对以下内容做脱敏:
@@ -205,6 +218,8 @@ artifacts/codex-dumps/<session-name>/
4. 结束后停止 `mitmdump`。
5. 重点分析:
- `websocket/` 里的 `response.create`
+ - `websocket/` 里的 `response.output_item.done`,尤其是 `item.type=="function_call"`
+ - `local-sessions/` 里的对应 `tool_calls[].output`
- `response.output_text.delta`
- `response.completed`
6. 把结论、差异和评估结果沉淀到仓库文档,而不是直接提交原始抓包。
@@ -219,6 +234,7 @@ artifacts/codex-dumps/<session-name>/
- 是否设置了 `SSL_CERT_FILE=$HOME/.mitmproxy/mitmproxy-ca-cert.pem`
- 是否在抓 `chatgpt.com/backend-api/codex/responses`
- 是否只盯着 HTTP,而没有看 `websocket/*.jsonl`
+- 如果要看本地 tool 结果,是否同时检查了 `local-sessions/*.json`
### 2. 为什么不直接抓 `api.openai.com`
@@ -267,3 +283,55 @@ printf '%s\n%s\n%s\n' \
- 插件缓存或安装态没有同步到最新
不要一开始就假设是 MCP server 逻辑本身坏了。先把“宿主问题”和“server 问题”分开,排查成本会低很多。
+
+### 6. 做官方 `computer-use` 和 `open-computer-use` A/B 时,建议显式隔离另一个 plugin
+
+如果两套 plugin 同时启用,prompt 里的 tool 名称锚点会显著影响模型路由。做更纯净的 A/B 时,建议在单次 `codex exec` 上临时关闭另一套 plugin,而不是直接共存跑。
+
+仓库内已经提供 helper:
+
+```bash
+./scripts/run-isolated-codex-exec.sh computer-use --skip-git-repo-check -C /tmp \
+ '使用computer-use列出正在运行的前三个应用'
+
+./scripts/run-isolated-codex-exec.sh open-computer-use --skip-git-repo-check -C /tmp --json \
+ '使用open-computer-use列出正在运行的前三个应用'
+```
+
+它本质上只是给 `codex exec` 增加临时 config override:
+
+- `computer-use`
+ 会加 `-c 'plugins."open-computer-use@open-computer-use-local".enabled=false'`
+- `open-computer-use`
+ 会加 `-c 'plugins."computer-use@openai-bundled".enabled=false'`
+
+这比直接改 `~/.codex/config.toml` 更安全,因为:
+
+- 只影响当前这一条命令。
+- 不需要手工改全局配置后再恢复。
+- 更适合批量 eval 或 Agent 后台脚本。
+
+### 7. 当前这台机器上的隔离验证结论
+
+2026-04-17 的隔离样本已经验证:
+
+1. `-c 'plugins."...".enabled=false'` 这条覆写是生效的。
+2. 只保留官方 `computer-use` 时,`computer-use/list_apps` 可以正常完成。
+3. 只保留 `open-computer-use` 时,`open-computer-use/list_apps` 仍然直接返回 `user cancelled MCP tool call`。
+4. 同时,直接对 `./plugins/open-computer-use/scripts/launch-open-computer-use.sh` 发 JSON-RPC 的 `tools/list` / `tools/call list_apps` 是正常的。
+
+这说明在当前环境里:
+
+- “两套 plugin 互相干扰”不是主要问题。
+- `open-computer-use` MCP server 本身不是这一步的主故障点。
+- 更可能的瓶颈仍然在 Codex host 对第三方 plugin 调用的 gate 或会话策略上。
+
+### 8. 后台 `mitmdump` 显示启动成功,但代理端口很快就没了
+
+先看 `mitmdump.log`。仓库内 `scripts/start-codex-mitm-dump.sh` 现在会额外检查端口是否真的开始监听,但在某些受控 runner / agent 宿主里,父进程结束时仍然可能把后台子进程一起清掉。
+
+如果你遇到这种情况,优先用下面几种更稳的方式:
+
+1. 在真实登录 shell、`tmux` 或单独终端里执行 `./scripts/start-codex-mitm-dump.sh`。
+2. 或者直接前台运行 `mitmdump` / `mitmweb`,再在另一个终端执行 `codex exec`。
+3. 不要把“脚本返回了 PID”误当成“代理一定还活着”,先用 `lsof -nP -iTCP:<port> -sTCP:LISTEN` 确认监听状态。
diff --git a/scripts/codex_dump.py b/scripts/codex_dump.py
index 6fb284b..996d3b3 100644
--- a/scripts/codex_dump.py
+++ b/scripts/codex_dump.py
@@ -3,7 +3,6 @@
from __future__ import annotations
import json
-import os
import re
import tempfile
from datetime import datetime, timezone
@@ -40,6 +39,12 @@ SENSITIVE_JSON_KEYS = {
"cookie",
}
TRUNCATE_PREVIEW_BYTES = 240
+SESSION_TEXT_PREVIEW_BYTES = 4000
+SESSION_MATCH_WINDOW_SECONDS = 6 * 60 * 60
+DEFAULT_SESSION_ROOT = Path.home() / ".codex" / "sessions"
+IGNORED_SESSION_TEXT_PREFIXES = (
+ "<environment_context>",
+)
def _utc_now() -> str:
@@ -77,6 +82,43 @@ def _json_preview(value: Any) -> str:
return text[:TRUNCATE_PREVIEW_BYTES] + "...<truncated>"
+def _truncate_text(value: str, limit: int = SESSION_TEXT_PREVIEW_BYTES) -> str:
+ if len(value) <= limit:
+ return value
+ return value[:limit] + "...<truncated>"
+
+
+def _truncate_nested(value: Any, limit: int = SESSION_TEXT_PREVIEW_BYTES) -> Any:
+ if isinstance(value, dict):
+ return {key: _truncate_nested(item, limit=limit) for key, item in value.items()}
+ if isinstance(value, list):
+ return [_truncate_nested(item, limit=limit) for item in value]
+ if isinstance(value, str):
+ return _truncate_text(value, limit=limit)
+ return value
+
+
+def _normalize_text(value: str) -> str:
+ return re.sub(r"\s+", " ", value).strip()
+
+
+def _extract_text_blocks(content: Any) -> list[str]:
+ if isinstance(content, str):
+ return [content]
+ if not isinstance(content, list):
+ return []
+
+ texts: list[str] = []
+ for item in content:
+ if not isinstance(item, dict):
+ continue
+ for key in ("text", "input_text", "output_text"):
+ value = item.get(key)
+ if isinstance(value, str) and value:
+ texts.append(value)
+ return texts
+
+
class CodexDump:
def __init__(self) -> None:
self.output_dir: Path | None = None
@@ -84,9 +126,16 @@ class CodexDump:
self.path_patterns: list[re.Pattern[str]] = []
self.include_http = True
self.include_ws = True
+ self.include_local_sessions = True
+ self.local_session_root = DEFAULT_SESSION_ROOT
+ self.capture_started_at = datetime.now(timezone.utc)
self._http_counter = 0
self._ws_counter = 0
self._ws_files: dict[str, Path] = {}
+ self._observed_session_ids: set[str] = set()
+ self._observed_prompts: set[str] = set()
+ self._local_session_exports: dict[Path, tuple[str, Path]] = {}
+ self._local_session_counter = 0
def load(self, loader) -> None:
loader.add_option(
@@ -119,6 +168,24 @@ class CodexDump:
default=True,
help="Whether to persist matching WebSocket messages.",
)
+ loader.add_option(
+ name="codex_dump_include_local_sessions",
+ typespec=bool,
+ default=True,
+ help="Whether to export recent ~/.codex/sessions JSONL summaries into the dump directory.",
+ )
+ loader.add_option(
+ name="codex_dump_local_session_root",
+ typespec=str,
+ default=str(DEFAULT_SESSION_ROOT),
+ help="Directory that contains Codex local rollout session JSONL files.",
+ )
+ loader.add_option(
+ name="codex_dump_local_session_window_seconds",
+ typespec=int,
+ default=SESSION_MATCH_WINDOW_SECONDS,
+ help="How far back to scan local session files when exporting summaries.",
+ )
def configure(self, updated) -> None:
hosts = [item.strip() for item in ctx.options.codex_dump_hosts.split(",") if item.strip()]
@@ -127,6 +194,17 @@ class CodexDump:
self.path_patterns = [re.compile(pattern) for pattern in paths]
self.include_http = bool(ctx.options.codex_dump_include_http)
self.include_ws = bool(ctx.options.codex_dump_include_ws)
+ self.include_local_sessions = bool(ctx.options.codex_dump_include_local_sessions)
+ self.capture_started_at = datetime.now(timezone.utc)
+ self._observed_session_ids.clear()
+ self._observed_prompts.clear()
+ self._local_session_exports.clear()
+ self._local_session_counter = 0
+ self._http_counter = 0
+ self._ws_counter = 0
+ self._ws_files.clear()
+ self.local_session_root = Path(ctx.options.codex_dump_local_session_root).expanduser()
+ self.local_session_window_seconds = int(ctx.options.codex_dump_local_session_window_seconds)
if ctx.options.codex_dump_dir:
base_dir = Path(ctx.options.codex_dump_dir).expanduser()
@@ -138,6 +216,8 @@ class CodexDump:
self.output_dir.mkdir(parents=True, exist_ok=True)
(self.output_dir / "http").mkdir(exist_ok=True)
(self.output_dir / "websocket").mkdir(exist_ok=True)
+ if self.include_local_sessions:
+ (self.output_dir / "local-sessions").mkdir(exist_ok=True)
def request(self, flow: http.HTTPFlow) -> None:
if self.include_http and self._matches(flow) and not self._is_ws_upgrade(flow):
@@ -149,6 +229,7 @@ class CodexDump:
self._ws_counter += 1
request = flow.request
+ self._observe_request_session(request)
path_stem = _safe_stem(request.path.split("?", 1)[0].strip("/"))
file_path = self.output_dir / "websocket" / f"{self._ws_counter:03d}-{path_stem}.jsonl"
self._ws_files[flow.id] = file_path
@@ -190,6 +271,7 @@ class CodexDump:
redacted = _redact_json(parsed)
payload["json"] = redacted
payload["preview"] = _json_preview(redacted)
+ self._observe_ws_payload(redacted)
else:
payload["text"] = decoded
payload["preview"] = decoded[:TRUNCATE_PREVIEW_BYTES]
@@ -212,6 +294,10 @@ class CodexDump:
"close_reason": getattr(flow.websocket, "close_reason", None),
}
self._append_jsonl(file_path, payload)
+ self._sync_local_sessions()
+
+ def done(self) -> None:
+ self._sync_local_sessions()
def _matches(self, flow: http.HTTPFlow) -> bool:
request = flow.request
@@ -299,5 +385,244 @@ class CodexDump:
with file_path.open("a", encoding="utf-8") as handle:
handle.write(json.dumps(payload, ensure_ascii=False) + "\n")
+ def _observe_ws_payload(self, payload: Any) -> None:
+ if not isinstance(payload, dict):
+ return
+
+ if payload.get("type") == "response.create":
+ for prompt in self._extract_observed_prompts(payload):
+ normalized = _normalize_text(prompt)
+ if normalized:
+ self._observed_prompts.add(normalized)
+
+ if payload.get("type") == "response.completed":
+ self._sync_local_sessions()
+
+ def _extract_observed_prompts(self, payload: dict[str, Any]) -> list[str]:
+ prompts: list[str] = []
+ for item in payload.get("input", []):
+ if not isinstance(item, dict):
+ continue
+ if item.get("type") != "message" or item.get("role") != "user":
+ continue
+ prompts.extend(_extract_text_blocks(item.get("content")))
+ return prompts
+
+ def _sync_local_sessions(self) -> None:
+ if not self.include_local_sessions or self.output_dir is None:
+ return
+ if self.local_session_root is None or not self.local_session_root.exists():
+ return
+
+ for session_path in sorted(self.local_session_root.rglob("rollout-*.jsonl")):
+ if self._observed_session_ids and not any(session_id in session_path.name for session_id in self._observed_session_ids):
+ continue
+ try:
+ stat = session_path.stat()
+ except OSError:
+ continue
+
+ age_seconds = (self.capture_started_at.timestamp() - stat.st_mtime)
+ if age_seconds > self.local_session_window_seconds:
+ continue
+
+ signature = f"{stat.st_mtime_ns}:{stat.st_size}"
+ existing = self._local_session_exports.get(session_path)
+ if existing is not None and existing[0] == signature:
+ continue
+
+ summary = self._summarize_local_session(session_path)
+ if summary is None or not self._session_matches_capture(summary):
+ continue
+
+ if existing is None:
+ self._local_session_counter += 1
+ session_id = summary.get("session", {}).get("id") or session_path.stem
+ export_path = self.output_dir / "local-sessions" / f"{self._local_session_counter:03d}-{_safe_stem(session_id)}.json"
+ else:
+ export_path = existing[1]
+
+ export_path.write_text(json.dumps(summary, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ self._local_session_exports[session_path] = (signature, export_path)
+ ctx.log.info(f"codex_dump local_session -> {export_path}")
+
+ def _summarize_local_session(self, session_path: Path) -> dict[str, Any] | None:
+ try:
+ raw_lines = session_path.read_text(encoding="utf-8").splitlines()
+ except OSError:
+ return None
+
+ session_meta: dict[str, Any] = {}
+ user_prompts: list[str] = []
+ tool_calls: list[dict[str, Any]] = []
+ tool_call_index: dict[str, dict[str, Any]] = {}
+ final_answers: list[str] = []
+
+ for raw_line in raw_lines:
+ try:
+ entry = json.loads(raw_line)
+ except json.JSONDecodeError:
+ continue
+
+ entry_type = entry.get("type")
+ payload = entry.get("payload")
+
+ if entry_type == "session_meta" and isinstance(payload, dict):
+ session_meta = {
+ "id": payload.get("id"),
+ "timestamp": payload.get("timestamp"),
+ "cwd": payload.get("cwd"),
+ "originator": payload.get("originator"),
+ "cli_version": payload.get("cli_version"),
+ "source": payload.get("source"),
+ "model_provider": payload.get("model_provider"),
+ }
+ continue
+
+ if entry_type != "response_item" or not isinstance(payload, dict):
+ continue
+
+ payload_type = payload.get("type")
+
+ if payload_type == "message":
+ role = payload.get("role")
+ texts = _extract_text_blocks(payload.get("content"))
+ if role == "user":
+ for text in texts:
+ if not any(text.startswith(prefix) for prefix in IGNORED_SESSION_TEXT_PREFIXES):
+ user_prompts.append(text)
+ if role == "assistant" and payload.get("phase") == "final_answer":
+ final_answers.extend(texts)
+ continue
+
+ if payload_type == "function_call":
+ call = {
+ "timestamp": entry.get("timestamp"),
+ "call_id": payload.get("call_id"),
+ "namespace": payload.get("namespace"),
+ "name": payload.get("name"),
+ "arguments": self._parse_function_arguments(payload.get("arguments")),
+ }
+ tool_calls.append(call)
+ call_id = payload.get("call_id")
+ if isinstance(call_id, str) and call_id:
+ tool_call_index[call_id] = call
+ continue
+
+ if payload_type == "function_call_output":
+ output_summary = {
+ "timestamp": entry.get("timestamp"),
+ "result": self._parse_function_output(payload.get("output")),
+ }
+ call_id = payload.get("call_id")
+ existing_call = tool_call_index.get(call_id) if isinstance(call_id, str) else None
+ if existing_call is not None:
+ existing_call["output"] = output_summary
+ else:
+ tool_calls.append(
+ {
+ "timestamp": entry.get("timestamp"),
+ "call_id": call_id,
+ "output": output_summary,
+ }
+ )
+
+ unique_prompts = []
+ seen_prompts: set[str] = set()
+ for prompt in user_prompts:
+ normalized = _normalize_text(prompt)
+ if not normalized or normalized in seen_prompts:
+ continue
+ seen_prompts.add(normalized)
+ unique_prompts.append(prompt)
+
+ final_answer = "\n".join(text for text in final_answers if text).strip()
+
+ return {
+ "captured_at": _utc_now(),
+ "source_path": str(session_path),
+ "session": session_meta,
+ "user_prompts": [_truncate_text(text) for text in unique_prompts],
+ "tool_calls": tool_calls,
+ "final_answer": _truncate_text(final_answer) if final_answer else None,
+ }
+
+ def _session_matches_capture(self, summary: dict[str, Any]) -> bool:
+ if self._observed_prompts:
+ session_prompts = [_normalize_text(item) for item in summary.get("user_prompts", []) if isinstance(item, str)]
+ for session_prompt in session_prompts:
+ if not session_prompt:
+ continue
+ for observed_prompt in self._observed_prompts:
+ if session_prompt in observed_prompt or observed_prompt in session_prompt:
+ summary["matched_prompt"] = _truncate_text(session_prompt)
+ return True
+ return False
+
+ session_meta = summary.get("session")
+ if not isinstance(session_meta, dict):
+ return False
+
+ session_id = session_meta.get("id")
+ if self._observed_session_ids:
+ return isinstance(session_id, str) and session_id in self._observed_session_ids
+
+ timestamp = session_meta.get("timestamp")
+ if not isinstance(timestamp, str):
+ return False
+
+ try:
+ session_time = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
+ except ValueError:
+ return False
+
+ delta = abs((session_time - self.capture_started_at).total_seconds())
+ return delta <= self.local_session_window_seconds
+
+ def _observe_request_session(self, request: http.Request) -> None:
+ for header_name in ("session_id", "x-client-request-id"):
+ value = request.headers.get(header_name)
+ if isinstance(value, str) and value:
+ self._observed_session_ids.add(value)
+
+ metadata = request.headers.get("x-codex-turn-metadata")
+ if not isinstance(metadata, str) or not metadata:
+ return
+
+ parsed = self._try_parse_json(metadata)
+ if not isinstance(parsed, dict):
+ return
+
+ session_id = parsed.get("session_id")
+ if isinstance(session_id, str) and session_id:
+ self._observed_session_ids.add(session_id)
+
+ def _parse_function_arguments(self, arguments: Any) -> Any:
+ if not isinstance(arguments, str):
+ return _truncate_nested(_redact_json(arguments))
+ parsed = self._try_parse_json(arguments)
+ if parsed is not None:
+ return _truncate_nested(_redact_json(parsed))
+ return _truncate_text(arguments)
+
+ def _parse_function_output(self, output: Any) -> Any:
+ if not isinstance(output, str):
+ return _truncate_nested(_redact_json(output))
+
+ match = re.match(r"^Wall time:\s*([0-9.]+)\s+seconds\nOutput:\n(.*)$", output, flags=re.DOTALL)
+ if match is None:
+ return {"text": _truncate_text(output)}
+
+ result: dict[str, Any] = {
+ "wall_time_seconds": float(match.group(1)),
+ }
+ body = match.group(2)
+ parsed = self._try_parse_json(body)
+ if parsed is not None:
+ result["output"] = _truncate_nested(_redact_json(parsed))
+ else:
+ result["text"] = _truncate_text(body)
+ return result
+
addons = [CodexDump()]
diff --git a/scripts/run-isolated-codex-exec.sh b/scripts/run-isolated-codex-exec.sh
new file mode 100755
index 0000000..063c09c
--- /dev/null
+++ b/scripts/run-isolated-codex-exec.sh
@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+ cat <<'EOF' >&2
+Usage:
+ ./scripts/run-isolated-codex-exec.sh <computer-use|open-computer-use|all> [codex exec args...]
+
+Examples:
+ ./scripts/run-isolated-codex-exec.sh computer-use --skip-git-repo-check -C /tmp '使用computer-use列出正在运行的前三个应用'
+ ./scripts/run-isolated-codex-exec.sh open-computer-use --skip-git-repo-check -C /tmp --json '使用open-computer-use列出正在运行的前三个应用'
+ ./scripts/run-isolated-codex-exec.sh all --skip-git-repo-check -C /tmp 'reply with one word: ok'
+EOF
+ exit 1
+fi
+
+mode="$1"
+shift
+
+declare -a overrides=()
+
+case "${mode}" in
+ computer-use)
+ overrides=(-c 'plugins."open-computer-use@open-computer-use-local".enabled=false')
+ ;;
+ open-computer-use)
+ overrides=(-c 'plugins."computer-use@openai-bundled".enabled=false')
+ ;;
+ all)
+ ;;
+ *)
+ echo "Unsupported mode: ${mode}" >&2
+ echo "Expected one of: computer-use, open-computer-use, all" >&2
+ exit 1
+ ;;
+esac
+
+exec codex exec "${overrides[@]}" "$@"
diff --git a/scripts/start-codex-mitm-dump.sh b/scripts/start-codex-mitm-dump.sh
index cbeaf39..903562e 100755
--- a/scripts/start-codex-mitm-dump.sh
+++ b/scripts/start-codex-mitm-dump.sh
@@ -72,17 +72,31 @@ export NO_PROXY="127.0.0.1,localhost"
export SSL_CERT_FILE="${ca_cert}"
EOF
-nohup mitmdump \
+launcher=(nohup)
+if command -v setsid >/dev/null 2>&1; then
+ launcher+=(setsid)
+fi
+launcher+=(mitmdump)
+
+"${launcher[@]}" \
--listen-host "${listen_host}" \
--listen-port "${listen_port}" \
-s "${addon_script}" \
--set codex_dump_dir="${session_dir}" \
- >"${log_path}" 2>&1 &
+ </dev/null >"${log_path}" 2>&1 &
pid=$!
echo "${pid}" >"${pid_path}"
-sleep 1
+for _ in $(seq 1 20); do
+ if ! kill -0 "${pid}" >/dev/null 2>&1; then
+ break
+ fi
+ if lsof -nP -iTCP:"${listen_port}" -sTCP:LISTEN >/dev/null 2>&1; then
+ break
+ fi
+ sleep 0.25
+done
if ! kill -0 "${pid}" >/dev/null 2>&1; then
echo "mitmdump 启动失败,最近日志:" >&2
@@ -92,6 +106,14 @@ if ! kill -0 "${pid}" >/dev/null 2>&1; then
exit 1
fi
+if ! lsof -nP -iTCP:"${listen_port}" -sTCP:LISTEN >/dev/null 2>&1; then
+ echo "mitmdump 进程已启动,但端口 ${listen_port} 尚未开始监听。" >&2
+ if [[ -f "${log_path}" ]]; then
+ tail -n 40 "${log_path}" >&2
+ fi
+ exit 1
+fi
+
cat <<EOF
mitmdump 已后台启动。