OpenViking + OpenClaw PC部署指南

[MaojiaSheng]

—— 副标题：如何在办公电脑(MacOS)上低成本安全养虾

前置要求

1. 假设你已经在飞书开放平台（https://open.larkoffice.com/app）申请了自己的 Bot 应用，并且具备收发消息的权限了
2. 假设你已经在火山引擎获得了可用的 API KEY 能够正确调用豆包大模型
3. 假设你正在使用 Macbook 进行办公（我自己的配置是 M3 芯片）

方案介绍

本方案通过容器化实现稳定的 OpenClaw 和 OpenViking 部署，无论你的办公机在什么情况下运行，容器化方案都可以保证你的本地龙虾和上下文数据库能够持久、安全地运行。当然，你可以随时暂停和恢复你的服务。

部署流程

1. 我们先完成 OpenViking 的服务配置创建

容易踩的坑：

1. 忘记配置两处 api_key 导致模型不可用
2. 由于容器内地址监听要求为 0.0.0.0，因此需要配置好 root_api_key

pip install openviking

# vim ~/.openviking/ov.conf
{
  "server": {
    "host": "0.0.0.0",
    "port": 1933,
    "root_api_key": "123456"
  },
  "embedding": {
    "dense": {
        "model": "doubao-embedding-vision-250615",
        "api_key": "...",
        "api_base": "https://ark.cn-beijing.volces.com/api/v3",
        "dimension": 1024,
        "input": "multimodal",
        "provider": "volcengine"
    }
  },
  "vlm": {
    "model": "doubao-seed-2-0-code-preview-260215",
    "api_key": "...",
    "api_base": "https://ark.cn-beijing.volces.com/api/v3",
    "temperature": 0.0,
    "max_retries": 2,
    "provider": "volcengine",
    "thinking": false
  },
  "log": {
    "level": "INFO",
    "format": "%(asctime)s - %(name)s - %(levelname)s - %(message)s",
    "output": "stdout",
    "rotation": true,
    "rotation_days": 3,
    "rotation_interval": "midnight"
  }
}

2. 启动 OpenViking 容器

容易踩的坑：

1. colima template 没有详细配置，有问题可以查看 colima 官方文档或社区文档（如 https://blog.frognew.com/2025/03/macos-colima-docker.html）

brew install colima
brew install docker docker-compose

# 建议根据实际情况编辑配置资源：cpu, mem, disk, vmType=vz if use Apple M silicon
colima template

# 启动 colima
brew services start colima
colima start

# 注意要先配置好 OpenViking （~/.openviking/ov.conf）
# 拉取最新镜像并启动容器
docker run -d \
  --name openviking \
  -p 1933:1933 \
  -p 8020:8020 \
  -v ~/.openviking/ov.conf:/app/ov.conf \
  -v /var/lib/openviking/data:/app/data \
  --restart unless-stopped \
  ghcr.io/volcengine/openviking:latest

# 随时可以暂停和重启  
docker pause openviking
docker unpause openviking

# 查看服务日志
docker logs -f openviking

4. 由于我们启动的是多租户服务，因此需要先以管理员身份登录并创建一个普通用户

容易踩的坑：

1. 没有正确创建租户和密钥，导致使用 admin 身份使用数据库，带来更多风险
2. 没有正确安装 openviking 以至于没有获得 ov CLI

# vim ~/.openviking/ovcli.conf
{
  "url": "http://localhost:1933",
  "api_key": "123456"
}

ov admin register-user default shengmaojia
# 该命令会返回用户的新 apikey，假设为：f29eb21c588d12b9704d24846356b5709db2893addb37788bd3b48e9f4763089

# 然后我们可以以正常用户身份登录了
# vim ~/.openviking/ovcli.conf
{
  "url": "http://localhost:1933",
  "api_key": "f29eb21c588d12b9704d24846356b5709db2893addb37788bd3b48e9f4763089",
  "user": "shengmaojia",
  "account": "default",
  "agent_id": "smj-bot"
}

# 开始试用 CLI
# 本地需要先安装 OpenViking CLI: pip install openviking --upgrade --force-reinstall
ov ls

5. 在容器安装 OpenClaw https://docs.openclaw.ai/install/docker

容易踩的坑：

1. 没有正确创建租户和密钥，导致使用 admin 身份使用数据库，带来更多风险
2. 没有正确安装 openviking 以至于没有获得 ov CLI
3. Openclaw onboard 配置不正确，你可以重新 onboard 以修复，直到可以正确通过飞书与其对话

# 安装和部署容器
docker pull ghcr.io/openclaw/openclaw:2026.4.5-slim

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v /opt/openclaw/data:/app/data \
  --restart unless-stopped \
  --link openviking:openviking \
  ghcr.io/openclaw/openclaw:2026.4.5-slim
# 如果后续工作有错误，可以 docker stop openclaw, docker rm openclaw 然后重试


# 进入容器命令行，完成下面的配置工作!!!
docker exec -it openclaw bash

# 在容器内，查看是否能连通 openviking（我们使用了 --link 进行主机名链接）
curl openviking:1933/health

# 修复 openclaw logs 里面的 pairing 相关报错，这个命令可以学习下，以后也会用到，比如要通过 web console 访问时，需要再次为新的来源地址审批一下授权
openclaw devices list
openclaw devices approve <Request-id>

# 开始配置
openclaw onboard # 用快速模式配置好模型和飞书 channel即可
> 提示，选择手动模式
> 配置模型，建议只选在列的模型，火山的最新模型尚未更新到 openclaw 的默认列表中，请不要选择，我们这里选择了 GLM4.7
> 请选择 lan 模式 0.0.0.0:18789 作为服务端口

# 配置完成后容器会自动重启，因此需要重新进入，在容器外可以查看 docker top openclaw 看看 gateway 是否已经启动运行
# 接下来飞书给你的 bot 发一条消息，然后在【容器内】敲命令以配对成功
openclaw pairing approve feishu xxx

6. 为 OpenClaw 安装 OpenViking 插件并连接至 OpenViking 容器（地址为 openviking:1933）

容易踩的坑：

1. 安装 npm 失败，注意在容器里可以重新制定 npm 安装目录以避免文件系统权限问题
2. OpenViking 配置错误，注意：
3. 一定要选择 remote
4. OV 服务地址为 http://openviking:1933，因为我们在步骤4中已经将 OpenViking 容器的 hostname 通过 --link 参数注入给 OpenClaw 的容器了
5. OV 的 APIKEY 不是模型的密钥，而是 ~/.openviking/ovcli.conf 中的 api_key，来自步骤3

# 在容器中进行下列操作：(docker exec -it openclaw bash)
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
ov-install
# 注意在引导流程中填入 remote 模式，以及你已经测试过的 ov apikey, agent 等
# OpenViking server URL [http://127.0.0.1:1933]: http://openviking:1933
# 但好像 ov-install 不会生效，建议继续通过 config 设置
openclaw config get plugins.slots.contextEngine # 验证 OV 插件生效，显示 openviking 即可


openclaw config set plugins.entries.openviking.config.mode "remote"
openclaw config set plugins.entries.openviking.config.baseUrl "http://openviking:1933"
openclaw config set plugins.entries.openviking.config.apiKey "f29eb21c588d12b9704d24846356b5709db2893addb37788bd3b48e9f4763089" # 使用此前步骤获得的 ov apikey
openclaw config set plugins.entries.openviking.config.agentId "smj-claw"

openclaw gateway restart

ov-install 配置和安装完成后，你的龙虾应该就已经具备 OpenViking 赋予的记忆能力了

其他调试说明

• 查看容器实例状态：docker ps
• 查看龙虾日志的方法(在容器外)：docker logs -f openclaw
• 暂停/恢复容器：docker pause/unpause openclaw