接入教程 · 笔记本

让小智（OpenClaw）直接用你的笔记本

笔记本对外是一个标准 MCP 服务器（Streamable HTTP 协议）。你的 MCP Hub 已经支持 streamable_http + 自定义请求头，所以不需要 Worker、不需要本地常驻进程、不需要新增部署单元 —— 下面这份配置贴进 Hub 就能用。

第 1 步 · 访问令牌 (API_TOKEN)

这就是小智接入要用的那串钥匙。不用再去服务器翻 .secrets.local 了 —— 直接在这里看、在这里改，改完立即生效。

当前令牌读取中…

加载中…

⚠️ API_TOKEN 不是网页访问口令，填成口令会一直 401。改完令牌后，小智 / MCP Hub 里那段 Authorization 要跟着改一遍，否则也会 401。令牌是全权密钥，别发给任何人、别贴到聊天里。

第 2 步 · 在 Hub 配置里加一段

编辑 Hub 的 MCP 配置（或直接在 /mcp 管理页粘贴 JSON，走「AI 自动新增 + 人工审批」流程）：

{
  "mcpServers": {
    "biji-notes": {
      "type": "streamable_http",
      "url": "https://zhangchong-biji-web.pages.dev/api/mcp/rpc",
      "headers": {
        "Authorization": "Bearer <API_TOKEN>"
      }
    }
  }
}

不想手抄就用上面这个按钮 —— 它会把你第 1 步那串真实令牌填进 Authorization 再复制到剪贴板，直接粘到 Hub 配置里就行。

工具开关

随时关掉不想让小智用的工具。关掉之后，小智在工具列表里根本看不到它 —— 就算它记着旧名字硬调，也会被明确拒绝。改动立即生效，不用去动 Hub 的配置。

MCP 总开关

关掉 = 小智完全碰不到笔记本（所有工具一律拒绝）

读取中…

怎么让小智记记忆

记忆（/memory）是带 memory 标签的普通笔记 —— 没有新表、没有第二套存储。小智把关于你的长期信息（偏好、习惯、交代过的事）打上这个标签，就会出现在记忆页；你在那一页能搜、能加、能删（删是软删，进回收站可还原）。

对小智说这句就行

记住这件事，用 memory 标签记进笔记库：我习惯先看结论再看细节。

两个必须守住的约定

一、标签名固定用 memory —— 不带 #、全小写。标签匹配是大小写敏感的，写成 Memory 或 #memory 都会查不到（# 在网址里还会被当成锚点）。
二、这套约定要写进 Hub 侧的人设指引，否则小智不知道要打这个标签。

能力边界

能：新增记忆（add_note 带 memory 标签）、 只搜记忆（search_notes 只给 tag=memory → 列出全部记忆；再加 query → 在记忆里按关键词搜）、删除记忆（delete_notes，软删可还原）。
不能：改记忆 —— MCP 不暴露改笔记的工具，这是有意设计：AI 改不动你亲手记的东西。要改就「删掉重新记」。

怎么让小智整理知识库

知识库（/kb）是「整理层」—— 小智把散落的原始笔记提炼成按主题组织的、可复用的知识。原始笔记一条都不会被动，整理错了随时清空重来。

对小智说这句就行

把这些笔记整理进我的知识库：先调 list_unorganized 看有哪些还没整理的，按整理规范归到主题文档里，冲突以最新的为准。

整理规范

小智调 list_unorganized 时会一并收到这段规范 —— 所以不用每次都交代。想换口味就改下面这份（改完保存，立即生效）。

查看 / 编辑整理规范

小智能用的 18 个工具

按用途分四组：查（只读）、记（新增）、整理（会改动数据，强制确认）、凭据（读要已批准，写要你审批）。

查 · 只读

工具	参数	说明
`search_notes`	`query`（必填） `limit`（默认 10）	关键词搜索。三个字以上走全文索引 + 相关度排序，两个字自动降级模糊匹配。返回标题 / 标签 / 时间 / 地点 / 正文。
`list_recent`	`limit`（默认 10） `since`：today / yesterday / 3d / 7d / ISO 日期 `source` / `sourceName`	按时间倒序列出最近记的笔记，回答「今天记了什么」「最近记了啥」。只给元数据，不含正文。
`list_by_date`	`date`（YYYY-MM-DD，不传 = 今天）	按天总结核心工具。精确列出某个自然日（北京时间）的全部笔记，从早到晚排序。问「9 月 10 号做了什么」走它。
`get_note`	`id`（必填）	按 id 取一条的完整正文 + 元数据。已知 id（从搜索或列表拿到）时最省事。
`list_tags`	`limit`（默认 30，最多 80）	列出出现过的标签及条数，用来了解有哪些主题。

记 · 新增

工具	参数	说明
`add_note`	`content`（必填） `title`（必填，≤30 字） `tags`（必填，3–6 个） `agent`（身份名）	记一条笔记，原文一字不改地保存。`title` / `tags` 由调用方 AI 自己提炼：标题要 8–20 字的名词短语、别带日期时间或用「速记」「笔记」占位词；标签 3–6 个主题词、英文逗号分隔。`agent` 会记进来源，用户能按它筛选（不传记为「未具名 Agent」）。

整理 · 改动数据

工具	参数	说明
`find_duplicates`	`limit`（默认 10）	按正文指纹找出内容几乎一样的重复候选组，由 Agent 判断是否真重复。只读，不改动任何数据。
`merge_notes`	`ids`（至少 2 个） `mode`：concat / keep_primary `confirm`（两步确认）	把多条重复笔记合并成一条：保留创建最早那条，其余移入回收站，标签取并集。默认 concat 把其余正文带来源注释拼进主条目（信息零丢失）。先不传 confirm 看计划，确认无误再带 confirm=true 执行。
`delete_notes`	`ids`（最多 50 条） `reason`（删除原因） `agent`（谁删的）	把笔记移入回收站（软删除，可还原）。只能删 AI 自己记的（source=agent）—— 你在网页手记的笔记它碰不到，硬传会被拒绝。真正从数据库里删掉，只有你在回收站里亲手点。AI 没有这个权限。

知识库 · 整理

工具	参数	说明
`list_unorganized`	`limit`（默认 20）	每日整理的起点。列出还没进知识库的原始笔记（带正文片段）+ 整理规范。已经整理过的不会重复出现。
`save_kb_doc`	`topic` `content`（必填） `category` / `summary` `sourceNoteIds` / `agent`	写入或更新一篇主题文档：同一个 topic 就覆盖更新（revision+1）。`sourceNoteIds` 一定要填 —— 既用于溯源，也让这些笔记不再出现在「未整理」里。
`search_kb`	`query`（必填） `limit`（默认 10）	回答问题时优先用它 —— 知识库里的内容是提炼过的结论，比翻原始碎碎念准确。
`list_kb_docs`	`category` / `limit`	列出所有主题文档。整理前先调它，优先复用已有主题名，避免同一件事出现两个名字。
`get_kb_doc`	`topic` 或 `id`	取一篇文档的完整正文 + 它的来源笔记列表。

知识库是派生物：允许 AI 直接写入和覆盖，因为原始笔记一条没动 —— 整理乱了在 /kb 页一键清空重来即可。

账号凭据 · 自助（v3.9.20）

工具	参数	说明
`list_accounts`	`website`（可选，模糊过滤）	脱敏清单：登记了哪些凭据、各有哪些字段（有/无密码·Token·API Key）、备注、来源。不含任何密钥原文。
`get_account`	`website`（必填，大小写不敏感）	取已批准条目的明文。同名多条一起返回，优先用网页登记的；待审批的取不到内容。
`add_account`	`website`（必填） `username` / `password` / `token` / `apiKey` / `url` / `note` / `agent`	提交一条新凭据。提交后是「待审批」，你在网页点批准前任何工具都读不到它（见下方说明）。
`update_account`	`id` `agent`（必填）其余字段不给=不变、空串=清空	只能改 Agent 自己登记的条目；网页登记的凭据是权威，它碰不到。改完自动打回待审批。

为什么写也要你点头：Agent 经 MCP 提交的凭据一律「待审批」，你到 /accounts 页核对内容（提交人、用途、scope）后点「批准」， MCP 才读得到它。这样即使 Agent 被提示注入诱导、提交了一条假的「GitHub」令牌， 你不点批准，它就永远读不到；拒绝即删除。Agent 也无权批准自己。

删除能力是 v3.9.5 新加的，但它是软删除：小智只能把笔记搬进回收站，而且只能搬它自己记的（source=agent）—— 你网页手记的笔记它碰不到。真正删掉只有你在回收站里亲手点，AI 没有这个权限。

换句话说：小智永远删不掉东西。它最多只能把东西挪个地方，而挪到哪、要不要真扔，决定权在你手上。

第 3 步 · 验证

配置生效后，直接对小智说：

「帮我查一下笔记里关于 显卡散热 的内容」
「把这段记到笔记本里：服务器重启流程是先停服务再启动」

也可以用 curl 手工验证端点（把 $API_TOKEN 换成真实值）：

curl -H "Authorization: Bearer $API_TOKEN" \
  "https://zhangchong-biji-web.pages.dev/api/mcp/search?query=显卡"

curl -X POST -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"content":"小智记录：这条来自 REST 测试"}' \
  "https://zhangchong-biji-web.pages.dev/api/mcp/add_note"

常见问题

一直 401？　先看是不是把 Bearer 后面填成了网页访问口令 —— 两者是不同的密钥。令牌直接复制本页第 1 步「当前令牌」右边那个「复制」按钮，不要手打。

搜索两字词搜不到？　正常。三个字以上走全文索引，两个字自动降级模糊匹配，返回里会有 mode 字段标明走的是哪条路径。

想屏蔽账号密码类笔记的正文？　默认返回正文（Agent 才能回答问题）。需要收紧时把环境变量 MCP_MASK_SENSITIVE 设为 1 重新部署，敏感笔记就只给标题和标签。

协议细节？　端点实现了 initialize / tools/list / tools/call / ping，协议版本协商 2025-06-18（默认）/ 2025-03-26 / 2024-11-05，无状态模式，无 SSE 推送流。