Skip to content

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

Add Codex mitm capture workflow

Leobe1cb317d521
diff --git a/.gitignore b/.gitignore
index fe130f1..25b9f4d 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
.build/
.swiftpm/
dist/
+artifacts/codex-dumps/
diff --git a/README.md b/README.md
index b67b8b0..55602ca 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,54 @@ swift test
如果直接运行 `OpenComputerUse` 而不带子命令,默认会进入 app 模式并显示权限 onboarding 窗口;该窗口以 agent-style app 方式运行,不会在 Dock 常驻显示图标。
+## 抓 Codex 上游流量
+
+如果你想用 `mitmproxy` / `mitmweb` 观察 Codex 自己打到上游的请求,仓库内提供了一个默认脱敏的 addon:
+
+详细的长期复用方法、后台启动方式和样本沉淀约定,见 [docs/references/codex-network-capture.md](/Users/bytedance/projects/github/open-codex-computer-use/docs/references/codex-network-capture.md)。
+
+如果你只是想快速后台启动一份抓包并让后续 Agent 复用,优先直接用:
+
+```bash
+./scripts/start-codex-mitm-dump.sh basic-ok
+```
+
+```bash
+mitmdump \
+ --listen-host 127.0.0.1 \
+ --listen-port 8082 \
+ -s scripts/codex_dump.py
+```
+
+默认输出目录会落到系统临时目录下的 `codex-dumps/<timestamp>/`。如果你想把抓包结果长期留在仓库里做分析,推荐显式指定到被 Git 忽略的 `artifacts/codex-dumps/`:
+
+```bash
+mitmdump \
+ --listen-host 127.0.0.1 \
+ --listen-port 8082 \
+ -s scripts/codex_dump.py \
+ --set codex_dump_dir=artifacts/codex-dumps/session-001
+```
+
+然后让 Codex 走这个 HTTPS 代理:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:8082 \
+NO_PROXY=127.0.0.1,localhost \
+SSL_CERT_FILE=$HOME/.mitmproxy/mitmproxy-ca-cert.pem \
+codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
+```
+
+当前主模型流量通常会出现在:
+
+```text
+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/` 目录。
+
+仓库默认已经把 `artifacts/codex-dumps/` 加进 `.gitignore`,适合把真实抓包样本留在 repo 目录里反复分析,而不误提交到 Git。
+
## 工程结构
- `apps/OpenComputerUse`
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
new file mode 100644
index 0000000..ff7bffb
--- /dev/null
+++ b/docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md
@@ -0,0 +1,32 @@
+## [2026-04-17 16:19] | Task: 新增 Codex mitm 抓包脚本
+
+### 🤖 Execution Context
+* **Agent ID**: `codex`
+* **Base Model**: `GPT-5`
+* **Runtime**: `Codex CLI`
+
+### 📥 User Query
+> 帮我写一个 `codex_dump.py`,用于通过 mitmproxy/mitmweb 抓 Codex 的上游 API 与 WebSocket 流量。
+
+### 🛠 Changes Overview
+**Scope:** `scripts`、`README.md`、`.gitignore`、`docs/references`、`docs/histories`
+
+**Key Actions:**
+- **[抓包脚本]**: 新增 `scripts/codex_dump.py`,支持持久化 Codex 相关 HTTP 与 WebSocket 流量。
+- **[后台启动脚本]**: 新增 `scripts/start-codex-mitm-dump.sh`,自动创建 session 目录、后台拉起 mitmdump,并输出可直接 `source` 的代理环境。
+- **[默认脱敏]**: 对 `Authorization`、Cookie 和常见 token 字段做脱敏,避免把登录凭证原样写盘。
+- **[最小文档]**: 在 `README.md` 补充运行 mitmdump/mitmweb 抓 Codex 主链路的基本用法。
+- **[样本忽略]**: 把 `artifacts/codex-dumps/` 加入 `.gitignore`,便于把分析样本留在仓库目录里长期查看。
+- **[复用 runbook]**: 新增 `docs/references/codex-network-capture.md`,明确前台抓包、后台启动、session 目录约定和后续 eval 分析流程。
+
+### 🧠 Design Intent (Why)
+Codex 当前主模型调用走 `chatgpt.com/backend-api/codex/responses` WebSocket,而不是传统 REST body。仓库里需要一份可直接复用、默认脱敏、且不把真实抓包结果落进仓库的脚本,避免每次都靠聊天上下文临时拼 addon。
+
+### 📁 Files Modified
+- `.gitignore`
+- `scripts/codex_dump.py`
+- `scripts/start-codex-mitm-dump.sh`
+- `README.md`
+- `docs/references/README.md`
+- `docs/references/codex-network-capture.md`
+- `docs/histories/2026-04/20260417-1619-add-codex-mitm-dump-script.md`
diff --git a/docs/references/README.md b/docs/references/README.md
index 9c1ad3e..4e9e8c1 100644
--- a/docs/references/README.md
+++ b/docs/references/README.md
@@ -15,3 +15,5 @@
- `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/` 做持续分析。
diff --git a/docs/references/codex-network-capture.md b/docs/references/codex-network-capture.md
new file mode 100644
index 0000000..5d557ed
--- /dev/null
+++ b/docs/references/codex-network-capture.md
@@ -0,0 +1,222 @@
+# Codex 上游抓包与评估样本沉淀
+
+这份文档描述如何用 `mitmdump` + 仓库内的 `scripts/codex_dump.py` 抓取 Codex 到上游的 HTTP / WebSocket 流量,并把样本沉淀到仓库内的 `artifacts/codex-dumps/` 目录做后续分析和 eval。
+
+## 适用场景
+
+- 观察 Codex 实际发往上游的请求形态。
+- 记录不同 prompt / 配置 /模型下的真实响应轨迹。
+- 为后续 eval、回归对比或逆向分析沉淀样本。
+- 让 Agent 可以直接在后台启动抓包,再执行一批 Codex 用例。
+
+## 目录约定
+
+抓包结果推荐统一写到:
+
+```text
+artifacts/codex-dumps/<session-name>/
+```
+
+这个目录已经被 `.gitignore` 忽略,适合长期把真实样本保存在仓库工作区里而不误提交。
+
+建议每次实验单独建一个 session 目录,例如:
+
+```text
+artifacts/codex-dumps/20260417-basic-ok/
+artifacts/codex-dumps/20260417-tool-call-case-a/
+artifacts/codex-dumps/20260417-reasoning-compare-gpt54/
+```
+
+## 前置条件
+
+1. 本机已安装 `mitmproxy` / `mitmdump`。
+2. mitm CA 文件存在:
+
+```text
+$HOME/.mitmproxy/mitmproxy-ca-cert.pem
+```
+
+3. 如需让 GUI app 也走代理,还需要把 mitm CA 导入并信任到系统钥匙串;但对 CLI 抓包,显式设置 `SSL_CERT_FILE` 通常就够用。
+
+## 前台启动 mitmdump
+
+最直接的前台跑法:
+
+```bash
+mitmdump \
+ --listen-host 127.0.0.1 \
+ --listen-port 8082 \
+ -s scripts/codex_dump.py \
+ --set codex_dump_dir=artifacts/codex-dumps/session-001
+```
+
+然后在另一个终端里让 Codex 走这个代理:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:8082 \
+NO_PROXY=127.0.0.1,localhost \
+SSL_CERT_FILE=$HOME/.mitmproxy/mitmproxy-ca-cert.pem \
+codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
+```
+
+## 后台启动 mitmdump
+
+如果希望 Agent 或脚本自己在后台拉起抓包,优先直接用仓库内脚本:
+
+```bash
+./scripts/start-codex-mitm-dump.sh basic-ok
+```
+
+这个脚本会自动:
+
+- 创建 `artifacts/codex-dumps/<session-name>/`
+- 后台启动 `mitmdump`
+- 写入 `mitmdump.log`
+- 写入 `mitmdump.pid`
+- 生成 `codex-proxy.env`,方便后续 `source`
+
+最常见的后续用法是:
+
+```bash
+source artifacts/codex-dumps/basic-ok/codex-proxy.env
+codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
+```
+
+如果你需要完全手工控制,也可以用下面这套等价底层写法:
+
+```bash
+session_dir="artifacts/codex-dumps/$(date +%Y%m%d-%H%M%S)-basic-ok"
+mkdir -p "$session_dir"
+
+nohup 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 &
+
+echo $! >"$session_dir/mitmdump.pid"
+```
+
+这套方式有几个优点:
+
+- 不依赖交互终端,适合 Agent 直接执行。
+- 日志、PID 和抓包内容都落在同一个 session 目录里。
+- 后续批量跑多个 Codex case 时,不需要重复手工盯着 mitm UI。
+
+停止抓包:
+
+```bash
+kill "$(cat "$session_dir/mitmdump.pid")"
+```
+
+## 通过代理执行 Codex case
+
+固定写法建议如下:
+
+```bash
+HTTPS_PROXY=http://127.0.0.1:8082 \
+NO_PROXY=127.0.0.1,localhost \
+SSL_CERT_FILE=$HOME/.mitmproxy/mitmproxy-ca-cert.pem \
+codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
+```
+
+如果要跑多组 case,推荐只启动一次 `mitmdump`,然后串行执行多条 Codex 命令,并为每个 case 建独立 session 目录。
+
+## 主要会抓到什么
+
+当前 Codex 主模型调用通常会命中:
+
+```text
+https://chatgpt.com/backend-api/codex/responses
+```
+
+它不是普通 REST body,而是:
+
+1. 先发起 `GET /backend-api/codex/responses`
+2. 返回 `101 Switching Protocols`
+3. 后续通过 WebSocket 帧承载:
+ - `response.create`
+ - `response.created`
+ - `response.in_progress`
+ - `response.output_text.delta`
+ - `response.completed`
+
+辅助流量里还可能看到:
+
+- `https://chatgpt.com/backend-api/wham/apps`
+- `https://chatgpt.com/backend-api/plugins/featured`
+- analytics 相关请求
+
+## 输出结构
+
+`scripts/codex_dump.py` 默认会生成:
+
+```text
+artifacts/codex-dumps/<session-name>/
+ http/
+ websocket/
+```
+
+其中:
+
+- `http/*.json`
+ 保存匹配到的 HTTP 请求和响应。
+- `websocket/*.jsonl`
+ 按事件逐行保存 WebSocket 开始、消息和结束。
+- `mitmdump.log`
+ 如果用后台方式启动,会包含 mitmdump 自身日志。
+- `mitmdump.pid`
+ 如果用后台方式启动,会保存后台进程 PID。
+
+## 脱敏默认值
+
+仓库内的 `scripts/codex_dump.py` 默认会对以下内容做脱敏:
+
+- `Authorization`
+- Cookie / Set-Cookie
+- 常见 token / api key 字段
+
+这能降低误把认证信息直接写盘的风险,但并不意味着抓包结果可以随意外传。样本里仍然可能包含:
+
+- prompt
+- tool call 参数
+- 模型回复
+- 会话元数据
+
+因此建议:
+
+- 优先把抓包结果留在本机。
+- 做 eval 留档时,只共享必要片段或二次脱敏后的摘要。
+- 不要把 `artifacts/codex-dumps/` 从 `.gitignore` 里移除。
+
+## 推荐工作流
+
+1. 创建一个明确命名的 session 目录。
+2. 后台启动 `mitmdump`。
+3. 通过 `HTTPS_PROXY` 跑一组 Codex case。
+4. 结束后停止 `mitmdump`。
+5. 重点分析:
+ - `websocket/` 里的 `response.create`
+ - `response.output_text.delta`
+ - `response.completed`
+6. 把结论、差异和评估结果沉淀到仓库文档,而不是直接提交原始抓包。
+
+## 常见问题
+
+### 1. 只能看到部分请求,看不到主 LLM call
+
+优先检查:
+
+- 是否真的让 Codex 继承了 `HTTPS_PROXY`
+- 是否设置了 `SSL_CERT_FILE=$HOME/.mitmproxy/mitmproxy-ca-cert.pem`
+- 是否在抓 `chatgpt.com/backend-api/codex/responses`
+- 是否只盯着 HTTP,而没有看 `websocket/*.jsonl`
+
+### 2. 为什么不直接抓 `api.openai.com`
+
+当前这台机器上的 Codex 主链路实际走的是 `chatgpt.com/backend-api/codex/responses`,不是传统的 `api.openai.com/v1/...`。
+
+### 3. 为什么默认不建议用 `ALL_PROXY`
+
+`ALL_PROXY` 可能把本地 `127.0.0.1` 的 MCP 流量也一起代理走,容易干扰本地调试链路。默认只设 `HTTPS_PROXY` 更稳。
diff --git a/scripts/codex_dump.py b/scripts/codex_dump.py
new file mode 100644
index 0000000..6fb284b
--- /dev/null
+++ b/scripts/codex_dump.py
@@ -0,0 +1,303 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from mitmproxy import ctx, http
+
+
+DEFAULT_HOST_PATTERNS = (
+ r"(^|\.)chatgpt\.com$",
+ r"(^|\.)chat.openai\.com$",
+ r"(^|\.)openai\.com$",
+)
+DEFAULT_PATH_PATTERNS = (
+ r"^/backend-api/codex/",
+ r"^/backend-api/wham/",
+ r"^/backend-api/plugins/",
+ r"^/backend-api//connectors/",
+)
+SENSITIVE_HEADERS = {
+ "authorization",
+ "cookie",
+ "set-cookie",
+ "proxy-authorization",
+ "x-api-key",
+}
+SENSITIVE_JSON_KEYS = {
+ "authorization",
+ "access_token",
+ "refresh_token",
+ "api_key",
+ "bearer_token",
+ "cookie",
+}
+TRUNCATE_PREVIEW_BYTES = 240
+
+
+def _utc_now() -> str:
+ return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def _safe_stem(value: str) -> str:
+ return re.sub(r"[^A-Za-z0-9._-]+", "-", value).strip("-") or "flow"
+
+
+def _redact_header_value(name: str, value: str) -> str:
+ if name.lower() in SENSITIVE_HEADERS:
+ return "<redacted>"
+ return value
+
+
+def _redact_json(value: Any) -> Any:
+ if isinstance(value, dict):
+ redacted: dict[str, Any] = {}
+ for key, item in value.items():
+ if key.lower() in SENSITIVE_JSON_KEYS:
+ redacted[key] = "<redacted>"
+ else:
+ redacted[key] = _redact_json(item)
+ return redacted
+ if isinstance(value, list):
+ return [_redact_json(item) for item in value]
+ return value
+
+
+def _json_preview(value: Any) -> str:
+ text = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+ if len(text) <= TRUNCATE_PREVIEW_BYTES:
+ return text
+ return text[:TRUNCATE_PREVIEW_BYTES] + "...<truncated>"
+
+
+class CodexDump:
+ def __init__(self) -> None:
+ self.output_dir: Path | None = None
+ self.host_patterns: list[re.Pattern[str]] = []
+ self.path_patterns: list[re.Pattern[str]] = []
+ self.include_http = True
+ self.include_ws = True
+ self._http_counter = 0
+ self._ws_counter = 0
+ self._ws_files: dict[str, Path] = {}
+
+ def load(self, loader) -> None:
+ loader.add_option(
+ name="codex_dump_dir",
+ typespec=str,
+ default="",
+ help="Directory used to persist captured Codex HTTP and WebSocket traffic.",
+ )
+ loader.add_option(
+ name="codex_dump_hosts",
+ typespec=str,
+ default=",".join(DEFAULT_HOST_PATTERNS),
+ help="Comma-separated regex patterns for host allowlist.",
+ )
+ loader.add_option(
+ name="codex_dump_paths",
+ typespec=str,
+ default=",".join(DEFAULT_PATH_PATTERNS),
+ help="Comma-separated regex patterns for request path allowlist.",
+ )
+ loader.add_option(
+ name="codex_dump_include_http",
+ typespec=bool,
+ default=True,
+ help="Whether to persist matching HTTP request/response flows.",
+ )
+ loader.add_option(
+ name="codex_dump_include_ws",
+ typespec=bool,
+ default=True,
+ help="Whether to persist matching WebSocket messages.",
+ )
+
+ def configure(self, updated) -> None:
+ hosts = [item.strip() for item in ctx.options.codex_dump_hosts.split(",") if item.strip()]
+ paths = [item.strip() for item in ctx.options.codex_dump_paths.split(",") if item.strip()]
+ self.host_patterns = [re.compile(pattern) for pattern in hosts]
+ 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)
+
+ if ctx.options.codex_dump_dir:
+ base_dir = Path(ctx.options.codex_dump_dir).expanduser()
+ else:
+ timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+ base_dir = Path(tempfile.gettempdir()) / "codex-dumps" / timestamp
+
+ self.output_dir = base_dir
+ 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)
+
+ def request(self, flow: http.HTTPFlow) -> None:
+ if self.include_http and self._matches(flow) and not self._is_ws_upgrade(flow):
+ self._persist_http_flow(flow)
+
+ def websocket_start(self, flow: http.HTTPFlow) -> None:
+ if not self.include_ws or not self._matches(flow):
+ return
+
+ self._ws_counter += 1
+ request = flow.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
+
+ metadata = {
+ "event": "websocket_start",
+ "captured_at": _utc_now(),
+ "id": flow.id,
+ "request": self._serialize_request(request),
+ }
+ self._append_jsonl(file_path, metadata)
+ ctx.log.info(f"codex_dump websocket -> {file_path}")
+
+ def websocket_message(self, flow: http.HTTPFlow) -> None:
+ if not self.include_ws or not self._matches(flow):
+ return
+
+ file_path = self._ws_files.get(flow.id)
+ if file_path is None:
+ self.websocket_start(flow)
+ file_path = self._ws_files.get(flow.id)
+ if file_path is None:
+ return
+
+ message = flow.websocket.messages[-1]
+ decoded = self._decode_message(message.content)
+ payload = {
+ "event": "websocket_message",
+ "captured_at": _utc_now(),
+ "id": flow.id,
+ "from_client": bool(message.from_client),
+ "is_text": isinstance(decoded, str),
+ "size_bytes": len(message.content),
+ }
+
+ if isinstance(decoded, str):
+ parsed = self._try_parse_json(decoded)
+ if parsed is not None:
+ redacted = _redact_json(parsed)
+ payload["json"] = redacted
+ payload["preview"] = _json_preview(redacted)
+ else:
+ payload["text"] = decoded
+ payload["preview"] = decoded[:TRUNCATE_PREVIEW_BYTES]
+ else:
+ payload["binary_preview_hex"] = decoded[:64].hex()
+
+ self._append_jsonl(file_path, payload)
+
+ def websocket_end(self, flow: http.HTTPFlow) -> None:
+ file_path = self._ws_files.pop(flow.id, None)
+ if file_path is None:
+ return
+
+ payload = {
+ "event": "websocket_end",
+ "captured_at": _utc_now(),
+ "id": flow.id,
+ "closed_by_client": getattr(flow.websocket, "closed_by_client", None),
+ "close_code": getattr(flow.websocket, "close_code", None),
+ "close_reason": getattr(flow.websocket, "close_reason", None),
+ }
+ self._append_jsonl(file_path, payload)
+
+ def _matches(self, flow: http.HTTPFlow) -> bool:
+ request = flow.request
+ host = request.pretty_host or request.host or ""
+ path = request.path or ""
+ return (
+ any(pattern.search(host) for pattern in self.host_patterns)
+ and any(pattern.search(path) for pattern in self.path_patterns)
+ )
+
+ def _is_ws_upgrade(self, flow: http.HTTPFlow) -> bool:
+ upgrade = flow.request.headers.get("upgrade", "")
+ connection = flow.request.headers.get("connection", "")
+ return "websocket" in upgrade.lower() or "upgrade" in connection.lower()
+
+ def _persist_http_flow(self, flow: http.HTTPFlow) -> None:
+ self._http_counter += 1
+ request = flow.request
+ path_stem = _safe_stem(request.path.split("?", 1)[0].strip("/"))
+ file_path = self.output_dir / "http" / f"{self._http_counter:03d}-{request.method.lower()}-{path_stem}.json"
+
+ payload = {
+ "captured_at": _utc_now(),
+ "id": flow.id,
+ "request": self._serialize_request(request),
+ "response": self._serialize_response(flow.response),
+ }
+ file_path.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+ ctx.log.info(f"codex_dump http -> {file_path}")
+
+ def _serialize_request(self, request: http.Request) -> dict[str, Any]:
+ payload: dict[str, Any] = {
+ "method": request.method,
+ "scheme": request.scheme,
+ "host": request.pretty_host,
+ "port": request.port,
+ "path": request.path,
+ "pretty_url": request.pretty_url,
+ "headers": {
+ name: _redact_header_value(name, value) for name, value in request.headers.items(multi=True)
+ },
+ }
+ body = self._decode_message(request.raw_content or b"")
+ if isinstance(body, str) and body:
+ parsed = self._try_parse_json(body)
+ payload["body"] = _redact_json(parsed) if parsed is not None else body
+ elif isinstance(body, bytes) and body:
+ payload["body_binary_preview_hex"] = body[:64].hex()
+ return payload
+
+ def _serialize_response(self, response: http.Response | None) -> dict[str, Any] | None:
+ if response is None:
+ return None
+
+ payload: dict[str, Any] = {
+ "status_code": response.status_code,
+ "reason": response.reason,
+ "headers": {
+ name: _redact_header_value(name, value) for name, value in response.headers.items(multi=True)
+ },
+ }
+ body = self._decode_message(response.raw_content or b"")
+ if isinstance(body, str) and body:
+ parsed = self._try_parse_json(body)
+ payload["body"] = _redact_json(parsed) if parsed is not None else body
+ elif isinstance(body, bytes) and body:
+ payload["body_binary_preview_hex"] = body[:64].hex()
+ return payload
+
+ def _try_parse_json(self, value: str) -> Any | None:
+ try:
+ return json.loads(value)
+ except json.JSONDecodeError:
+ return None
+
+ def _decode_message(self, content: bytes) -> str | bytes:
+ if not content:
+ return ""
+ try:
+ return content.decode("utf-8")
+ except UnicodeDecodeError:
+ return content
+
+ def _append_jsonl(self, file_path: Path, payload: dict[str, Any]) -> None:
+ with file_path.open("a", encoding="utf-8") as handle:
+ handle.write(json.dumps(payload, ensure_ascii=False) + "\n")
+
+
+addons = [CodexDump()]
diff --git a/scripts/start-codex-mitm-dump.sh b/scripts/start-codex-mitm-dump.sh
new file mode 100755
index 0000000..cbeaf39
--- /dev/null
+++ b/scripts/start-codex-mitm-dump.sh
@@ -0,0 +1,111 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+usage() {
+ cat <<'EOF'
+用法:
+ ./scripts/start-codex-mitm-dump.sh [session-name]
+
+说明:
+ 后台启动 mitmdump,并把抓包样本写到 artifacts/codex-dumps/<session-name>/。
+ 如果不传 session-name,则默认使用时间戳自动生成目录。
+
+可选环境变量:
+ MITM_LISTEN_HOST 监听地址,默认 127.0.0.1
+ MITM_LISTEN_PORT 监听端口,默认 8082
+ MITM_CA_CERT mitm CA 证书路径,默认 $HOME/.mitmproxy/mitmproxy-ca-cert.pem
+ CODEX_DUMP_BASE_DIR 抓包输出根目录,默认 <repo>/artifacts/codex-dumps
+EOF
+}
+
+if [[ "${1:-}" == "-h" || "${1:-}" == "--help" ]]; then
+ usage
+ exit 0
+fi
+
+repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+listen_host="${MITM_LISTEN_HOST:-127.0.0.1}"
+listen_port="${MITM_LISTEN_PORT:-8082}"
+ca_cert="${MITM_CA_CERT:-${HOME}/.mitmproxy/mitmproxy-ca-cert.pem}"
+dump_base_dir="${CODEX_DUMP_BASE_DIR:-${repo_root}/artifacts/codex-dumps}"
+addon_script="${repo_root}/scripts/codex_dump.py"
+timestamp="$(date +%Y%m%d-%H%M%S)"
+session_name="${1:-${timestamp}-codex-capture}"
+session_dir="${dump_base_dir}/${session_name}"
+log_path="${session_dir}/mitmdump.log"
+pid_path="${session_dir}/mitmdump.pid"
+env_path="${session_dir}/codex-proxy.env"
+
+if ! command -v mitmdump >/dev/null 2>&1; then
+ echo "未找到 mitmdump,请先安装 mitmproxy。" >&2
+ exit 1
+fi
+
+if [[ ! -f "${addon_script}" ]]; then
+ echo "缺少抓包 addon: ${addon_script}" >&2
+ exit 1
+fi
+
+if [[ ! -f "${ca_cert}" ]]; then
+ echo "未找到 mitm CA 证书: ${ca_cert}" >&2
+ exit 1
+fi
+
+if lsof -nP -iTCP:"${listen_port}" -sTCP:LISTEN >/dev/null 2>&1; then
+ echo "端口 ${listen_port} 已被占用,请调整 MITM_LISTEN_PORT。" >&2
+ exit 1
+fi
+
+if [[ -e "${session_dir}" ]]; then
+ if find "${session_dir}" -mindepth 1 -maxdepth 1 | read -r _; then
+ echo "session 目录已存在且非空: ${session_dir}" >&2
+ exit 1
+ fi
+else
+ mkdir -p "${session_dir}"
+fi
+
+cat >"${env_path}" <<EOF
+export HTTPS_PROXY="http://${listen_host}:${listen_port}"
+export NO_PROXY="127.0.0.1,localhost"
+export SSL_CERT_FILE="${ca_cert}"
+EOF
+
+nohup mitmdump \
+ --listen-host "${listen_host}" \
+ --listen-port "${listen_port}" \
+ -s "${addon_script}" \
+ --set codex_dump_dir="${session_dir}" \
+ >"${log_path}" 2>&1 &
+
+pid=$!
+echo "${pid}" >"${pid_path}"
+
+sleep 1
+
+if ! kill -0 "${pid}" >/dev/null 2>&1; then
+ echo "mitmdump 启动失败,最近日志:" >&2
+ if [[ -f "${log_path}" ]]; then
+ tail -n 40 "${log_path}" >&2
+ fi
+ exit 1
+fi
+
+cat <<EOF
+mitmdump 已后台启动。
+
+session_dir: ${session_dir}
+pid: ${pid}
+log: ${log_path}
+env: ${env_path}
+
+后续让 Codex 走代理时,可直接执行:
+
+ source "${env_path}"
+ codex exec --skip-git-repo-check -C /tmp 'reply with one word: ok'
+
+停止抓包:
+
+ kill "${pid}"
+EOF