cluic · cluic · May 20, 2026 · May 19, 2026 · May 20, 2026
diff --git a/README.md b/README.md
@@ -96,6 +96,8 @@ Add an optional section like:
 [codex_remote_proxy]
 upstream_base_url = "https://your-upstream.example.com"
 upstream_api_key = "sk-your-key"
+capture_enabled = true
+capture_db_path = "/Users/you/.codex-remote-proxy/traffic.sqlite3"
 ```
 
 Then later runs only need:
@@ -128,17 +130,58 @@ crp start
 ```bash
 export CRP_UPSTREAM_BASE_URL="https://your-upstream.example.com"
 export CRP_UPSTREAM_API_KEY="sk-your-key"
+export CRP_CAPTURE_ENABLED="true"
+export CRP_CAPTURE_DB_PATH="/Users/you/.codex-remote-proxy/traffic.sqlite3"
 crp start
 ```
 
 `crp start` resolves values in this order:
 
 1. CLI flags
 2. Environment variables
-3. `~/.codex/config.toml` under `[codex_remote_proxy]` using `upstream_base_url` and `upstream_api_key`
+3. `~/.codex/config.toml` under `[codex_remote_proxy]` using `upstream_base_url`, `upstream_api_key`, `capture_enabled`, and `capture_db_path`
 4. Saved config from `crp init`
 5. Interactive prompts
 
+## Request Capture
+
+Request capture is optional and disabled by default.
+
+When enabled, the proxy stores one SQLite row per proxied HTTP transaction under:
+
+```text
+~/.codex-remote-proxy/traffic.sqlite3
+```
+
+or a custom path you provide with `capture_db_path`.
+
+What is stored:
+
+- full request headers after proxy rewrites
+- full request body
+- full response headers
+- full response body
+- SSE responses aggregated into one stored body
+
+Sensitive headers such as `Authorization`, `Cookie`, `Set-Cookie`, and token-like header names are redacted before writing.
+
+Enable capture at startup:
+
+```bash
+crp start --capture
+crp start --capture --capture-db-path /Users/you/.codex-remote-proxy/custom-traffic.sqlite3
+```
+
+Hot-toggle capture on a running managed proxy:
+
+```bash
+crp capture on
+crp capture off
+crp capture status --json
+```
+
+You can also edit `~/.codex-remote-proxy/node/proxy-config.json` directly. Changes to `capture.enabled` hot-apply after the proxy validates the SQLite connection. Changes to `capture.dbPath` are detected, but require a restart before the new path is used.
+
 ## Global CLI
 
 Main commands:
@@ -150,11 +193,14 @@ Main commands:
   Accept upstream settings from CLI flags, environment variables, `~/.codex/config.toml` `[codex_remote_proxy]`, or prompts; choose a free port, patch Codex, and start the proxy in the background by default
 
 - `crp init`
-  Save upstream settings once under `~/.codex-remote-proxy/` so later `crp start` calls do not require secrets again if you do not want to place them in `~/.codex/config.toml`
+  Save upstream settings and optional capture defaults once under `~/.codex-remote-proxy/` so later `crp start` calls do not require secrets again if you do not want to place them in `~/.codex/config.toml`
 
 - `crp install`
   Compatibility alias for `crp start`
 
+- `crp capture on|off|status`
+  Toggle SQLite request capture on a running managed proxy, or persist the preference for the next start if the proxy is not running
+
 - `crp status`
   Show managed service status and health. If the proxy is running but not managed by this CLI, it will try to detect that too
 
@@ -168,6 +214,7 @@ Machine-readable examples:
 
 ```bash
 crp check --json
+crp capture status --json
 crp guide --json
 crp status --json
 ```
@@ -179,7 +226,7 @@ Recommended flow:
 1. Run `crp check --json`
 2. Read `recommendedImplementation`
 3. If Node dependencies are ready, prefer `node`
-4. Prefer existing `~/.codex/config.toml` `[codex_remote_proxy]` with `upstream_base_url` and `upstream_api_key`, otherwise ask the user to run `crp init` once locally, or rely on environment variables already set outside the AI session
+4. Prefer existing `~/.codex/config.toml` `[codex_remote_proxy]` with `upstream_base_url`, `upstream_api_key`, `capture_enabled`, and `capture_db_path`, otherwise ask the user to run `crp init` once locally, or rely on environment variables already set outside the AI session
 5. Run `crp start`
 6. Read `proxyUrl`, `pid`, and `health` from the JSON result
 7. Use `crp status --json` for later verification
@@ -189,6 +236,7 @@ Notes:
 - `start` modifies `~/.codex/config.toml` and creates a backup
 - the managed proxy runs in the background by default
 - managed state and logs live under `~/.codex-remote-proxy/`
+- request capture writes to SQLite only when enabled
 - when running directly from this repository, install Node dependencies first
 - `~/.codex/config.toml`, `crp init`, or environment variables can keep secrets out of later AI interactions
 

diff --git a/README.zh-CN.md b/README.zh-CN.md
@@ -92,6 +92,8 @@ CLI 统一管理目录：
 [codex_remote_proxy]
 upstream_base_url = "https://your-upstream.example.com"
 upstream_api_key = "sk-your-key"
+capture_enabled = true
+capture_db_path = "/Users/you/.codex-remote-proxy/traffic.sqlite3"
 ```
 
 之后直接执行：
@@ -124,17 +126,48 @@ crp start
 ```bash
 export CRP_UPSTREAM_BASE_URL="https://your-upstream.example.com"
 export CRP_UPSTREAM_API_KEY="sk-your-key"
+export CRP_CAPTURE_ENABLED="true"
+export CRP_CAPTURE_DB_PATH="/Users/you/.codex-remote-proxy/traffic.sqlite3"
 crp start
 ```
 
 `crp start` 的取值优先级是：
 
 1. CLI 参数
 2. 环境变量
-3. `~/.codex/config.toml` 里的 `[codex_remote_proxy]`，键名使用 `upstream_base_url` 和 `upstream_api_key`
+3. `~/.codex/config.toml` 里的 `[codex_remote_proxy]`，键名使用 `upstream_base_url`、`upstream_api_key`、`capture_enabled` 和 `capture_db_path`
 4. `crp init` 保存的本地配置
 5. 交互式输入
 
+## 请求记录
+
+SQLite 请求记录是可选功能，默认关闭。
+
+开启后，代理会把每次完整请求/响应保存成一条 SQLite 记录，默认数据库路径是：
+
+```text
+~/.codex-remote-proxy/traffic.sqlite3
+```
+
+启动时开启：
+
+```bash
+crp start --capture
+crp start --capture --capture-db-path /Users/you/.codex-remote-proxy/custom-traffic.sqlite3
+```
+
+对正在运行的代理做热切换：
+
+```bash
+crp capture on
+crp capture off
+crp capture status --json
+```
+
+你也可以直接编辑 `~/.codex-remote-proxy/node/proxy-config.json`。其中 `capture.enabled` 会在代理校验 SQLite 成功后热生效；`capture.dbPath` 的变化会被探测到，但需要重启后才会真正切到新路径。
+
+写入前会默认脱敏敏感请求头，例如 `Authorization`、`Cookie`、`Set-Cookie` 以及名称中包含 `token`、`secret`、`api-key` 的头。
+
 ## 全局 CLI
 
 主要命令：
@@ -146,11 +179,14 @@ crp start
   从 CLI 参数、环境变量、`~/.codex/config.toml` 的 `[codex_remote_proxy]` 或交互输入中获取上游配置，自动选择空闲端口，修改 Codex 配置，并默认后台启动代理
 
 - `crp init`
-  先把上游配置安全保存到 `~/.codex-remote-proxy/`，如果你不想把密钥写进 `~/.codex/config.toml`，以后 `crp start` 也不需要再重复输入
+  先把上游配置和可选的请求记录默认值安全保存到 `~/.codex-remote-proxy/`，如果你不想把密钥写进 `~/.codex/config.toml`，以后 `crp start` 也不需要再重复输入
 
 - `crp install`
   与 `crp start` 等价的兼容别名
 
+- `crp capture on|off|status`
+  对托管中的代理热切换 SQLite 请求记录；如果代理当前没运行，则保存为下次启动时生效的偏好
+
 - `crp status`
   查看当前托管服务状态和健康检查结果。如果代理在运行但不是 CLI 托管的，也会尝试探测
 
@@ -164,6 +200,7 @@ crp start
 
 ```bash
 crp check --json
+crp capture status --json
 crp guide --json
 crp status --json
 ```
@@ -175,7 +212,7 @@ crp status --json
 1. 先跑 `crp check --json`
 2. 读取 `recommendedImplementation`
 3. 如果 Node 依赖就绪，优先走 `node`
-4. 优先使用现有 `~/.codex/config.toml` 里的 `[codex_remote_proxy]`，并使用 `upstream_base_url` / `upstream_api_key` 这两个键，否则让用户先在本地跑一次 `crp init`，或者提前在系统里设置好环境变量
+4. 优先使用现有 `~/.codex/config.toml` 里的 `[codex_remote_proxy]`，并使用 `upstream_base_url` / `upstream_api_key` / `capture_enabled` / `capture_db_path` 这些键，否则让用户先在本地跑一次 `crp init`，或者提前在系统里设置好环境变量
 5. 再跑 `crp start`
 6. 从返回结果中读取 `proxyUrl`、`pid`、`health`
 7. 之后用 `crp status --json` 做确认
@@ -185,6 +222,7 @@ crp status --json
 - `start` 会修改 `~/.codex/config.toml`
 - `install` 会先创建备份
 - 托管状态和日志保存在 `~/.codex-remote-proxy/`
+- 只有在显式开启时才会写 SQLite 请求记录
 - 如果你是直接从当前仓库运行，需要先执行 `cd node && npm install`
 - `~/.codex/config.toml`、`crp init` 或环境变量模式都可以避免后续 AI 直接接触密钥
 

diff --git a/node/.changeset/add-sqlite-capture.md b/node/.changeset/add-sqlite-capture.md
@@ -0,0 +1,5 @@
+---
+"@cluic/codex-remote-proxy": minor
+---
+
+Add optional SQLite request capture with hot toggle support.
diff --git a/node/README.md b/node/README.md
@@ -43,6 +43,8 @@ The easiest persistent setup is to add this section to `~/.codex/config.toml`:
 [codex_remote_proxy]
 upstream_base_url = "https://your-upstream.example.com"
 upstream_api_key = "sk-your-key"
+capture_enabled = true
+capture_db_path = "/Users/you/.codex-remote-proxy/traffic.sqlite3"
 ```
 
 Then run:
@@ -71,17 +73,46 @@ crp start
 ```bash
 export CRP_UPSTREAM_BASE_URL="https://your-upstream.example.com"
 export CRP_UPSTREAM_API_KEY="sk-your-key"
+export CRP_CAPTURE_ENABLED="true"
+export CRP_CAPTURE_DB_PATH="/Users/you/.codex-remote-proxy/traffic.sqlite3"
 crp start
 ```
 
 `crp start` resolves values in this order:
 
 1. CLI flags
 2. Environment variables
-3. `~/.codex/config.toml` under `[codex_remote_proxy]` using `upstream_base_url` and `upstream_api_key`
+3. `~/.codex/config.toml` under `[codex_remote_proxy]` using `upstream_base_url`, `upstream_api_key`, `capture_enabled`, and `capture_db_path`
 4. Saved config from `crp init`
 5. Interactive prompts
 
+## Request Capture
+
+SQLite request capture is optional and off by default.
+
+When enabled, the proxy stores one full request/response transaction per row in:
+
+```text
+~/.codex-remote-proxy/traffic.sqlite3
+```
+
+You can enable it at startup:
+
+```bash
+crp start --capture
+crp start --capture --capture-db-path /Users/you/.codex-remote-proxy/custom-traffic.sqlite3
+```
+
+Or hot-toggle it on a running proxy:
+
+```bash
+crp capture on
+crp capture off
+crp capture status --json
+```
+
+Edits to `~/.codex-remote-proxy/node/proxy-config.json` also hot-apply `capture.enabled`. Changes to `capture.dbPath` are detected but require a restart before the new database path is used.
+
 ## Main Commands
 
 - `crp check`
@@ -91,7 +122,10 @@ crp start
   Accept upstream settings from CLI flags, environment variables, `~/.codex/config.toml` `[codex_remote_proxy]`, or prompts; choose a free port, patch Codex, and start the proxy in the background by default
 
 - `crp init`
-  Save upstream settings once under `~/.codex-remote-proxy/`
+  Save upstream settings and optional capture defaults once under `~/.codex-remote-proxy/`
+
+- `crp capture on|off|status`
+  Toggle SQLite request capture at runtime for a managed proxy, or save the preference for the next start
 
 - `crp status`
   Show managed service status and health
@@ -121,4 +155,5 @@ See [RELEASING.md](./RELEASING.md) for the one-time npm Trusted Publishing setup
 - `crp start` modifies `~/.codex/config.toml` and creates a backup
 - the managed proxy runs in the background by default
 - managed state and logs live under `~/.codex-remote-proxy/`
-- Node.js 20 or newer is required
+- request capture redacts sensitive headers before writing
+- Node.js 22.13.0 or newer is required