Skip to content

openclaw-quickstart.md

Latest commit

 

History

History
415 lines (291 loc) · 18.6 KB

openclaw-quickstart.md

File metadata and controls

415 lines (291 loc) · 18.6 KB
Raw

OpenClaw / Hermes / WorkBuddy Agent Bridge 接入指南

给 Agent 宿主和维护者的完整落地说明：怎么部署 OpenBiliClaw、怎么初始化、怎么协商当前能力、以及日常怎么用。OpenClaw 是兼容入口名，协议本身是 host-neutral。

适用场景

当你希望 OpenClaw、Hermes、WorkBuddy 或其他本地 Agent 宿主直接调用 OpenBiliClaw 的学习与推荐能力时，使用这份指南。

当前接入方式不是 Python SDK 注册，而是：

  1. 仓库根目录提供 workspace skill：skills/openbiliclaw-adapter/SKILL.md
  2. skill 通过 JSON CLI bridge 调用：src/openbiliclaw/integrations/openclaw/cli.py
  3. CLI bridge 再调用协议中立的 Agent adapter operation；src/openbiliclaw/integrations/agent.py 提供 Python 别名

部署策略

推荐按目标机器能力决定：

  1. 目标机器有 Docker：优先 Docker 部署
  2. 目标机器没有 Docker：退回本地 Python 部署

这个判断很直接，因为 Agent 宿主最终只需要两件事：

  1. 能发现仓库里的 workspace skill
  2. 能执行 skill 要求的命令

前置条件

  • 已克隆当前仓库
  • 目标机器可用 Python 3.11+
  • 可以访问当前配置所需的 LLM provider
  • B 站登录态：v0.3.12+ 推荐装浏览器扩展自动同步（下载），不再需要 F12 贴 Cookie。也可以用交互式终端现场粘
  • 小红书 / 抖音 / YouTube 登录态：只有在你明确选择把这些源加入初始化画像或 discovery 时需要；后端不代爬账号，依赖同一个浏览器扩展里的登录会话执行任务
  • 如果走 Docker 路径，目标机器上还需要可用的 Docker / Docker Compose

方案 A：Docker 优先

这是推荐方案，适合长期运行 OpenBiliClaw 后端。

1. 启动后端容器

在仓库根目录执行：

docker compose up -d --build

当前 compose 定义见：

  • docker-compose.yml
  • Dockerfile

默认行为：

  • 容器名：openbiliclaw-backend
  • 对外端口：8420
  • 运行时目录：/app/runtime
  • 配置、数据、日志分别持久化在 Docker volumes 中

2. 完成首次初始化

推荐用 bootstrap 继续走自动 init 流程，而不是让用户手动记一条 docker exec 命令：

python3 scripts/agent_bootstrap.py --mode docker --interactive-confirm --wait-for-extension-cookie

它会启动 / 复用 Docker Compose、向用户确认 LLM / embedding / B 站 Cookie / 小红书 / 抖音 / YouTube 选择，并在确认齐全后自动运行 init。docker exec -it openbiliclaw-backend openbiliclaw init 只作为高级手动 fallback。

⏱ 首次运行预计 2–5 分钟。LLM 单次响应可能就要 10–30s，全程会打印进度，不要以为卡住了。

init 是 v0.3.27+ 的交互式向导，自动检测 config.toml 缺哪些字段并按需补齐。每一步都有"不确定就回 1"的默认值：

  1. Phase 1 — LLM 服务选择(7 项菜单): DeepSeek 第一推荐,中转站 / OpenAI 协议兼容第二推荐。每项标注 2026-05 当前默认模型:
    • 1) DeepSeek 官方 ★默认推荐 —— 默认 deepseek-v4-flash(可选 deepseek-v4-pro;旧 deepseek-chat / deepseek-reasoner 将于 2026/07/24 弃用)/ ¥0.001/千 token / 国内可直连。最便宜 + 最容易,新人无脑选这个
    • ★ 2) 中转站 / OpenAI 协议兼容服务 ★第二推荐 —— 国内用户买中转站 / OneAPI Key 走这个。也覆盖 Kimi / 通义 / 智谱 / 商汤日日新 / Yi / MiniMax 官方 + Azure / vLLM / LMStudio。选这个进子菜单(10 个 preset):
      • ★ a) 中转站 / OneAPI / 公司团队 LLM 网关(大多数人选这个) —— Base URL 自填 / 默认 gpt-5-nano;按你充值的中转站给的模型清单填
      • b) Kimi (Moonshot AI) 官方 —— https://api.moonshot.ai/v1 / 默认 kimi-k2.6。⚠ 旧 K2-series 2026/05/25 停服
      • c) MiniMax 官方 —— https://api.minimax.io/v1 / 默认 MiniMax-M2.7(4/2026)
      • d) 通义千问 (阿里 DashScope) 官方 —— https://dashscope.aliyuncs.com/compatible-mode/v1 / 默认 qwen-plus
      • e) 智谱 ChatGLM 官方 —— https://open.bigmodel.cn/api/paas/v4 / 默认 glm-4.7-flash(免费档);旗舰 glm-5
      • f) 商汤日日新 (SenseNova) 官方 —— https://token.sensenova.cn/v1 / 默认 deepseek-v4-flash(已实测连通)。新用户免费额度，零成本体验(issue #193);embedding 未验证，Phase 3 默认独立 Ollama bge-m3
      • g) 零一万物 (Yi) 官方 —— https://api.lingyiwanwu.com/v1 / 默认 yi-medium
      • h) Azure OpenAI —— https://YOUR-RESOURCE.openai.azure.com/openai/deployments/YOUR-DEP
      • i) 自建 vLLM / LMStudio / Ollama 网关 —— http://localhost:8000/v1 / 模型 HuggingFace 路径,强制手填
      • j) 其它(完全手填) —— escape hatch
    • 3) OpenAI 官方 —— 默认 gpt-5-nano(最便宜的 GPT-5);可选 gpt-5.4-nano / gpt-5.4-mini / gpt-5.5(旗舰) / gpt-5.5-pro
    • 4) Gemini 官方 —— 默认 gemini-2.5-flash(稳定);免费档每天 1500 次。可选 gemini-3-flash-preview / gemini-3.1-pro-preview(旗舰,Public Preview,需付费项目) / gemini-3.1-flash-lite-preview(最便宜)
    • 5) Claude 官方 —— 默认 claude-sonnet-4-6(1M ctx),按 token 付费,质量高。可选 claude-haiku-4-5(便宜) / claude-opus-4-7(旗舰)
    • 6) OpenRouter 聚合 —— 默认 openai/gpt-5-nano;格式 <vendor>/<model>(如 anthropic/claude-sonnet-4-6 / google/gemini-2.5-flash)
    • 7) OrcaRouter 聚合 —— 默认 openai/gpt-4o;格式 <vendor>/<model>。一个 Key 跑 150+ 模型,网关级零信任安全
    • 本地 Ollama（完全离线,不在交互菜单里） —— 默认 qwen2.5:7b(中文好);可选 llama3.2 / gemma2 / mistral / deepseek-r1。无 Key / 16GB+ 内存。需要时用 --provider ollama 显式选择或到桌面设置页配置
  2. Phase 2 — 给所选服务填配置：每个选项只问该选项需要的字段。所有 provider 在 prompt 模型名前都会显示一行"可选/常见模型"提示(DeepSeek 列 v4-flash / v4-pro,OpenAI 列 gpt-4o-mini / gpt-4o / gpt-4-turbo,Gemini / Claude / Ollama 同样,OpenAI 协议兼容子菜单见上 10 个 preset),用户主动确认而不是回车跳过一个不知道是啥的字符串。Ollama 不问 Key(自动装 + 拉模型);自建网关 / 其它路径强制手填模型名(写错会 404)。
  3. Phase 3 — Embedding（向量化，3 选 1 + 高级）：默认推荐 本地 Ollama bge-m3（免费、离线、效果够用），其次 Gemini（云端、效果最好但要 Key），也可以选择暂不启用。Embedding 与主 LLM 独立，不再默认跟随主 LLM。高级选项里有"自定义 OpenAI 兼容 endpoint"。
  4. Phase 4 — Per-module 覆盖（高级，默认跳过）：可单独给 soul / discovery / recommendation / evaluation 指定不同模型。

接着 B 站登录态走 2 选 1（v0.3.12+）：

  • 装浏览器扩展自动同步（推荐，零配置）—— 选这条向导先退出，等扩展同步后再 openbiliclaw init 跑剩下的
  • 现场手动贴 Cookie —— 向导附 F12 → Network 取 cookie 的 5 步教程

🌸 小红书数据是否加入（v0.3.27+ 新增可选项）：拉 B 站数据之前会单独弹一个交互式问题——把小红书收藏 / 点赞混进画像吗？

  • 想加就回 Y，会有准备清单提示你装扩展 + 登录小红书 + 让浏览器是活跃窗口。注意：扩展会在浏览器开一个前台 tab（会抢一次焦点）跑 ~10–30s 抓数据，完成后自动关
  • 直接回车或回 N 会跳过，只用 B 站数据建画像
  • 脚本化场景用 --no-xhs 跳过 / --yes-xhs 强制启用 / OPENBILICLAW_NO_XHS=1 环境变量永久跳过

🎵 抖音数据是否加入（v0.3.67+ 新增可选项）：随后会单独询问是否把抖音发布 / 收藏 / 点赞 / 关注混进画像。

  • 想加就回 Y，需要已安装扩展并在同一浏览器登录 https://www.douyin.com；扩展会打开抖音页面执行 bootstrap_profile 任务
  • 不想加就回 N，只用 B 站和已同意的其他源建画像
  • 脚本化场景用 --no-douyin 跳过 / --yes-douyin 强制启用 / OPENBILICLAW_NO_DOUYIN=1 环境变量永久跳过

🌐 YouTube 数据是否加入：随后会单独询问是否把 YouTube 观看历史 / 订阅 / 点赞混进画像。

  • 想加就回 Y，需要已安装扩展并在同一浏览器登录 https://www.youtube.com；扩展会打开 YouTube 页面执行 bootstrap_profile 任务
  • 不想加就回 N，只用 B 站和已同意的其他源建画像
  • 脚本化场景用 --no-youtube 跳过 / --yes-youtube 强制启用 / OPENBILICLAW_NO_YOUTUBE=1 环境变量永久跳过

最后进入真正的 init 阶段：

  1. （可选）拉取小红书收藏 / 点赞 —— 仅在上面同意时执行；与 B 站拉取并行跑
  2. （可选）拉取抖音发布 / 收藏 / 点赞 / 关注 —— 仅在上面同意时执行
  3. （可选）拉取 YouTube 观看历史 / 订阅 / 点赞 —— 仅在上面同意时执行
  4. 拉取 B 站历史 / 收藏 / 关注（≈ 20–60s）
  5. 分析偏好（LLM 调用，≈ 30–90s）
  6. 生成初始画像（LLM 调用，≈ 30–60s）—— 若有小红书 / 抖音 / YouTube 数据会一并喂入
  7. 自动补首轮内容池（多策略并发 + LLM 评估，≈ 1–3 分钟）

跑完后可以用 openbiliclaw cost 查看本次 init 在 LLM 上花了多少钱（v0.3.26+ 计费台账）。

如果当前终端不是交互式（CI / 服务器脚本），init 不会等待输入，而是直接报错——这是为了避免把脚本挂死。这时改用 python3 scripts/agent_bootstrap.py --provider ... --llm-api-key ... --bilibili-cookie ... --yes-xhs/--no-xhs --yes-douyin/--no-douyin --yes-youtube/--no-youtube（详见 docs/agent-install.md）。

3. 给 OpenClaw 保留一个本地 workspace

即使后端跑在 Docker 里，OpenClaw 仍需要能看到当前仓库，因为它要发现：

  • skills/openbiliclaw-adapter/SKILL.md

同时，宿主机最好保留一套轻量 Python 环境，方便 OpenClaw 或维护者执行 bridge / doctor 命令：

# 推荐：使用 uv（更快）
uv sync

# 或使用传统 venv
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

方案 B：本地部署

当目标机器没有 Docker 时，直接全本地部署。

在仓库根目录执行：

# 推荐：使用 uv（更快）
uv sync
cp config.example.toml config.toml

# 或使用传统 venv
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp config.example.toml config.toml

然后初始化：

openbiliclaw init

⏱ 首次运行预计 2–5 分钟。同 Docker 路径，触发同一份配置向导（LLM → Embedding → Cookie → Per-module 覆盖），然后弹小红书 / 抖音 / YouTube 可选问题，最后跑实际 init（可选拉小红书 / 抖音 / YouTube → 拉 B 站历史 → 生成画像 → 首轮发现）。

如果你想跳过交互式向导（自动化场景），用 scripts/agent_bootstrap.py 的命令行 flag 一次性把所有字段传进去——见 docs/agent-install.md。

Agent 宿主如何发现并调用

宿主当前应直接发现仓库里的 workspace skill：

  • skills/openbiliclaw-adapter/SKILL.md

这个 skill 不直接实现推荐逻辑，而是要求宿主调用下面的 CLI bridge：

uv run python -m openbiliclaw.integrations.openclaw.cli <command> [flags]

启动后先协商能力版本：

uv run python -m openbiliclaw.integrations.openclaw.cli capabilities

返回的 protocol_version 当前为 agent-bridge/v2，skill_names 是宿主应缓存的完整清单。每次 CLI bridge 构造 direct adapter 时，会在任何画像、对话或推荐 LLM operation 可调用前，先同步执行一次零 LLM 的候选池历史恢复与原子维护；同一 controller 后续若进入后台 runtime，不会重复执行该启动维护。 direct adapter 构造推荐引擎时会把 [scheduler].copy_ready_target_count 钳到 0..pool_target_count，并同时注入公开 pool_target_count，与 API/普通 CLI 使用同一 eligible topic-first 双缺口文案调度；配置为 0 时明确保留 legacy drain-all，便于紧急回滚。

已支持的命令：

  • capabilities — 返回协议版本、兼容宿主和完整能力清单
  • sync-account
  • get-profile
  • recommend --limit 5 [--source-platform <platform>]
  • reshuffle / append — 换一批或追加
  • get-delight / respond-delight — 惊喜推荐及反馈
  • activity-feed / platform-availability
  • next-probe / respond-interest-probe — 兴趣假设四态反馈
  • next-avoidance-probe / respond-avoidance-probe — 避雷假设四态反馈
  • chat --message "..." [--session openclaw] / chat-history — durable 苏格拉底式对话
  • profile-edit-state / edit-profile — 画像 overlay
  • save-local / list-saved / remove-saved / sync-saved
  • runtime-status
  • submit-feedback --recommendation-id 7 --feedback-type like --request-id feedback-7-like-1
  • listen — 长连接推送候选和 probe 结果事件
  • doctor
  • emit-skill-descriptors

首次初始化后要做什么

不管是 Docker 还是本地部署，初始化完成后都建议做一轮自检。

Docker 路径最小自检

docker exec -it openbiliclaw-backend openbiliclaw profile
uv run python -m openbiliclaw.integrations.openclaw.cli doctor
uv run python -m openbiliclaw.integrations.openclaw.cli get-profile
uv run python -m openbiliclaw.integrations.openclaw.cli recommend --limit 3

本地路径最小自检

openbiliclaw profile
uv run python -m openbiliclaw.integrations.openclaw.cli doctor
uv run python -m openbiliclaw.integrations.openclaw.cli get-profile
uv run python -m openbiliclaw.integrations.openclaw.cli recommend --limit 3

期望结果：

  1. profile 能读到画像或至少给出初始化后状态
  2. doctor 返回 skill_pack_exists: true
  3. get-profile 返回 {"ok": true, "data": ...}
  4. recommend --limit 3 返回推荐列表

Agent 宿主日常使用流程

推荐给 Agent 宿主的常规使用顺序如下。

0. 协商能力

uv run python -m openbiliclaw.integrations.openclaw.cli capabilities

不要在宿主配置里长期维护一份旧的静态命令列表；升级后以该清单刷新工具缓存。

1. 读当前画像

uv run python -m openbiliclaw.integrations.openclaw.cli get-profile

2. 确认猜测兴趣（主动追问）

先看有没有待确认的猜测兴趣方向：

uv run python -m openbiliclaw.integrations.openclaw.cli next-probe

如果返回了一条假设，宿主应把 question 字段展示给用户，然后可以使用显式四态反馈：

uv run python -m openbiliclaw.integrations.openclaw.cli respond-interest-probe \
  --domain "建筑美学" --response confirm

需要继续讨论时再使用：

uv run python -m openbiliclaw.integrations.openclaw.cli chat \
  --message "嗯对，最近在看很多参数化设计的东西"

苏格拉底式对话支持多轮——每次 chat 都会返回一个新的追问/回应，并且对话内容会自动回写进灵魂画像；返回的 turn_id 可用于重试和 chat-history。

3. 取推荐

优先走快路径：

uv run python -m openbiliclaw.integrations.openclaw.cli recommend --limit 3

4. 写反馈

uv run python -m openbiliclaw.integrations.openclaw.cli submit-feedback \
  --recommendation-id 12 \
  --feedback-type like \
  --request-id feedback-12-like-1

如果是评论型反馈：

uv run python -m openbiliclaw.integrations.openclaw.cli submit-feedback \
  --recommendation-id 12 \
  --feedback-type comment \
  --request-id feedback-12-comment-1 \
  --note "方向对，但我想看更深一点。"

--request-id 必填，trim 后必须为 1–400 字符。同一个用户动作因超时、响应丢失或 agent 重试而再次提交时必须复用；不同动作即使 recommendation/type/note 相同，也应生成新的 ID。

惊喜卡片支持同样的反馈闭环：

uv run python -m openbiliclaw.integrations.openclaw.cli respond-delight \
  --bvid BV1xxx --response like --request-id delight-BV1xxx-like-1

5. 画像和本地保存

uv run python -m openbiliclaw.integrations.openclaw.cli profile-edit-state
uv run python -m openbiliclaw.integrations.openclaw.cli save-local \
  --list-kind favorite --source-platform bilibili --content-id BV1xxx
uv run python -m openbiliclaw.integrations.openclaw.cli list-saved --list-kind favorite

save-local 不会写外部账号。只有用户明确授权时才运行：

uv run python -m openbiliclaw.integrations.openclaw.cli sync-saved \
  --list-kind favorite --allow-state-changing

6. 查看运行时状态

uv run python -m openbiliclaw.integrations.openclaw.cli runtime-status

7. 低频做账户同步

uv run python -m openbiliclaw.integrations.openclaw.cli sync-account

Agent 宿主调用约定

给宿主的规则建议保持为：

  1. 优先用 recommend --limit <n>，这是快路径
  2. 只有明确需要新鲜度检查时，才加 --refresh-if-needed
  3. 解析 CLI 返回 JSON，不要依赖自然语言输出
  4. 如果返回 { "ok": false, ... }，直接上抛错误，不要继续串后续动作
  5. 对 comment 反馈，必须带 --note
  6. 把 doctor 当成接线排障入口，而不是日常业务命令
  7. 写操作使用稳定 request_id；native save 必须携带显式授权
  8. 使用 capabilities / emit-skill-descriptors 发现能力，不要依赖过时文档中的旧列表

常见问题

1. 不确定该走 Docker 还是本地

按目标机能力判断：

  • 有 Docker：优先 Docker
  • 没 Docker：本地部署

2. doctor 失败

优先检查：

  • 当前目录是不是仓库根目录
  • 虚拟环境是否已激活
  • 依赖是否已安装
  • src/openbiliclaw/integrations/openclaw/cli.py 是否存在
  • skills/openbiliclaw-adapter/SKILL.md 是否存在

3. get-profile 或 recommend 报未初始化

说明还没有完成初始化：

Docker：

docker exec -it openbiliclaw-backend openbiliclaw init

本地：

openbiliclaw init

4. 显式 refresh 太慢

这是预期风险之一。OpenClaw 交互默认应走快路径：

uv run python -m openbiliclaw.integrations.openclaw.cli recommend --limit 3

只有在用户明确要求更强新鲜度时，才触发：

uv run python -m openbiliclaw.integrations.openclaw.cli recommend --limit 3 --refresh-if-needed