VikingBot 安装与配置

VikingBot 是 OpenViking 内置的多渠道 AI Agent。它既可以和 OpenViking 一起启动，也可以在本地独立调试，或作为长期运行的 Gateway 接入聊天平台。

本指南介绍安装方式，以及三种主要使用场景的配置和启动方法。Agent 工具、聊天渠道、架构等完整说明请参见 VikingBot 中文文档。

安装

VikingBot 建议使用 Python 3.11 或更高版本。

从 PyPI 安装

pip install "openviking[bot]"

安装后检查版本：

vikingbot --version

从源码安装

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

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

Windows 使用以下命令激活虚拟环境：

.venv\Scripts\activate

配置文件

VikingBot 与 OpenViking 共用 ~/.openviking/ov.conf。如果配置文件位于其他路径，通过环境变量指定：

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

修改配置后，需要重启 VikingBot 或 OpenViking Server 才会生效。

选择使用场景

场景	适用情况	启动命令	OpenViking
A. OpenViking + Bot 一体启动	完整体验资源、记忆和 Agent	openviking-server --with-bot	使用当前启动的 Server
B. 本地调试 Agent	快速试用 Bot，开发 Tool 或 Skill	vikingbot chat	可选
C. Gateway 统一入口	长期运行、远程访问或接入聊天平台	vikingbot gateway	可连接已有 Server，也可 standalone 运行

三种场景是不同的运行入口，可以共用同一份 ov.conf。

场景 A：OpenViking + Bot 一体启动

这是本地完整体验的推荐方式。OpenViking Server 和 VikingBot Gateway 会一起启动：

ov chat → OpenViking Server → VikingBot Gateway → Agent

1. 配置 OpenViking

首次使用时运行初始化向导，并检查模型和存储配置：

openviking-server init
openviking-server doctor

详细配置见 OpenViking 配置指南。VikingBot 默认继承根级 vlm 作为 Agent 模型，因此通常不需要重复配置 bot.agents。

2. 一体启动

openviking-server --with-bot

在此模式下，Bot 固定连接当前启动的 OpenViking Server，不使用 bot.ov_server.server_url 指向其他服务。

3. 配置并使用 ov CLI

ov config
ov chat
ov chat -m "记住我更喜欢简洁的回答"
ov find "我的回答偏好"

ov config 中的 URL 应指向当前 OpenViking Server，默认是 http://127.0.0.1:1933。如果 Server 开启了鉴权，还需要配置当前调用者的 User/Admin API Key。

场景 B：本地调试 Agent

适合快速试用 VikingBot，或开发 Agent、Tool 和 Skill。vikingbot chat 会在当前进程中直接运行 Agent，不需要先启动 Gateway。

1. 配置 Agent 模型

如果 ov.conf 已经配置根级 vlm，VikingBot 会直接继承。也可以使用独立的 Agent 模型：

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

2. 启动对话

# 单次调用
vikingbot chat -m "帮我总结当前目录的项目结构"

# 交互式多轮对话
vikingbot chat

# 指定会话
vikingbot chat --session my-session

没有可用的 OpenViking Server 时，VikingBot 会以 standalone 方式运行。本地文件、Shell、Web 和 Skill 等能力仍可使用，但不会提供 OpenViking 资源检索和长期记忆能力。

场景 C：Gateway 统一入口

适合长期运行、远程访问和接入飞书、Slack、Telegram 等聊天平台。Gateway 提供 Bot HTTP API，也可以代理 OpenViking API，让 ov CLI 使用同一个入口。

1. 配置 Gateway 和 OpenViking

下面的示例让 Gateway 连接一个已有的 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": "<bot-openviking-user-api-key>"
    }
  }
}

Gateway 有三种 OpenViking 连接状态：

• 配置 bot.ov_server.server_url：连接指定的 OpenViking Server；连接失败时拒绝启动。
• 未配置该 URL，但同一份 ov.conf 配置了 server：继承该 Server 地址；不可用时降级为 standalone。
• 没有可用 Server：Chat 仍可使用，但 OpenViking 工具和 API 代理不可用。

2. 启动 Gateway

vikingbot gateway

3. 让 ov CLI 使用 Gateway

编辑 ~/.openviking/ovcli.conf：

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

随后 Chat 和 OpenViking 命令都可以通过 Gateway：

ov chat -m "检索项目资料并给出结论"
ov ls viking://resources/
ov find "项目发布流程"

Gateway 默认只监听 127.0.0.1。如果改为 0.0.0.0 或其他非 localhost 地址，必须配置 bot.gateway.token，并在客户端设置对应的 gateway_token。

聊天平台的凭证和权限配置见 VikingBot 渠道配置。

更多文档

• VikingBot 完整使用说明
• VikingBot 架构
• Agent 能力体系
• 渠道、Gateway 与运行管理
• VikingBot 与 OpenViking 集成
• 聊天渠道配置