VikingBot Installation and Configuration

For its role and architecture, read VikingBot, then use this page to install it.

VikingBot is the multi-channel AI Agent built into OpenViking. It can start together with OpenViking, run independently for local debugging, or operate as a long-running Gateway connected to chat platforms.

This guide covers installation and configuration for the three main usage scenarios. For complete documentation about Agent tools, chat channels, and architecture, see the VikingBot documentation.

Installation

Python 3.11 or later is recommended for VikingBot.

Install from PyPI

Choose your preferred Python package manager to install VikingBot:

uv (recommended)

uv tool install "openviking[bot]" --upgrade

pip

pip install "openviking[bot]" --upgrade

pipx

# Install
pipx install "openviking[bot]"

# Update
pipx upgrade openviking

Verify the installation:

vikingbot --version

Use a virtual environment for the pip option. Source installation also requires the development build dependencies.

Install from Source

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

uv venv --python 3.11
source .venv/bin/activate
uv pip install -e ".[bot]"

On Windows, activate the virtual environment with:

.venv\Scripts\activate

Configuration File

VikingBot and OpenViking share ~/.openviking/ov.conf. If the file is stored elsewhere, set:

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

Restart VikingBot or OpenViking Server after changing the configuration.

Choose a Usage Scenario

Scenario	Best for	Start command	OpenViking
A. Start OpenViking and the Bot together	Full experience with resources, memory, and the Agent	openviking-server --with-bot	Uses the Server being started
B. Debug the Agent locally	Trying the Bot or developing Tools and Skills	vikingbot chat	Optional
C. Use the Gateway as a unified entry point	Long-running service, remote access, or chat platforms	vikingbot gateway	Connects to an existing Server or runs standalone

The three scenarios are different runtime entry points and can share the same ov.conf.

Scenario A: Start OpenViking and the Bot Together

This is the recommended option for a complete local experience. OpenViking Server and VikingBot Gateway start together:

ov chat → OpenViking Server → VikingBot Gateway → Agent

1. Configure OpenViking

Run the initialization wizard, then validate the model and storage configuration:

openviking-server init
openviking-server doctor

See the OpenViking Configuration Guide for details. VikingBot inherits the root-level vlm as its Agent model by default, so you normally do not need to configure bot.agents again.

For an api_key server, register a User/Admin key and set it in bot.ov_server.api_key before starting the Bot; the root API key cannot serve as that user key. See Authentication. In inherited trusted mode the Bot uses the server’s trusted identity configuration.

2. Start Both Services

openviking-server --with-bot

In this mode, the Bot always connects to the OpenViking Server being started and does not use bot.ov_server.server_url to connect to another service.

3. Configure and Use the ov CLI

ov config
ov chat
ov chat -m "Remember that I prefer concise answers"
ov find "my response preference"

The URL configured by ov config should point to the current OpenViking Server, which defaults to http://127.0.0.1:1933. If authentication is enabled, also configure the current caller's User/Admin API Key.

Memory extraction runs asynchronously after a commit. An immediate ov find may return no result; check that the memory task completed before using retrieval as a persistence check.

Scenario B: Debug the Agent Locally

Use this scenario to try VikingBot quickly or develop Agents, Tools, and Skills. vikingbot chat runs the Agent directly in the current process, without starting the Gateway first.

1. Configure the Agent Model

If ov.conf already contains a root-level vlm, VikingBot inherits it. You can also configure a separate Agent model:

{
  "bot": {
    "agents": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key": "<your-model-api-key>",
      "max_tokens": 8192
    }
  }
}

The Bot can define its own ordered credentials failover chain. When every credential defines model, the outer bot.agents.model may be omitted:

{
  "bot": {
    "agents": {
      "max_tokens": 8192,
      "credentials": [
        {
          "id": "bot-primary",
          "provider": "volcengine",
          "model": "bot-primary-model",
          "api_key": "${BOT_PRIMARY_API_KEY}",
          "max_tokens": 4096
        },
        {
          "id": "bot-backup",
          "provider": "openai",
          "model": "bot-backup-model",
          "api_key": "${BOT_BACKUP_API_KEY}"
        }
      ],
      "failback_timeout_seconds": 600,
      "failback_request_count": 50
    }
  }
}

The precedence is deterministic: a non-empty bot.agents.model or bot.agents.credentials uses the Bot's own model/credentials. When both are omitted, VikingBot inherits the complete root vlm model, credentials, and failover/failback settings. If Bot credentials are configured without an outer model, every credential must define its own model. The two credential chains are never mixed. max_tokens is optional: a credential-specific value overrides bot.agents.max_tokens; a credential without one inherits the Agent value. When neither is configured, VikingBot omits the request field and lets the model provider choose its default.

2. Start a Chat

# Send one message
vikingbot chat -m "Summarize the structure of the current project"

# Start an interactive multi-turn conversation
vikingbot chat

# Use a specific session
vikingbot chat --session my-session

Without an explicit bot.ov_server.server_url, a connection failure to the inherited server allows standalone mode in local chat. An unavailable explicitly configured server stops startup. An inherited authentication-mode mismatch also stops startup; for an explicit server, Bot adopts the reported mode and validates the credentials. Authentication failures and unhealthy HTTP responses stop startup. In integrated server-managed startup, Bot keeps the inherited upstream while the server starts.

In standalone mode, local files, Shell, Web, and Skills remain available, but OpenViking resource retrieval and long-term memory are disabled.

Scenario C: Use the Gateway as a Unified Entry Point

Use this scenario for a long-running service, remote access, or chat platforms such as Feishu, Slack, and Telegram. The Gateway exposes the Bot HTTP API and can proxy OpenViking APIs, allowing the ov CLI to use one entry point.

1. Configure the Gateway and OpenViking

The following example connects the Gateway to an existing OpenViking Server:

{
  "bot": {
    "agents": {
      "provider": "openai",
      "model": "gpt-4o-mini",
      "api_key": "<your-model-api-key>"
    },
    "gateway": {
      "host": "127.0.0.1",
      "port": 18790
    },
    "ov_server": {
      "server_url": "https://openviking.example.com",
      "api_key_type": "user",
      "api_key": "<bot-openviking-user-api-key>"
    }
  }
}

The Gateway has three OpenViking connection states:

• When bot.ov_server.server_url is configured, it connects to that Server and refuses to start if the connection fails.
• When that URL is omitted but the same ov.conf contains server, the Gateway inherits that Server address and falls back to standalone mode if it is unavailable.
• When no Server is available, Chat still works, but OpenViking tools and API proxying are disabled.

2. Start the Gateway

vikingbot gateway

3. Point the ov CLI to the Gateway

Edit ~/.openviking/ovcli.conf:

{
  "url": "http://127.0.0.1:18790",
  "api_key": "<caller-openviking-user-or-admin-api-key>",
  "actor_peer_id": "cli"
}

Chat and OpenViking commands can then use the same Gateway:

ov chat -m "Retrieve the project information and give me a conclusion"
ov ls viking://resources/
ov find "project release process"

The Gateway listens on 127.0.0.1 by default. If you change it to 0.0.0.0 or another non-localhost address, configure bot.gateway.token and set the matching gateway_token on the client.

For credentials and permissions required by each chat platform, see VikingBot Channel Configuration.

Manage through Web Studio

Open Web Studio's /vikingbot page to chat on the web or manage Feishu connections for a Server-managed Bot. Connection management and Feishu history require ROOT access and are isolated by the account selected in Studio; an account ADMIN key is not sufficient. Studio calls GET /api/v1/admin/bot/capabilities and the connection, conversation, verification, and onboarding endpoints under /api/v1/admin/accounts/{account_id}/bot.

The Feishu QR setup has three steps:

1. Select a regular user in the same account as the connection's runtime identity. The server binds an available credential; the browser does not need that user's API key.
2. Scan the Feishu QR code to create the application, configure permissions/events, and submit it for publication. Existing applications can use manual credential setup instead.
3. Add the bot to a group and verify message receipt and reply. API acceptance of a reply does not prove that it is visible in the group; check the group as part of setup.

Connections and captured messages are stored in studio.sqlite3 under the Bot data directory with mode 0600. The database contains application and bound-user credentials, so handle its backups like server configuration. Studio-managed Feishu sessions use only the OpenViking query and memory tools allowed for the bound identity; shell, local-file, scheduling, and unapproved MCP tools are unavailable.

Pause stops the connection and keeps history. Deleting a connection removes its local records, not the Feishu application or messages in Feishu. Feishu history is read-only in Studio and starts with messages captured by that Studio connection; channels already configured in ov.conf and their old history are not migrated automatically. Resuming or restarting a connection preserves its context; deleting and recreating it creates a new context.

More Documentation

• Complete VikingBot documentation
• VikingBot Architecture
• Agent Capabilities
• Channels, Gateway, and Operations
• VikingBot and OpenViking Integration
• Chat Channel Configuration