openclaw-server

openclaw-server 是一个给 OpenClaw 用的 OpenAI-compatible 后端。

它不是通用大模型，也不会调用真实 AI API。当前版本的重点很明确: 把 书签篮 的搜索、分类浏览和最近更新能力，包装成 OpenClaw 可以直接接入的聊天服务。

如果你想让 OpenClaw 在聊天里直接回答下面这类问题，这个项目就是最短路径:

• 搜 python
• 搜索 cesium 教程
• 看看最近更新
• 列出分类
• 开发工具常用链接
• 每天早上 6 点推送最近更新的文章

为什么要接书签篮

书签篮 适合把常用网站、教程、工具、文章整理成一个长期可维护的知识入口。
把它接进 OpenClaw 之后，机器人返回的就不再只是“网上搜一下”的泛结果，而是你已经沉淀好的个人或团队导航内容。

这个项目当前内置的数据源就是 https://shuqianlan.com。

当前能力

• 关键词搜索书签篮内容
• 查看最近更新文章
• 列出一级分类
• 查看某个分类下的文章
• 查看某个分类下的常用链接
• 支持 GET /healthz
• 支持 GET /v1/models
• 支持 POST /v1/chat/completions
• 支持 POST /v1/responses
• 支持 SSE 流式输出
• 支持每天定时生成“最近更新文章”摘要
• 能识别 OpenClaw 包装过的用户输入，并提取其中的真实文本和 sender_id

快速开始

1. 环境要求

• Node.js >= 22.12.0
• pnpm

2. 安装依赖

pnpm install

3. 配置环境变量

最少只需要一个 API Key:

export OPENCLAW_SERVER_API_KEY='replace-me'

常用配置如下:

export OPENCLAW_SERVER_HOST='127.0.0.1'
export OPENCLAW_SERVER_PORT='4318'
export OPENCLAW_SERVER_API_KEY='replace-me'
export OPENCLAW_SERVER_MODEL_ID='default-assistant'
export OPENCLAW_SERVER_DEBUG_LOG='1'

4. 启动服务

开发模式:

pnpm dev

或直接启动:

pnpm start

默认监听:

http://127.0.0.1:4318

5. 健康检查

curl http://127.0.0.1:4318/healthz

预期返回:

{"ok":true,"version":"0.1.0"}

直接调用

除了 /healthz，其余接口都需要 Bearer Token。

查看模型列表

curl http://127.0.0.1:4318/v1/models \
  -H 'Authorization: Bearer replace-me'

用 Chat Completions 搜索书签

curl http://127.0.0.1:4318/v1/chat/completions \
  -H 'Authorization: Bearer replace-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "default-assistant",
    "messages": [
      { "role": "user", "content": "搜 python" }
    ]
  }'

用 Responses API 搜索书签

curl http://127.0.0.1:4318/v1/responses \
  -H 'Authorization: Bearer replace-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "default-assistant",
    "input": "搜索 notion ai"
  }'

使用方式

服务当前更像一个“书签篮助手”，而不是通用聊天模型。推荐直接对它说明确指令:

• 搜索: 搜 python、搜索 cesium 教程、帮我找 Notion AI
• 最近更新: 看看最近更新、最新文章
• 分类列表: 列出分类、有哪些一级分类
• 分类文章: 开发工具分类、看看开发工具的文章
• 分类链接: 开发工具常用链接
• 每日摘要: 每天早上 6 点推送最近更新的文章

接入 OpenClaw

最直接的接法，是把 openclaw-server 配成一个自定义 provider。

下面示例里的 contextWindow 和 maxTokens 主要是给 OpenClaw 填模型目录元数据，按你的使用习惯调整即可。

下面是一份可直接参考的 OpenClaw 配置示例:

{
  env: {
    OPENCLAW_SERVER_API_KEY: "replace-me",
  },
  agents: {
    defaults: {
      model: { primary: "openclaw-server/default-assistant" },
      models: {
        "openclaw-server/default-assistant": { alias: "书签篮助手" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      "openclaw-server": {
        baseUrl: "http://127.0.0.1:4318/v1",
        apiKey: "${OPENCLAW_SERVER_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "default-assistant",
            name: "Bookmark Assistant",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 32000,
            maxTokens: 4096,
          },
        ],
      },
    },
  },
}

接入时注意:

• baseUrl 要指向服务的 /v1
• apiKey 要和 OPENCLAW_SERVER_API_KEY 一致
• model 引用格式是 providerId/modelId，这里就是 openclaw-server/default-assistant
• 如果你在 OpenClaw 里统一使用 Responses API，也可以把 api 改成 openai-responses，本服务同样提供 /v1/responses

和 OpenClaw 对接时，这个服务会帮你做什么

• 自动从 OpenClaw 包装过的用户消息里提取真实用户输入
• 自动尝试从 Conversation info (untrusted metadata) 里提取 sender_id
• 书签更新订阅会按用户维度保存，便于后续做消息回推或轮询投递

这意味着，OpenClaw 把聊天请求转发过来之后，不需要你再额外清洗一层用户文本。

每日更新摘要怎么接

当用户说出类似 每天早上 6 点推送最近更新的文章 的指令后，服务会:

1. 记录订阅关系
2. 定时检查书签篮最近更新
3. 生成待发送通知

你可以用两种方式把这些通知送出去:

方式一: 配置 webhook 自动投递

export OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_URL='https://your-bridge.example.com/hooks/bookmark-digest'
export OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_AUTH_TOKEN='replace-me'

服务会定时向该地址发送 JSON:

{
  "type": "bookmark_digest",
  "user": "sender-1",
  "message": "早上好，以下是 ...",
  "payload": {
    "type": "bookmark_digest",
    "userId": "sender-1",
    "slotAt": "2026-03-14T06:00:00.000Z",
    "hasNewArticles": true,
    "articles": [],
    "browseUrl": "https://shuqianlan.com/static-article/page/page_1.html"
  }
}

方式二: 自己轮询管理接口

拉取待发送通知:

curl 'http://127.0.0.1:4318/admin/bookmark-digests/pending?user=sender-1' \
  -H 'Authorization: Bearer replace-me'

标记已送达:

curl http://127.0.0.1:4318/admin/bookmark-digests/mark-delivered \
  -H 'Authorization: Bearer replace-me' \
  -H 'Content-Type: application/json' \
  -d '{
    "ids": ["notification-id"]
  }'

如果你当前只想先把搜索能力接进 OpenClaw，这一部分可以先不配。

管理接口

• GET /healthz: 健康检查，无需鉴权
• GET /v1/models: 返回模型列表
• POST /v1/chat/completions: OpenAI Chat Completions 兼容接口
• POST /v1/responses: OpenAI Responses 兼容接口
• GET /admin/stats: 查看运行时统计
• POST /admin/packs/reload: 热重载 packs/<packId>
• GET /admin/bookmark-digests/pending: 查看待发送摘要
• POST /admin/bookmark-digests/mark-delivered: 标记摘要已送达

常用环境变量

• OPENCLAW_SERVER_HOST: 监听地址，默认 127.0.0.1
• OPENCLAW_SERVER_PORT: 监听端口，默认 4318
• OPENCLAW_SERVER_API_KEY: 鉴权令牌，默认 openclaw-server-dev
• OPENCLAW_SERVER_MODEL_ID: 默认模型 ID，默认 default-assistant
• OPENCLAW_SERVER_PACK_ID: 要加载的 pack，默认 default
• OPENCLAW_SERVER_PACK_DIR: 自定义 pack 目录
• OPENCLAW_SERVER_SESSION_LOG: 会话日志输出路径
• OPENCLAW_SERVER_TIMEZONE: 默认时区
• OPENCLAW_SERVER_BOOKMARK_DIGEST_TIMEZONE: 摘要时区
• OPENCLAW_SERVER_BOOKMARK_DIGEST_POLL_MS: 摘要轮询间隔
• OPENCLAW_SERVER_BOOKMARK_DIGEST_LIMIT: 每次摘要最多带多少条文章
• OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_URL: 自动投递 webhook
• OPENCLAW_SERVER_BOOKMARK_DIGEST_WEBHOOK_AUTH_TOKEN: webhook Bearer Token
• OPENCLAW_SERVER_DEBUG_LOG: 是否开启调试日志

自定义回复

默认 pack 在 packs/default，你可以直接修改这些文件来调整回复风格和兜底逻辑:

• packs/default/pack.yaml
• packs/default/intents.yaml
• packs/default/templates.yaml
• packs/default/faq.yaml
• packs/default/scenarios.yaml

修改后可以调用:

curl http://127.0.0.1:4318/admin/packs/reload \
  -X POST \
  -H 'Authorization: Bearer replace-me'

当前边界

• 它不是通用大模型服务
• 它当前不调用真实 AI API
• 它当前的核心价值是“把书签篮接到 OpenClaw 里”
• 它当前内置的数据源是 书签篮

如果你的目标是让 OpenClaw 拥有一个真正可搜索、可沉淀、可长期维护的资料入口，而不是再接一个泛化聊天模型，这个项目和书签篮的组合会很合适。