### Install and Start OpenViking Server (from repo)

Source: https://github.com/volcengine/openviking/blob/main/web-studio/README.md

Steps to install OpenViking Server from the repository and start it with bot support.

```bash
uv pip install -e ".[bot,dev]"
openviking-server init
openviking-server doctor
openviking-server --with-bot
```

--------------------------------

### Install and Start OpenViking Server (from package)

Source: https://github.com/volcengine/openviking/blob/main/web-studio/README.md

Steps to install OpenViking Server from the published package and start it with bot support.

```bash
pip install "openviking[bot]"
openviking-server init
openviking-server doctor
openviking-server --with-bot
```

--------------------------------

### Install and Setup OpenViking Plugin

Source: https://github.com/volcengine/openviking/blob/main/docs/images/agents/en/openclaw.md

Run this command to install the OpenViking plugin and initiate its setup process.

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin && openclaw openviking setup
```

--------------------------------

### Setup Project Environment

Source: https://github.com/volcengine/openviking/blob/main/tests/oc2ov_test/README.md

Automatically create a virtual environment and install project dependencies using the setup script.

```bash
./setup.sh
```

--------------------------------

### Install and Initialize OpenViking Server

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

Install OpenViking, initialize its configuration, and start the server if a local instance is desired.

```bash
pip install openviking --upgrade --force-reinstall
openviking-server init
openviking-server doctor
openviking-server
```

--------------------------------

### Install OpenViking Setup Helper

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL.md

Install the `openclaw-openviking-setup-helper` globally as a backup installation path.

```bash
npm install -g openclaw-openviking-setup-helper
```

--------------------------------

### Install OpenViking CLI and Start Configuration

Source: https://github.com/volcengine/openviking/blob/main/docs/images/agents/en/cli.md

Run this command to install the OpenViking CLI globally and initiate the configuration process.

```bash
npm i -g @openviking/cli && ov config
```

--------------------------------

### Start OpenViking Server

Source: https://github.com/volcengine/openviking/blob/main/examples/opencode-memory-plugin/README.md

Start the OpenViking server before installing the plugin. Ensure it is running if it is not already.

```bash
openviking-server --config ~/.openviking/ov.conf
```

--------------------------------

### Start Web Studio Development Server

Source: https://github.com/volcengine/openviking/blob/main/web-studio/README.md

Commands to install dependencies and start the Vite development server for Web Studio.

```bash
cd web-studio
npm install
npm run dev
```

--------------------------------

### Install and Setup OpenViking Plugin

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/README.md

Quickly install the OpenViking plugin, set up the connection to your OpenViking server, and restart the OpenClaw gateway.

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url http://my-server:1933 --api-key sk-xxx --json
openclaw gateway restart
```

--------------------------------

### Run LangChain/LangGraph Examples with uv

Source: https://github.com/volcengine/openviking/blob/main/docs/en/agent-integrations/07-langchain-langgraph.md

Execute provided examples using the `uv` command-line tool. Ensure the `langgraph` extra is installed. Examples cover RAG, context backend, message history, agent, and middleware.

```bash
uv run --extra langgraph python examples/langchain-langgraph/langchain/rag/quick_app.py
```

```bash
uv run --extra langgraph python examples/langchain-langgraph/langchain/context-backend/quick_app.py
```

```bash
uv run --extra langgraph python examples/langchain-langgraph/langchain/message-history/quick_app.py
```

```bash
uv run --extra langgraph python examples/langchain-langgraph/langgraph/agent/quick_app.py
```

```bash
uv run --extra langgraph python examples/langchain-langgraph/langgraph/middleware/quick_app.py
```

--------------------------------

### OpenViking CLI Quick Start Commands

Source: https://github.com/volcengine/openviking/blob/main/crates/ov_cli/README.md

Demonstrates basic OpenViking CLI commands for adding resources, listing contents, performing semantic searches, getting file trees, and reading content.

```bash
# Add a resource
ov add-resource https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/docs/en/about/01-about-us.md --wait

# List contents
ov ls viking://resources

# Semantic search
ov find "what is openviking"

# Get file tree
ov tree viking://resources

# Read content
ov read viking://resources/...
```

--------------------------------

### Quick Start Helm Installation

Source: https://github.com/volcengine/openviking/blob/main/deploy/helm/README.md

Install OpenViking using the Helm chart with essential configuration parameters like API keys.

```bash
helm install openviking ./deploy/helm/openviking \
  --set-string config.server.root_api_key="YOUR_ROOT_API_KEY" \
  --set-string config.embedding.dense.api_key="YOUR_VOLCENGINE_API_KEY" \
  --set-string config.vlm.api_key="YOUR_VOLCENGINE_API_KEY"
```

--------------------------------

### Quick Start Examples for Summarize CLI

Source: https://github.com/volcengine/openviking/blob/main/bot/workspace/skills/summarize/SKILL.md

Demonstrates basic usage for summarizing URLs, local files, and YouTube links. Specify the desired model using the --model flag.

```bash
summarize "https://example.com" --model google/gemini-3-flash-preview
summarize "/path/to/file.pdf" --model google/gemini-3-flash-preview
summarize "https://youtu.be/dQw4w9WgXcQ" --youtube auto
```

--------------------------------

### Primary Installation Workflow

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

Standard workflow for installing or upgrading the plugin from published packages, followed by setup and gateway restart.

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
openclaw gateway restart
openclaw openviking status --json
```

--------------------------------

### Configure OpenViking Plugin (Interactive)

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL.md

Run the interactive setup command for the OpenViking plugin. This command guides you through the configuration process for human setup.

```bash
openclaw openviking setup
```

--------------------------------

### Clone and Run Basic Usage Example

Source: https://github.com/volcengine/openviking/blob/main/examples/basic-usage/README.md

Clone the OpenViking repository and navigate to the basic usage example directory. Then, run the example script using Python.

```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking/examples/basic-usage
python basic_usage.py
```

--------------------------------

### Setup OpenViking Plugin with JSON Output

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

Run the setup command with the --json flag for machine-readable output. This is crucial for branching logic based on setup results.

```bash
openclaw openviking setup --base-url <OPENVIKING_URL> --api-key <API_KEY> --json
```

--------------------------------

### Example: Targeted ov_search Command

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md

Demonstrates using the `ov_search` command to find resources related to 'OpenViking install' within a specific resource URI.

```text
/ov-search "OpenViking install" --uri viking://resources/openviking-readme
```

--------------------------------

### Configure OpenViking Plugin with Local URL and API Key

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL.md

Example of non-interactive setup for the OpenViking plugin using a local OpenViking server URL and a sample API key.

```bash
openclaw openviking setup --base-url http://127.0.0.1:1933 --api-key sk-xxx --json
```

--------------------------------

### Configure OpenViking Plugin Manually (Path A)

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md

Run the setup wizard non-interactively for Path A installations. Ensure you provide the required `--base-url` and conditionally include other flags based on collected user information.

```bash
openclaw openviking setup --base-url BASE_URL --json [--api-key API_KEY] [--peer-role PEER_ROLE] [--peer-prefix PEER_PREFIX] [--account-id ACCOUNT_ID] [--user-id USER_ID] [--allow-offline] [--force-slot]
```

--------------------------------

### Start OpenViking Services

Source: https://github.com/volcengine/openviking/blob/main/docs/en/guides/11-oauth.md

Start the OpenViking services using Docker Compose for a managed environment or directly using the `openviking-server` command for a standalone setup.

```bash
docker compose up -d
```

```bash
openviking-server
```

--------------------------------

### Initialize and Use OpenViking Client in Python

Source: https://github.com/volcengine/openviking/blob/main/docs/en/getting-started/02-quickstart.md

This Python script demonstrates initializing the OpenViking client, adding a resource from a URL, exploring its structure, reading content, getting an abstract and overview, and performing a semantic search. Ensure the 'openviking' library is installed. The script handles potential exceptions during operation.

```python
import openviking as ov

# Initialize OpenViking client with data directory
client = ov.OpenViking(path="./data")

try:
    # Initialize the client
    client.initialize()

    # Add resource (supports URL, file, or directory)
    # Local directory scans respect .gitignore by default.
    # Wait until semantic processing completes before inspecting the resource.
    print("Wait for semantic processing...")
    add_result = client.add_resource(
        path="https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md",
        wait=True,
    )
    root_uri = add_result['root_uri']

    # Explore the resource tree structure
    ls_result = client.ls(root_uri)
    print(f"Directory structure:\n{ls_result}\n")

    # Use glob to find markdown files
    glob_result = client.glob(pattern="**/*.md", uri=root_uri)
    if glob_result['matches']:
        content = client.read(glob_result['matches'][0])
        print(f"Content preview: {content[:200]}...\n")

    # Get abstract and overview of the resource
    abstract = client.abstract(root_uri)
    overview = client.overview(root_uri)
    print(f"Abstract:\n{abstract}\n\nOverview:\n{overview}\n")

    # Perform semantic search
    results = client.find("what is openviking", target_uri=root_uri)
    print("Search results:")
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

    # Close the client
    client.close()

except Exception as e:
    print(f"Error: {e}")
```

--------------------------------

### Local TAU-2 Setup Script

Source: https://github.com/volcengine/openviking/blob/main/benchmark/tau2/llm/README.md

Executes a script to clone and install the TAU-2 repository into benchmark directories, followed by sourcing an environment file for configuration.

```bash
benchmark/tau2/llm/scripts/setup_tau2_repo.sh
source benchmark/tau2/llm/.env.tau2
```

--------------------------------

### Quickstart: Initialize tmux Session

Source: https://github.com/volcengine/openviking/blob/main/bot/workspace/skills/tmux/SKILL.md

Sets up a new detached tmux session named 'vikingbot-python' and starts a Python REPL within the first pane. Use this for interactive CLI tasks.

```bash
SOCKET_DIR="${NANOBOT_TMUX_SOCKET_DIR:-"${TMPDIR:-/tmp}/vikingbot-tmux-sockets}""
mkdir -p "$SOCKET_DIR"
SOCKET="$SOCKET_DIR/vikingbot.sock"
SESSION=vikingbot-python

tmux -S "$SOCKET" new -d -s "$SESSION" -n shell
tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'PYTHON_BASIC_REPL=1 python3 -q' Enter
tmux -S "$SOCKET" capture-pane -p -J -t "$SESSION":0.0 -S -200
```

--------------------------------

### Install Dependencies and uv

Source: https://github.com/volcengine/openviking/blob/main/docs/en/getting-started/03-quickstart-server.md

Installs essential command-line tools like curl, git, and tree, then installs the uv package manager.

```bash
yum install -y curl git tree

# Step 1: Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Step 2: Configure environment variables
echo 'source $HOME/.cargo/env' >> ~/.bashrc
source ~/.bashrc

# Verify installation
uv --version

```

--------------------------------

### Install OpenClaw and Onboard

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

Install OpenClaw globally if it is missing and complete the initial onboarding process.

```bash
npm install -g openclaw
openclaw onboard
```

--------------------------------

### Install Plugin from Source

Source: https://github.com/volcengine/openviking/blob/main/examples/opencode-plugin/README.md

For development or testing, install the plugin from source by copying files and running npm install within the plugin directory.

```bash
mkdir -p ~/.config/opencode/plugins/openviking
cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cd ~/.config/opencode/plugins/openviking
npm install
```

--------------------------------

### Start OpenViking Server

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

Commands to initialize, check the health of, and start the OpenViking server.

```bash
openviking-server init && openviking-server doctor && openviking-server
```

--------------------------------

### Install OpenViking Helm Chart Locally

Source: https://github.com/volcengine/openviking/blob/main/examples/k8s-helm/README.md

Install the OpenViking Helm chart from a local clone of the repository. Supports installation with default or custom values.

```bash
# Clone the repository
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking/deploy/helm

# Install with default values
helm install openviking ./openviking

# Install with custom values
helm install openviking ./openviking -f my-values.yaml
```

--------------------------------

### AI Assistant Prompt for OpenViking CLI Setup

Source: https://github.com/volcengine/openviking/blob/main/docs/images/agents/en/agent-cli.md

This prompt guides an AI assistant to automate the installation, configuration, and learning of the OpenViking CLI. It includes steps for obtaining the API key, creating the configuration file, and installing the CLI.

```text
First ask the user for the OpenViking API Key and store it as OPENVIKING_API_KEY.

Write the following content to ~/.openviking/ovcli.conf, replacing ${OPENVIKING_API_KEY} with the actual value provided by the user:
{
  "url": "https://api.vikingdb.cn-beijing.volces.com/openviking",
  "api_key": "${OPENVIKING_API_KEY}"
}

If ~/.openviking/ovcli.conf already exists and the content conflicts, ask the user whether to back up the original file before overwriting it.

Install OpenViking CLI:
npm i -g @openviking/cli

After installation, run:
ov --help

Explore the CLI usage and write the OpenViking CLI workflow into your long-term memory.
```

--------------------------------

### Full Python SDK Example

Source: https://github.com/volcengine/openviking/blob/main/docs/en/getting-started/03-quickstart-server.md

Demonstrates initializing the client, adding a resource, waiting for processing, searching, and closing the client connection.

```python
import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")

try:
    client.initialize()

    # Add a resource
    result = client.add_resource(
        "https://raw.githubusercontent.com/volcengine/OpenViking/refs/heads/main/README.md"
    )
    root_uri = result["root_uri"]

    # Wait for processing
    client.wait_processed()

    # Search
    results = client.find("what is openviking", target_uri=root_uri)
    for r in results.resources:
        print(f"  {r.uri} (score: {r.score:.4f})")

finally:
    client.close()
```

--------------------------------

### Initialize and Start OpenViking Server

Source: https://github.com/volcengine/openviking/blob/main/docs/en/guides/03-deployment.md

Quickly set up and launch the OpenViking server using the command line. Ensure your configuration is valid before starting.

```bash
openviking-server init

openviking-server doctor

openviking-server

openviking-server --config /path/to/ov.conf

curl http://localhost:1933/health
```

--------------------------------

### Typical Admin Workflow - Step 1: Create Account

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/08-admin.md

Use the CLI with --sudo to create a new workspace (account) and assign an initial admin.

```bash
# Step 1: ROOT creates workspace with alice as first admin (requires --sudo)
ov --sudo admin create-account acme --admin alice
# Returns alice's user_key
```

--------------------------------

### Token Budget Management Example

Source: https://github.com/volcengine/openviking/blob/main/docs/en/concepts/03-context-layers.md

Demonstrates a best practice for managing token budgets by prioritizing L1 overview content and loading L2 detail content only when required.

```python
# Use L1 first, load L2 only when needed
overview = client.overview(uri)

if needs_more_detail(overview):
    content = client.read(uri)
```

--------------------------------

### Retrieval Instruction Configuration Example

Source: https://github.com/volcengine/openviking/blob/main/benchmark/RAG/README.md

Example of how to configure a custom retrieval instruction in `config.yaml`. This instruction is prepended to queries to guide the retrieval process.

```yaml
# ===========Execution Configuration============
# Instruction for retrieval, empty by default
# Recommended format: "Target_modality: xxx.\nInstruction:xxx.\nQuery:"
retrieval_instruction: "Target_modality: text.\nInstruction:Locate the part of the conversation where the speakers discuss.\nQuery:"
```

--------------------------------

### Install OpenClaw Plugin via CLI

Source: https://github.com/volcengine/openviking/blob/main/docs/en/agent-integrations/03-openclaw.md

Standard installation of the OpenClaw plugin using the 'openclaw' command-line interface. This includes setup and restarting the gateway.

```bash
openclaw plugins install clawhub:@openviking/openclaw-plugin
openclaw openviking setup --base-url http://your-server:1933 --api-key sk-xxx --json
openclaw gateway restart
```

--------------------------------

### OpenViking Query Formulation Examples

Source: https://github.com/volcengine/openviking/blob/main/examples/opencode/plugin/skills/openviking/SKILL.md

Examples demonstrating how to formulate effective search queries. More specific and contextual queries yield better results. Narrowing the scope with `--uri` is recommended.

```bash
ov search "API"                                                       # too vague
ov search "REST API authentication with JWT tokens"                   # better
ov search "JWT token refresh flow" --uri viking://resources/backend   # best

```

--------------------------------

### Copy Example Deployment Configuration

Source: https://github.com/volcengine/openviking/blob/main/bot/deploy/vke/README.md

Copy the example deployment configuration file to your local configuration directory. This file will be edited with your specific VKE and Volcengine details.

```bash
mkdir -p ~/.config/vikingbot
cp deploy/vke/vke_deploy.example.yaml ~/.config/vikingbot/vke_deploy.yaml
```

--------------------------------

### LevelDB Get, Put, and Delete Operations

Source: https://github.com/volcengine/openviking/blob/main/third_party/leveldb-1.23/doc/index.md

Performs a Get, Put, and Delete operation on the LevelDB database. This example moves a value from one key to another.

```c++
std::string value;
leveldb::Status s = db->Get(leveldb::ReadOptions(), key1, &value);
if (s.ok()) s = db->Put(leveldb::WriteOptions(), key2, value);
if (s.ok()) s = db->Delete(leveldb::WriteOptions(), key1);
```

--------------------------------

### Dream Tasks Configuration Example

Source: https://github.com/volcengine/openviking/blob/main/docs/design/memory-link-design.md

An example configuration for 'dream_tasks', specifying input sources (entity, conflict) and their corresponding output memory types (report). This guides the T+1 batch processing for report generation.

```yaml
dream_tasks:
  - input:
      source: entity
      scope: 1-hop-neighbors
    output:
      memory_type: report
  - input:
      source: conflict
    output:
      memory_type: report
```

--------------------------------

### Initialize and Use OpenViking Client

Source: https://github.com/volcengine/openviking/blob/main/examples/k8s-helm/README.md

Demonstrates how to initialize the OpenViking client, add a resource, perform a search, and close the client connection.

```python
client = ov.OpenViking(url="http://<load-balancer-ip>:1933", api_key="your-key")
client.initialize()

# Add a resource
client.add_resource(path="./document.pdf")
client.wait_processed()

# Search
results = client.find("your search query")
print(results)

client.close()
```

--------------------------------

### Get Resource Relations

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/03-filesystem.md

Retrieve all relations associated with a given resource URI. This example fetches relations for the authentication documentation.

```python
relations = client.relations("viking://resources/docs/auth/")
for rel in relations:
    print(f"Related: {rel['uri']}")
    print(f"  Reason: {rel['reason']}")
```

--------------------------------

### Get Resource Relations (CLI)

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/03-filesystem.md

Use the CLI to retrieve relations for a specific resource. This example fetches relations for the authentication documentation.

```bash
openviking relations viking://resources/docs/auth/
```

--------------------------------

### Install spdlog (Compiled Version)

Source: https://github.com/volcengine/openviking/blob/main/third_party/spdlog-1.14.1/README.md

Instructions for cloning the spdlog repository, building it with CMake, and compiling.

```console
$ git clone https://github.com/gabime/spdlog.git
$ cd spdlog && mkdir build && cd build
$ cmake .. && make -j
```

--------------------------------

### Start Werewolf Demo with Configuration

Source: https://github.com/volcengine/openviking/blob/main/bot/demo/werewolf/README.md

Launches the Werewolf demo service with specified configuration. It automatically sets up necessary channels, working directories, and SOUL files, then starts the OpenViking server and UI service.

```bash
python start_werewolf_demo.py --config ~/.openviking/ov.conf
```

--------------------------------

### Get Resource Relations (HTTP API)

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/03-filesystem.md

Use the HTTP API to retrieve relations for a specific resource. This example fetches relations for the authentication documentation.

```bash
curl -X GET "http://localhost:1933/api/v1/relations?uri=viking://resources/docs/auth/" \
  -H "X-API-Key: your-key"
```

--------------------------------

### OpenViking Server Command Line Options

Source: https://github.com/volcengine/openviking/blob/main/docs/en/guides/03-deployment.md

Demonstrates starting the OpenViking server with default configuration, a custom port, or custom configuration file, host, and port.

```bash
openviking-server

openviking-server --port 8000

openviking-server --config /path/to/ov.conf --host 127.0.0.1 --port 8000
```

--------------------------------

### Example: Importing a Local Resource

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md

Demonstrates how to use the add-resource command to import a local file as a resource, specifying its destination URI and requesting a wait for completion.

```text
/add-resource ./README.md --to viking://resources/openviking-readme --wait
```

--------------------------------

### Start Claude Code

Source: https://github.com/volcengine/openviking/blob/main/examples/claude-code-memory-plugin/README.md

Launch Claude Code after installation. If the plugin does not appear to be active, set the `OPENVIKING_DEBUG` environment variable to `1` and check the log file for errors.

```bash
claude
```

--------------------------------

### Source Shell Configuration

Source: https://github.com/volcengine/openviking/blob/main/examples/codex-memory-plugin/README.md

After installation, source your shell's configuration file (e.g., .zshrc or .bashrc) to apply the changes. Then, run 'codex' to start using the plugin.

```bash
source ~/.zshrc   # or ~/.bashrc
codex             # first run: review /hooks once
```

--------------------------------

### Get npm Global Prefix

Source: https://github.com/volcengine/openviking/blob/main/docs/en/getting-started/05-cli-setup.md

If the `ov` command is not found after installation, check the npm global prefix directory. This helps in verifying if the binary directory is on your system's PATH.

```bash
npm prefix -g
```

--------------------------------

### Install Dependencies and Run Sampling

Source: https://github.com/volcengine/openviking/blob/main/benchmark/RAG/README.md

Installs project dependencies, activates the virtual environment, downloads datasets, and runs the sampling process for benchmark reproduction.

```bash
cd OpenViking/benchmark/RAG

# 1. Install dependencies (if not already installed)
uv pip install -e ".[benchmark]"
source .venv/bin/activate

# 2. Download all datasets
python scripts/download_dataset.py

# 3. Run one-click sampling for all datasets with the same parameters as the benchmark
python scripts/run_sampling.py
```

--------------------------------

### OpenViking Server Configuration Example

Source: https://github.com/volcengine/openviking/blob/main/bot/docs/rfc-openviking-cli-ov-chat.md

Example `ov.conf` file showing server and bot configurations, including agent settings, gateway details, and channel configurations.

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "root_api_key": "your-api-key",
    "with_bot": true,
    "bot_api_url": "http://localhost:18790"
  },
  "bot": {
    "agents": {
      "model": "openai/gpt-4o",
      "max_tool_iterations": 50,
      "memory_window": 50
    },
    "gateway": {
      "host": "127.0.0.1",
      "port": 18790,
      "token": ""
    },
    "channels": [
      {"type": "feishu", "enabled": false, "app_id": "", "app_secret": ""}
    ],
    "sandbox": {
      "backend": "direct",
      "mode": "shared"
    }
  }
}

```

--------------------------------

### Example API Documentation for add_resource()

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/99-api-doc-writing-guide.md

This is a complete example of API documentation for the `add_resource` method, detailing its implementation, parameters, and workflow.

```markdown
### add_resource()

#### 1. API Implementation Introduction

Add resources to the knowledge base, supporting various sources such as local files, directories, URLs, etc.

**Processing Workflow**:
1. Identify resource type (local file/directory/URL)
2. Call corresponding parser to parse content
3. Build directory tree and write to AGFS
4. Asynchronously generate L0/L1 semantic abstracts
5. Build vector index

**Code Entry**:
- `openviking/core/client.py:OpenViking.add_resource()` - SDK entry
- `openviking/resource/importer.py:ResourceImporter.import_resource()` - Core implementation
- `openviking/server/routers/resources.py` - HTTP router
- `openviking_cli/commands/resources.py` - CLI command

#### 2. Interface and Parameter Description

**Parameters**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| path | str | Yes | - | Local path, directory path, or URL |
| to | str | No | None | Target Viking URI (must be within the resources scope) |
| reason | str | No | "" | Reason for adding this resource |
| wait | bool | No | False | Whether to wait for semantic processing completion |

**Notes**

- SDK/CLI can directly pass local paths; raw HTTP requires `temp_upload` first
- When `to` is specified and the target already exists, an incremental update process is used

```

--------------------------------

### Quick Start: Deploy OpenViking on GCP or AWS

Source: https://github.com/volcengine/openviking/blob/main/examples/k8s-helm/README.md

Quickly install OpenViking on Kubernetes, specifying the cloud provider (GCP or AWS) and providing the necessary API key for embedding services.

```bash
# GCP deployment
helm install openviking ./openviking \
  --set cloudProvider=gcp \
  --set openviking.config.embedding.dense.api_key=YOUR_API_KEY

# AWS deployment
helm install openviking ./openviking \
  --set cloudProvider=aws \
  --set openviking.config.embedding.dense.api_key=YOUR_API_KEY
```

--------------------------------

### Run Tests Using Quick Script - Help

Source: https://github.com/volcengine/openviking/blob/main/tests/oc2ov_test/README.md

Display help information for the quick test run script.

```bash
./run.sh -h
```

--------------------------------

### Start Werewolf Demo with Optional Parameters

Source: https://github.com/volcengine/openviking/blob/main/bot/demo/werewolf/README.md

Starts the Werewolf demo with custom UI port, game mode, and smart button display enabled. Smart buttons dynamically adjust visibility based on game state.

```bash
python start_werewolf_demo.py \
  --config ~/.openviking/ov.conf \
  --ui-port 1995 \
  --game-mode all_agents \
  --smart-buttons
```

--------------------------------

### Setup Environment for VikingBot and tau2-bench

Source: https://github.com/volcengine/openviking/blob/main/benchmark/tau2/vikingbot/README.md

Source this script to set up the virtual environment, install dependencies, and export necessary runtime environment variables. Use --reinstall to rebuild the venv from scratch.

```bash
source benchmark/tau2/vikingbot/setup_env.sh              # first run: install, then activate + export
source benchmark/tau2/vikingbot/setup_env.sh --reinstall  # rebuild the .venv from scratch
```

--------------------------------

### Example: Importing a Local Skill

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md

Shows how to import a skill from a local file path, with the --wait flag to ensure the operation completes before proceeding.

```text
/add-skill ./skills/install-openviking-memory --wait
```

--------------------------------

### Example: Resource Import Response and Next Steps

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md

Provides an example of the expected response after importing a resource, including its URI, processing status, and a suggested search command.

```text
Imported OpenViking resource: viking://resources/openviking-readme
Processing: completed
Try: /ov-search "OpenViking install" --uri viking://resources/openviking-readme
```

--------------------------------

### Initialize and Check Open Viking Server

Source: https://github.com/volcengine/openviking/blob/main/README.md

Run these commands for the recommended first-time setup of the Open Viking server. The `init` command can optionally import existing Codex auth or start the Codex sign-in flow.

```bash
openviking-server init
openviking-server doctor
```

--------------------------------

### Get Specific Fields of a Pull Request via API

Source: https://github.com/volcengine/openviking/blob/main/bot/workspace/skills/github/SKILL.md

Access detailed information about a pull request using the `gh api` command. This example retrieves the title, state, and user login, filtering with `--jq`.

```bash
gh api repos/owner/repo/pulls/55 --jq '.title, .state, .user.login'
```

--------------------------------

### Vikingbot Configuration for Multi-User Management

Source: https://github.com/volcengine/openviking/blob/main/docs/en/concepts/11-multi-tenant.md

Example JSON configuration for the Vikingbot, using a root API key to manage multiple end-users within a specified account. This setup is suitable for a platform serving many chat users.

```json
{
  "bot": {
    "ov_server": {
      "server_url": "http://127.0.0.1:1933",
      "root_api_key": "test",
      "account_id": "default",
      "admin_user_id": "default"
    }
  }
}
```

--------------------------------

### Initialize Skill Script

Source: https://github.com/volcengine/openviking/blob/main/bot/workspace/skills/skill-creator/SKILL.md

Use this script to generate a new skill template. Specify the skill name, output directory, and desired resource types (scripts, references, assets). The `--examples` flag can be used to include placeholder example files.

```bash
scripts/init_skill.py <skill-name> --path <output-directory> [--resources scripts,references,assets] [--examples]
```

```bash
scripts/init_skill.py my-skill --path skills/public
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts,references
```

```bash
scripts/init_skill.py my-skill --path skills/public --resources scripts --examples
```

--------------------------------

### Setup TAU-2 Repository with Specific Ref

Source: https://github.com/volcengine/openviking/blob/main/benchmark/tau2/llm/README.md

Installs the TAU-2 repository using a specific Git reference (e.g., a pull request head) and sources the environment file. This is useful for reproducing results tied to specific changes.

```bash
benchmark/tau2/llm/scripts/setup_tau2_repo.sh \
  --ref refs/pull/297/head
source benchmark/tau2/llm/.env.tau2
```

--------------------------------

### Upload Local File and Create Skill (HTTP)

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/04-skills.md

This example demonstrates a two-step process: first, upload a local skill file (e.g., my-skill.json) using `temp_upload`, and then use the returned `temp_file_id` to create the skill. This is the recommended approach for handling local files.

```bash
TEMP_FILE_ID=$( \
  curl -s -X POST http://localhost:1933/api/v1/resources/temp_upload \
    -H "X-API-Key: your-key" \
    -F "file=@./skills/my-skill.json" \
  | jq -r '.result.temp_file_id'
)

curl -X POST http://localhost:1933/api/v1/skills \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d "{
    \"temp_file_id\": \"$TEMP_FILE_ID\"
  }"
```

--------------------------------

### Install uv package installer

Source: https://github.com/volcengine/openviking/blob/main/bot/README.md

Installs uv, a fast Python package installer, required for installing from source. Choose the command appropriate for your operating system.

```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Manual Installation: Install Local Plugin

Source: https://github.com/volcengine/openviking/blob/main/docs/images/agents/en/claude-code.md

After adding the plugin to the marketplace, use this command to install the 'claude-code-memory-plugin' from your local plugins. This is a step in the manual installation process.

```bash
claude plugin install claude-code-memory-plugin@openviking-plugins-local
```

--------------------------------

### Connect with Python SDK (Basic)

Source: https://github.com/volcengine/openviking/blob/main/docs/en/getting-started/03-quickstart-server.md

Initialize a synchronous HTTP client for OpenViking, pointing to the server URL.

```python
import openviking as ov

client = ov.SyncHTTPClient(url="http://localhost:1933")
```

--------------------------------

### Avoid Incorrect Installation

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/INSTALL-AGENT.md

This command installs an AgentSkill, not the OpenClaw plugin. Use the correct command for plugin installation.

```bash
clawhub install openviking
```

--------------------------------

### Install OpenViking CLI from Source

Source: https://github.com/volcengine/openviking/blob/main/crates/ov_cli/README.md

Installs the OpenViking CLI from source using Cargo. Ensure Rust is installed and up-to-date (>= 1.91.1).

```bash
# openviking need rust >= 1.91.1, please upgrade it if necessary
# brew upgrade rust
cargo install --path crates/ov_cli
```

--------------------------------

### Copy Example Configuration

Source: https://github.com/volcengine/openviking/blob/main/examples/cloud/GUIDE.md

Copies the example configuration file to be edited. This file is ignored by git.

```bash
cp examples/cloud/ov.conf.example examples/cloud/ov.conf
```

--------------------------------

### Build Examples

Source: https://github.com/volcengine/openviking/blob/main/third_party/spdlog-1.14.1/CMakeLists.txt

Conditionally builds the example targets if SPDLOG_BUILD_EXAMPLE, SPDLOG_BUILD_EXAMPLE_HO, or SPDLOG_BUILD_ALL is enabled. It also enables warnings for the example targets.

```cmake
if(SPDLOG_BUILD_EXAMPLE OR SPDLOG_BUILD_EXAMPLE_HO OR SPDLOG_BUILD_ALL)
    message(STATUS "Generating example(s)")
    add_subdirectory(example)
    spdlog_enable_warnings(example)
    if(SPDLOG_BUILD_EXAMPLE_HO)
        spdlog_enable_warnings(example_header_only)
    endif()
endif()
```

--------------------------------

### OpenViking Setup with Root API Key

Source: https://github.com/volcengine/openviking/blob/main/examples/openclaw-plugin/skills/install-openviking-memory/SKILL.md

When using a root API key, you need to provide both account ID and user ID. This command retries the setup with the necessary flags.

```bash
openclaw openviking setup --base-url BASE_URL --api-key API_KEY --account-id ACCOUNT_ID --user-id USER_ID --json
```

--------------------------------

### CLI Command for Overview

Source: https://github.com/volcengine/openviking/blob/main/docs/en/api/03-filesystem.md

Example of how to retrieve the overview of a directory using the OpenViking CLI.

```bash
openviking overview viking://resources/docs/
```

--------------------------------

### OpenViking Server Configuration Example

Source: https://github.com/volcengine/openviking/blob/main/bot/README.md

Example of how to configure the OpenViking server connection details within the `ov.conf` file. This includes host, port, and an optional `root_api_key` for enabling multi-tenant mode.

```json
{
  "server": {
    "host": "127.0.0.1",
    "port": 1933,
    "root_api_key": "test"
  }
}
```