VikingBot

VikingBot 是 OpenViking 内置的多渠道 AI Agent。它可以在命令行中直接使用，也可以作为长期运行的 Gateway 接入飞书、Slack、Telegram 等平台；连接 OpenViking 后，还能使用资源检索、用户记忆、经验记忆和会话沉淀能力。

主要能力

• 多入口对话：支持 vikingbot chat、ov chat、HTTP API 和多个聊天平台。
• Agent 工具：内置文件、Shell、Web、图片生成、定时任务和 OpenViking 工具。
• Skill 与子 Agent：按需加载 Skill，可使用后台子 Agent 处理独立任务。
• 长期上下文：从 OpenViking 召回 Resource、Peer Memory 和 Experience，并自动提交会话。
• 安全执行：支持 Direct、SRT、OpenSandbox 和 AIO Sandbox 后端。
• 服务化运行：Gateway 提供同步 Chat API、SSE 流式事件、反馈和 OpenViking API 代理。

安装

从 PyPI 安装

pip install "openviking[bot]"

从源码安装

需要 Python 3.11 或更高版本，并建议使用 uv：

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 有三种主要使用方式。它们不是互相替代的模式，而是面向不同需求的入口。

场景 A：OpenViking + Bot 一体启动

适合本地完整体验。OpenViking Server 和 VikingBot Gateway 一起启动，ov chat 先访问 OpenViking Server，再由 Server 的 /bot/v1 路由转发到 VikingBot。

ov chat → OpenViking Server → VikingBot Gateway → Agent

1. 准备配置

先按照 OpenViking 快速开始配置好 OpenViking 所需的模型和存储。Bot 默认继承根级 vlm 作为 Agent 模型；如需使用独立模型，再配置 bot.agents。

一体启动时，Bot 固定使用当前启动的 OpenViking Server，忽略 bot.ov_server 中指向其他服务的配置。OpenViking Server 会为每个 Chat 请求向 Bot 注入已经认证的 request-scoped 身份。

2. 一体启动

openviking-server --with-bot

该命令会启动当前 OpenViking Server，并启动一个受管的 VikingBot Gateway。此时 Bot 使用当前 Server，不会连接 bot.ov_server.server_url 指向的另一套服务。

3. 配置并使用 ov CLI

运行交互式配置：

ov config

让当前 CLI 配置指向 OpenViking Server，例如 http://127.0.0.1:1933；如果 Server 开启了鉴权，再填写调用者的 User/Admin API Key。然后：

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

这里的身份关系是：

• ovcli.conf.api_key 是当前调用者身份；
• OpenViking Server 校验该身份后，将 request-scoped 连接传给 Bot；
• 该请求身份优先于任何进程级默认身份，避免多个调用者共享同一个 Bot 用户。

场景 B：本地调试 Agent

适合快速试用 VikingBot，或者开发 Agent、Tool、Skill。vikingbot chat 在当前进程内启动 Agent，不需要先启动 Gateway，也不读取 ovcli.conf 作为 Bot 配置。

1. 配置模型

编辑 ~/.openviking/ov.conf：

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

也可以只配置根级 vlm，VikingBot 会继承其中的模型、Provider、API Key、API Base 和超时配置。

2. 开始对话

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

# 交互式多轮对话
vikingbot chat

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

没有可用 OpenViking Server 时，VikingBot 会以 standalone 方式运行：文件、Shell、Web、Skill 等能力仍可使用，但不会提供 OpenViking 记忆和文件工具。

如果希望调试时连接 OpenViking，可在同一个 ov.conf 中配置 server，或显式配置 bot.ov_server.server_url，参见连接 OpenViking。

场景 C：Gateway 统一入口

适合长期运行、远程访问和多渠道接入。ovcli.conf.url 可以直接指向 VikingBot Gateway：

ov chat                  → Gateway /bot/v1/chat
ov ls/find/session/...   → Gateway /api/v1/* → OpenViking Server

Gateway 与 OpenViking 有三种连接状态：

1. 配置 Gateway 和 OpenViking

下面是显式连接远端 OpenViking 的示例：

{
  "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>"
    }
  }
}

如果远端 OpenViking 使用 trusted 模式，应设置 api_key_type: "root"，并在 api_key 中填写 Root Key。

2. 启动 Gateway

vikingbot gateway

启动日志会显示 openviking_explicit、openviking_inherited 或 standalone_local 等实际状态。

3. 让 ov CLI 指向 Gateway

可以使用 ov config，也可以编辑 ~/.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 命令都使用同一个入口：

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

4. 对外监听时配置 Gateway Token

Gateway 默认只监听 127.0.0.1。改成 0.0.0.0 或其他非 localhost 地址时，必须配置 Token，否则拒绝启动：

{
  "bot": {
    "gateway": {
      "host": "0.0.0.0",
      "port": 18790,
      "token": "<strong-random-token>"
    }
  }
}

客户端在 ovcli.conf 中增加：

{
  "url": "https://bot.example.com",
  "api_key": "<caller-openviking-user-or-admin-api-key>",
  "gateway_token": "<strong-random-token>",
  "actor_peer_id": "cli"
}

Gateway Token 只保护 Gateway 入口；OpenViking API Key 表示调用者身份，两者不能互相替代。Gateway Token 不会转发给 OpenViking。

接入聊天平台

需要飞书、Slack、Telegram、Discord、WhatsApp、钉钉、QQ、Email 或 MoChat 时，在场景 C 的基础上配置 bot.channels，然后启动 Gateway。

以飞书为例：

{
  "bot": {
    "channels": [
      {
        "type": "feishu",
        "enabled": true,
        "app_id": "<feishu-app-id>",
        "app_secret": "<feishu-app-secret>",
        "allow_from": [],
        "ov_tools_enable": true
      }
    ]
  }
}

vikingbot gateway
vikingbot channels status

同一种渠道可以配置多个实例。VikingBot 使用 type + channel_id + chat_id 隔离会话和路由回复。各平台的凭证、事件订阅和权限配置见 渠道配置。

连接 OpenViking

VikingBot 与 OpenViking 共用 ~/.openviking/ov.conf。连接优先级和行为如下：

1. openviking-server --with-bot 启动的受管 Bot 使用当前 Server；
2. 普通 vikingbot gateway/chat 优先使用显式 bot.ov_server.server_url；
3. 没有显式 URL 时，从同一份 ov.conf.server 推导地址；
4. 没有可用地址时以 standalone 运行。

鉴权要求：

Gateway 会在启动时校验 upstream 和 Bot 凭证，并在每个请求中检查 OpenViking 当前鉴权模式。运行时模式发生变化时会 fail closed，要求修正配置或重启 Gateway。

VikingBot 使用 OpenViking 完成：

• 读取当前 Peer Profile；
• 按类型召回 events、entities 和 preferences；
• 检索 Agent Experience；
• 浏览、搜索和读取 Resource；
• 增量同步并提交 Session，提取长期记忆与经验。

详细调用链见 VikingBot 与 OpenViking 集成。Gateway 入口与鉴权边界来自 RFC #3042。

配置说明

配置文件默认为 ~/.openviking/ov.conf，可通过环境变量指定：

export OPENVIKING_CONFIG_FILE=/path/to/ov.conf

修改配置后需要重启 vikingbot gateway。

常用配置

OpenViking 召回配置

Workspace 与 Agent 定制

Workspace 是 VikingBot 的本地工作目录。它保存 Agent 启动指令、Skill、Heartbeat 任务以及文件和 Shell 工具操作的内容；OpenViking Workspace 则通过 openviking_* 工具访问 Resource、Memory 和 Skill，两者不是同一个目录。

找到当前 Workspace

Workspace 根目录由 storage.workspace 决定：

<storage.workspace>/bot/workspace

未配置 storage.workspace 时，默认为 ~/.openviking/data/bot/workspace。可以运行以下命令确认：

vikingbot status

Agent 实际使用的活动目录还取决于 bot.sandbox.mode：

例如，默认配置下应修改 ~/.openviking/data/bot/workspace/shared/SOUL.md。

定制 Agent

首次使用某个活动 Workspace 时，VikingBot 会从内置 bot/workspace 模板复制初始文件。常用定制入口如下：

例如，可以修改活动 Workspace 中的 SOUL.md：

# Soul

你是团队的研发助手。

- 默认使用中文回答
- 先给结论，再补充必要细节
- 修改代码前先确认现状，修改后运行相关验证
- 不确定时明确说明假设，不编造结果

保存后通常会在下一轮 Agent 对话中生效，无需重启 Gateway。SOUL.md 只能改变提示行为，不能绕过 Channel 权限、工具可见性或 Sandbox 限制。

[!NOTE] 请修改活动 Workspace 中的文件。仓库或安装包中的 bot/workspace 是初始化模板，不会覆盖已经存在的 Workspace。不要在启动文件中保存 API Key 等秘密。

完整加载顺序、文件职责和定制边界见 Agent 能力体系。

Agent 工具

内置工具

readonly 模式不会注册 openviking_add_resource。渠道设置 ov_tools_enable: false 时，该渠道不显示 OpenViking 工具，也不注入 Profile、Memory 和 Experience。

MCP 工具

第三方 MCP Server 配置在 bot.tools.mcp_servers：

{
  "bot": {
    "tools": {
      "mcp_servers": {
        "filesystem": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
          "tool_timeout": 30,
          "enabled_tools": ["*"]
        },
        "remote": {
          "type": "streamableHttp",
          "url": "https://example.com/mcp",
          "headers": {"Authorization": "Bearer $MCP_TOKEN"},
          "enabled_tools": ["search"]
        }
      }
    }
  }
}

支持 stdio、sse 和 streamableHttp。工具注册名为 mcp_<server>_<tool>；单个 MCP 连接失败不会阻断其他 Agent 能力。

沙箱

工作区模式支持：

• shared：所有会话共享工作区；
• per-session：每个 Session 独立；
• per-channel：同一渠道实例共享。

DirectBackend 默认 restrict_to_workspace: false。对不可信用户开放 Gateway 时，应选择隔离后端，并设置渠道白名单和网络/文件策略。

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

HTTP API

Gateway 的 Bot API 前缀为 /bot/v1：

配置 OpenViking upstream 后，/api/v1/* 会代理到 OpenViking Server。

运维命令

启用 Langfuse：

{
  "bot": {
    "langfuse": {
      "enabled": true,
      "secret_key": "<langfuse-secret-key>",
      "public_key": "<langfuse-public-key>",
      "base_url": "http://localhost:3000"
    }
  }
}

仓库内提供了 deploy/docker/deploy_langfuse.sh，可用于本地部署。

安全提示

• 不要把模型 API Key、OpenViking API Key 或 Gateway Token 提交到仓库。
• 非 localhost Gateway 必须配置高强度随机 Token，并在网络层启用 HTTPS。
• X-Gateway-Token 只保护 Gateway，不能代替 OpenViking 用户身份。
• allow_from: [] 表示不限制发送者；对外服务建议配置明确白名单。
• direct 后端会以 Bot 进程用户权限执行文件和 Shell 操作，不适合不可信调用者。
• openviking_connection 只能来自可信 Server 代理或本地可信链路，不应接受公网请求体自行声明。

更多文档

• VikingBot 架构
• Agent 能力体系
• 渠道、Gateway 与运行管理
• VikingBot 与 OpenViking 集成
• 渠道配置