Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
docs: overhaul agent-integrations section (#2217)
t0saki77a2ee88c3e2
diff --git a/docs/en/agent-integrations/01-overview.md b/docs/en/agent-integrations/01-overview.mdindex 95909b879..214eaab6a 100644--- a/docs/en/agent-integrations/01-overview.md+++ b/docs/en/agent-integrations/01-overview.md@@ -1,26 +1,25 @@# Agent Integrations Overview-OpenViking can act as the long-term memory and context backend for many agent runtimes. This section collects the supported integration paths — pick the one that matches your agent.+OpenViking can act as the long-term memory and context backend for many agent runtimes. Pick the integration that matches your agent.## Which integration should I use?| If you use… | Use this ||-------------|----------|-| **Claude Code** | [Claude Code Memory Plugin](./02-claude-code.md) — auto-recall + auto-capture via hooks, no MCP tool calls required from the model |-| **OpenClaw** | [OpenClaw Plugin](./03-openclaw.md) — context-engine + hooks + tools + runtime manager, deep lifecycle integration |-| **Codex** | [Codex Memory Plugin](./04-codex.md) — lifecycle hooks for auto-recall, incremental capture, and pre-compact commit |-| **LangChain / LangGraph** | [LangChain and LangGraph](./06-langchain-langgraph.md) — session context backend, chat history, retriever, `viking_*` tools, LangGraph store, and middleware for agent workflows |-| **AstrBot** (QQ / Telegram / Discord and other IMs) | [Other community plugins](./05-other-plugins.md#astrbot-plugin) — auto-capture group chats, semantic recall, configurable venue memory isolation |-| **OpenCode** | [Other community plugins](./05-other-plugins.md) — explicit-tool and context-injection variants |-| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP Integration Guide](../guides/06-mcp-integration.md) — point any MCP-compatible client at the built-in `/mcp` endpoint |-| **Hermes Agent (Nous Research)** | [Hermes — OpenViking memory provider](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — first-class OpenViking memory provider, no plugin install needed |+| **Claude Code** | [Claude Code Memory Plugin](./02-claude-code.md) — auto-recall + auto-capture via hooks |+| **OpenClaw** | [OpenClaw Plugin](./03-openclaw.md) — context-engine with full lifecycle integration |+| **Codex** | [Codex Memory Plugin](./04-codex.md) — lifecycle hooks for auto-recall and incremental capture |+| **Hermes Agent** | [Hermes Agent](./05-hermes.md) — built-in OpenViking memory provider, no plugin install needed |+| **LangChain / LangGraph** | [LangChain and LangGraph](./07-langchain-langgraph.md) — retriever, tools, context backend, store, and middleware |+| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP Clients](./06-mcp-clients.md) — point any MCP-compatible client at the built-in `/mcp` endpoint |+| **AstrBot / OpenCode / …** | [Community Plugins](./08-community-plugins.md) — community-maintained integrations for various runtimes |-## Integration Depths+## Integration depthsSome integrations go beyond what a generic MCP client can do:- **Generic MCP clients** call OpenViking on demand through tools the model decides to invoke. Setup is one config snippet.-- **Hooks-based plugins** (Claude Code, Codex, OpenClaw, AstrBot) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."+- **Hooks-based / native plugins** (Claude Code, Codex, OpenClaw, Hermes Agent, AstrBot) drive recall and capture from runtime lifecycle events — every prompt, every turn, session start/end, compact, subagent spawn. The model doesn't need to "remember to recall."- **SDK integrations** (LangChain/LangGraph) wire OpenViking into framework-native abstractions such as retrievers, tools, chat history, stores, and middleware.For agents whose runtime exposes hooks, middleware, or a context-engine slot, the native integration path is usually the better default.diff --git a/docs/en/agent-integrations/02-claude-code.md b/docs/en/agent-integrations/02-claude-code.mdindex e7af8ae33..74fce9e18 100644--- a/docs/en/agent-integrations/02-claude-code.md+++ b/docs/en/agent-integrations/02-claude-code.md@@ -1,199 +1,98 @@# Claude Code Memory Plugin-Long-term semantic memory for [Claude Code](https://docs.claude.com/en/docs/claude-code/overview). Recall happens automatically before every prompt and capture happens automatically after every turn — no MCP tool calls required from the model.+Give [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) a cross-project, cross-session memory that grows smarter over time. Install once — recall and capture happen automatically on every conversation, no MCP tool calls required from the model.-Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin)+Source: [examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [Blog: motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)-## Quick Start--### One-line installer (recommended)+## Install```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)```-The script runs on macOS and Linux. It checks dependencies, asks whether you'll connect to a **self-hosted** server or to **Volcengine OpenViking Cloud** (`https://api.vikingdb.cn-beijing.volces.com/openviking`), sets up `~/.openviking/ovcli.conf` (prompting only if missing), clones the OpenViking repo to `~/.openviking/openviking-repo`, adds the `claude` function wrapper to your shell rc, and installs the plugin via `claude plugin install`. Every step is idempotent — re-running is safe.+The installer checks dependencies, configures your OpenViking connection, and installs the plugin. Every step is idempotent — re-running is safe.-If you'd rather do it by hand, follow the three steps below.+After install, start Claude Code and ask it something from a previous session. It remembers.-### Manual setup+<details>+<summary><b>Manual setup</b></summary>-#### 1. Wrap `claude` to inject env from `ovcli.conf`+If you prefer to set things up by hand:-This is the recommended path. The plugin's hooks **and** the bundled MCP server both read env vars, so we set them once — but scoped to the `claude` invocation only, not exported globally. Append to `~/.zshrc` or `~/.bashrc`:+1. **Shell function wrapper** — append a `claude()` function to `~/.zshrc` or `~/.bashrc` that injects `OPENVIKING_URL` and `OPENVIKING_API_KEY` from `~/.openviking/ovcli.conf` at each invocation. This keeps the API key scoped to the `claude` process tree. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf) for the full function and security rationale.-```bash-claude() {- if [ -f ~/.openviking/ovcli.conf ]; then- OPENVIKING_URL=$(jq -r '.url' ~/.openviking/ovcli.conf) \- OPENVIKING_API_KEY=$(jq -r '.api_key' ~/.openviking/ovcli.conf) \- command claude "$@"- else- command claude "$@"- fi-}-```+2. **Install the plugin** from the OpenViking repo root:-Re-source your rc and verify (use `~/.bashrc` if you're on bash):+ ```bash+ claude plugin marketplace add "$(pwd)/examples"+ claude plugin install claude-code-memory-plugin@openviking-plugins-local+ ```-```bash-source ~/.zshrc # or: source ~/.bashrc-type claude # expect: claude is a shell function-```+3. **Start Claude Code** and run `/mcp` to confirm the OpenViking entry shows your server URL.-Inside Claude Code, run `/mcp` after the next start — the OpenViking entry should show your remote URL with valid auth.--> **Don't have `ovcli.conf` yet?** See the [CLI section of the Deployment Guide](../guides/03-deployment.md#cli) to set one up.+> Don't have `ovcli.conf` yet? See [Deployment Guide → CLI](../guides/03-deployment.md#cli).>-> **Pure local mode** (`http://127.0.0.1:1933`, no auth)? Skip this step — the plugin uses the local default silently.+> Pure local mode (`http://127.0.0.1:1933`, no auth)? Skip step 1 — the plugin uses the local default.>-> **Why a function instead of `export`?** Globally exported env vars leak into every child process spawned from your shell — npm scripts, build tools, crash dumps, `/proc/<pid>/environ`. The function-wrapper limits the secret to the `claude` process tree only.+> Claude Code < 2.0? See the [plugin README's Legacy mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20).-#### 2. Install the plugin+</details>-From the OpenViking repo root:+## Verify```bash-claude plugin marketplace add "$(pwd)/examples"-claude plugin install claude-code-memory-plugin@openviking-plugins-local-```--> The plugin installs at user scope by default — active from any directory. We don't pass `--scope` because older Claude Code 2.0.x builds (e.g. 2.0.76) reject the flag.->-> The marketplace entry points Claude Code at the source directory. Edits to `scripts/`, `hooks/`, and config files take effect on the next hook invocation — no reinstall. But moving / renaming / deleting the source dir, or `git checkout`-ing to a branch without these files, breaks the plugin.->-> **Claude Code < 2.0?** `claude plugin` shipped in 2.0 (Oct 2025). Older builds still expose `claude mcp add` + the hooks system — the [plugin README's Legacy mode section](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#legacy-mode-claude-code--20) shows how to wire the same functionality by hand, and the one-line installer detects the version and offers it automatically.--#### 3. Start Claude Code--```bash-claude+type claude # expect: claude is a shell function```-Inside Claude Code, run `/mcp` to confirm the OpenViking MCP entry shows your remote URL. If the plugin doesn't seem to fire, set `OPENVIKING_DEBUG=1` and check `~/.openviking/logs/cc-hooks.log`.--## Why a function wrapper?+Inside Claude Code:-The plugin's hooks read `ovcli.conf` directly — but the bundled `.mcp.json` entry **cannot**. Claude Code parses `.mcp.json` itself and only supports `${VAR}` substitution, so config-file values can't transparently reach the MCP server URL or auth headers.+- `/plugins` → find **openviking-memory** in Installed (with **openviking** MCP connected underneath)+- `/mcp` → the OpenViking entry should show your server URL with valid auth+- `/openviking-memory:ov` → shows server health, identity, recall/injection stats, and toggle states-Injecting env vars at `claude` invocation is the single path that covers both hooks and MCP. Wrapping in a shell function (rather than a global `export`) keeps the API key out of every other shell child process — see the security note in [the manual setup step 1](#1-wrap-claude-to-inject-env-from-ovcli-conf).+If the plugin doesn't seem to fire, set `OPENVIKING_DEBUG=1` and check `~/.openviking/logs/cc-hooks.log`.-**Symptom of misconfiguration**: hooks (auto-recall, auto-capture) work fine because they read `ovcli.conf` via Node, but the on-demand MCP tools (`search`, `read`, `store`, …) silently connect to `http://127.0.0.1:1933` with empty auth headers, and `/mcp` shows the wrong URL.+## How it works-## Configuration+The plugin hooks into Claude Code's lifecycle: it searches OpenViking and injects relevant memories before every prompt, captures new conversation turns after each response, injects your profile and memory index on session start, commits pending messages before compaction and on session end, and gives each subagent an isolated memory session. All write operations run asynchronously so you never wait for OpenViking.-### Resolution priority+<details>+<summary><b>Configuration</b></summary>-Every plugin field follows this chain (highest → lowest):+Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).-1. **Environment variables** (`OPENVIKING_*`)-2. **`ovcli.conf`** — connection fields only (`url`, `api_key`, `account`, `user`, `agent_id`)-3. **`ov.conf`** — server config; the plugin reads `server.url`, `server.root_api_key`, and a legacy `claude_code` block if present-4. **Built-in defaults** (`http://127.0.0.1:1933`, no auth)+| Env Var | Default | Description |+|---------|---------|-------------|+| `OPENVIKING_AUTO_RECALL` | `true` | Auto-recall on every user prompt |+| `OPENVIKING_RECALL_LIMIT` | `6` | Max memories to inject per turn |+| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | Token budget for inline content |+| `OPENVIKING_AUTO_CAPTURE` | `true` | Auto-capture after each turn |+| `OPENVIKING_BYPASS_SESSION` | `false` | Skip all hooks for this session |+| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob patterns to auto-bypass |+| `OPENVIKING_MEMORY_ENABLED` | (auto) | Force on/off |+| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/cc-hooks.log` |-> ⚠️ **Hooks only.** This chain is implemented in `scripts/config.mjs` and consumed by hook scripts. It does **not** apply to MCP server registration — see [Why a function wrapper?](#why-a-function-wrapper) above.+For multi-tenant deployments, set `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, and `OPENVIKING_AGENT_ID`. Full env-var list in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration).-### Key environment variables--| Env Var | Default | Description |-|--------------------------------------------------|---------------|-----------------------------------------------------------------------|-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL |-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key; sent as `Authorization: Bearer <key>` |-| `OPENVIKING_AUTO_RECALL` | `true` | Enable auto-recall on every user prompt |-| `OPENVIKING_RECALL_LIMIT` | `6` | Max memories to inject per turn |-| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | Token budget for inline content; over-budget items degrade to URI hints |-| `OPENVIKING_AUTO_CAPTURE` | `true` | Enable auto-capture; also gates write hooks |-| `OPENVIKING_BYPASS_SESSION` | `false` | One-shot: `1`/`true` skips every hook in the current process |-| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV of glob patterns matched against `session_id` or `cwd` |-| `OPENVIKING_MEMORY_ENABLED` | (auto) | `0`/`false`=force off; `1`/`true`=force on |-| `OPENVIKING_DEBUG` | `false` | Write hook logs to `~/.openviking/logs/cc-hooks.log` |--For multi-tenant deployments, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, and `OPENVIKING_AGENT_ID` set the corresponding `X-OpenViking-*` headers. The full env-var list (recall tuning, capture tuning, lifecycle, debug) is in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration).--### Bypass a session--Use Claude Code in a `/tmp` PoC directory without polluting your long-term memory:--```bash-# Persistent: any session whose session_id or cwd matches a pattern-export OPENVIKING_BYPASS_SESSION_PATTERNS='/tmp/**,**/scratch/**,/Users/me/Dev/throwaway/*'--# Or one-shot:-OPENVIKING_BYPASS_SESSION=1 claude-```--When bypass is active, every hook approves immediately without contacting OpenViking.+</details>## Statusline-The plugin also renders a one-line OpenViking status under your Claude Code input box. The installer registers it in `~/.claude/settings.json` (CC's plugin manifest doesn't accept a `statusLine` field, so it has to live in user settings).--```text-OV ✓ │ ↩ 6 mem (0.92) · 50ms last turn injected 6 memories, top score 0.92-OV ⚠ slow probe missed the 1 s budget (server may be lagging)-OV ✗ offline server unreachable-OV ⚡ bypass OPENVIKING_BYPASS_SESSION* matched-OV ✓ │ ✎ 573/20k · 2 arch pending capture, two archives produced this session-OV ✓ │ 🔗 resumed │ +3 today session re-hydrated; 3 archives committed today-```--The hook scripts write small JSON snapshots to `~/.openviking/state/`; the statusline script reads those plus a 5 s shared cache of `GET /health`. The probe is bounded by a 1 s hard timeout; the cache is shared across sessions to prevent stampedes.--Set `OPENVIKING_STATUSLINE=off` to silence without removing the registration, or `jq 'del(.statusLine)' ~/.claude/settings.json` to remove. If you already had a custom statusline, the installer prompts replace / skip / manual compose.--For the full segment glossary (when each one shows, why one might be missing) and personalization recipes (hide segments, recolor, compose with another statusline, add a custom segment), see [`examples/claude-code-memory-plugin/STATUSLINE.md`](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md). The easiest path is to open Claude Code and ask it to read the doc, explain the segments, and tailor anything to your preference.--## Compared to Claude Code's built-in `MEMORY.md`--This plugin **complements** Claude Code's native memory system, it doesn't replace it:--| Feature | Built-in `MEMORY.md` | OpenViking plugin |-|--------------|-----------------------------------|----------------------------------------------------|-| Storage | Flat markdown | Vector DB + structured extraction |-| Search | Loaded into context wholesale | Semantic similarity + ranking + token budget |-| Scope | Per-project | Cross-project, cross-session, cross-agent |-| Capacity | ~200 lines (context limit) | Unlimited (server-side storage) |-| Extraction | Manual rules | LLM-powered entity / preference / event extraction |-| Subagents | Same as parent | Isolated session + typed agent namespace |--## Hook behavior--| Hook | Trigger | Action |-|-----------------------|--------------------------------------------|---------------------------------------------------------------------------------------------------|-| `UserPromptSubmit` | Each user turn | Search OV → rank → inject `<openviking-context>` block within a token budget |-| `Stop` | Claude finishes a response | Parse transcript → push new user turns to OV session → commit when pending tokens cross threshold |-| `SessionStart` | New / resumed / post-compact session | Every source (startup/clear/resume/compact): inject the user's `profile.md` and an annotated listing of `preferences/` + `entities/`, capped by `OPENVIKING_PROFILE_TOKEN_BUDGET` (default `10000` tokens, CJK-aware; set `OPENVIKING_NO_AUTO_INJECT=1` to skip). On `resume`/`compact` additionally fetch the persistent session's latest archive overview + pre-archive abstracts. Both halves compose into a single `<openviking-context>` envelope. |-| `PreCompact` | Before Claude Code rewrites the transcript | Commit pending messages so they become an archive before CC mutates the transcript |-| `SessionEnd` | Claude Code session closes | Final commit so the last window is archived |-| `SubagentStart` | Parent spawns a subagent via Task tool | Derive an isolated OV session ID for the subagent, persist start state |-| `SubagentStop` | Subagent finishes | Read subagent transcript → push to isolated session with subagent-typed agent header → commit |--`Stop`, `SessionEnd`, and `SubagentStop` use a detached-worker pattern so the user never waits for OpenViking. Disable with `OPENVIKING_WRITE_PATH_ASYNC=false` if you need deterministic ordering.--`auto-capture` strips `<openviking-context>`, `<system-reminder>`, `<relevant-memories>`, and `[Subagent Context]` blocks before pushing to OV — without this, the recall context the plugin injects this turn would be captured back as part of the user's message next turn.--### OV session ID derivation--The OV session ID embeds the CC `session_id` verbatim, so you can map between the two by eye:--- Parent: `cc-<ccSessionId>`, e.g. `cc-7d978bb3-cd9c-4ac6-828d-20965d66b783`-- Subagent: `cc-<ccSessionId>__agent-<agentId>`, e.g. `cc-7d978bb3-cd9c-4ac6-828d-20965d66b783__agent-abc123`--`~/.openviking/state/last-capture.json` shows the live `cc_session_id` and `ov_session_id` for the current session; the CC side's session ID is also the filename of `~/.claude/projects/<encoded-cwd>/<session_id>.jsonl`.+The plugin renders an OpenViking status indicator under your Claude Code input box — connection health, recall count, capture progress, and session state at a glance. See [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md) for the full segment glossary and personalization recipes.## Troubleshooting-| Symptom | Cause | Fix |-|--------------------------------------------|----------------------------------------------------------------|----------------------------------------------------------------------------------------------|-| Plugin not activating | No `ov.conf` / `ovcli.conf` found | Run the [one-line installer](#one-line-installer-recommended), or set `OPENVIKING_MEMORY_ENABLED=1` plus URL/API_KEY env vars |-| Hooks fire but recall is empty | OpenViking server not running, or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |-| MCP tools hit `127.0.0.1` instead of remote | `.mcp.json` only resolves `${VAR}`, no `ovcli.conf` integration | See [Why a function wrapper?](#why-a-function-wrapper) |-| Remote auth 401 / 403 | Wrong API key or missing tenant headers | Verify `OPENVIKING_API_KEY`; for multi-tenant, also check `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |-| `Stop` hook times out | Server slow + sync write path | Leave `OPENVIKING_WRITE_PATH_ASYNC=true` (default), or raise the `Stop` timeout in `hooks/hooks.json` |+| Symptom | Cause | Fix |+|---------|-------|-----|+| Plugin not activating | No `ov.conf` / `ovcli.conf` found | Run the [installer](#install), or set `OPENVIKING_MEMORY_ENABLED=1` plus URL/API_KEY env vars |+| Hooks fire but recall is empty | Server not running or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |+| MCP tools hit `127.0.0.1` instead of remote | Missing function wrapper | Ensure `type claude` says "shell function"; see [Manual setup](#install) |+| Remote auth 401 / 403 | Wrong API key or missing tenant headers | Check `OPENVIKING_API_KEY`; for multi-tenant also check `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |## See also-- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — exhaustive env-var tables, hook timeouts, debug logging, architecture diagram+- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — motivation, architecture overview, and demo+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — full env-var tables, hook details, architecture diagram- [Migration notes](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/MIGRATION.md) — upgrading from earlier plugin versions-- [MCP Integration Guide](../guides/06-mcp-integration.md) — for MCP tool parameters and other clients+- [MCP Clients](./06-mcp-clients.md) — for MCP tool parameters and other clients- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setupdiff --git a/docs/en/agent-integrations/03-openclaw.md b/docs/en/agent-integrations/03-openclaw.mdindex 2209f4447..40e75ec86 100644--- a/docs/en/agent-integrations/03-openclaw.md+++ b/docs/en/agent-integrations/03-openclaw.md@@ -1,8 +1,6 @@# OpenClaw Plugin-Use OpenViking as the long-term memory backend for [OpenClaw](https://github.com/openclaw/openclaw). After installation, OpenClaw will automatically remember important facts from conversations and recall relevant context before replying.--This plugin is registered as the `openviking` context engine — it owns long-term memory retrieval, session archiving, archive summaries, and memory extraction across the OpenClaw lifecycle.+Add long-term memory to [OpenClaw](https://github.com/openclaw/openclaw). After installation, OpenClaw automatically remembers important facts from conversations and recalls relevant context before every reply.Source: [examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin)@@ -13,19 +11,19 @@ Source: [examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree| Node.js | >= 22 || OpenClaw | >= 2026.4.8 |-The plugin connects to an existing OpenViking server. Make sure you have one reachable over HTTP — see the [Deployment Guide](../guides/03-deployment.md). Quick check:+The plugin connects to a running OpenViking server — see the [Deployment Guide](../guides/03-deployment.md) if you need one.++<details>+<summary><b>Upgrading from the legacy <code>memory-openviking</code> plugin?</b></summary>++The old plugin is not compatible. Run the cleanup script first:```bash-node -v-openclaw --version+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh+bash cleanup-memory-openviking.sh```-> **Upgrading from the legacy `memory-openviking` plugin?** It's not compatible with the new `openviking` plugin. Run the cleanup script first:->-> ```bash-> curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh-> bash cleanup-memory-openviking.sh-> ```+</details>## Install@@ -33,128 +31,79 @@ openclaw --versionopenclaw plugins install clawhub:@openviking/openclaw-pluginopenclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --jsonopenclaw gateway restart-openclaw openviking status --json```-The `setup` wizard writes configuration to `$OPENCLAW_STATE_DIR/openclaw.json` (default: `~/.openclaw/openclaw.json`) and activates the context-engine slot.+The `setup` wizard writes configuration and activates the plugin. After install, start a conversation — OpenClaw will begin remembering and recalling automatically.<details>-<summary><b>Alternative: Install via <code>ov-install</code></b></summary>+<summary><b>Alternative: install via <code>ov-install</code></b></summary>-If ClawHub is unavailable (rate-limited, offline, or auth issues), use the `ov-install` backup path:+If ClawHub is unavailable:```bashnpm install -g openclaw-openviking-setup-helper-ov-install+ov-install --base-url http://your-server:1933```-Common variants:+Key parameters:-```bash-# Target a specific OpenClaw data directory-ov-install --workdir ~/.openclaw-second--# Pin to a specific plugin release-ov-install --base-url http://your-server:1933 --plugin-version=0.2.9-```--To upgrade later:--```bash-npm install -g openclaw-openviking-setup-helper@latest && ov-install --base-url http://your-server:1933-```+| Parameter | Meaning |+| --- | --- |+| `--workdir PATH` | OpenClaw data directory (default `~/.openclaw`) |+| `--plugin-version=VER` | Plugin version: npm version, dist-tag, or Git ref |+| `--base-url URL` | OpenViking server URL |+| `--api-key KEY` | OpenViking API key |+| `--uninstall` | Uninstall the plugin |-### `ov-install` parameters--| Parameter | Meaning |-| ----------------------------- | ------------------------------------------------------------------ |-| `--workdir PATH` | Target OpenClaw data directory (default `~/.openclaw`) |-| `--plugin-version=VER` | Plugin version: npm version (e.g. `2026.5.8`), npm dist-tag (e.g. `dev`), or Git ref (e.g. `v0.3.16`, `main`). Default: npm `latest` |-| `--plugin-source=npm\|github` | Plugin download source (default `npm`) |-| `--plugin-package=NAME` | npm plugin package name (default `@openviking/openclaw-plugin`) |-| `--github-repo owner/repo` | Use a different GitHub repo for plugin files (default `volcengine/OpenViking`) |-| `--current-version` | Print the currently installed plugin version and exit |-| `--update` | Upgrade only the plugin to the requested `--plugin-version` |-| `--rollback` | Roll back the last plugin upgrade |-| `--uninstall` | Uninstall the plugin |-| `--base-url URL` | OpenViking server URL |-| `--api-key KEY` | OpenViking API key |-| `--agent-prefix PREFIX` | Agent prefix for memory namespace isolation |-| `--account-id ID` | Multi-tenant account ID (root-key deployments only) |-| `--user-id ID` | Multi-tenant user ID (root-key deployments only) |-| `--force-slot` | Force-replace the contextEngine slot if another plugin owns it |-| `--allow-offline` | Save config even if the OpenViking server is unreachable |+Full parameter list in the [install guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md).</details>-## Plugin configuration--The plugin configuration lives under `plugins.entries.openviking.config`. Setup usually writes this for you — manual edits are only needed if you change servers later.--```bash-openclaw config get plugins.entries.openviking.config-```--| Parameter | Default | Meaning |-| -------------- | ------------------------ | -------------------------------------------------------- |-| `baseUrl` | `http://127.0.0.1:1933` | Remote OpenViking HTTP endpoint |-| `apiKey` | empty | Optional OpenViking API key |-| `agent_prefix` | `default` | Agent prefix used by this OpenClaw instance on the server |--Common settings:--```bash-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933-openclaw config set plugins.entries.openviking.config.apiKey your-api-key-openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix-```-## Verify-For a one-shot health check covering plugin registration, server connectivity, and version compatibility, run:-```bashopenclaw openviking status```-For automation, append `--json` to `openclaw openviking status` to get a machine-readable result. `openclaw openviking setup` also supports `--json` when used with `--base-url`.+This checks plugin registration, server connectivity, and version compatibility in one command. Append `--json` for machine-readable output.-Or check the underlying signals manually. The plugin owns the `contextEngine` slot:+<details>+<summary><b>Manual verification</b></summary>++Check the plugin owns the `contextEngine` slot:```bashopenclaw config get plugins.slots.contextEngine+# expect: openviking```-If the output is `openviking`, the plugin is active.--Follow OpenClaw logs for the registration message:+For an end-to-end pipeline test:```bash-openclaw logs --follow-# expect: openviking: registered context-engine+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py```-OpenViking server log (default location):+See [HEALTHCHECK.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md) for details.-```bash-cat ~/.openviking/data/log/openviking.log-```--Currently-installed plugin version:+</details>-```bash-ov-install --current-version-```+<details>+<summary><b>Configuration</b></summary>-### Pipeline health check (optional)+Plugin config lives under `plugins.entries.openviking.config`. Setup usually writes this for you.-For an end-to-end sanity check (Gateway → OpenViking pipeline), run:+| Parameter | Default | Meaning |+| --- | --- | --- |+| `baseUrl` | `http://127.0.0.1:1933` | OpenViking server endpoint |+| `apiKey` | empty | OpenViking API key |+| `agent_prefix` | `default` | Agent prefix for memory namespace isolation |```bash-python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key```-This script injects a real conversation through Gateway and verifies from the OpenViking side that the session was captured, committed, archived, and had memories extracted. See [HEALTHCHECK.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md) for details.+</details>## Uninstall@@ -163,10 +112,8 @@ curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examplesbash uninstall-openviking.sh```-For a non-default OpenClaw state directory, append `--workdir ~/.openclaw-second`.-## See also-- [Full install guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md) — every install path, parameter, and verification step+- [Full install guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md) — every install path and parameter- [Plugin design notes](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md) — architecture, identity & routing, hook lifecycle-- [Agent operator guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md) — for agents driving installation on behalf of a user\ No newline at end of file+- [Agent operator guide](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md) — for agents driving installation on behalf of a userdiff --git a/docs/en/agent-integrations/04-codex.md b/docs/en/agent-integrations/04-codex.mdindex 991adca52..2f3328363 100644--- a/docs/en/agent-integrations/04-codex.md+++ b/docs/en/agent-integrations/04-codex.md@@ -1,177 +1,82 @@# Codex Memory Plugin-Long-term semantic memory for [Codex](https://developers.openai.com/codex). Auto-recalls relevant memories on every prompt, incrementally captures each turn, commits to OpenViking's memory extractor before compaction, and wires Codex up to OpenViking's native `/mcp` endpoint so the model can `search` / `store` / `read` / `grep` / `glob` / `list` / `forget` / `add_resource` memories directly — no local MCP server to maintain.+Give [Codex](https://developers.openai.com/codex) persistent memory across sessions. Install once — memories are recalled on every prompt, captured after each turn, and committed before compaction. The plugin also wires Codex up to OpenViking's `/mcp` endpoint so the model can search, store, and manage memories directly.-Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)+Source: [examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [Blog: motivation & demo](https://blog.openviking.ai/post/openviking-coding-agent/)-## Quick Start--### One-line installer (recommended)+## Install```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)```-The installer checks `codex`, `git`, and Node.js 22+, refreshes (or clones on first run) `~/.openviking/openviking-repo`, registers a local `openviking-plugins-local` marketplace, enables `openviking-memory@openviking-plugins-local`, sets `features.plugin_hooks = true`, and pre-populates Codex's plugin cache so the plugin resolves immediately. Rerunning the installer is idempotent — it always pulls latest before installing.--It reads `~/.openviking/ovcli.conf` for the OpenViking URL, renders the `/mcp` endpoint into the cached `.mcp.json`, and appends a `codex()` shell function to your rc that pulls `OPENVIKING_API_KEY` / `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` from ovcli.conf at every codex invocation. The API key stays in `ovcli.conf`; the `.mcp.json` on disk only references `OPENVIKING_API_KEY` via `bearer_token_env_var`, never embeds it.+The installer checks dependencies, configures the OpenViking connection, and registers the plugin. Every step is idempotent.After install:```bashsource ~/.zshrc # or ~/.bashrc-codex # first run: review /hooks once when prompted+codex # first run: approve hooks once when prompted via /hooks```-### Manual setup+<details>+<summary><b>Manual setup</b></summary>-Prerequisites:--```bash-node --version # >= 22-codex --version # >= 0.130.0-codex features list | grep codex_hooks-```+Prerequisites: Node.js >= 22, Codex >= 0.130.0, `codex_hooks` feature enabled.-Three steps the installer does for you, that you can do manually:--1. **Shell function wrapper** in `~/.zshrc` / `~/.bashrc`. The installer-emitted version (see `setup-helper/install.sh`) additionally re-renders the cached `.mcp.json` bearer field on each launch, which is required if you swap `OPENVIKING_CLI_CONFIG_FILE` between configs with and without `api_key`. A simpler fixed-config equivalent:-- ```bash- codex() {- local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"- local _ov_url _ov_key _ov_account _ov_user- if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then- local _ov_env- _ov_env=$(node -e '- try {- const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));- const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";- process.stdout.write(- out("OV_URL", c.url) +- out("OV_KEY", c.api_key) +- out("OV_ACCOUNT", c.account) +- out("OV_USER", c.user)- );- } catch {}- ' "$_ov_conf" 2>/dev/null)- eval "$_ov_env"- fi- _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"- _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"- _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"- _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"- unset OV_URL OV_KEY OV_ACCOUNT OV_USER- # Empty values are NOT exported — Codex hard-fails on empty- # bearer_token_env_var targets.- local -a _env_args=()- [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")- [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")- [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")- [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")- _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")- env "${_env_args[@]}" codex "$@"- }- ```--2. **Plugin install** via a local marketplace pointing at the plugin directory. See `setup-helper/install.sh` for the exact `codex plugin marketplace add` invocation.--3. **Placeholder rendering**: the checked-in `.mcp.json` keeps `__OPENVIKING_MCP_URL__` and `hooks/hooks.json` keeps `__OPENVIKING_PLUGIN_ROOT__`; both must be `sed`-substituted to absolute values when the plugin is copied into Codex's cache (`~/.codex/plugins/cache/...`). The installer does this automatically.--## Configuration--Resolution priority for every connection / identity field — env vars always win:--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` (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.--Auth is sent as `Authorization: Bearer <api_key>` to both the REST API (used by hooks) and the `/mcp` endpoint (used by the model).--For **unauthenticated local OV** (`ovcli.conf` without `api_key`, or no ovcli.conf at all), `.mcp.json` is rendered *without* `bearer_token_env_var`. Codex 0.130 hard-fails MCP startup with `Environment variable ... is empty` when `bearer_token_env_var` points at an empty/unset env var. The `codex()` shell-function wrapper re-renders this field on every codex launch based on whichever ovcli.conf `OPENVIKING_CLI_CONFIG_FILE` is currently pointing at, so swapping configs (e.g. for benchmark isolation) doesn't require a re-install. Identity headers still flow through `env_http_headers`.--### Key environment variables--| Variable | Default | Notes |-|----------|---------|-------|-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL (the `/mcp` endpoint is derived from this at install time) |-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key, sent as `Authorization: Bearer` |-| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | Multi-tenant identity headers |-| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | Alternate `ovcli.conf` path |-| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | Alternate `ov.conf` path |-| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart active-window threshold |-| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle-TTL sweep threshold |-| `OPENVIKING_DEBUG` | `false` | Write JSONL events to `~/.openviking/logs/codex-hooks.log` |+1. **Shell function wrapper** — append a `codex()` function to your shell rc that injects OpenViking env vars from `ovcli.conf`. See the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) for the full function.-### Tuning+2. **Plugin install** — register a local marketplace and enable the plugin. See `setup-helper/install.sh` for the exact commands.-Plugin tuning is set via `OPENVIKING_*` environment variables in your shell rc — they take effect on every codex launch.+3. **Placeholder rendering** — the checked-in `.mcp.json` and `hooks.json` contain placeholders that must be substituted when copied to Codex's plugin cache. The installer does this automatically.-```sh-# ~/.zshrc-export OPENVIKING_RECALL_LIMIT=6-export OPENVIKING_CAPTURE_ASSISTANT_TURNS=1-export OPENVIKING_AUTO_COMMIT_ON_COMPACT=1-export OPENVIKING_DEBUG=1-```+</details>-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).+## Verify-> **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.+```bash+type codex # expect: codex is a shell function+```-## Hook behavior+Inside Codex, the plugin should recall memories on each prompt. Set `OPENVIKING_DEBUG=1` to write events to `~/.openviking/logs/codex-hooks.log`.-| Hook | When | Behavior |-|------|------|----------|-| `SessionStart` (matcher `clear\|startup`) | Fresh process, `/new`, or `/clear` | Active-window heuristic: if exactly one other state file was touched in the last 2 min, commit it (the just-ended session). Idle-TTL sweep at the tail picks up SIGTERM/`/exit` orphans older than 30 min. `source=resume` is a hard no-op. |-| `UserPromptSubmit` | Every prompt | Search OpenViking REST `/search/find`, rank, inject top results into `hookSpecificOutput.additionalContext`. |-| `Stop` | Every turn end | Append new user/assistant turns to the long-lived OpenViking session keyed by Codex `session_id`. No commit per turn. |-| `PreCompact` | Before Codex summarizes | Catch-up append + commit so OpenViking's extractor runs against the full pre-compact transcript, then null `ovSessionId` so the next `Stop` opens a fresh OV session. |+## How it works-`Stop` deliberately does not commit per turn — committing extracts memories, and per-turn extraction would over-fragment the memory tree. The decision tree behind which hook seals which OV session is in [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md).+The plugin hooks into Codex's lifecycle: it searches OpenViking and injects relevant memories before every prompt (`UserPromptSubmit`), appends new turns to the session after each response (`Stop`), and commits the full transcript before compaction (`PreCompact`) so memory extraction runs against the complete conversation. On fresh session start, it also cleans up orphaned sessions from prior runs.-### Known gap: SIGTERM / Ctrl+C / `/exit` are silent+> **Known gap**: Codex fires no hook on `SIGTERM` / `Ctrl+C` / `/exit`. Orphaned sessions are recovered by the next `SessionStart`'s idle-TTL sweep (30 min) or active-window heuristic.-Codex fires no hook on process exit. If you `/exit` without `/compact`, the OV session for that codex session_id stays open server-side. Two fallbacks recover the orphan:+<details>+<summary><b>Configuration</b></summary>-1. The next `SessionStart` (source=startup|clear) idle-TTL sweep commits any state file older than 30 min.-2. The active-window heuristic catches the orphan if you `/new` or `/clear` shortly after.+Config priority: env vars > `ovcli.conf` > `ov.conf` > built-in defaults (`http://127.0.0.1:1933`, no auth).-## MCP tools+| Env Var | Default | Description |+|---------|---------|-------------|+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | Full server URL |+| `OPENVIKING_API_KEY` | — | API key (sent as `Authorization: Bearer`) |+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart active-window threshold |+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart idle-TTL sweep threshold |+| `OPENVIKING_DEBUG` | `false` | Write logs to `~/.openviking/logs/codex-hooks.log` |-The plugin wires Codex up to OpenViking's built-in `/mcp` endpoint via streamable HTTP. Tool list, per-tool semantics, and protocol details live in the [MCP Integration Guide](../guides/06-mcp-integration.md) — not duplicated here.+Tuning knobs (`OPENVIKING_RECALL_LIMIT`, `OPENVIKING_CAPTURE_ASSISTANT_TURNS`, etc.) are documented in the [plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin).-`.mcp.json` ships with the OV server URL rendered at install time and uses `bearer_token_env_var: "OPENVIKING_API_KEY"` plus `env_http_headers` for the multi-tenant identity headers. The API key never lands on disk in `.mcp.json`; it's pulled from env at codex launch by the shell function wrapper.+</details>## Troubleshooting| Symptom | Cause | Fix ||---------|-------|-----|-| `MCP server is not logged in. Run codex mcp login` | `OPENVIKING_API_KEY` not in env at codex launch, and OV server returned 401, so Codex fell back to OAuth | Make sure the `codex()` shell function is sourced (`type codex` should say "shell function") and `ovcli.conf` has `api_key` |-| `4 hooks need review before they can run` | First-launch security review | Open `/hooks` in Codex and approve |-| `hook (failed) exited with code 1` after approval | Stale `hooks.json` placeholder; cache wasn't re-rendered | Rerun the one-line installer |-| 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 legacy `codex.debug=true` in `ov.conf`) to write JSON-Lines events to `~/.openviking/logs/codex-hooks.log`.--## Differences from the Claude Code plugin--| Aspect | Claude Code Plugin | Codex Plugin |-|--------|--------------------|--------------|-| Plugin root env | `CLAUDE_PLUGIN_ROOT` (expanded by CC) | `CODEX_PLUGIN_ROOT` (NOT expanded by Codex 0.130; installer renders absolute paths) |-| `UserPromptSubmit` output | `decision: "approve"` + `additionalContext` | `additionalContext` only — `approve` is not a Codex output |-| Compaction hook | n/a | `PreCompact` — full-transcript commit before context loss |-| Config section | `claude_code` | `codex` |-| Default config file | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`, falls back to `ov.conf` |-| MCP server | Local stdio (CC's `.mcp.json` doesn't support env-var Bearer) | Streamable-HTTP to OpenViking's native `/mcp` |+| `MCP server is not logged in` | `OPENVIKING_API_KEY` not in env at launch | Ensure `codex()` shell function is sourced and `ovcli.conf` has `api_key` |+| `4 hooks need review` | First-launch security review | Run `/hooks` in Codex and approve |+| `hook (failed) exited with code 1` | Stale placeholder in plugin cache | Re-run the one-line installer |+| Recall returns nothing | Server unreachable or wrong URL | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |+| Hook 401 but MCP works (or vice versa) | env vs ovcli.conf mismatch | Hooks re-read ovcli.conf every fire; MCP reads env at startup. Restart codex. |## See also-- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — full env-var list, validation SOP, architecture diagram-- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit decision tree-- [MCP Integration Guide](../guides/06-mcp-integration.md) — protocol, tools, and how OpenViking exposes `/mcp`+- [Blog: OpenViking in Claude Code / Codex](https://blog.openviking.ai/post/openviking-coding-agent/) — motivation, architecture overview, and demo+- [Plugin README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — full env-var list, architecture diagram+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit decision tree+- [MCP Clients](./06-mcp-clients.md) — MCP protocol, tools, and other clients- [Deployment Guide → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` setupdiff --git a/docs/en/agent-integrations/05-hermes.md b/docs/en/agent-integrations/05-hermes.mdnew file mode 100644index 000000000..d70cc06a8--- /dev/null+++ b/docs/en/agent-integrations/05-hermes.md@@ -0,0 +1,33 @@+# Hermes Agent++[Hermes Agent](https://hermes-agent.nousresearch.com/) by Nous Research has a first-class OpenViking memory provider built in. No plugin to install — just point Hermes at your OpenViking server and it handles memory storage, recall, and extraction natively.++## Setup++Run the Hermes memory setup wizard:++```bash+hermes memory setup+```++The wizard prompts for:++- **OpenViking server URL** — your self-hosted server (default `http://127.0.0.1:1933`) or Volcengine OpenViking Cloud+- **API key** — leave blank for local dev mode+- **Tenant account / user / agent IDs** — for multi-tenant deployments++Configuration is saved to Hermes's `config.yaml` and `.env` files.++## Verify++```bash+hermes memory status+```++Once configured, Hermes automatically uses OpenViking for long-term memory — `viking_remember`, `viking_recall`, and other memory tools become available to the agent.++## See also++- [Hermes — OpenViking memory provider docs](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — full setup guide and configuration options+- [Deployment Guide](../guides/03-deployment.md) — setting up your OpenViking server+- [Authentication](../guides/04-authentication.md) — API key setup for remote accessdiff --git a/docs/en/agent-integrations/05-other-plugins.md b/docs/en/agent-integrations/05-other-plugins.mddeleted file mode 100644index 049f01e0f..000000000--- a/docs/en/agent-integrations/05-other-plugins.md+++ /dev/null@@ -1,49 +0,0 @@-# Other Plugins--The repo also ships several community/experimental plugins beyond the headline Claude Code, Codex, and OpenClaw integrations. They differ in target runtime, integration depth, and maintenance status — read each one's README before adopting.--## AstrBot plugin--[AstrBot](https://github.com/AstrBotDevs/AstrBot) is a multi-platform IM bot framework supporting QQ (AIOCQHTTP), Telegram, Discord, Lark, and 20+ other platforms.--Source: [astrbot_plugin_openviking_memory](https://github.com/t0saki/astrbot_plugin_openviking_memory)--Provides OpenViking long-term memory for AstrBot: auto-captures group/DM conversations, performs semantic recall before each LLM request, and supports configurable venue memory isolation.--**Installation**: In AstrBot WebUI, search **OpenViking Memory** in the Plugin Marketplace; or install from URL: `https://github.com/t0saki/astrbot_plugin_openviking_memory.git`--**Key features**:--- Hooks-based auto-recall and auto-capture — the model doesn't need to invoke tools explicitly-- Three isolation modes: `venue_user` (per-group/DM), `venue_user_fanout` (cross-venue sharing), `global_user` (single user)-- Four auto-commit triggers: message count, token threshold, idle timeout, and process-exit flush-- Backfills platform message history on first venue encounter--## OpenCode plugins--Two OpenCode plugin variants exist with different design choices. Pick whichever matches your usage — we don't make the decision for you.--### `opencode-memory-plugin` — explicit-tool variant--Source: [examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)--Exposes OpenViking memories as explicit OpenCode tools and syncs the conversation session into OpenViking.--- the agent sees concrete tools and decides when to call them-- OpenViking data is fetched on demand via tool execution, not pre-injected into every prompt-- the plugin keeps an OpenViking session in sync with the OpenCode conversation and triggers background extraction with `memcommit`--### `opencode/plugin` — context-injection variant--Source: [examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)--Injects indexed code repos into OpenCode's context and auto-starts the OpenViking server when needed.--- prompt context is augmented with relevant code from indexed repos-- bundles a small launcher that brings up the OpenViking server on demand--## Generic MCP clients--For Cursor, Trae, Manus, Claude Desktop, ChatGPT/Codex, and any other MCP-compatible runtime, you don't need a dedicated plugin — just point the client at the built-in `/mcp` endpoint.--→ See the [MCP Integration Guide](../guides/06-mcp-integration.md).diff --git a/docs/en/agent-integrations/06-langchain-langgraph.md b/docs/en/agent-integrations/06-langchain-langgraph.mddeleted file mode 100644index 37304a2bc..000000000--- a/docs/en/agent-integrations/06-langchain-langgraph.md+++ /dev/null@@ -1,230 +0,0 @@-# LangChain and LangGraph--OpenViking can be configured as the context backend for LangChain and LangGraph agents through optional Python SDK adapters. The recommended deployment is HTTP mode: the agent app connects to a running OpenViking server, and OpenViking handles storage, indexing, embeddings, VLM parsing, session compression, and memory extraction.--- `with_openviking_context()` wraps LangChain runnables with session assembly, recall, capture, and optional commit policy.-- `OpenVikingContextMiddleware` gives LangGraph agents the same session lifecycle through middleware.-- `OpenVikingChatMessageHistory` stores LangChain history in OpenViking sessions.-- `create_openviking_tools()` exposes common `viking_*` tools for agents.-- `OpenVikingRetriever` returns LangChain `Document` objects from OpenViking `find` or `search`.-- `OpenVikingStore` implements LangGraph's `BaseStore` for durable user or agent state.--Install the optional dependencies:--```bash-pip install "openviking[langgraph]"-```--For retriever-only LangChain usage:--```bash-pip install "openviking[langchain]"-```--## Connection Setup--In production, configure OpenViking once, start `openviking-server`, and connect from the LangChain/LangGraph app:--```python-connection = {- "url": "http://localhost:1933",- "api_key": "...",- "user_id": "user-123",- "agent_id": "support-agent",-}-```--The application still owns its LLM calls. OpenViking owns context storage and processing. Embedding and VLM providers are configured in OpenViking, not in the LangChain or LangGraph app.--If `client`, `url`, and `path` are all omitted, the adapters create `SyncHTTPClient()` and load connection settings from the OpenViking CLI config.--Embedded local clients can be passed explicitly with `client=...` or `path=...` for tests, notebooks, and single-process scripts. The primary examples below use HTTP mode.--## LangChain Retriever--```python-from openviking.integrations.langchain import OpenVikingRetriever--retriever = OpenVikingRetriever(- url="http://localhost:1933",- api_key="...",- target_uri=["viking://user/memories", "viking://resources"],- search_mode="find",- limit=6,-)--docs = retriever.invoke("What did the user decide about deployment color?")-```--Use `search_mode="search"` with `session_id=...` when you want OpenViking's session-aware retrieval. Use `content_mode="read"` to force full L2 reads, or keep the default `auto` mode to read L2 hits and use abstracts/overviews for higher-level hits.--The retriever is a LangChain compatibility surface. For OpenViking-managed context lifecycle, prefer `with_openviking_context()` or `OpenVikingContextMiddleware`.--## LangChain Context Backend--Use `with_openviking_context()` when OpenViking should own the agent context lifecycle, not just retrieval:--```python-from langchain_core.messages import AIMessage, HumanMessage-from langchain_core.runnables import RunnableLambda-from openviking.integrations.langchain import (- OpenVikingCommitPolicy,- with_openviking_context,-)---def answer(messages):- return AIMessage(content="Answer using the injected OpenViking context.")---chain = with_openviking_context(- RunnableLambda(answer),- url="http://localhost:1933",- api_key="...",- target_uri=["viking://user/memories", "viking://resources"],- commit_policy=OpenVikingCommitPolicy(- mode="pending_tokens",- pending_token_threshold=8_000,- ),-)--result = chain.invoke(- [HumanMessage(content="What did we decide about deploys?")],- config={"configurable": {"session_id": "agent-thread-123"}},-)-```--When `session_id` is omitted from `with_openviking_context()`, each invoke must pass the configured session ID. For one-off scripts or single-session apps, pass `session_id="..."` to `with_openviking_context()` and then call `invoke()` without config.--The wrapper calls `get_session_context()`, injects archive/recall context, stores the completed turn through `OpenVikingChatMessageHistory`, and commits when the configured policy is met. Use the same session ID across invocations when the conversation should share OpenViking working memory and archives.--For direct LangChain history usage:--```python-from langchain_core.runnables.history import RunnableWithMessageHistory-from openviking.integrations.langchain import OpenVikingChatMessageHistory--with_history = RunnableWithMessageHistory(- runnable,- lambda session_id: OpenVikingChatMessageHistory(- session_id=session_id,- url="http://localhost:1933",- api_key="...",- ),-)-```--`OpenVikingChatMessageHistory` stores text, tool calls/results, and context references as OpenViking `TextPart`, `ToolPart`, and `ContextPart` payloads where those details are available.--## Agent Tools--```python-from openviking.integrations.langchain import create_openviking_tools--tools = create_openviking_tools(- url="http://localhost:1933",- api_key="...",- profile="agent",-)-```--The default agent profile includes:--- `viking_find`: quick semantic recall without session context.-- `viking_search`: session-aware hierarchical retrieval.-- `viking_browse`: list or glob OpenViking namespaces.-- `viking_read`: read one or more Viking URIs as L0 `abstract`, L1 `overview`, or full L2 `read` content.-- `viking_grep`: grep-style content search.-- `viking_archive_search`: search assembled session/archive context.-- `viking_archive_expand`: expand a specific committed session archive.-- `viking_store`: write conversation turns to an OpenViking session.-- `viking_add_resource`: import files, directories, URLs, or repositories.-- `viking_add_skill`: register reusable skills.-- `viking_health`: check OpenViking status.--The default `agent` profile is intended for trusted, app-controlled agents. Use `profile="retrieval"` or explicit `tool_names=[...]` when a model should only retrieve/read context.--`viking_forget` is intentionally not exposed by the default profile. Use `profile="admin"` or `allow_forget=True` only for trusted agents.--`viking_add_resource` exposes OpenViking resource ingestion to agents. OpenViking parses and indexes documents, repositories, URLs, and supported media according to the server's configured parsers, embedding model, and VLM model. Chat message capture focuses on text, tool, and context parts.--## LangGraph Store--```python-from openviking.integrations.langchain import OpenVikingStore--store = OpenVikingStore(- url="http://localhost:1933",- api_key="...",- root_uri="viking://user/memories/langgraph_store",-)--store.put(("users", "ada"), "preferences", {"color": "azure"})-items = store.search(("users",), query="azure", limit=3)-```--The store writes JSON records under `<root_uri>/data` and a compact markdown index under `<root_uri>/index`. Query-based `search()` uses OpenViking `find()` over that index, then resolves the original JSON values.--Store writes wait for indexing by default so immediate query-based `search()` can see just-written values. Pass `wait=False` when asynchronous indexing is acceptable.--`OpenVikingStore` is for durable LangGraph store data. It is separate from LangGraph checkpointing.--## LangGraph Middleware--```python-from langchain.agents import create_agent-from openviking.integrations.langchain import (- OpenVikingCommitPolicy,- OpenVikingContextMiddleware,-)--middleware = OpenVikingContextMiddleware(- url="http://localhost:1933",- api_key="...",- target_uri=["viking://user/memories", "viking://resources"],- limit=5,- capture_on_after_agent=True,- commit_policy=OpenVikingCommitPolicy(- mode="pending_tokens",- pending_token_threshold=8_000,- ),-)--agent = create_agent(- model="...",- tools=[],- middleware=[middleware],-)-```--The middleware adds a marked OpenViking context block to the model system message. The block includes session archive overview and recall results; the active request messages are left as normal LangGraph messages to avoid duplication. After the agent finishes, the middleware captures new user, assistant, tool, and context parts into the OpenViking session.--If your graph passes only the latest request and relies on OpenViking for the session window, set `include_active_messages=True` on the middleware.--LangGraph `thread_id` is the natural OpenViking `session_id`. Reuse the same ID for both systems when you also configure a LangGraph checkpointer. OpenViking handles semantic context and memory; the checkpointer handles exact graph execution resume. Provide `session_id_resolver` if your graph uses a custom thread/session identifier.--The middleware requires a session identifier. If no `thread_id`, `session_id`, or custom resolver is available, it raises `ValueError` instead of writing to a shared default session.--## Try The Examples--The repository includes small deterministic examples that exercise real LangChain and LangGraph application flows without requiring model credentials or a running OpenViking server. They use an OpenViking-compatible in-memory test client so you can see how the adapters fit into an agent app before connecting to a real backend.--From the repository root:--```bash-uv run --extra langgraph python examples/langchain-langgraph/langchain/rag/quick_app.py-uv run --extra langgraph python examples/langchain-langgraph/langchain/context-backend/quick_app.py-uv run --extra langgraph python examples/langchain-langgraph/langchain/message-history/quick_app.py-uv run --extra langgraph python examples/langchain-langgraph/langgraph/agent/quick_app.py-uv run --extra langgraph python examples/langchain-langgraph/langgraph/middleware/quick_app.py-```--The examples cover:--- [LangChain RAG quick app](../../../examples/langchain-langgraph/langchain/rag/quick_app.py): LangChain RAG with `OpenVikingRetriever`.-- [LangChain context backend quick app](../../../examples/langchain-langgraph/langchain/context-backend/quick_app.py): LangChain session context injection with `with_openviking_context()`.-- [LangChain message history quick app](../../../examples/langchain-langgraph/langchain/message-history/quick_app.py): LangChain chat history backed by `OpenVikingChatMessageHistory`.-- [LangGraph agent quick app](../../../examples/langchain-langgraph/langgraph/agent/quick_app.py): LangGraph workflow using OpenViking tools and `OpenVikingStore`.-- [LangGraph middleware quick app](../../../examples/langchain-langgraph/langgraph/middleware/quick_app.py): LangGraph context injection and capture with `OpenVikingContextMiddleware`.--For a real OpenViking server and OpenAI-compatible model flow, see the [live LangGraph app](../../../examples/langchain-langgraph/langgraph/agent/live_app.py).diff --git a/docs/en/agent-integrations/06-mcp-clients.md b/docs/en/agent-integrations/06-mcp-clients.mdnew file mode 100644index 000000000..7f3fcbdb4--- /dev/null+++ b/docs/en/agent-integrations/06-mcp-clients.md@@ -0,0 +1,86 @@+# MCP Clients++Any [MCP](https://modelcontextprotocol.io/)-compatible client can connect to OpenViking's built-in `/mcp` endpoint — no plugin installation or extra processes needed. This covers Cursor, Trae, Manus, Claude Desktop, ChatGPT, and others.++## Quick setup++Most MCP clients use the standard `mcpServers` format:++```json+{+ "mcpServers": {+ "openviking": {+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }+ }+ }+}+```++No authentication is needed when connecting to a local server without `root_api_key` configured (dev mode).++## Platform-specific notes++### Claude Code++Claude Code requires `"type": "http"`. Add via CLI:++```bash+claude mcp add --transport http openviking \+ https://your-server.com/mcp \+ --header "Authorization: Bearer your-api-key-here"+```++Add `--scope user` to make the config global across all projects.++> For auto-recall and auto-capture without manual tool calls, use the [Claude Code Memory Plugin](./02-claude-code.md) instead.++### Trae / Cursor / ChatGPT / Codex / OpenCode++Standard `mcpServers` config as shown above — all verified with API key auth.++### Claude Desktop / Claude.ai (OAuth)++These clients require OAuth 2.1 — API keys cannot be passed directly. OpenViking ships a native OAuth 2.1 implementation, so no external proxy is needed.++If you already have HTTPS configured for your OpenViking server, just connect to `https://your-server.com/mcp` — the client will walk you through the OAuth authorization flow automatically.++See the [OAuth 2.1 Guide](../guides/11-oauth.md) and [Public Access Guide](../guides/12-public-access.md) for HTTPS setup, deployment templates, and the full authorization flow.++## Available tools++Once connected, OpenViking exposes 14 tools:++| Tool | Description |+|------|-------------|+| `search` | Semantic search across memories, resources, and skills |+| `read` | Read one or more `viking://` URIs |+| `list` | List entries under a `viking://` directory |+| `store` | Store messages into long-term memory |+| `add_resource` | Add a local file or URL as a resource |+| `grep` | Regex content search across `viking://` files |+| `glob` | Find files matching a glob pattern |+| `forget` | Delete a `viking://` URI |+| `code_outline` | Show a file's symbol structure |+| `code_search` | Search symbol names across a directory |+| `code_expand` | Return the full source of a single named symbol |+| `health` | Check OpenViking service health |+| `list_watches` | List auto-refresh subscriptions |+| `cancel_watch` | Cancel a watch task |++For tool parameters, progressive file upload, and advanced configuration, see the [MCP Integration Guide](../guides/06-mcp-integration.md).++## Troubleshooting++| Symptom | Fix |+|---------|-----|+| Connection refused | Verify `openviking-server` is running: `curl http://localhost:1933/health` |+| Authentication errors | Ensure the API key in your client config matches the server. See [Authentication Guide](../guides/04-authentication.md) |++## See also++- [MCP Integration Guide](../guides/06-mcp-integration.md) — tool parameters, progressive upload, `OPENVIKING_PUBLIC_BASE_URL`+- [OAuth 2.1 Guide](../guides/11-oauth.md) — for Claude Desktop, Claude.ai, Cursor+- [MCP Specification](https://modelcontextprotocol.io/)diff --git a/docs/en/agent-integrations/07-langchain-langgraph.md b/docs/en/agent-integrations/07-langchain-langgraph.mdnew file mode 100644index 000000000..88578aa10--- /dev/null+++ b/docs/en/agent-integrations/07-langchain-langgraph.md@@ -0,0 +1,111 @@+# LangChain and LangGraph++Wire OpenViking into your LangChain or LangGraph agent as the context backend. The SDK provides a retriever, chat history, context wrapper, agent tools, LangGraph store, and middleware — all connecting to a running OpenViking server over HTTP.++## Install++```bash+pip install "openviking[langchain]" # retriever + chat history+pip install "openviking[langgraph]" # full LangGraph support (includes langchain)+```++## Connection++```python+from openviking.integrations.langchain import create_openviking_tools++tools = create_openviking_tools(+ url="http://localhost:1933",+ api_key="...",+ profile="agent",+)+```++When `url` is omitted, the adapters load connection settings from the OpenViking CLI config. Embedding and VLM providers are configured in OpenViking, not in your app.++## Which adapter should I use?++| I want to… | Use this |+|------------|----------|+| Retrieve relevant context for RAG | `OpenVikingRetriever` |+| Wrap a runnable with full session lifecycle (recall + capture + commit) | `with_openviking_context()` |+| Give the agent explicit memory tools | `create_openviking_tools()` |+| Store durable cross-thread state | `OpenVikingStore` |+| Inject context into LangGraph as middleware | `OpenVikingContextMiddleware` |+| Back LangChain chat history with OpenViking | `OpenVikingChatMessageHistory` |++## Quick examples++### Retriever++```python+from openviking.integrations.langchain import OpenVikingRetriever++retriever = OpenVikingRetriever(url="http://localhost:1933", api_key="...")+docs = retriever.invoke("What did the user decide about deployment?")+```++### Context backend++```python+from langchain_core.messages import AIMessage+from langchain_core.runnables import RunnableLambda+from openviking.integrations.langchain import with_openviking_context++chain = with_openviking_context(+ RunnableLambda(lambda msgs: AIMessage(content="...")),+ url="http://localhost:1933",+ api_key="...",+)+```++### Agent tools++```python+from openviking.integrations.langchain import create_openviking_tools++tools = create_openviking_tools(url="http://localhost:1933", profile="agent")+# Includes: viking_find, viking_search, viking_browse, viking_read,+# viking_grep, viking_store, viking_add_resource, and more+```++### LangGraph store++```python+from openviking.integrations.langchain import OpenVikingStore++store = OpenVikingStore(url="http://localhost:1933", api_key="...")+store.put(("users", "ada"), "preferences", {"color": "azure"})+items = store.search(("users",), query="azure", limit=3)+```++### LangGraph middleware++```python+from openviking.integrations.langchain import OpenVikingContextMiddleware++middleware = OpenVikingContextMiddleware(+ url="http://localhost:1933",+ api_key="...",+ capture_on_after_agent=True,+)+```++## Try the examples++The repository includes runnable examples that work without model credentials using an in-memory test client:++```bash+uv run --extra langgraph python examples/langchain-langgraph/langchain/rag/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langchain/context-backend/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langchain/message-history/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langgraph/agent/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langgraph/middleware/quick_app.py+```++For a real OpenViking server and OpenAI-compatible model flow, see the [live LangGraph app](https://github.com/volcengine/OpenViking/blob/main/examples/langchain-langgraph/langgraph/agent/live_app.py).++## See also++- [examples/langchain-langgraph/](https://github.com/volcengine/OpenViking/tree/main/examples/langchain-langgraph) — full source for all examples above+- [MCP Clients](./06-mcp-clients.md) — for non-SDK MCP integrationdiff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.mdnew file mode 100644index 000000000..89ae6f8ad--- /dev/null+++ b/docs/en/agent-integrations/08-community-plugins.md@@ -0,0 +1,36 @@+# Community Plugins++Community-maintained integrations for various agent runtimes. Each differs in target platform, integration depth, and maintenance status — check the linked README before adopting.++## AstrBot plugin++[AstrBot](https://github.com/AstrBotDevs/AstrBot) is a multi-platform IM bot framework supporting QQ, Telegram, Discord, Lark, and 20+ other platforms.++Source: [astrbot_plugin_openviking_memory](https://github.com/t0saki/astrbot_plugin_openviking_memory)++Provides auto-capture of group/DM conversations, semantic recall before each LLM request, and configurable venue memory isolation.++**Install**: In AstrBot WebUI, search **OpenViking Memory** in the Plugin Marketplace; or install from URL: `https://github.com/t0saki/astrbot_plugin_openviking_memory.git`++**Key features**:++- Auto-recall and auto-capture via hooks — the model doesn't need to invoke tools+- Three isolation modes: `venue_user` (per-group/DM), `venue_user_fanout` (cross-venue sharing), `global_user` (single user)+- Four auto-commit triggers: message count, token threshold, idle timeout, and process-exit flush+- Backfills platform message history on first venue encounter++## OpenCode plugins++Two OpenCode plugin variants exist with different design choices. Pick whichever matches your usage.++### `opencode-memory-plugin` — explicit-tool variant++Source: [examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)++Exposes OpenViking memories as explicit OpenCode tools. The agent decides when to call them, and data is fetched on demand rather than pre-injected.++### `opencode/plugin` — context-injection variant++Source: [examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)++Injects indexed code repos into OpenCode's context and auto-starts the OpenViking server when needed.\ No newline at end of filediff --git a/docs/en/guides/06-mcp-integration.md b/docs/en/guides/06-mcp-integration.mdindex 34368bfce..3e7a06d92 100644--- a/docs/en/guides/06-mcp-integration.md+++ b/docs/en/guides/06-mcp-integration.md@@ -2,6 +2,8 @@OpenViking server has a built-in [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) endpoint, allowing any MCP-compatible client to access its memory and resource capabilities over HTTP — no additional processes needed.+> **Quick setup?** See [MCP Clients](../agent-integrations/06-mcp-clients.md) for client configuration snippets and platform-specific notes. This page covers the full tool reference and advanced configuration.+## Prerequisites1. OpenViking installed (`pip install openviking` or from source)@@ -17,10 +19,12 @@ The following platforms have been successfully integrated with OpenViking MCP:| Platform | Integration Method ||----------|-------------------|| **Claude Code** | `type: http` |+| **Trae** | Standard MCP config |+| **Cursor** | Standard MCP config || **ChatGPT & Codex** | Standard MCP config |-| **Claude.ai / Claude Desktop** | Native OAuth 2.1 (see [11-oauth](11-oauth.md)) |+| **OpenCode** | Standard MCP config || **Manus** | Standard MCP config |-| **Trae** | Standard MCP config |+| **Claude.ai / Claude Desktop** | Native OAuth 2.1 (see [11-oauth](11-oauth.md)) |## Authentication@@ -78,20 +82,22 @@ Or in `.mcp.json`:Add `--scope user` to make the config global (shared across all projects).-### Claude.ai / Claude Desktop / ChatGPT / Cursor (OAuth)+### Claude.ai / Claude Desktop (OAuth)These clients only accept OAuth 2.1 — API Keys cannot be passed directly.OpenViking ships a native OAuth 2.1 implementation (DCR + PKCE + opaquetokens, backed by SQLite, with a console-driven OTP authorization page) sono external proxy is needed.-**See the [OAuth 2.1 Guide](11-oauth.md)** for:+If you already have HTTPS configured, just connect to `https://your-server.com/mcp` — the client will walk you through the authorization flow automatically.++**See the [OAuth 2.1 Guide](11-oauth.md)** and **[Public Access Guide](12-public-access.md)** for:- End-to-end flow (device-flow style: page displays a 6-character code,user confirms in the OpenViking console)- HTTP (local) and HTTPS (production) deployment, including Caddy and nginxreverse-proxy templates plus a docker-compose example-- Connecting Claude.ai / Claude Desktop / Cursor / ChatGPT step by step+- Connecting Claude.ai / Claude Desktop step by step- `OPENVIKING_PUBLIC_BASE_URL` and the `oauth` config block- Token model (`ovat_` / `ovrt_` / `ovac_` prefixes) and revocationdiff --git a/docs/zh/agent-integrations/01-overview.md b/docs/zh/agent-integrations/01-overview.mdindex 360e88e28..db4613bc0 100644--- a/docs/zh/agent-integrations/01-overview.md+++ b/docs/zh/agent-integrations/01-overview.md@@ -1,29 +1,28 @@# Agent 集成概览-OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端。本节汇总了已支持的接入方式,按运行时挑选适合的方式即可。+OpenViking 可以作为多种 Agent 运行时的长期记忆与上下文后端。按你的运行时挑选合适的接入方式即可。## 该用哪个集成?| 你在用… | 选这个 ||---------|---------|-| **Claude Code** | [Claude Code 记忆插件](./02-claude-code.md) — 通过 hooks 实现自动召回与自动捕获,模型侧无需主动调用 MCP 工具 |-| **OpenClaw** | [OpenClaw 插件](./03-openclaw.md) — context-engine + hooks + tools + 运行时管理一体化集成,覆盖完整生命周期 |-| **Codex** | [Codex 记忆插件](./04-codex.md) — 生命周期 hooks 自动召回、增量捕获、compaction 前 commit |-| **LangChain / LangGraph** | [LangChain 和 LangGraph](./06-langchain-langgraph.md) — session context backend、chat history、retriever、`viking_*` tools、LangGraph store 和 workflow middleware |-| **AstrBot**(QQ / Telegram / Discord 等 IM) | [其他社区插件](./05-other-plugins.md#astrbot-插件) — 自动捕获群聊对话、语义召回、可配置的 venue 记忆隔离 |-| **OpenCode** | [其他社区插件](./05-other-plugins.md) — 显式工具版本与上下文注入版本 |-| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP 集成指南](../guides/06-mcp-integration.md) — 任何兼容 MCP 的客户端都可直接对接内置 `/mcp` 端点 |-| **Hermes Agent (Nous Research)** | [Hermes — OpenViking 记忆提供方](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 一等公民支持,无需额外安装插件 |+| **Claude Code** | [Claude Code 记忆插件](./02-claude-code.md) — 通过 hooks 实现自动召回与自动捕获 |+| **OpenClaw** | [OpenClaw 插件](./03-openclaw.md) — 全生命周期一体化集成 |+| **Codex** | [Codex 记忆插件](./04-codex.md) — 生命周期 hooks 自动召回与增量捕获 |+| **Hermes Agent** | [Hermes Agent](./05-hermes.md) — 内置 OpenViking 记忆提供方,无需安装插件 |+| **LangChain / LangGraph** | [LangChain 和 LangGraph](./07-langchain-langgraph.md) — retriever、tools、context backend、store 和 middleware |+| **Cursor / Trae / Manus / Claude Desktop / ChatGPT / …** | [MCP 客户端](./06-mcp-clients.md) — 任何兼容 MCP 的客户端直接对接内置 `/mcp` 端点 |+| **AstrBot / OpenCode / …** | [社区插件](./08-community-plugins.md) — 社区维护的各运行时集成 |## 集成深度部分集成能力超过通用 MCP 客户端:- **通用 MCP 客户端**:模型主动调用工具时按需访问 OpenViking。配置只需一份连接片段。-- **基于 hooks 的插件**(Claude Code、Codex、OpenClaw、AstrBot):在运行时生命周期事件(每次 prompt、每轮结束、session 起止、compact、subagent 派生等)中驱动召回与捕获。模型不需要"记得调用"。+- **基于 hooks / 原生插件**(Claude Code、Codex、OpenClaw、Hermes Agent、AstrBot):在运行时生命周期事件(每次 prompt、每轮结束、session 起止、compact、subagent 派生等)中驱动召回与捕获。模型不需要"记得调用"。- **SDK 集成**(LangChain/LangGraph):把 OpenViking 接入框架原生抽象,例如 retriever、tools、chat history、store 和 middleware。-如果你的 Agent runtime 暴露 hooks、middleware 或 context-engine 槽位,原生集成通常是更好的默认选择。+如果你的 Agent 运行时暴露 hooks、middleware 或 context-engine 槽位,原生集成通常是更好的默认选择。## 所有集成的共同前置diff --git a/docs/zh/agent-integrations/02-claude-code.md b/docs/zh/agent-integrations/02-claude-code.mdindex aa0009dec..ee1ea6cf1 100644--- a/docs/zh/agent-integrations/02-claude-code.md+++ b/docs/zh/agent-integrations/02-claude-code.md@@ -1,199 +1,98 @@# Claude Code 记忆插件-为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 提供长期语义记忆。每次用户输入前自动召回相关记忆,每轮对话结束后自动捕获上下文——模型不需要主动调用任何 MCP 工具。+为 [Claude Code](https://docs.claude.com/zh-CN/docs/claude-code/overview) 提供跨项目、跨 session 的长期记忆,越用越聪明。安装一次,每次对话自动召回和捕获,模型不需要主动调用任何工具。-源码:[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin)+源码:[examples/claude-code-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/claude-code-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)-## 快速开始--### 一行安装(推荐)+## 安装```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/claude-code-memory-plugin/setup-helper/install.sh)```-脚本支持 macOS 和 Linux。它会检查依赖、询问你接入**自托管**服务器还是**火山引擎 OpenViking Cloud**(`https://api.vikingdb.cn-beijing.volces.com/openviking`)、按需配置 `~/.openviking/ovcli.conf`(已存在则复用)、把 OpenViking 仓库 clone 到 `~/.openviking/openviking-repo`、把 `claude` function 包装写入 shell rc,然后通过 `claude plugin install` 安装插件。每一步都是幂等的——重复执行安全。+脚本会检查依赖、配置 OpenViking 连接并安装插件。每一步都是幂等的——重复执行安全。-如果你更喜欢手动操作,按下面三步走。+安装完成后启动 Claude Code,问它上次 session 聊过什么——它记得。-### 手动安装+<details>+<summary><b>手动安装</b></summary>-#### 1. 用 shell function 在调用 `claude` 时注入 env+如果你更喜欢手动操作:-这是推荐路径。插件的 hooks **和**自带的 MCP 服务器都读 env vars,所以我们把它们设一次——但**只在调用 `claude` 时注入**,不全局 export。在 `~/.zshrc` 或 `~/.bashrc` 末尾追加:+1. **Shell 函数包装** — 在 `~/.zshrc` 或 `~/.bashrc` 末尾追加一个 `claude()` 函数,每次调用时从 `~/.openviking/ovcli.conf` 注入 `OPENVIKING_URL` 和 `OPENVIKING_API_KEY`。这样 API Key 只在 `claude` 进程树内有效。完整函数和安全说明见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#1-wrap-claude-to-inject-env-from-ovcliconf)。-```bash-claude() {- if [ -f ~/.openviking/ovcli.conf ]; then- OPENVIKING_URL=$(jq -r '.url' ~/.openviking/ovcli.conf) \- OPENVIKING_API_KEY=$(jq -r '.api_key' ~/.openviking/ovcli.conf) \- command claude "$@"- else- command claude "$@"- fi-}-```+2. **安装插件**,在 OpenViking 仓库根目录:-重新 source 后验证(用 bash 的话改成 `~/.bashrc`):+ ```bash+ claude plugin marketplace add "$(pwd)/examples"+ claude plugin install claude-code-memory-plugin@openviking-plugins-local+ ```-```bash-source ~/.zshrc # 或:source ~/.bashrc-type claude # 期望输出:claude is a shell function-```+3. **启动 Claude Code**,执行 `/mcp` 确认 OpenViking 这一项显示的是你的服务器 URL。-下一次启动 `claude` 后,进入 `/mcp` 应该能看到 OpenViking 这一项的 URL 是远程地址,认证也有效。--> **还没有 `ovcli.conf`?** 先按 [部署指南 → CLI 章节](../guides/03-deployment.md#cli) 创建一份。+> 还没有 `ovcli.conf`?先按 [部署指南 → CLI](../guides/03-deployment.md#cli) 创建。>-> **纯本地模式**(`http://127.0.0.1:1933`,无鉴权)?这一步可以跳过——插件会静默使用本地默认值。+> 纯本地模式(`http://127.0.0.1:1933`,无鉴权)?跳过第 1 步——插件会静默使用本地默认值。>-> **为什么用 function 而不是 `export`?** 全局 export 的 env vars 会被该 shell 派生的所有子进程继承——npm 脚本、构建工具、崩溃 dump、`/proc/<pid>/environ` 都会带上。函数包装把秘钥限定在 `claude` 进程树内。+> Claude Code < 2.0?见 [插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)。-#### 2. 安装插件+</details>-在 OpenViking 仓库根目录执行:+## 验证```bash-claude plugin marketplace add "$(pwd)/examples"-claude plugin install claude-code-memory-plugin@openviking-plugins-local-```--> 默认装在 user scope —— 任何目录下都生效。这里**不显式传 `--scope`**,因为老的 Claude Code 2.0.x(比如 2.0.76)不识别这个 flag 会直接报错。->-> marketplace 条目让 Claude Code 直接引用源码目录,对 `scripts/`、`hooks/`、配置文件的修改下次 hook 触发即生效,无需重装。但移动 / 重命名 / 删除源码目录,或 `git checkout` 到不含这些文件的分支,会让插件失效。->-> **Claude Code < 2.0?** `claude plugin` 是 2.0(2025-10)才引入的。更老的版本仍然有 `claude mcp add` 和 hooks 系统,可以走[插件 README 的兼容模式章节](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README_CN.md#兼容模式claude-code--20)手动接同样的功能。一键安装脚本会自动检测版本并询问你是否走这条路径。--#### 3. 启动 Claude Code--```bash-claude-```--进入后执行 `/mcp`,确认 OpenViking 这一项的 URL 是你的远程地址。如果插件似乎没在工作,开 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。--## 为什么用 function 包装?--插件的 hook 会自动读 `ovcli.conf`,但**自带的 `.mcp.json` 条目读不到**。Claude Code 自己解析 `.mcp.json` 且只支持 `${VAR}` 替换,所以插件无法把配置文件里的值透明地注入 MCP URL 和认证头。--在 `claude` 调用时注入 env vars 是同时覆盖 hooks 和 MCP 的唯一路径。用 shell function 包装(而不是全局 `export`)能把 API Key 限定在 `claude` 一个进程树内,不会泄漏到其他子进程——见 [手动安装的步骤 1](#1-用-shell-function-在调用-claude-时注入-env) 的安全说明。--**配错的症状**:hook(auto-recall、auto-capture)正常工作,因为它们直接通过 Node 读配置文件;但按需 MCP 工具(`search`、`read`、`store`…)会静默连到 `http://127.0.0.1:1933`、认证头为空,且 `/mcp` 显示错误的 URL。--## 配置--### 解析优先级--每个插件字段按从高到低:--1. **环境变量**(`OPENVIKING_*`)-2. **`ovcli.conf`** — 只承载连接字段(`url`、`api_key`、`account`、`user`、`agent_id`)-3. **`ov.conf`** — 服务端配置;插件读取 `server.url`、`server.root_api_key`,以及(旧版兼容)`claude_code` 区块(如有)-4. **内置默认值**(`http://127.0.0.1:1933`,无鉴权)--> ⚠️ **仅适用于 hooks。** 这条优先级链由 `scripts/config.mjs` 实现,hook 脚本消费。它**不**适用于 MCP 服务器注册——见 [为什么用 function 包装?](#为什么用-function-包装) 一节。--### 主要环境变量--| 环境变量 | 默认值 | 说明 |-|--------------------------------------------------|---------------|------------------------------------------------------------------------|-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API Key;通过 `Authorization: Bearer <key>` 发送 |-| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前是否自动召回 |-| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮最多注入的记忆条数 |-| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联内容的 token 预算;超出预算的条目降级为 URI 提示 |-| `OPENVIKING_AUTO_CAPTURE` | `true` | 是否自动捕获;同时控制写入类 hooks |-| `OPENVIKING_BYPASS_SESSION` | `false` | 一次性开关:`1`/`true` 让当前进程跳过所有 hook |-| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV 形式的 glob,匹配 `session_id` 或 `cwd` |-| `OPENVIKING_MEMORY_ENABLED` | (auto) | `0`/`false`=强制关闭;`1`/`true`=强制开启 |-| `OPENVIKING_DEBUG` | `false` | 把 hook 日志写到 `~/.openviking/logs/cc-hooks.log` |--多租户场景下,`OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、`OPENVIKING_AGENT_ID` 用于设置对应的 `X-OpenViking-*` 请求头。完整环境变量列表(召回/捕获微调、生命周期、调试)见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。--### 临时跳过当前 session--在 `/tmp` 下用 Claude Code 做 PoC,不污染长期记忆:--```bash-# 持久化:任何 session_id 或 cwd 命中模式的 session 都跳过-export OPENVIKING_BYPASS_SESSION_PATTERNS='/tmp/**,**/scratch/**,/Users/me/Dev/throwaway/*'--# 或一次性:-OPENVIKING_BYPASS_SESSION=1 claude-```--bypass 启用时,所有 hook 立即返回 approve,不与 OpenViking 通信。--## Statusline 状态行--插件会在 Claude Code 输入框下方渲染一行 OpenViking 状态。安装脚本把它注册到 `~/.claude/settings.json`(CC 插件 manifest 不支持 `statusLine`,必须走用户 settings)。--```text-OV ✓ │ ↩ 6 mem (0.92) · 50ms 本轮注入 6 条记忆,最高分 0.92-OV ⚠ slow 探针超过 1s 预算(服务器可能在抽风)-OV ✗ offline 服务器不可达-OV ⚡ bypass 命中 OPENVIKING_BYPASS_SESSION*-OV ✓ │ ✎ 573/20k · 2 arch 待提交进度 + 本 session 已归档 2 次-OV ✓ │ 🔗 resumed │ +3 today session 已恢复上下文;今日累计归档 3 次+type claude # 期望输出:claude is a shell function```-hook 脚本把每轮的小快照写到 `~/.openviking/state/`;statusline 脚本读快照,再加 5 秒共享缓存的 `GET /health`。探针 1s 硬超时,多 session 共享缓存避免风暴。--`OPENVIKING_STATUSLINE=off` 可静默不删;`jq 'del(.statusLine)' ~/.claude/settings.json` 彻底移除。已有自定义 statusline 时安装会询问替换 / 跳过 / 手动 compose。--完整的段位说明(每个 segment 何时出现、为什么有时不显示)以及个性化 recipe(隐藏段位、改色、与已有 statusline 组合、自定义段位),参见 [`examples/claude-code-memory-plugin/STATUSLINE.md`](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。最方便的方式是打开 Claude Code 把链接喂给它,让它读完文档既能解释你看到的内容,又能按你的偏好调整。+进入 Claude Code 后:-## 与 Claude Code 内置 `MEMORY.md` 的对比+- `/plugins` → 在 Installed 中找到 **openviking-memory**(下属 **openviking** MCP 应显示已连接)+- `/mcp` → OpenViking 这一项应显示你的服务器 URL 和有效认证+- `/openviking-memory:ov` → 展示服务器状态、身份、召回/注入统计和开关状态-本插件**补充**Claude Code 原生记忆系统,不替代:+如果插件似乎没在工作,设 `OPENVIKING_DEBUG=1` 看 `~/.openviking/logs/cc-hooks.log`。-| 维度 | 内置 `MEMORY.md` | OpenViking 插件 |-|---------------|-----------------------------------|----------------------------------------------------|-| 存储 | 平铺 markdown | 向量库 + 结构化抽取 |-| 检索 | 整体加载到上下文 | 语义相似度 + 排序 + token 预算 |-| 范围 | 单项目 | 跨项目、跨 session、跨 agent |-| 容量 | ~200 行(受上下文限制) | 无限(服务端存储) |-| 抽取 | 手写规则 | LLM 驱动的实体 / 偏好 / 事件抽取 |-| Subagents | 与父 agent 共享 | 隔离 session + agent 命名空间分类 |+## 工作原理-## Hook 行为+插件挂载到 Claude Code 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆,每轮回复后捕获新的对话内容,session 启动时注入用户画像和记忆索引,compact 前和 session 结束时提交待处理的消息,并为每个 subagent 分配隔离的记忆 session。所有写入操作异步执行,不会让你等待。-| Hook | 触发时机 | 行为 |-|-----------------------|-----------------------------------------|---------------------------------------------------------------------------------------------------|-| `UserPromptSubmit` | 每次用户输入 | 搜索 OV → 排序 → 在 token 预算内注入 `<openviking-context>` 块 |-| `Stop` | Claude 完成一次回复 | 解析 transcript → 把新的用户轮推入 OV session → pending tokens 超阈值时 commit |-| `SessionStart` | 新建 / 恢复 / compact 后的 session | 每次启动(startup/clear/resume/compact):注入用户 `profile.md` 及 `preferences/` + `entities/` 的带描述目录清单,受 `OPENVIKING_PROFILE_TOKEN_BUDGET` 限制(默认 `10000` tokens,CJK-aware;设 `OPENVIKING_NO_AUTO_INJECT=1` 可跳过)。`resume`/`compact` 场景额外拉取持久化 session 的最新归档摘要 + pre-archive abstracts。两部分合成单一 `<openviking-context>` 信封。 |-| `PreCompact` | Claude Code 重写 transcript 之前 | 在 CC 改写前,把待写入消息 commit 成归档 |-| `SessionEnd` | Claude Code session 关闭 | 最终 commit,让最后一个窗口归档 |-| `SubagentStart` | 父 agent 通过 Task 工具派生 subagent | 为 subagent 派生隔离的 OV session ID,持久化启动状态 |-| `SubagentStop` | Subagent 完成 | 读取 subagent transcript → 推入隔离 session(带 subagent 类型的 agent 头)→ commit |+<details>+<summary><b>配置</b></summary>-`Stop`、`SessionEnd`、`SubagentStop` 用 detached-worker 模式,用户感知不到 OV 的 RTT。需要确定性顺序时设置 `OPENVIKING_WRITE_PATH_ASYNC=false`。+配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。-`auto-capture` 在推送到 OV 前会剥离 `<openviking-context>`、`<system-reminder>`、`<relevant-memories>`、`[Subagent Context]` 等区块——否则插件本轮注入的召回上下文会作为下一轮"用户消息"被回灌进去,形成自污染。+| 环境变量 | 默认值 | 说明 |+|---------|--------|------|+| `OPENVIKING_AUTO_RECALL` | `true` | 每次用户输入前自动召回 |+| `OPENVIKING_RECALL_LIMIT` | `6` | 单轮最多注入的记忆条数 |+| `OPENVIKING_RECALL_TOKEN_BUDGET` | `2000` | 内联内容的 token 预算 |+| `OPENVIKING_AUTO_CAPTURE` | `true` | 每轮结束后自动捕获 |+| `OPENVIKING_BYPASS_SESSION` | `false` | 跳过当前 session 的所有 hook |+| `OPENVIKING_BYPASS_SESSION_PATTERNS` | `""` | CSV glob 模式自动跳过 |+| `OPENVIKING_MEMORY_ENABLED` | (auto) | 强制开启/关闭 |+| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/cc-hooks.log` |-### OV session id 派生+多租户场景设置 `OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、`OPENVIKING_AGENT_ID`。完整环境变量列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md#configuration)。-OV 端的 session id 直接包含 CC 的 `session_id`,方便肉眼对账:+</details>-- 主 session:`cc-<ccSessionId>`,例如 `cc-7d978bb3-cd9c-4ac6-828d-20965d66b783`-- subagent:`cc-<ccSessionId>__agent-<agentId>`,例如 `cc-7d978bb3-cd9c-4ac6-828d-20965d66b783__agent-abc123`+## 状态行-可在 `~/.openviking/state/last-capture.json` 看到当前 session 的 `cc_session_id` 和 `ov_session_id` 对应关系;CC 这边的 session id 也是 `~/.claude/projects/<encoded-cwd>/<session_id>.jsonl` 的文件名。+插件在 Claude Code 输入框下方渲染 OpenViking 状态:连接健康度、召回数量、捕获进度和 session 状态一目了然。完整段位说明和个性化 recipe 见 [STATUSLINE.md](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/STATUSLINE.md)。## 故障排查-| 现象 | 原因 | 修复 |-|----------------------------------------------|--------------------------------------------------------------|----------------------------------------------------------------------------------------------|-| 插件未激活 | 找不到 `ov.conf` / `ovcli.conf` | 跑 [一行安装脚本](#一行安装推荐),或者设 `OPENVIKING_MEMORY_ENABLED=1` + URL/API_KEY env vars |-| Hook 触发但召回为空 | OpenViking 服务器没起来,或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |-| MCP 工具连到 `127.0.0.1` 而不是远程 | `.mcp.json` 只支持 `${VAR}` 替换,读不到 `ovcli.conf` | 见 [为什么用 function 包装?](#为什么用-function-包装) |-| 远程认证 401 / 403 | API Key 错误,或多租户头缺失 | 检查 `OPENVIKING_API_KEY`;多租户场景还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |-| `Stop` hook 超时 | 服务器慢 + 同步写路径 | 保持 `OPENVIKING_WRITE_PATH_ASYNC=true`(默认),或在 `hooks/hooks.json` 提高 `Stop` 超时 |+| 现象 | 原因 | 修复 |+|------|------|------|+| 插件未激活 | 找不到 `ov.conf` / `ovcli.conf` | 跑 [安装脚本](#安装),或设 `OPENVIKING_MEMORY_ENABLED=1` + URL/API_KEY |+| Hook 触发但召回为空 | 服务器没起来或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |+| MCP 工具连到 `127.0.0.1` 而不是远程 | 缺少函数包装 | 确认 `type claude` 返回 "shell function";见 [手动安装](#安装) |+| 远程认证 401 / 403 | API Key 错误或缺少租户头 | 检查 `OPENVIKING_API_KEY`;多租户还要核对 `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` |## 参见-- [完整插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 完整环境变量表、hook 超时、调试日志、架构图+- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/README.md) — 完整环境变量表、hook 细节、架构图- [迁移说明](https://github.com/volcengine/OpenViking/blob/main/examples/claude-code-memory-plugin/MIGRATION.md) — 从旧版插件升级-- [MCP 集成指南](../guides/06-mcp-integration.md) — MCP 工具参数与其他客户端+- [MCP 客户端](./06-mcp-clients.md) — MCP 工具参数与其他客户端- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置diff --git a/docs/zh/agent-integrations/03-openclaw.md b/docs/zh/agent-integrations/03-openclaw.mdindex 32899d86f..cea71a5a0 100644--- a/docs/zh/agent-integrations/03-openclaw.md+++ b/docs/zh/agent-integrations/03-openclaw.md@@ -1,8 +1,6 @@# OpenClaw 插件-通过 OpenViking 为 [OpenClaw](https://github.com/openclaw/openclaw) 提供长效记忆能力。安装完成后,OpenClaw 会自动记住对话中的重要信息,并在回复前回忆相关内容。--插件以 `openviking` context engine 的形式注册——负责长期记忆检索、会话归档、归档摘要与记忆抽取,覆盖 OpenClaw 全生命周期。+为 [OpenClaw](https://github.com/openclaw/openclaw) 添加长效记忆。安装完成后,OpenClaw 会自动记住对话中的重要信息,并在每次回复前召回相关上下文。源码:[examples/openclaw-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/openclaw-plugin)@@ -13,19 +11,19 @@| Node.js | >= 22 || OpenClaw | >= 2026.4.8 |-插件以远程模式连接到已有的 OpenViking 服务,安装前请确保有可访问的 HTTP 服务——参见 [部署指南](../guides/03-deployment.md)。快速检查:+插件需要连接到一个正在运行的 OpenViking 服务——参见 [部署指南](../guides/03-deployment.md)。++<details>+<summary><b>从旧版 <code>memory-openviking</code> 升级?</b></summary>++旧插件不兼容,请先清理:```bash-node -v-openclaw --version+curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh+bash cleanup-memory-openviking.sh```-> **从旧版 `memory-openviking` 升级?** 与新插件不兼容,请先清理:->-> ```bash-> curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/openclaw-plugin/upgrade_scripts/cleanup-memory-openviking.sh -o cleanup-memory-openviking.sh-> bash cleanup-memory-openviking.sh-> ```+</details>## 安装@@ -33,128 +31,79 @@ openclaw --versionopenclaw plugins install clawhub:@openviking/openclaw-pluginopenclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --jsonopenclaw gateway restart-openclaw openviking status --json```-`setup` 向导会将配置写入 `$OPENCLAW_STATE_DIR/openclaw.json`(默认:`~/.openclaw/openclaw.json`)并激活 context-engine slot。+`setup` 向导写入配置并激活插件。安装完成后开始对话——OpenClaw 会自动记忆和召回。<details><summary><b>备用方案:通过 <code>ov-install</code> 安装</b></summary>-当 ClawHub 不可用(被限流、离线或认证问题)时,可使用 `ov-install` 备用路径:+当 ClawHub 不可用时:```bashnpm install -g openclaw-openviking-setup-helper-ov-install+ov-install --base-url http://your-server:1933```-常用变体:+常用参数:-```bash-# 指定 OpenClaw 数据目录-ov-install --workdir ~/.openclaw-second--# 锁定到某个发布版本-ov-install --base-url http://your-server:1933 --plugin-version=0.2.9-```--之后升级:--```bash-npm install -g openclaw-openviking-setup-helper@latest && ov-install --base-url http://your-server:1933-```+| 参数 | 含义 |+| --- | --- |+| `--workdir PATH` | OpenClaw 数据目录(默认 `~/.openclaw`) |+| `--plugin-version=VER` | 插件版本:npm 版本、dist-tag 或 Git ref |+| `--base-url URL` | OpenViking 服务地址 |+| `--api-key KEY` | OpenViking API Key |+| `--uninstall` | 卸载插件 |-### `ov-install` 参数--| 参数 | 含义 |-| ----------------------------- | --------------------------------------------------------------- |-| `--workdir PATH` | OpenClaw 数据目录(默认 `~/.openclaw`) |-| `--plugin-version=VER` | 插件版本:npm 版本(如 `2026.5.8`)、npm dist-tag(如 `dev`)或 Git ref(如 `v0.3.16`、`main`)。默认:npm `latest` |-| `--plugin-source=npm\|github` | 插件下载来源(默认 `npm`) |-| `--plugin-package=NAME` | npm 插件包名(默认 `@openviking/openclaw-plugin`) |-| `--github-repo owner/repo` | 指定插件来源仓库(默认 `volcengine/OpenViking`) |-| `--current-version` | 查看当前已安装的插件版本并退出 |-| `--update` | 仅升级插件到指定的 `--plugin-version` |-| `--rollback` | 回滚上次插件升级 |-| `--uninstall` | 卸载插件 |-| `--base-url URL` | OpenViking 服务地址 |-| `--api-key KEY` | OpenViking API Key |-| `--agent-prefix PREFIX` | Agent 前缀,用于记忆命名空间隔离 |-| `--account-id ID` | 多租户 Account ID(仅 root-key 部署需要) |-| `--user-id ID` | 多租户 User ID(仅 root-key 部署需要) |-| `--force-slot` | 强制替换 contextEngine slot(当其他插件占用时) |-| `--allow-offline` | 服务不可达时仍保存配置 |+完整参数列表见 [安装指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md)。</details>-## 插件配置--插件配置位于 `plugins.entries.openviking.config`。通常 setup 已经写好,仅在更换服务器等场景需要手动调整。--```bash-openclaw config get plugins.entries.openviking.config-```--| 参数 | 默认值 | 含义 |-| -------------- | ----------------------- | ----------------------------------------------------- |-| `baseUrl` | `http://127.0.0.1:1933` | 远程 OpenViking HTTP 端点 |-| `apiKey` | empty | 可选的 OpenViking API Key |-| `agent_prefix` | `default` | 本 OpenClaw 实例在远程使用的 agent 前缀 |--常见设置:--```bash-openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933-openclaw config set plugins.entries.openviking.config.apiKey your-api-key-openclaw config set plugins.entries.openviking.config.agent_prefix your-prefix-```-## 验证-要一键检查插件注册、服务端连通性和版本兼容性,运行:-```bashopenclaw openviking status```-自动化场景下,可为 `openclaw openviking status` 追加 `--json` 获取机器可读结果。`openclaw openviking setup` 也支持 `--json`,但自动化使用时需同时提供 `--base-url`。+一键检查插件注册、服务端连通性和版本兼容性。追加 `--json` 获取机器可读结果。-或手动核对各个信号。确认插件占用了 `contextEngine` 槽位:+<details>+<summary><b>手动验证</b></summary>++确认插件占用了 `contextEngine` 槽位:```bashopenclaw config get plugins.slots.contextEngine+# 期望输出:openviking```-输出 `openviking` 即说明插件已生效。--跟随 OpenClaw 日志查看注册信息:+全链路健康检查:```bash-openclaw logs --follow-# 期望出现:openviking: registered context-engine+python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py```-OpenViking 服务端日志(默认路径):+详见 [HEALTHCHECK.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md)。-```bash-cat ~/.openviking/data/log/openviking.log-```--当前插件版本:+</details>-```bash-ov-install --current-version-```+<details>+<summary><b>配置</b></summary>-### 全链路健康检查(可选)+插件配置位于 `plugins.entries.openviking.config`,通常 setup 已经写好。-如要进一步验证 Gateway → OpenViking 全链路,运行:+| 参数 | 默认值 | 含义 |+| --- | --- | --- |+| `baseUrl` | `http://127.0.0.1:1933` | OpenViking 服务端点 |+| `apiKey` | 空 | OpenViking API Key |+| `agent_prefix` | `default` | Agent 前缀,用于记忆命名空间隔离 |```bash-python examples/openclaw-plugin/health_check_tools/ov-healthcheck.py+openclaw config set plugins.entries.openviking.config.baseUrl http://your-server:1933+openclaw config set plugins.entries.openviking.config.apiKey your-api-key```-脚本会通过 Gateway 注入一段真实对话,从 OpenViking 侧验证 session 已捕获、commit、归档并完成记忆抽取。详见 [HEALTHCHECK.md](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/health_check_tools/HEALTHCHECK.md)。+</details>## 卸载@@ -163,10 +112,8 @@ curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examplesbash uninstall-openviking.sh```-非默认 OpenClaw 状态目录请追加 `--workdir ~/.openclaw-second`。-## 参见-- [完整安装指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md) — 所有安装路径、参数与验证步骤+- [完整安装指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL.md) — 所有安装路径与参数- [插件设计说明](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/README.md) — 架构、身份与路由、hook 生命周期-- [Agent 操作指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md) — 给代用户执行安装的 agent 看\ No newline at end of file+- [Agent 操作指南](https://github.com/volcengine/OpenViking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md) — 给代用户执行安装的 agent 看diff --git a/docs/zh/agent-integrations/04-codex.md b/docs/zh/agent-integrations/04-codex.mdindex 9b5e2658b..4916a9cd9 100644--- a/docs/zh/agent-integrations/04-codex.md+++ b/docs/zh/agent-integrations/04-codex.md@@ -1,176 +1,82 @@# Codex 记忆插件-为 [Codex](https://developers.openai.com/codex) 提供长期语义记忆。每次用户输入前自动召回相关记忆,每轮对话结束后增量捕获,compaction 前提交给 OpenViking 的记忆抽取器;同时把 Codex 直接接到 OpenViking 自带的 `/mcp` endpoint,模型可以直接调用 `search` / `store` / `read` / `grep` / `glob` / `list` / `forget` / `add_resource` 等工具——**没有本地 MCP server 进程要维护**。+为 [Codex](https://developers.openai.com/codex) 提供持久化的跨 session 记忆。安装一次——每次用户输入前自动召回,每轮结束后增量捕获,compaction 前提交给记忆抽取器。插件同时把 Codex 接到 OpenViking 的 `/mcp` 端点,模型可以直接调用 search、store 等工具管理记忆。-源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin)+源码:[examples/codex-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/codex-memory-plugin) | [博客:动机与效果展示](https://blog.openviking.ai/post/openviking-coding-agent/)-## 快速开始--### 一行安装(推荐)+## 安装```bashbash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/examples/codex-memory-plugin/setup-helper/install.sh)```-脚本会检查 `codex`、`git`、Node.js 22+;首次运行时把 OpenViking 仓库 clone 到 `~/.openviking/openviking-repo`,已存在则自动 `git fetch + reset --hard` 到 main;注册本地 `openviking-plugins-local` marketplace、启用 `openviking-memory@openviking-plugins-local`、把 `features.plugin_hooks = true` 写入 `~/.codex/config.toml`,并预填 Codex 的 plugin 缓存让插件立即解析到。每一步幂等,反复执行安全。--存在 `~/.openviking/ovcli.conf` 时直接读它,把 `/mcp` URL 渲染进缓存里的 `.mcp.json`;同时往你的 shell rc 追加一个 `codex()` 函数包装,每次调用 codex 时从 ovcli.conf 把 `OPENVIKING_API_KEY` / `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` 注入到环境变量。API key 只留在 `ovcli.conf` 里,**`.mcp.json` 磁盘文件里只通过 `bearer_token_env_var` 引用变量名,永远不会包含 key 明文**。+脚本会检查依赖、配置 OpenViking 连接并注册插件。每一步幂等,反复执行安全。-安装完成后启动 Codex:+安装完成后:```bashsource ~/.zshrc # 或 ~/.bashrccodex # 首次启动进 /hooks 审批一次```-### 手动安装+<details>+<summary><b>手动安装</b></summary>-前置:+前置:Node.js >= 22、Codex >= 0.130.0、`codex_hooks` feature 已启用。-```bash-node --version # >= 22-codex --version # >= 0.130.0-codex features list | grep codex_hooks-```+1. **Shell 函数包装** — 在 shell rc 中追加一个 `codex()` 函数,每次调用时从 ovcli.conf 注入 OpenViking 环境变量。完整函数见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md)。-installer 替你做的三件事,你也可以自己手动做:--1. **shell 函数包装**追加到 `~/.zshrc` / `~/.bashrc`。installer 实际生成的版本(见 `setup-helper/install.sh`)还会在每次 codex 启动时**重新渲染缓存里的 `.mcp.json` bearer 字段** —— 这是切 `OPENVIKING_CLI_CONFIG_FILE`(有 / 无 key 来回换)所必需的。下面是固定 conf 场景的简化版:-- ```bash- codex() {- local _ov_conf="${OPENVIKING_CLI_CONFIG_FILE:-$HOME/.openviking/ovcli.conf}"- local _ov_url _ov_key _ov_account _ov_user- if [ -f "$_ov_conf" ] && command -v node >/dev/null 2>&1; then- local _ov_env- _ov_env=$(node -e '- try {- const c = JSON.parse(require("node:fs").readFileSync(process.argv[1], "utf8"));- const out = (k, v) => v ? `${k}=${JSON.stringify(String(v))}\n` : "";- process.stdout.write(- out("OV_URL", c.url) +- out("OV_KEY", c.api_key) +- out("OV_ACCOUNT", c.account) +- out("OV_USER", c.user)- );- } catch {}- ' "$_ov_conf" 2>/dev/null)- eval "$_ov_env"- fi- _ov_url="${OPENVIKING_URL:-${OV_URL:-}}"- _ov_key="${OPENVIKING_API_KEY:-${OV_KEY:-}}"- _ov_account="${OPENVIKING_ACCOUNT:-${OV_ACCOUNT:-}}"- _ov_user="${OPENVIKING_USER:-${OV_USER:-}}"- unset OV_URL OV_KEY OV_ACCOUNT OV_USER- # 空值不导出 —— Codex 看到 bearer_token_env_var 指向空 env var 会硬错。- local -a _env_args=()- [ -n "$_ov_url" ] && _env_args+=("OPENVIKING_URL=$_ov_url")- [ -n "$_ov_key" ] && _env_args+=("OPENVIKING_API_KEY=$_ov_key")- [ -n "$_ov_account" ] && _env_args+=("OPENVIKING_ACCOUNT=$_ov_account")- [ -n "$_ov_user" ] && _env_args+=("OPENVIKING_USER=$_ov_user")- _env_args+=("OPENVIKING_AGENT_ID=${OPENVIKING_AGENT_ID:-codex}")- env "${_env_args[@]}" codex "$@"- }- ```--2. **插件安装**——通过指向插件目录的本地 marketplace。`setup-helper/install.sh` 里有完整的 `codex plugin marketplace add` 调用。--3. **占位符渲染**——仓库里 checked-in 的 `.mcp.json` 保留 `__OPENVIKING_MCP_URL__`,`hooks/hooks.json` 保留 `__OPENVIKING_PLUGIN_ROOT__`;这两个占位符必须在拷贝到 Codex 缓存目录 (`~/.codex/plugins/cache/...`) 时被 `sed` 替换成绝对值。installer 自动做。--## 配置--每个连接 / 身份字段的优先级从高到低(环境变量永远最高):--1. **环境变量**(`OPENVIKING_*`)-2. **`ovcli.conf`** — `~/.openviking/ovcli.conf` 或 `OPENVIKING_CLI_CONFIG_FILE`-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,不必重装**。--鉴权头同时发给 REST API(hook 用)和 `/mcp` endpoint(模型用):`Authorization: Bearer <api_key>`。--对于**无鉴权的本地 OV**(`ovcli.conf` 没有 `api_key`,或者根本没 ovcli.conf),`.mcp.json` 渲染时**不会**写入 `bearer_token_env_var`。Codex 0.130 一旦看到 `bearer_token_env_var` 指向空/未设置的 env var,会直接 `Environment variable ... is empty` 硬错。`codex()` shell 函数包装会在**每次 codex 启动时**根据当前 `OPENVIKING_CLI_CONFIG_FILE` 指向的 ovcli.conf 重新渲染这个字段,所以切换 conf(比如 benchmark 隔离)**不用重跑 installer**。多租户身份头通过 `env_http_headers` 始终传。--### 关键环境变量+2. **插件安装** — 注册本地 marketplace 并启用插件。具体命令见 `setup-helper/install.sh`。-| 环境变量 | 默认值 | 说明 |-|---------|--------|------|-| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL(`/mcp` endpoint 在 install 时由此推导) |-| `OPENVIKING_API_KEY` / `OPENVIKING_BEARER_TOKEN` | — | API key,通过 `Authorization: Bearer` 发送 |-| `OPENVIKING_ACCOUNT` / `OPENVIKING_USER` / `OPENVIKING_AGENT_ID` | — | 多租户身份头 |-| `OPENVIKING_CLI_CONFIG_FILE` | `~/.openviking/ovcli.conf` | 备用 `ovcli.conf` 路径 |-| `OPENVIKING_CONFIG_FILE` | `~/.openviking/ov.conf` | 备用 `ov.conf` 路径 |-| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |-| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |-| `OPENVIKING_DEBUG` | `false` | 把 hook 日志写到 `~/.openviking/logs/codex-hooks.log` |+3. **占位符渲染** — `.mcp.json` 和 `hooks.json` 中的占位符在拷贝到 Codex 缓存时需替换为绝对值。installer 会自动做。-### 调参+</details>-调参用 `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+```bash+type codex # 期望输出:codex is a shell function```-完整字段列表见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。+进入 Codex 后插件会在每次输入前召回记忆。设 `OPENVIKING_DEBUG=1` 可把事件写到 `~/.openviking/logs/codex-hooks.log`。-> **遗留 `codex.*` 块**:早期版本支持把调参字段放在 `~/.openviking/ov.conf` 的 `codex` 块下,仍向后兼容。但 codex 是 client 侧插件,per-machine 的调参不该住在 server-scope 的 `ov.conf` 里——新部署请用环境变量。+## 工作原理-## Hook 行为+插件挂载到 Codex 的生命周期:每次用户输入前搜索 OpenViking 并注入相关记忆(`UserPromptSubmit`),每轮结束后把新的对话追加到 session(`Stop`),compaction 前补齐并 commit 完整 transcript(`PreCompact`)让记忆抽取器跑在完整上下文上。新 session 启动时还会清理前次运行的孤儿 session。-| Hook | 触发时机 | 行为 |-|------|---------|------|-| `SessionStart`(matcher `clear\|startup`) | 全新进程 / `/new` / `/clear` | 活动窗口启发式:如果最近 2 分钟内恰好只有一个其他 state 文件被更新,就把它 commit 掉(视为刚刚结束的 session)。尾部的闲置 TTL 清理会捕获 30 分钟以上的孤儿 state(SIGTERM / `/exit` 等)。`source=resume` 是硬 no-op。 |-| `UserPromptSubmit` | 每次用户输入 | 走 REST `/search/find` 搜索 OpenViking → 排序 → 把 top 结果通过 `hookSpecificOutput.additionalContext` 注入到模型上下文。 |-| `Stop` | 每轮结束 | 把新的 user/assistant turn 追加到由 Codex `session_id` 索引的长生命周期 OV session。**不**每轮 commit。 |-| `PreCompact` | Codex 即将做摘要前 | 补齐追加 + commit,让 OV 抽取器跑在完整的 pre-compact transcript 上;commit 后清空 `ovSessionId`,下一次 `Stop` 会打开一个全新的 OV session。 |+> **已知盲区**:Codex 在 `SIGTERM` / `Ctrl+C` / `/exit` 时不触发任何 hook。孤儿 session 由下一次 `SessionStart` 的闲置 TTL 清理(30 分钟)或活动窗口启发式回收。-`Stop` 故意不每轮 commit——commit 会触发记忆抽取,每轮抽取会过度碎片化记忆树。完整的「哪个 hook 负责封住哪个 OV session」决策树见 [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md)。+<details>+<summary><b>配置</b></summary>-### 已知盲区:SIGTERM / Ctrl+C / `/exit` 不触发任何 hook+配置优先级:环境变量 > `ovcli.conf` > `ov.conf` > 内置默认值(`http://127.0.0.1:1933`,无鉴权)。-如果你 `/exit` 之前没跑 `/compact`,那个 codex session 对应的 OV session 会在服务端保持打开状态。两条兜底路径会回收孤儿:--1. 下一次 `SessionStart`(source=startup|clear)的闲置 TTL 清理会 commit 30 分钟以上的孤儿 state。-2. 如果你在孤儿之后立即 `/new` 或 `/clear`,活动窗口启发式会精准命中并 commit。--## MCP 工具+| 环境变量 | 默认值 | 说明 |+|---------|--------|------|+| `OPENVIKING_URL` / `OPENVIKING_BASE_URL` | — | 完整服务器 URL |+| `OPENVIKING_API_KEY` | — | API key(通过 `Authorization: Bearer` 发送) |+| `OPENVIKING_CODEX_ACTIVE_WINDOW_MS` | `120000` | SessionStart 活动窗口阈值 |+| `OPENVIKING_CODEX_IDLE_TTL_MS` | `1800000` | SessionStart 闲置 TTL 清理阈值 |+| `OPENVIKING_DEBUG` | `false` | 写日志到 `~/.openviking/logs/codex-hooks.log` |-插件通过 streamable HTTP 把 Codex 接到 OpenViking 自带的 `/mcp` endpoint。工具列表、每个工具的语义、协议细节统一见 [MCP 集成指南](../guides/06-mcp-integration.md),这里不重复。+调参(`OPENVIKING_RECALL_LIMIT`、`OPENVIKING_CAPTURE_ASSISTANT_TURNS` 等)见 [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md#tuning-the-plugin)。-`.mcp.json` 在 install 时写入 OV server URL,用 `bearer_token_env_var: "OPENVIKING_API_KEY"` + `env_http_headers` 传多租户身份头。**API key 永远不会落到 `.mcp.json` 文件里**,是 codex 启动时由 shell 函数包装从 env 取。+</details>## 故障排查| 现象 | 原因 | 修复 ||------|------|------|-| `MCP server is not logged in. Run codex mcp login` | codex 启动时 `OPENVIKING_API_KEY` 不在 env 里,OV 返回 401,Codex 回落到 OAuth | 确认 `codex()` shell 函数已 source(`type codex` 应该返回"shell function")、且 `ovcli.conf` 里有 `api_key` |-| `4 hooks need review before they can run` | 首次启动的安全审批 | 进入 Codex 输入 `/hooks` 批准 |-| 审批后还是 `hook (failed) exited with code 1` | `hooks.json` 占位符没渲染,cache 是旧的 | 重新跑一次一行安装脚本 |-| 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`(或老配置 `ov.conf` 里 `codex.debug=true`),会把 JSON-Lines 事件写到 `~/.openviking/logs/codex-hooks.log`。--## 与 Claude Code 插件的差异--| 维度 | Claude Code 插件 | Codex 插件 |-|------|------------------|-----------|-| Plugin root env | `CLAUDE_PLUGIN_ROOT`(CC 会展开) | `CODEX_PLUGIN_ROOT`(Codex 0.130 **不展开**;installer 渲染成绝对路径) |-| `UserPromptSubmit` 输出 | `decision: "approve"` + `additionalContext` | 只有 `additionalContext` —— Codex 没有 `approve` 这个 decision |-| Compaction hook | 无 | `PreCompact` —— 在上下文丢失前 commit 完整 transcript |-| 配置区块 | `claude_code` | `codex` |-| 默认配置文件 | `~/.openviking/ov.conf` | `~/.openviking/ovcli.conf`,回落到 `ov.conf` |-| MCP server | 本地 stdio(CC `.mcp.json` 不支持 env-var Bearer) | streamable-HTTP,直连 OpenViking 自带 `/mcp` |+| `MCP server is not logged in` | 启动时 `OPENVIKING_API_KEY` 不在 env 里 | 确认 `codex()` 函数已 source,`ovcli.conf` 有 `api_key` |+| `4 hooks need review` | 首次启动的安全审批 | 在 Codex 输入 `/hooks` 审批 |+| 审批后仍 `hook (failed) exited with code 1` | 缓存里占位符未渲染 | 重新跑一次一行安装脚本 |+| 召回为空 | 服务器不可达或 URL 不对 | `curl "$(jq -r '.url' ~/.openviking/ovcli.conf)/health"` |+| Hook 401 但 MCP 可用,或反之 | env vs ovcli.conf 不一致 | Hook 每次重读 ovcli.conf,MCP 在启动时读 env。改完重启 codex。 |## 参见-- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、Validation SOP、架构图-- [`DESIGN.md`](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树-- [MCP 集成指南](../guides/06-mcp-integration.md) — 协议、工具列表、OpenViking 如何暴露 `/mcp`+- [博客:在 Claude Code / Codex 中接入 OpenViking](https://blog.openviking.ai/post/openviking-coding-agent/) — 为什么以及如何给你的 Coding Agent 加上长期记忆+- [插件 README](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/README.md) — 完整环境变量、架构图+- [DESIGN.md](https://github.com/volcengine/OpenViking/blob/main/examples/codex-memory-plugin/DESIGN.md) — commit 决策树+- [MCP 客户端](./06-mcp-clients.md) — MCP 协议、工具列表、其他客户端- [部署指南 → CLI](../guides/03-deployment.md#cli) — `ovcli.conf` 配置diff --git a/docs/zh/agent-integrations/05-hermes.md b/docs/zh/agent-integrations/05-hermes.mdnew file mode 100644index 000000000..10b9079f0--- /dev/null+++ b/docs/zh/agent-integrations/05-hermes.md@@ -0,0 +1,33 @@+# Hermes Agent++[Hermes Agent](https://hermes-agent.nousresearch.com/) (Nous Research) 内置 OpenViking 记忆提供方。无需安装插件——把 Hermes 指向你的 OpenViking 服务即可,记忆存储、召回和抽取均原生支持。++## 配置++运行 Hermes 记忆配置向导:++```bash+hermes memory setup+```++向导会询问:++- **OpenViking 服务 URL** — 自托管服务器(默认 `http://127.0.0.1:1933`)或火山引擎 OpenViking Cloud+- **API Key** — 本地开发模式留空+- **租户 account / user / agent ID** — 多租户部署时使用++配置保存在 Hermes 的 `config.yaml` 和 `.env` 文件中。++## 验证++```bash+hermes memory status+```++配置完成后,Hermes 自动使用 OpenViking 作为长期记忆——`viking_remember`、`viking_recall` 等记忆工具即刻可用。++## 参见++- [Hermes — OpenViking memory provider 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers#openviking) — 完整配置指南+- [部署指南](../guides/03-deployment.md) — 搭建 OpenViking 服务+- [鉴权](../guides/04-authentication.md) — 远程访问的 API Key 设置diff --git a/docs/zh/agent-integrations/05-other-plugins.md b/docs/zh/agent-integrations/05-other-plugins.mddeleted file mode 100644index 210140d20..000000000--- a/docs/zh/agent-integrations/05-other-plugins.md+++ /dev/null@@ -1,49 +0,0 @@-# 其他插件--仓库里还附带了几个未在 Claude Code、Codex 和 OpenClaw 主集成中介绍的社区/实验性插件。它们在目标 runtime、集成深度和维护状态上各有差异,使用前请先阅读各自的 README。--## AstrBot 插件--[AstrBot](https://github.com/AstrBotDevs/AstrBot) 是一个多平台 IM Bot 框架,支持 QQ(AIOCQHTTP)、Telegram、Discord、飞书等 20+ 平台。--源码:[astrbot_plugin_openviking_memory](https://github.com/t0saki/astrbot_plugin_openviking_memory)--为 AstrBot 提供 OpenViking 长期记忆能力:自动捕获群聊/私聊对话,LLM 请求前语义召回相关记忆,支持三档 venue 记忆隔离。--**安装**:在 AstrBot WebUI → 插件市场搜索 **OpenViking Memory** 并安装;或从链接安装:`https://github.com/t0saki/astrbot_plugin_openviking_memory.git`--**主要特性**:--- 基于 hooks 的自动召回与捕获,模型不需要主动调用工具-- 三档隔离模式:`venue_user`(群/私聊各自独立)、`venue_user_fanout`(跨群共享)、`global_user`(全局共享)-- 四触发器自动 commit:消息计数、token 阈值、空闲超时、进程退出 flush-- 首次接入群聊时自动拉取平台历史消息入库--## OpenCode 插件--OpenCode 有两个设计路径不同的插件变体。请按你的使用方式自行选择,我们不替你决定。--### `opencode-memory-plugin` — 显式工具版本--源码:[examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)--通过 OpenCode 的工具机制把 OpenViking 记忆暴露为显式工具,并把对话会话同步到 OpenViking。--- 模型看到的是具体工具,由它决定何时调用-- OpenViking 数据按需通过工具调用获取,而不是预注入到每次 prompt-- 插件还会把 OpenViking session 与 OpenCode 对话保持同步,并通过 `memcommit` 触发后台抽取--### `opencode/plugin` — 上下文注入版本--源码:[examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)--把已索引的代码仓库注入 OpenCode 上下文,并按需自动启动 OpenViking 服务器。--- prompt 上下文中加入索引代码库的相关片段-- 自带一个轻量启动器,按需拉起 OpenViking 服务--## 通用 MCP 客户端--Cursor、Trae、Manus、Claude Desktop、ChatGPT/Codex 以及任何其他兼容 MCP 的 runtime,无需专属插件——直接把客户端指向内置 `/mcp` 端点即可。--→ 参见 [MCP 集成指南](../guides/06-mcp-integration.md)。diff --git a/docs/zh/agent-integrations/06-langchain-langgraph.md b/docs/zh/agent-integrations/06-langchain-langgraph.mddeleted file mode 100644index e30bf367c..000000000--- a/docs/zh/agent-integrations/06-langchain-langgraph.md+++ /dev/null@@ -1,50 +0,0 @@-# LangChain 和 LangGraph--OpenViking 可以作为 LangChain 与 LangGraph Agent 的上下文后端使用。该集成提供框架原生的 retriever、chat history、runnable wrapper、LangGraph middleware、LangGraph store,以及 `viking_*` tools。--## 安装--```bash-pip install "openviking[langchain]"-pip install "openviking[langgraph]"-```--如果同时使用 LangChain 和 LangGraph,可以一起安装:--```bash-pip install "openviking[langchain,langgraph]"-```--## 连接 OpenViking--本集成默认连接 `http://localhost:1933`。远程服务需要传入 `api_key`、`account`、`user_id`、`agent_id` 等连接参数,或使用环境变量和应用自己的配置层传入这些值。--```python-from openviking.integrations.langchain import create_openviking_tools--tools = create_openviking_tools(- url="http://localhost:1933",- profile="agent",-)-```--## 常见用法--- 使用 `OpenVikingRetriever` 把 OpenViking 检索结果接入 LangChain RAG。-- 使用 `create_openviking_tools()` 暴露 `viking_find`、`viking_search`、`viking_browse`、`viking_read`、`viking_grep`、`viking_store` 等工具。-- 使用 `with_openviking_context(...)` 在 LangChain runnable 前自动装配 OpenViking session context,并在模型调用后捕获对话。-- 使用 `OpenVikingContextMiddleware` 在 LangGraph agent 中注入上下文、捕获消息,并按 commit policy 触发 session commit。该 middleware 需要明确的 `thread_id`、`session_id` 或自定义 `session_id_resolver`,不会回退到共享默认 session。-- 使用 `OpenVikingStore` 作为 LangGraph `BaseStore`,把跨线程记忆存入 OpenViking。--## 示例--仓库内提供了可直接运行的最小示例:--- `examples/langchain-langgraph/langchain/rag/quick_app.py`-- `examples/langchain-langgraph/langchain/context-backend/quick_app.py`-- `examples/langchain-langgraph/langchain/message-history/quick_app.py`-- `examples/langchain-langgraph/langgraph/agent/quick_app.py`-- `examples/langchain-langgraph/langgraph/agent/live_app.py`-- `examples/langchain-langgraph/langgraph/middleware/quick_app.py`--更完整的英文说明见 [LangChain and LangGraph](../../en/agent-integrations/06-langchain-langgraph.md)。diff --git a/docs/zh/agent-integrations/06-mcp-clients.md b/docs/zh/agent-integrations/06-mcp-clients.mdnew file mode 100644index 000000000..ca567a310--- /dev/null+++ b/docs/zh/agent-integrations/06-mcp-clients.md@@ -0,0 +1,86 @@+# MCP 客户端++任何兼容 [MCP](https://modelcontextprotocol.io/) 的客户端都可以直接连接 OpenViking 内置的 `/mcp` 端点——无需安装插件或启动额外进程。适用于 Cursor、Trae、Manus、Claude Desktop、ChatGPT 等。++## 快速配置++大多数 MCP 客户端使用标准 `mcpServers` 格式:++```json+{+ "mcpServers": {+ "openviking": {+ "url": "https://your-server.com/mcp",+ "headers": {+ "Authorization": "Bearer your-api-key-here"+ }+ }+ }+}+```++本地服务未配置 `root_api_key` 时(dev 模式)无需认证。++## 各平台注意事项++### Claude Code++Claude Code 需要额外指定 `"type": "http"`,通过命令行添加:++```bash+claude mcp add --transport http openviking \+ https://your-server.com/mcp \+ --header "Authorization: Bearer your-api-key-here"+```++加 `--scope user` 使配置全局生效。++> 如果你需要免工具调用的自动召回与自动捕获,请使用 [Claude Code 记忆插件](./02-claude-code.md)。++### Trae / Cursor / ChatGPT / Codex / OpenCode++使用上面的标准 `mcpServers` 配置即可——均已通过 API Key 鉴权验证。++### Claude Desktop / Claude.ai (OAuth)++这些客户端要求 OAuth 2.1——无法直接传 API Key。OpenViking 自带原生 OAuth 2.1 实现,无需外部代理。++如果你已经为 OpenViking 服务配好了 HTTPS,直接连接 `https://your-server.com/mcp` 端点即可——客户端会自动引导你完成 OAuth 授权流程。++HTTPS 配置、部署模板和完整授权流程详见 [OAuth 2.1 指南](../guides/11-oauth.md) 和 [公网访问指南](../guides/12-public-access.md)。++## 可用工具++连接后 OpenViking 暴露 14 个工具:++| 工具 | 说明 |+|------|------|+| `search` | 跨记忆、资源、技能的语义搜索 |+| `read` | 读取一个或多个 `viking://` URI |+| `list` | 列出 `viking://` 目录下的条目 |+| `store` | 存储消息到长期记忆 |+| `add_resource` | 添加本地文件或 URL 作为资源 |+| `grep` | 正则内容搜索 |+| `glob` | 按 glob 模式查找文件 |+| `forget` | 删除 `viking://` URI |+| `code_outline` | 展示文件的符号结构 |+| `code_search` | 跨目录搜索符号名 |+| `code_expand` | 返回单个符号的完整源码 |+| `health` | 检查 OpenViking 服务状态 |+| `list_watches` | 列出自动刷新订阅 |+| `cancel_watch` | 取消 watch 任务 |++工具参数、渐进式文件上传和高级配置见 [MCP 集成指南](../guides/06-mcp-integration.md)。++## 故障排查++| 现象 | 修复 |+|------|------|+| 连接被拒绝 | 确认 `openviking-server` 正在运行:`curl http://localhost:1933/health` |+| 认证错误 | 确保客户端配置中的 API Key 与服务端一致。见 [鉴权指南](../guides/04-authentication.md) |++## 参见++- [MCP 集成指南](../guides/06-mcp-integration.md) — 工具参数、渐进式上传、`OPENVIKING_PUBLIC_BASE_URL`+- [OAuth 2.1 指南](../guides/11-oauth.md) — 用于 Claude Desktop、Claude.ai、Cursor+- [MCP 规范](https://modelcontextprotocol.io/)diff --git a/docs/zh/agent-integrations/07-langchain-langgraph.md b/docs/zh/agent-integrations/07-langchain-langgraph.mdnew file mode 100644index 000000000..8de4633a4--- /dev/null+++ b/docs/zh/agent-integrations/07-langchain-langgraph.md@@ -0,0 +1,111 @@+# LangChain 和 LangGraph++把 OpenViking 接入你的 LangChain 或 LangGraph Agent 作为上下文后端。SDK 提供 retriever、chat history、context wrapper、agent tools、LangGraph store 和 middleware——全部通过 HTTP 连接运行中的 OpenViking 服务。++## 安装++```bash+pip install "openviking[langchain]" # retriever + chat history+pip install "openviking[langgraph]" # 完整 LangGraph 支持(包含 langchain)+```++## 连接++```python+from openviking.integrations.langchain import create_openviking_tools++tools = create_openviking_tools(+ url="http://localhost:1933",+ api_key="...",+ profile="agent",+)+```++省略 `url` 时,适配器自动从 OpenViking CLI 配置加载连接信息。Embedding 和 VLM 在 OpenViking 侧配置,不在你的应用中。++## 选哪个适配器?++| 我想… | 用这个 |+|-------|--------|+| 为 RAG 检索相关上下文 | `OpenVikingRetriever` |+| 包装 runnable,自动召回 + 捕获 + 按策略 commit | `with_openviking_context()` |+| 给 agent 暴露显式记忆工具 | `create_openviking_tools()` |+| 存储跨线程的持久化状态 | `OpenVikingStore` |+| 在 LangGraph 中以 middleware 注入上下文 | `OpenVikingContextMiddleware` |+| 用 OpenViking 存储 LangChain 聊天记录 | `OpenVikingChatMessageHistory` |++## 快速示例++### Retriever++```python+from openviking.integrations.langchain import OpenVikingRetriever++retriever = OpenVikingRetriever(url="http://localhost:1933", api_key="...")+docs = retriever.invoke("用户之前对部署方案做了什么决定?")+```++### Context backend++```python+from langchain_core.messages import AIMessage+from langchain_core.runnables import RunnableLambda+from openviking.integrations.langchain import with_openviking_context++chain = with_openviking_context(+ RunnableLambda(lambda msgs: AIMessage(content="...")),+ url="http://localhost:1933",+ api_key="...",+)+```++### Agent tools++```python+from openviking.integrations.langchain import create_openviking_tools++tools = create_openviking_tools(url="http://localhost:1933", profile="agent")+# 包括:viking_find, viking_search, viking_browse, viking_read,+# viking_grep, viking_store, viking_add_resource 等+```++### LangGraph store++```python+from openviking.integrations.langchain import OpenVikingStore++store = OpenVikingStore(url="http://localhost:1933", api_key="...")+store.put(("users", "ada"), "preferences", {"color": "azure"})+items = store.search(("users",), query="azure", limit=3)+```++### LangGraph middleware++```python+from openviking.integrations.langchain import OpenVikingContextMiddleware++middleware = OpenVikingContextMiddleware(+ url="http://localhost:1933",+ api_key="...",+ capture_on_after_agent=True,+)+```++## 运行示例++仓库内提供了可直接运行的最小示例,使用内存测试客户端,无需模型凭证:++```bash+uv run --extra langgraph python examples/langchain-langgraph/langchain/rag/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langchain/context-backend/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langchain/message-history/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langgraph/agent/quick_app.py+uv run --extra langgraph python examples/langchain-langgraph/langgraph/middleware/quick_app.py+```++连接真实 OpenViking 服务和 OpenAI 兼容模型的示例见 [live LangGraph app](https://github.com/volcengine/OpenViking/blob/main/examples/langchain-langgraph/langgraph/agent/live_app.py)。++## 参见++- [examples/langchain-langgraph/](https://github.com/volcengine/OpenViking/tree/main/examples/langchain-langgraph) — 上面所有示例的完整源码+- [MCP 客户端](./06-mcp-clients.md) — 非 SDK 方式的 MCP 集成diff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.mdnew file mode 100644index 000000000..7c9fa6110--- /dev/null+++ b/docs/zh/agent-integrations/08-community-plugins.md@@ -0,0 +1,36 @@+# 社区插件++社区维护的各运行时集成。各插件在目标平台、集成深度和维护状态上各有差异,使用前请先阅读各自的 README。++## AstrBot 插件++[AstrBot](https://github.com/AstrBotDevs/AstrBot) 是一个多平台 IM Bot 框架,支持 QQ、Telegram、Discord、飞书等 20+ 平台。++源码:[astrbot_plugin_openviking_memory](https://github.com/t0saki/astrbot_plugin_openviking_memory)++为 AstrBot 提供群聊/私聊的自动捕获、LLM 请求前的语义召回,以及可配置的 venue 记忆隔离。++**安装**:在 AstrBot WebUI → 插件市场搜索 **OpenViking Memory** 并安装;或从链接安装:`https://github.com/t0saki/astrbot_plugin_openviking_memory.git`++**主要特性**:++- 基于 hooks 的自动召回与捕获,模型不需要主动调用工具+- 三档隔离模式:`venue_user`(群/私聊各自独立)、`venue_user_fanout`(跨群共享)、`global_user`(全局共享)+- 四触发器自动 commit:消息计数、token 阈值、空闲超时、进程退出 flush+- 首次接入群聊时自动拉取平台历史消息入库++## OpenCode 插件++OpenCode 有两个设计路径不同的插件变体,请按你的使用方式自行选择。++### `opencode-memory-plugin` — 显式工具版本++源码:[examples/opencode-memory-plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode-memory-plugin)++通过 OpenCode 的工具机制把 OpenViking 记忆暴露为显式工具。模型决定何时调用,数据按需获取。++### `opencode/plugin` — 上下文注入版本++源码:[examples/opencode/plugin](https://github.com/volcengine/OpenViking/tree/main/examples/opencode/plugin)++把已索引的代码仓库注入 OpenCode 上下文,并按需自动启动 OpenViking 服务器。\ No newline at end of filediff --git a/docs/zh/guides/06-mcp-integration.md b/docs/zh/guides/06-mcp-integration.mdindex 8a57220ec..4ad143420 100644--- a/docs/zh/guides/06-mcp-integration.md+++ b/docs/zh/guides/06-mcp-integration.md@@ -2,6 +2,8 @@OpenViking 服务器内置 [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 端点,任何兼容 MCP 的客户端都可以通过 HTTP 直接访问其记忆和资源能力,无需部署额外进程。+> **快速接入?** 见 [MCP 客户端](../agent-integrations/06-mcp-clients.md) 获取各平台配置片段和注意事项。本页面覆盖完整的工具参考和高级配置。+## 前提条件1. 已安装 OpenViking(`pip install openviking` 或从源码安装)@@ -17,10 +19,12 @@ MCP 端点位于 `http://<server>:1933/mcp`,与 REST API 同进程、同端口| 平台 | 接入方式 ||------|----------|| **Claude Code** | `type: http` 接入 |+| **Trae** | 标准 MCP 配置 |+| **Cursor** | 标准 MCP 配置 || **ChatGPT & Codex** | 标准 MCP 配置 |-| **Claude.ai / Claude Desktop** | 原生 OAuth 2.1(见 [11-oauth](11-oauth.md)) |+| **OpenCode** | 标准 MCP 配置 || **Manus** | 标准 MCP 配置 |-| **Trae** | 标准 MCP 配置 |+| **Claude.ai / Claude Desktop** | 原生 OAuth 2.1(见 [11-oauth](11-oauth.md)) |## 鉴权方式@@ -78,15 +82,17 @@ claude mcp add --transport http openviking \加 `--scope user` 可将配置设为全局(所有项目共享)。-### Claude.ai / Claude Desktop / ChatGPT / Cursor(OAuth)+### Claude.ai / Claude Desktop(OAuth)这些客户端只接受 OAuth 2.1,不接受 API Key。OpenViking 已经原生实现 OAuth 2.1(DCR + PKCE + opaque token,SQLite 后端,配合 console 驱动的 OTP 授权页),不再需要外部代理。-**详见 [OAuth 2.1 接入指南](11-oauth.md)**:+如果你已经为 OpenViking 服务配好了 HTTPS,直接连接 `https://your-server.com/mcp` 端点即可——客户端会自动引导完成 OAuth 授权流程。++**详见 [OAuth 2.1 接入指南](11-oauth.md)** 和 **[公网访问指南](12-public-access.md)**:- 端到端流程(device-flow 风格:authorize 页显示 6 字符码,用户在 console 确认)- HTTP(本地)与 HTTPS(生产)两阶段部署,包含 Caddy / nginx 反代模板和 docker-compose 示例-- Claude.ai / Claude Desktop / Cursor / ChatGPT 接入步骤+- Claude.ai / Claude Desktop 接入步骤- `OPENVIKING_PUBLIC_BASE_URL` 与 `oauth` 配置项- Token 模型(`ovat_` / `ovrt_` / `ovac_` 前缀)与撤销