Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(plugin/codex): default-on assistant capture, recommend env vars over ov.conf for tuning (#2065)

t0saki42484bf91d0b
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index a5ccbc642..991adca52 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -84,7 +84,7 @@ Resolution priority for every connection / identity field — env vars always wi
1. **Environment variables** (`OPENVIKING_*`)
2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
-3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)
+3. **`ov.conf`** — `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (only `server.url` / `server.root_api_key` as connection fallback; a legacy `codex.*` tuning block is still honored but deprecated — see [Tuning](#tuning))
4. **Built-in defaults** (`http://127.0.0.1:1933`, unauthenticated)
Hooks resolve this chain on every fire (changes to ovcli.conf take effect on the next hook). The MCP server URL is baked into `.mcp.json` at install time (changing the URL requires a re-install); the API key is read fresh from env on every codex launch via `bearer_token_env_var`, so rotating `OPENVIKING_API_KEY` in ovcli.conf only requires a codex restart, not a re-install.
@@ -106,22 +106,21 @@ For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.co
| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle-TTL sweep threshold |
| `OPENVIKING_DEBUG` | `false` | Write JSONL events to `~/.openviking/logs/codex-hooks.log` |
-Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:
-
-```jsonc
-{
- "url": "https://ov.example.com",
- "api_key": "...",
- "codex": {
- "agentId": "codex",
- "recallLimit": 6,
- "autoCommitOnCompact": true,
- "debug": false
- }
-}
+### Tuning
+
+Plugin tuning is set via `OPENVIKING_*` environment variables in your shell rc — they take effect on every codex launch.
+
+```sh
+# ~/.zshrc
+export OPENVIKING_RECALL_LIMIT=6
+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1
+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1
+export OPENVIKING_DEBUG=1
```
-The full field list is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration).
+The full field list is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).
+
+> **Legacy `codex.*` block**: earlier versions read tuning fields from a `codex` block in `~/.openviking/ov.conf`; that still works for backward compat. But codex is a client-side plugin and per-machine tuning doesn't belong in a server-scope `ov.conf` — new deployments should prefer env vars.
## Hook behavior
@@ -157,7 +156,7 @@ The plugin wires Codex up to OpenViking's built-in `/mcp` endpoint via streamabl
| Hook runs but recall returns nothing | OpenViking server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| Remote auth 401/403 from hooks but MCP works (or vice versa) | env vs ovcli.conf mismatch | Hooks re-read ovcli.conf every fire; MCP reads env only at codex start. Restart codex if you changed env. |
-Verbose debug logging: set `OPENVIKING_DEBUG=1` or `codex.debug=true` in `ovcli.conf` to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.
+Verbose debug logging: set `OPENVIKING_DEBUG=1` (or legacy `codex.debug=true` in `ov.conf`) to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.
## Differences from the Claude Code plugin
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index 9e357d11a..9b5e2658b 100644
--- a/docs/zh/agent-integrations/04-codex.md
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -83,7 +83,7 @@ installer 替你做的三件事,你也可以自己手动做:
1. **环境变量**(`OPENVIKING_*`)
2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` 或 `OPENVIKING_CLI_CONFIG_FILE`
-3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(顶层 `server.*` + 可选的 `codex.*` 调参块)
+3. **`ov.conf`** — `~/.openviking/ov.conf` 或 `OPENVIKING_CONFIG_FILE`(只用 `server.url` / `server.root_api_key` 当连接 fallback;`codex.*` 调参块仍被读取但已废弃,见下面 [调参](#调参))
4. **内置默认值**(`http://127.0.0.1:1933`,无鉴权)
Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一次 hook 立即生效。MCP server URL 在 install 时固化进 `.mcp.json`(改 URL 要重跑 installer),但 API key 通过 `bearer_token_env_var` 在 codex 启动时从 env 读,所以**轮换 API key 只需重启 codex,不必重装**。
@@ -105,22 +105,21 @@ Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一
| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |
| `OPENVIKING_DEBUG` | `false` | 把 hook 日志写到 `~/.openviking/logs/codex-hooks.log` |
-可选的 Codex 专属调参放在 `ovcli.conf` 的 `codex` 块下:
-
-```jsonc
-{
- "url": "https://ov.example.com",
- "api_key": "...",
- "codex": {
- "agentId": "codex",
- "recallLimit": 6,
- "autoCommitOnCompact": true,
- "debug": false
- }
-}
+### 调参
+
+调参用 `OPENVIKING_*` 环境变量,写进 shell rc 即可。每次 codex 启动都生效。
+
+```sh
+# ~/.zshrc
+export OPENVIKING_RECALL_LIMIT=6
+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1
+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1
+export OPENVIKING_DEBUG=1
```
-完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#configuration)。
+完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。
+
+> **遗留 `codex.*` 块**:早期版本支持把调参字段放在 `~/.openviking/ov.conf` 的 `codex` 块下,仍向后兼容。但 codex 是 client 侧插件,per-machine 的调参不该住在 server-scope 的 `ov.conf` 里——新部署请用环境变量。
## Hook 行为
@@ -156,7 +155,7 @@ Hook 每次触发都重新解析这条优先级链——改完 ovcli.conf 下一
| Hook 触发但召回为空 | OpenViking 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
| Hook 401/403 但 MCP 工具可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次都重读 ovcli.conf,MCP 只在 codex 启动读 env。改完 env 要重启 codex。 |
-调试日志:设 `OPENVIKING_DEBUG=1` 或 `ovcli.conf` 里 `codex.debug=true`,会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。
+调试日志:设 `OPENVIKING_DEBUG=1`(或老配置 `ov.conf` 里 `codex.debug=true`),会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。
## 与 Claude Code 插件的差异
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index b3585e09c..4054c5eff 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -88,7 +88,7 @@ Connection / identity resolution order (highest to lowest, applies to both hooks
1. **Environment variables**: `OPENVIKING_URL` / `OPENVIKING_BASE_URL`, `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, `OPENVIKING_AGENT_ID`
2. **`ovcli.conf`**: `~/.openviking/ovcli.conf` or `OPENVIKING_CLI_CONFIG_FILE`
-3. **`ov.conf`**: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (`server.*` + optional `codex.*` tuning block)
+3. **`ov.conf`**: `~/.openviking/ov.conf` or `OPENVIKING_CONFIG_FILE` (only `server.url` / `server.root_api_key` as connection fallback; tuning fields under a legacy `codex.*` block are honored but deprecated — see [Tuning the plugin](#tuning-the-plugin))
4. **Built-in defaults**: `http://127.0.0.1:1933`, unauthenticated
The shell function wrapper handles step 1 for you by promoting ovcli.conf fields into env vars before exec'ing codex. Hooks then re-resolve the full chain inside Node; the MCP server URL is baked into `.mcp.json` at install time and the API key flows in via `OPENVIKING_API_KEY` (referenced by `bearer_token_env_var` in `.mcp.json`).
@@ -99,21 +99,24 @@ For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.co
The `codex()` shell-function wrapper **re-renders this field on every codex launch** based on the currently-active `ovcli.conf` (the one `OPENVIKING_CLI_CONFIG_FILE` points at, falling back to `~/.openviking/ovcli.conf`). That means you can switch between authenticated and unauthenticated OV — e.g. to isolate a benchmark run from production memory — by just changing `OPENVIKING_CLI_CONFIG_FILE` before invoking `codex`, with no re-install needed. The wrapper also omits empty env-var assignments entirely (so `OPENVIKING_API_KEY=` is never passed to codex), keeping `env_http_headers` for identity (`X-OpenViking-Account` / `User` / `Agent`) intact.
-Optional Codex-specific tuning lives under `codex` in `ovcli.conf`:
-
-```jsonc
-{
- "url": "https://ov.example.com",
- "api_key": "...",
- "codex": {
- "agentId": "codex",
- "recallLimit": 6,
- "captureAssistantTurns": false,
- "autoCommitOnCompact": true
- }
-}
+### Tuning the plugin
+
+All plugin behavior is controlled by `OPENVIKING_*` environment variables — set them in your shell rc (`~/.zshrc` / `~/.bashrc`) so every `codex` launch picks them up. The shell-function wrapper installed alongside the plugin already exports identity vars from `ovcli.conf`; tuning vars sit next to it.
+
+```sh
+# ~/.zshrc — examples
+export OPENVIKING_RECALL_LIMIT=6
+export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1
+export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1
+export OPENVIKING_DEBUG=1
```
+Full list: see the `Misc env vars` block in `scripts/config.mjs`. Every field has a `OPENVIKING_*` counterpart and env vars always win.
+
+#### Legacy `codex` block in `ov.conf`
+
+Earlier plugin versions configured tuning fields under a `codex` block in `~/.openviking/ov.conf`. That still works for backward compat — every env var above has a camelCase counterpart (`OPENVIKING_RECALL_LIMIT` → `codex.recallLimit`, etc.) — but **new deployments should prefer env vars**: this is the codex CLI's per-machine plugin tuning, and the server-side `ov.conf` is the wrong place for it. (It's read from `ov.conf`, not `ovcli.conf`, by historical accident in `scripts/config.mjs`.)
+
## Architecture
```
diff --git a/examples/codex-memory-plugin/scripts/config.mjs b/examples/codex-memory-plugin/scripts/config.mjs
index 45655d510..c86607166 100644
--- a/examples/codex-memory-plugin/scripts/config.mjs
+++ b/examples/codex-memory-plugin/scripts/config.mjs
@@ -227,7 +227,11 @@ export function loadConfig() {
num(cx.captureMaxLength, 24000),
))),
captureTimeoutMs,
- captureAssistantTurns: envBool("OPENVIKING_CAPTURE_ASSISTANT_TURNS") ?? (cx.captureAssistantTurns === true),
+ // Default true: a "memory plugin" without assistant-side capture only sees half the
+ // conversation, which makes extraction noticeably worse. Mirrors the claude-code plugin
+ // (examples/claude-code-memory-plugin/scripts/config.mjs). Operators who want the old
+ // user-only behavior can set OPENVIKING_CAPTURE_ASSISTANT_TURNS=0 or codex.captureAssistantTurns=false.
+ captureAssistantTurns: envBool("OPENVIKING_CAPTURE_ASSISTANT_TURNS") ?? (cx.captureAssistantTurns !== false),
captureLastAssistantOnStop: envBool("OPENVIKING_CAPTURE_LAST_ASSISTANT_ON_STOP") ?? (cx.captureLastAssistantOnStop !== false),
autoCommitOnCompact: envBool("OPENVIKING_AUTO_COMMIT_ON_COMPACT") ?? (cx.autoCommitOnCompact !== false),