OpenViking/bot

Vikingbot

Vikingbot, built on the Nanobot project, is designed to deliver an OpenClaw-like bot integrated with OpenViking.

✨ Core Features of OpenViking

Vikingbot is deeply integrated with OpenViking, providing powerful knowledge management and memory retrieval capabilities:

• Dual local/remote modes: Supports local storage (~/.openviking/data/) and remote server mode
• 7 dedicated Agent tools: Resource management, semantic search, regex search, glob search, memory search
• Three-level content access: L0 (summary), L1 (overview), L2 (full content)
• Automatic session memory submission: Conversation history is automatically saved to OpenViking
• Model configuration: Read from OpenViking configuration (vlm section), no need to set provider separately in bot configuration

📦 Install

Option 1: Install from PyPI (Simplest)

pip install "openviking[bot]"

Option 2: Install from source (for development)

Prerequisites

First, install uv (an extremely fast Python package installer):

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

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

Install from source (latest features, recommended for development)

git clone https://github.com/volcengine/OpenViking
cd OpenViking

# Create a virtual environment using Python 3.11 or higher
uv venv --python 3.11

# Activate environment
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

# Install dependencies (minimal)
uv pip install -e ".[bot]"

# Or install with optional features
uv pip install -e ".[bot,bot-langfuse,bot-telegram]"

Optional Dependencies

Install only the features you need:

Feature Group	Install Command	Description
Full	uv pip install -e ".[bot-full]"	All features included
Langfuse	uv pip install -e ".[bot-langfuse]"	LLM observability and tracing
FUSE	uv pip install -e ".[bot-fuse]"	OpenViking filesystem mount
Sandbox	uv pip install -e ".[bot-sandbox]"	Code execution sandbox
OpenCode	uv pip install -e ".[bot-opencode]"	OpenCode AI integration

Channels (chat apps)

Channel	Install Command
Telegram	uv pip install -e ".[bot-telegram]"
Feishu/Lark	uv pip install -e ".[bot-feishu]"
DingTalk	uv pip install -e ".[bot-dingtalk]"
Slack	uv pip install -e ".[bot-slack]"
QQ	uv pip install -e ".[bot-qq]"

Multiple features can be combined:

uv pip install -e ".[bot,bot-langfuse,bot-telegram]"

🚀 Quick Start

Tip

Configure vikingbot through the configuration file ~/.openviking/ov.conf! Get API keys: OpenRouter (Global) · Brave Search (optional, for web search)

1. Initialize configuration

openviking-server --with-bot

This will automatically:

• Create a default config at ~/.openviking/ov.conf
• Create bot startup files in the OpenViking workspace, default path is ~/.openviking/data/bot/
• Start the OpenViking server with bot integration

2. Configure via ov.conf

Edit ~/.openviking/ov.conf to add your provider API keys (OpenRouter, OpenAI, etc.) and save the config.

3. Chat

# Send a single message directly
ov chat -m "What is 2+2?"

# Enter interactive chat mode (supports multi-turn conversations)
ov chat

# Show plain-text replies (no Markdown rendering)
ov chat --no-format

That's it! You have a working AI assistant in 2 minutes.

Talk to your vikingbot through Telegram, Discord, WhatsApp, Feishu, Mochat, DingTalk, Slack, Email, or QQ — anytime, anywhere.

For detailed configuration, please refer to CHANNEL.md.

🌐 Agent Social Network

🐈 vikingbot is capable of linking to the agent social network (agent community). Just send one message and your vikingbot joins automatically!

Platform	How to Join (send this message to your bot)
Moltbook	Read https://moltbook.com/skill.md and follow the instructions to join Moltbook
ClawdChat	Read https://clawdchat.ai/skill.md and follow the instructions to join ClawdChat

Simply send the command above to your vikingbot (via CLI or any chat channel), and it will handle the rest.

⚙️ Configuration

Config file: ~/.openviking/ov.conf (custom path can be set via environment variable OPENVIKING_CONFIG_FILE)

Tip

Vikingbot shares the same configuration file with OpenViking. Configuration items are located under the bot field of the file, and will automatically merge global configurations such as vlm, storage, server, etc. No need to maintain a separate configuration file.

Important

After modifying the configuration (by editing the file directly), you need to restart the gateway service for changes to take effect.

OpenViking Server Configuration

The bot will connect to the remote OpenViking server. Please start the OpenViking Server before use. By default, the OpenViking server information configured in ov.conf is used

• OpenViking default startup address is 127.0.0.1:1933
• Vikingbot follows OpenViking server.auth_mode: api_key mode uses an OpenViking User API key; trusted mode uses server.root_api_key plus trusted identity headers; dev mode is local-only.
• OpenViking Server configuration example

{
  "server": {
    "auth_mode": "api_key",
    "host": "127.0.0.1",
    "port": 1933,
    "root_api_key": "<your-openviking-root-api-key>"
  },
  "bot": {
    "ov_server": {
      "api_key": "<your-openviking-user-api-key>"
    }
  }
}

Bot Configuration

All configurations are under the bot field in ov.conf, with default values for configuration items. The optional manual configuration items are described as follows:

• agents: Agent configuration
  • model: LLM model name used by the bot. When provider is set, use the provider-native model name (for example doubao-seed-2-0-pro-260215).
  • temperature: Sampling temperature for LLM requests. Defaults to 0.7.
  • thinking: Enable provider reasoning/thinking mode for bot LLM requests when the selected provider protocol supports an explicit thinking parameter. Defaults to true; set to false to disable (for example to reduce latency/cost or for models where reasoning params are unsupported). Applied per provider — VolcEngine thinking={"type": "enabled"}, DashScope extra_body.enable_thinking=true, and OpenAI reasoning models reasoning_effort.
  • timeout: Per-request timeout in seconds for fetching chat results from the model provider. Inherits vlm.timeout when omitted (default 60.0).
  • provider: Optional model provider name. When set, vikingbot uses OpenViking's VLMFactory + adapter path to create the backend directly (for example volcengine, openai, deepseek).
  • api_key: Optional API key for the agent model provider. Can be configured here directly when you want bot-specific credentials.
  • api_base: Optional API base for the agent model provider. Useful for provider gateways or custom endpoints such as VolcEngine Ark.
  • extra_headers: Optional extra HTTP headers passed to the model provider.
  • max_tool_iterations: Maximum number of cycles for a single round of conversation tasks, returns results directly if exceeded
  • memory_window: Upper limit of conversation rounds for automatically submitting sessions to OpenViking
  • gen_image_model: Model for generating images
• gateway: Gateway configuration
  • host: Gateway listening address, default value is 0.0.0.0
  • port: Gateway listening port, default value is 18790
  • token: Gateway authentication token. Required when host is non-localhost (such as the default 0.0.0.0) — the gateway refuses to start without it (SECURITY: bot.gateway.token is required when gateway.host is non-localhost). Set a random secret; clients then send it in the X-Gateway-Token header.
• sandbox: Sandbox configuration
  • mode: Sandbox mode, optional values are shared (all sessions share workspace) or private (private, workspace isolated by Channel and session). Default value is shared.
• ov_server: OpenViking Server configuration.
  • If not configured, the OpenViking server information configured in ov.conf is used by default
  • If you use a remote OpenViking Server, configure the target service URL and API key here
    • server_url: OpenViking server base URL, for example https://api.vikingdb.cn-beijing.volces.com/openviking or http://localhost:1933.
    • api_key: API key used by the bot when calling the OpenViking server. In api_key mode, this must be an OpenViking User key; in trusted mode with api_key_type: "root", this is the OpenViking root key.
    • root_api_key: Deprecated compatibility field. Do not use it for new configs; use api_key with api_key_type: "root" for trusted mode.
    • account_id: Defaults to default, which is the OpenViking account ID. All users under the same OpenViking account share resources.
    • api_key_type: Defaults from the OpenViking server.auth_mode in the same ov.conf: user for api_key/dev, root for trusted. Manual configuration is usually unnecessary. If bot.ov_server points to another OpenViking server and that server uses trusted auth, set api_key_type: "root" and provide its root key in api_key.
    • exp_write_tools: Optional list of tool names that trigger experience-memory injection before the call (self-evolving agent memory loop, see #2007). Defaults to ["write_file", "edit_file"]. This only controls the bot-side injection trigger; stored experience generation is governed by OpenViking memory extraction and the active session memory_policy.memory_types whitelist.
    • recall_exp_first_round_only: Optional. When true, ContextBuilder._build_user_memory skips per-turn user/agent experience recall and injects experiences only once on the first user turn. Defaults to false.
    • Per-turn user/peer memory recall uses type-quota search by default. profile.md is injected through the profile path and does not occupy auto-search candidates.
    • memory_recall_events_limit: Optional. Number of events/ memories retrieved per turn. Defaults to 10.
    • memory_recall_entities_limit: Optional. Number of entities/ memories retrieved per turn. Defaults to 10.
    • memory_recall_preferences_limit: Optional. Number of preferences/ memories retrieved per turn. Defaults to 3.
    • memory_recall_max_chars: Optional. Character budget for injected user/peer full memories. Defaults to 4000.
    • exp_recall_limit: Optional. Number of experiences to retrieve per task during recall. Defaults to 5.
    • exp_recall_max_chars: Optional. Character budget for the formatted experience block injected into context. Defaults to 2000.
• channels: Message platform configuration, see Message Platform Configuration for details

{
  "bot": {
    "agents": {
      "model": "doubao-seed-2-0-pro-260215",
      "api_key": "<your-ark-api-key>",
      "api_base": "https://ark.cn-beijing.volces.com/api/v3",
      "provider": "volcengine",
      "temperature": 0.7,
      "thinking": true,
      "timeout": 60.0,
      "max_tool_iterations": 50,
      "memory_window": 50
    },
    "gateway": {
      "host": "0.0.0.0",
      "port": 18790,
      "token": "<set-a-random-gateway-token>"
    },
    "sandbox": {
      "mode": "shared"
    },
    "ov_server": {
      "server_url": "https://api.vikingdb.cn-beijing.volces.com/openviking",
      "api_key": "<your-openviking-user-api-key>",
      "account_id": "default"
    },
    "channels": [
      {
        "type": "feishu",
        "enabled": true,
        "ov_tools_enable": true,
        "appId": "<your-feishu-app-id>",
        "appSecret": "<your-feishu-app-secret>",
        "allowFrom": []
      }
    ]
  }
}

If you only want to try the bot through vikingbot gateway or vikingbot chat, you can set channels to an empty list ([]).

With the configuration above, you can try the bot directly, or configure Feishu at the same time:

# Start the HTTP gateway
vikingbot gateway

# Or chat with the bot directly in CLI
vikingbot chat
vikingbot chat -m "Hello"

OpenViking Agent Tools

Vikingbot provides 7 dedicated OpenViking tools:

Tool Name	Description
openviking_read	Read OpenViking resources (supports three levels: abstract/overview/read)
openviking_list	List OpenViking resources
openviking_search	Semantic search OpenViking resources
openviking_add_resource	Add local files as OpenViking resources
openviking_grep	Search OpenViking resources using regular expressions
openviking_glob	Match OpenViking resources using glob patterns
openviking_memory_commit	Commit session to ov

External MCP Servers

Vikingbot can also consume tools from third-party MCP (Model Context Protocol) servers (filesystem, GitHub, browsers, databases, etc.). Configure servers under tools.mcp_servers in ov.conf; each server's tools are registered when the agent starts and appear as mcp_<server>_<tool>.

{
  "bot": {
    "tools": {
      "mcp_servers": {
        "filesystem": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
          "env": {},
          "tool_timeout": 30,
          "enabled_tools": ["*"]
        },
        "github": {
          "type": "streamableHttp",
          "url": "https://api.githubcopilot.com/mcp/",
          "headers": {"Authorization": "Bearer $GITHUB_TOKEN"},
          "enabled_tools": ["search_repositories", "create_issue"]
        }
      }
    }
  }
}

Field	Description
type	Transport: stdio / sse / streamableHttp. Auto-detected when omitted (stdio if command is set, otherwise HTTP from url).
command	(stdio) Command to launch the server process (e.g. npx, uvx).
args	(stdio) Command arguments.
env	(stdio) Extra environment variables for the spawned server.
url	(sse / streamableHttp) Endpoint URL.
headers	(sse / streamableHttp) Custom request headers (e.g. Authorization).
tool_timeout	Per-call timeout in seconds (default 30).
enabled_tools	Tool allowlist. Accepts raw MCP names or wrapped mcp_<server>_<tool> names; ["*"] exposes every tool.

MCP servers are connected when the agent loop starts and closed automatically on shutdown. If a server has neither command nor url, it is skipped with a warning. Connection failures are logged and the bot continues without that server's tools.

OpenViking Hooks

Vikingbot enables OpenViking hooks by default:

{
  "hooks": ["vikingbot.hooks.builtins.openviking_hooks.hooks"]
}

Hook	Function
OpenVikingCompactHook	Automatically submit session messages to OpenViking
OpenVikingPostCallHook	Post tool call hook (for testing purposes)

Manual Configuration (Advanced)

Edit the config file directly:

{
  "bot": {
    "agents": {
      "model": "openai/doubao-seed-2-0-pro-260215"
    }
  }
}

Provider configuration is read from OpenViking config (vlm section in ov.conf).

Providers

Tip

• Groq provides free voice transcription via Whisper. If configured, Telegram voice messages will be automatically transcribed.
• Zhipu Coding Plan: If you're on Zhipu's coding plan, set "apiBase": "https://open.bigmodel.cn/api/coding/paas/v4" in your zhipu provider config.
• MiniMax (Mainland China): If your API key is from MiniMax's mainland China platform (minimaxi.com), set "apiBase": "https://api.minimaxi.com/v1" in your minimax provider config.
• MiniMax Recommended Models: MiniMax-M3 (flagship, default), MiniMax-M2.7 (peak performance) and MiniMax-M2.7-highspeed (faster, more agile). Configure with "model": "MiniMax-M3" in your agent config.

Provider	Purpose	Get API Key
openrouter	LLM (recommended, access to all models)	openrouter.ai
anthropic	LLM (Claude direct)	console.anthropic.com
openai	LLM (GPT direct)	platform.openai.com
deepseek	LLM (DeepSeek direct)	platform.deepseek.com
groq	LLM + Voice transcription (Whisper)	console.groq.com
gemini	LLM (Gemini direct)	aistudio.google.com
minimax	LLM (MiniMax direct)	platform.minimax.io
aihubmix	LLM (API gateway, access to all models)	aihubmix.com
dashscope	LLM (Qwen)	dashscope.console.aliyun.com
moonshot	LLM (Moonshot/Kimi)	platform.moonshot.cn
zhipu	LLM (Zhipu GLM)	open.bigmodel.cn
vllm	LLM (local, any OpenAI-compatible server)	—

Adding a New Provider (Developer Guide)

vikingbot uses a Provider Registry (vikingbot/providers/registry.py) as the single source of truth. Adding a new provider only takes 2 steps — no if-elif chains to touch.

Step 1. Add a ProviderSpec entry to PROVIDERS in vikingbot/providers/registry.py:

ProviderSpec(
    name="myprovider",                   # config field name
    keywords=("myprovider", "mymodel"),  # model-name keywords for auto-matching
    env_key="MYPROVIDER_API_KEY",        # env var for LiteLLM
    display_name="My Provider",          # shown in `vikingbot status`
    litellm_prefix="myprovider",         # auto-prefix: model → myprovider/model
    skip_prefixes=("myprovider/",),      # don't double-prefix
)

Step 2. Add a field to ProvidersConfig in vikingbot/config/schema.py:

class ProvidersConfig(BaseModel):
    ...
    myprovider: ProviderConfig = ProviderConfig()

That's it! Environment variables, model prefixing, config matching, and vikingbot status display will all work automatically.

Common ProviderSpec options:

Field	Description	Example
litellm_prefix	Auto-prefix model names for LiteLLM	"dashscope" → dashscope/qwen-max
skip_prefixes	Don't prefix if model already starts with these	("dashscope/", "openrouter/")
env_extras	Additional env vars to set	(("ZHIPUAI_API_KEY", "{api_key}"),)
model_overrides	Per-model parameter overrides	(("kimi-k2.5", {"temperature": 1.0}),)
is_gateway	Can route any model (like OpenRouter)	True
detect_by_key_prefix	Detect gateway by API key prefix	"sk-or-"
detect_by_base_keyword	Detect gateway by API base URL	"openrouter"
strip_model_prefix	Strip existing prefix before re-prefixing	True (for AiHubMix)

Security

Option	Default	Description
tools.restrictToWorkspace	true	When true, restricts all agent tools (shell, file read/write/edit, list) to the workspace directory. Prevents path traversal and out-of-scope access.
channels.*.allowFrom	[] (allow all)	Whitelist of user IDs. Empty = allow everyone; non-empty = only listed users can interact.
channels.*.ov_tools_enable	true	When false, disables OpenViking tools (openviking_*) and skips memory / user-profile context injection for this channel. Useful for lightweight channels that should not pull from OV memory. See #1352.

Observability (Optional)

Langfuse integration for LLM observability and tracing.

Langfuse Configuration

Option 1: Local Deployment (Recommended for testing)

Deploy Langfuse locally using Docker:

# Navigate to the deployment script
cd deploy/docker

# Run the deployment script
./deploy_langfuse.sh

This will start Langfuse locally at http://localhost:3000 with pre-configured credentials.

Option 2: Langfuse Cloud

1. Sign up at langfuse.com
2. Create a new project
3. Copy the Secret Key and Public Key from project settings

Configuration

Add to ~/.openviking/ov.conf:

{
  "bot": {
    "langfuse": {
      "enabled": true,
      "secret_key": "sk-lf-vikingbot-secret-key-2026",
      "public_key": "pk-lf-vikingbot-public-key-2026",
      "base_url": "http://localhost:3000"
    }
  }
}

For Langfuse Cloud, use https://cloud.langfuse.com as the base_url.

Install Langfuse support:

uv pip install -e ".[bot-langfuse]"

Restart vikingbot:

vikingbot gateway

Features enabled:

• Automatic trace creation for each conversation
• Session and user tracking
• LLM call monitoring
• Token usage tracking
• Feedback observability design: bot/docs/vikingbot-feedback-observability-design.md

Sandbox

vikingbot supports sandboxed execution for enhanced security.

By default, no sandbox configuration is needed in ov.conf:

• Default backend: direct (runs code directly on host)
• Default mode: shared (single sandbox shared across all sessions)

You only need to add sandbox configuration when you want to change these defaults.

Sandbox Configuration Options

To use a different backend or mode:

{
  "bot": {
    "sandbox": {
      "backend": "srt",
      "mode": "per-session"
    }
  }
}

Available Backends:

Backend	Description
direct	(Default) Runs code directly on the host
srt	Uses Anthropic's SRT sandbox runtime

Available Modes:

Mode	Description
shared	(Default) Single sandbox shared across all sessions
per-session	Separate sandbox instance for each session

Backend-specific Configuration (only needed when using that backend):

Direct Backend:

{
  "bot": {
    "sandbox": {
      "backends": {
        "direct": {
          "restrictToWorkspace": false
        }
      }
    }
  }
}

SRT Backend:

{
  "bot": {
    "sandbox": {
      "backend": "srt",
      "backends": {
        "srt": {
          "nodePath": "node",
          "network": {
            "allowedDomains": [],
            "deniedDomains": [],
            "allowLocalBinding": false
          },
          "filesystem": {
            "denyRead": [],
            "allowWrite": [],
            "denyWrite": []
          },
          "runtime": {
            "cleanupOnExit": true,
            "timeout": 300
          }
        }
      }
    }
  }
}

SRT Backend Setup:

The SRT backend uses @anthropic-ai/sandbox-runtime.

System Dependencies:

The SRT backend also requires these system packages to be installed:

• ripgrep (rg) - for text search
• bubblewrap (bwrap) - for sandbox isolation
• socat - for network proxy

Install on macOS:

brew install ripgrep bubblewrap socat

Install on Ubuntu/Debian:

sudo apt-get install -y ripgrep bubblewrap socat

Install on Fedora/CentOS:

sudo dnf install -y ripgrep bubblewrap socat

To verify installation:

npm list -g @anthropic-ai/sandbox-runtime

If not installed, install it manually:

npm install -g @anthropic-ai/sandbox-runtime

Node.js Path Configuration:

If node command is not found in PATH, specify the full path in your config:

{
  "bot": {
    "sandbox": {
      "backends": {
        "srt": {
          "nodePath": "/usr/local/bin/node"
        }
      }
    }
  }
}

To find your Node.js path:

which node
# or
which nodejs

CLI Reference

Command	Description
ov chat -m "..."	Send a single message to the agent
ov chat	Interactive chat mode
ov chat --no-format	Show plain-text replies (no Markdown)