Skip to content

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

docs: explain the startup hook-trust step for Codex and TraeCode CLI 2.0 (#5257)

t0saki14dd4e9e61e0
diff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.md
index 9aa413964..f8b6bb0cf 100644
--- a/docs/en/agent-integrations/04-codex.md
+++ b/docs/en/agent-integrations/04-codex.md
@@ -26,12 +26,35 @@ In regions where GitHub is hard to reach, run the same installer from the Volcen
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
```
-No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads `~/.openviking/ovcli.conf` (or `OPENVIKING_*` env vars) at runtime, same as the hooks. After installing:
+No shell wrapper is needed anymore — the plugin ships a stdio MCP proxy that reads `~/.openviking/ovcli.conf` (or `OPENVIKING_*` env vars) at runtime, same as the hooks. After installing, launch Codex (`trae-cli` for TraeCode CLI 2.0):
```bash
-codex # First run: approve hooks once when prompted via /hooks
+codex
```
+### First launch: trust the hooks
+
+The plugin's hooks are new to Codex, so startup stops on a trust prompt. Pick **Trust all and continue**, or Review hooks first if you want to read the commands:
+
+```text
+Hooks need review
+6 hooks are new or changed.
+Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+> 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+```
+
+A fresh install lists all 6 hooks the plugin registers. After that, any plugin update that touches a hook stops startup again, with the count of what changed this time (`1 hook is new or changed`, say) — pick Trust all and continue there too.
+
+Pick the third option, or skip past the prompt, and the hooks never run: MCP tools still work, but automatic recall and capture are both dead. Recovering means switching on two independent things:
+
+- `/hooks` — hook trust and on/off state. Trust and enable the entries marked *New hook - review required* or *Modified since last trusted*.
+- `/plugins` — the plugin's own enabled state. Confirm `openviking-memory` is enabled.
+
+If either side is off, nothing is recalled or captured.
+
<details>
<summary><b>Manual setup</b></summary>
@@ -103,7 +126,7 @@ Change it with `OPENVIKING_PEER_SOURCE`, with `plugin.peerSource` in `ovcli.conf
|---------|-------|-----|
| MCP tool calls fail with an auth error | The active ovcli config has no valid `api_key` for an authenticated server | Fix `~/.openviking/ovcli.conf` (or run `node <plugin-dir>/scripts/setup.mjs`) and restart Codex; the stdio proxy re-reads it on launch and after auth failures. |
| MCP tool calls fail with a connection error | Server unreachable or the URL is wrong | Check the endpoint: `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| `6 hooks need review` | Security review on first launch; after an upgrade that adds a hook, Codex asks again for the new one | Run `/hooks` within Codex and approve the hooks. |
+| `6 hooks need review`, or the plugin is installed but no hook fires | A fresh install trusts all 6 hooks at once, and every later update that touches a hook asks again; choosing *Continue without trusting* or skipping it leaves the hooks off for good | Trust and enable the entries in `/hooks`, and confirm `openviking-memory` is enabled in `/plugins` — two independent switches, both have to be on. |
| Plugin still targets an old server after `ov config switch` | Codex keeps the proxy process from the previous session | Restart Codex; the proxy resolves credentials at startup. |
| Hooks use one server, MCP another | Stale `OPENVIKING_*` credential env vars in one context (env vars override ovcli.conf by default) | Unset the stale env vars (ovcli.conf then drives both), set `OPENVIKING_CREDENTIAL_SOURCE=cli`, or make the env vars consistent. |
diff --git a/docs/en/agent-integrations/13-trae.md b/docs/en/agent-integrations/13-trae.md
index 9fcb3f0e5..cf12dbb3b 100644
--- a/docs/en/agent-integrations/13-trae.md
+++ b/docs/en/agent-integrations/13-trae.md
@@ -39,6 +39,29 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
Quit and restart the corresponding client after installation.
+### TraeCode CLI 2.0: trust the hooks on first launch
+
+TraeCode CLI 2.0 uses the Codex plugin format, where hooks only run once you trust them. Starting `trae-cli` stops on this prompt — pick **Trust all and continue**, or Review hooks first if you want to read the commands:
+
+```text
+Hooks need review
+6 hooks are new or changed.
+Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+> 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+```
+
+A fresh install lists all 6 hooks the plugin registers. After that, any plugin update that touches a hook stops startup again, with the count of what changed this time (`1 hook is new or changed`, say) — pick Trust all and continue there too.
+
+Pick the third option, or skip past the prompt, and the hooks never run: MCP tools still work, but automatic recall and capture are both dead. Recovering means switching on two independent things:
+
+- `/hooks` — hook trust and on/off state. Trust and enable the entries marked *New hook - review required* or *Modified since last trusted*.
+- `/plugins` — the plugin's own enabled state. Confirm `openviking-memory` is enabled.
+
+TRAE and TRAE CN read `hooks.json` directly and need no such approval — restarting the client is enough.
+
## What gets installed
- `SessionStart` loads your profile and current project memory.
@@ -53,7 +76,7 @@ Quit and restart the corresponding client after installation.
2. Confirm that `openviking` is connected in the client's MCP settings.
3. Ask about an existing project or preference and confirm that the answer uses stored memory.
4. Tell the Agent a temporary preference, wait for the response to finish, then create a new session and ask for it again to verify capture, commit, and cross-session recall.
-5. For TraeCode CLI 2.0, run `trae-cli plugin list` and confirm that `openviking-memory` is enabled.
+5. For TraeCode CLI 2.0, run `trae-cli plugin list` to confirm that `openviking-memory` is enabled, then run `/hooks` in the session and confirm the OpenViking entries are trusted and switched on.
For Hook diagnostics, start the client with `OPENVIKING_DEBUG=1` and inspect:
@@ -82,6 +105,7 @@ Replace `trae-cn` with `trae` for TRAE. For TraeCode CLI 2.0, use `trae-cli plug
| Symptom | Cause and fix |
|---------|---------------|
| Automatic recall does not run | Quit the client completely, restart it, and create a new Agent session. |
+| TraeCode CLI 2.0 has the plugin, but nothing is recalled or captured | The startup hook-trust prompt was skipped or answered with *Continue without trusting*; an update that touches a hook asks for trust again. Trust and enable the OpenViking entries in `/hooks`, and confirm `openviking-memory` is enabled in `/plugins` — two independent switches, both have to be on. |
| MCP does not connect | Check the URL/API key in `~/.openviking/ovcli.conf`, then restart the client. |
| A new session cannot recall the previous turn | Inspect the Hook log and confirm that `Stop` ran without `/commit` connection or authentication errors. |
| The same content is captured more than once | Check user and project Hooks for older `trae-auto-recall.mjs` or `trae-auto-capture.mjs` entries. Re-running the installer removes OpenViking-managed legacy entries. |
diff --git a/docs/images/agents/en/codex.md b/docs/images/agents/en/codex.md
index bc9a45454..d0c54350d 100644
--- a/docs/images/agents/en/codex.md
+++ b/docs/images/agents/en/codex.md
@@ -14,17 +14,32 @@
## Step 2: Verify
-1. Start Codex.
-2. Approve Hooks: enter `/hooks`. Codex should show a prompt similar to `4 hooks need review`; approve them one by one. The four OpenViking hooks are:
+1. Start Codex. The first launch stops on a hook trust prompt — pick **Trust all and continue**:
+
+ ```text
+ Hooks need review
+ 6 hooks are new or changed.
+ Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+ > 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+ ```
+
+ The six hooks OpenViking registers are (an older Codex may show fewer):
```text
SessionStart
UserPromptSubmit
+ PreToolUse
Stop
+ SessionEnd
PreCompact
```
-3. Verify Profile loading: after approval, submit your first Prompt. Any prompt is fine. The plugin should load your Profile automatically. If the beginning of the conversation contains recalled memory context, the integration is working:
+2. If you miss the prompt or pick the third option, the hooks never run. Enter `/hooks` to trust and enable the entries, and check `/plugins` shows `openviking-memory` as enabled — two independent switches, both have to be on. A plugin update that touches a hook asks for trust again.
+
+3. Verify Profile loading: once trusted, submit your first Prompt. Any prompt is fine. The plugin should load your Profile automatically. If the beginning of the conversation contains recalled memory context, the integration is working:
```text
• UserPromptSubmit hook (completed)
@@ -38,7 +53,7 @@
|---|---|
| Auth error | Check `api_key` in `~/.openviking/ovcli.conf`, restart Codex |
| Connection error | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| `4 hooks need review` | `/hooks` and approve |
+| `6 hooks need review`, or no hook fires | Trust and enable in `/hooks`; confirm the plugin is enabled in `/plugins` |
| Need logs | `OPENVIKING_DEBUG=1` and `~/.openviking/logs/codex-hooks.log` |
## Reference
diff --git a/docs/images/agents/zh/codex.md b/docs/images/agents/zh/codex.md
index 302be607f..ea245d858 100644
--- a/docs/images/agents/zh/codex.md
+++ b/docs/images/agents/zh/codex.md
@@ -14,17 +14,32 @@
## 步骤2:验证
-1. 启动 Codex。
-2. 审批 Hooks:输入 `/hooks`,系统将提示类似 `4 hooks need review` 的信息,逐一审批通过。其中 OpenViking 相关的 4 个 Hook 为:
+1. 启动 Codex。首次启动会停在 Hook 信任确认上,选 **Trust all and continue**:
+
+ ```text
+ Hooks need review
+ 6 hooks are new or changed.
+ Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+ > 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+ ```
+
+ OpenViking 注册的 6 个 Hook 是(Codex 版本较旧时可能少几个):
```text
SessionStart
UserPromptSubmit
+ PreToolUse
Stop
+ SessionEnd
PreCompact
```
-3. 验证 Profile 加载:审批完成后,提交第一条 Prompt(内容随意即可)。此时插件应自动加载 Profile——若对话开头出现记忆召回内容,则表明接入成功:
+2. 错过这个提示,或当时选了第 3 项,Hook 就不会运行。输入 `/hooks` 补上信任并开启条目,`/plugins` 里确认 `openviking-memory` 已启用——两个开关相互独立,都要是开着的。插件更新动了 Hook 时会再要求信任一次。
+
+3. 验证 Profile 加载:信任完成后,提交第一条 Prompt(内容随意即可)。此时插件应自动加载 Profile——若对话开头出现记忆召回内容,则表明接入成功:
```text
• UserPromptSubmit hook (completed)
@@ -38,7 +53,7 @@
|---|---|
| 鉴权失败 | 检查 `~/.openviking/ovcli.conf` 的 `api_key`,重启 Codex |
| 连接失败 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |
-| `4 hooks need review` | `/hooks` 里批准 |
+| `6 hooks need review`,或 Hook 不生效 | `/hooks` 里信任并开启,`/plugins` 里确认插件已启用 |
| 需要日志 | `OPENVIKING_DEBUG=1`,看 `~/.openviking/logs/codex-hooks.log` |
## 参考
diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.md
index 8367e11a7..cc72283ff 100644
--- a/docs/zh/agent-integrations/04-codex.md
+++ b/docs/zh/agent-integrations/04-codex.md
@@ -25,12 +25,35 @@ GitHub 访问受限的地区,从火山引擎 TOS 镜像运行同一个安装
bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)
```
-现在不再需要任何 shell wrapper——插件自带的 stdio MCP 代理会在运行时读取 `~/.openviking/ovcli.conf`(或 `OPENVIKING_*` 环境变量),与 hooks 使用同一套配置链。安装完成后:
+现在不再需要任何 shell wrapper——插件自带的 stdio MCP 代理会在运行时读取 `~/.openviking/ovcli.conf`(或 `OPENVIKING_*` 环境变量),与 hooks 使用同一套配置链。安装完成后启动 Codex(TraeCode CLI 2.0 是 `trae-cli`):
```bash
-codex # 首次启动需进入 /hooks 完成一次审批
+codex
```
+### 首次启动:信任 hooks
+
+插件的 hooks 对 Codex 是新的,启动时会先停在一次信任确认上,选 **Trust all and continue**;想先看一眼 hook 命令就选 Review hooks:
+
+```text
+Hooks need review
+6 hooks are new or changed.
+Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+> 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+```
+
+全新安装会一次列出插件注册的全部 6 个 hook。之后每次插件更新只要动了 hook,Codex 都会再拦一次,数字是这次新增或改动的条数(比如只改了一个就是 `1 hook is new or changed`),同样选 Trust all and continue。
+
+选第 3 项或错过这一步,hooks 就不会运行:MCP 工具仍能调用,但自动召回和捕获全部停摆。要恢复,得让两个彼此独立的开关都处于开启状态:
+
+- `/hooks` — hook 的信任与开关,把标着 *New hook - review required* 或 *Modified since last trusted* 的条目信任并打开。
+- `/plugins` — 插件本身的启用状态,确认 `openviking-memory` 是 enabled。
+
+任何一边是关着的,自动召回和捕获都不会发生。
+
<details>
<summary><b>手动安装</b></summary>
@@ -102,7 +125,7 @@ TraeCode CLI 2.0 用户启动 `trae-cli`,并可用 `trae-cli plugin list` 确
|------|------|------|
| MCP 工具调用报认证错误 | 当前 ovcli 配置没有 authenticated server 所需的有效 `api_key` | 修正 `~/.openviking/ovcli.conf`(或运行 `node <插件目录>/scripts/setup.mjs`)后重启 Codex;stdio 代理会在启动时和认证失败后重新读取配置 |
| MCP 工具调用报连接错误 | 服务器不可达或 URL 配置错误 | 执行 `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` 检查服务器状态 |
-| `6 hooks need review` | 首次启动需要进行安全审批;升级新增 hook 后,Codex 会要求再次审批新增的 hook | 在 Codex 终端内输入 `/hooks` 完成审批 |
+| `6 hooks need review`,或插件已装但 hook 不生效 | 全新安装要信任全部 6 个 hook,之后每次插件更新改动到 hook 时还会再问一次;当时选了 *Continue without trusting* 或直接跳过,hooks 就一直不会运行 | `/hooks` 里信任并开启相关条目,`/plugins` 里确认 `openviking-memory` 已启用——两个开关相互独立,都要是开着的 |
| `ov config switch` 后插件仍指向旧服务器 | 上个会话的代理进程仍在运行 | 重启 Codex;代理在启动时解析凭据 |
| Hook 与 MCP 指向不同服务器 | 某一侧残留了过期的 `OPENVIKING_*` 凭据环境变量(默认环境变量优先于 ovcli.conf) | 清除过期环境变量(让 ovcli.conf 同时驱动两者)、设置 `OPENVIKING_CREDENTIAL_SOURCE=cli`,或保证环境变量一致 |
diff --git a/docs/zh/agent-integrations/13-trae.md b/docs/zh/agent-integrations/13-trae.md
index b36e2b620..60562c41c 100644
--- a/docs/zh/agent-integrations/13-trae.md
+++ b/docs/zh/agent-integrations/13-trae.md
@@ -39,6 +39,29 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
安装后完全退出并重启对应客户端。
+### TraeCode CLI 2.0:首次启动信任 hooks
+
+TraeCode CLI 2.0 用的是 Codex 插件格式,hooks 要先信任才会运行。启动 `trae-cli` 时会停在这个确认上,选 **Trust all and continue**;想先看一眼 hook 命令就选 Review hooks:
+
+```text
+Hooks need review
+6 hooks are new or changed.
+Hooks can run outside the sandbox after you trust them.
+
+ 1. Review hooks
+> 2. Trust all and continue
+ 3. Continue without trusting (hooks won't run)
+```
+
+全新安装会一次列出插件注册的全部 6 个 hook。之后每次插件更新只要动了 hook,启动时都会再拦一次,数字是这次新增或改动的条数(比如只改了一个就是 `1 hook is new or changed`),同样选 Trust all and continue。
+
+选第 3 项或错过这一步,hooks 就不会运行:MCP 工具仍能调用,但自动召回和捕获全部停摆。要恢复,得让两个彼此独立的开关都处于开启状态:
+
+- `/hooks` — hook 的信任与开关,把标着 *New hook - review required* 或 *Modified since last trusted* 的条目信任并打开。
+- `/plugins` — 插件本身的启用状态,确认 `openviking-memory` 是 enabled。
+
+TRAE 和 TRAE CN 走 `hooks.json`,重启客户端后直接生效,没有这一步。
+
## 安装内容
- `SessionStart`:加载用户画像和当前项目记忆。
@@ -53,7 +76,7 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
2. 在客户端的 MCP 设置中确认 `openviking` 已连接。
3. 提问一个与已有项目或个人偏好相关的问题,确认回答使用了已有记忆。
4. 告诉 Agent 一个临时偏好,等待回复完成;新建会话后再次询问,确认捕获、提交和跨会话召回均生效。
-5. 对 TraeCode CLI 2.0,运行 `trae-cli plugin list`,确认 `openviking-memory` 已启用。
+5. 对 TraeCode CLI 2.0,运行 `trae-cli plugin list` 确认 `openviking-memory` 已启用,并在会话里输入 `/hooks`,确认 OpenViking 的条目已信任且处于开启状态。
需要排查 Hook 时,设置 `OPENVIKING_DEBUG=1` 后启动客户端,并查看:
@@ -82,6 +105,7 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
| 现象 | 原因与处理 |
|------|-----------|
| 安装后没有自动召回 | 完全退出客户端后重新启动,并新建 Agent 会话。 |
+| TraeCode CLI 2.0 插件已装,但召回和捕获都不发生 | 启动时的 hook 信任确认被跳过,或当时选了 *Continue without trusting*;插件更新动了 hook 后也会重新要求信任。`/hooks` 里信任并开启 OpenViking 的条目,`/plugins` 里确认 `openviking-memory` 已启用——两个开关相互独立,都要是开着的。 |
| MCP 未连接 | 检查 `~/.openviking/ovcli.conf` 中的 URL/API Key,然后重启客户端。 |
| 新会话无法回忆上一轮内容 | 查看 Hook 日志,确认 `Stop` 已执行且 `/commit` 没有连接或鉴权错误。 |
| 同一内容被捕获多次 | 检查用户级与项目级 Hook 中是否仍有旧版 `trae-auto-recall.mjs` 或 `trae-auto-capture.mjs`;重跑安装器会移除由 OpenViking 管理的旧条目。 |
diff --git a/examples/codex-memory-plugin/README.md b/examples/codex-memory-plugin/README.md
index 64077c35f..0e37a26e8 100644
--- a/examples/codex-memory-plugin/README.md
+++ b/examples/codex-memory-plugin/README.md
@@ -46,9 +46,11 @@ Claude Code and Codex share this installer (drop `--harness codex` to pick inter
After install:
```bash
-codex # first run: review /hooks once
+codex # first run: pick "Trust all and continue" at the hook review prompt
```
+Startup stops on `6 hooks need review` — pick **Trust all and continue**. Every later update that touches a hook asks again, for however many changed. Choosing *Continue without trusting*, or skipping the prompt, leaves the hooks off: MCP tools still work, but recall and capture never fire. Two independent switches have to be on to get them back: `/hooks` (hook trust and on/off) and `/plugins` (the plugin's own enabled state). The same applies to TraeCode CLI 2.0, which runs this plugin under `trae-cli`.
+
### B. Codex marketplace install
This path uses the same checked-in stdio MCP proxy as the installer path. Authenticated and remote/cloud servers work when `~/.openviking/ovcli.conf` or the relevant `OPENVIKING_*` env vars are present in Codex's environment.
@@ -76,7 +78,7 @@ hooks = true
Finally start Codex and trust the plugin hooks once:
```bash
-codex # then run /hooks inside Codex to review & approve the hooks
+codex # then trust the hooks at the startup prompt, or via /hooks
```
> **Requirements & notes**