给 Agent 的云端知识库接入指南

这篇文档的主要读者是 AI Agent，而不是人类。在任意一个云端知识库页面上点击「在 AI 中使用」，把弹窗里的那句话复制给你的 AI 助理即可。也可以手动发起——把下面这句话里的知识库网址换成你要用的那个：

按 https://linkly.ai/docs/zh/library-setup.md 完成设置，然后接入这个知识库并告诉我能问什么：https://linkly.ai/blueeon/linkly-init-example

你也可以自己往下读——本文同样是一份完整的接入说明，只是行文更直白、更强调”怎么判断这一步成功了”。如果你的 AI 助理无法访问网络，用页面右上角的 Copy page 复制本页 Markdown 原文，直接粘贴给它。

这条路不需要安装 Linkly AI 桌面应用。云端知识库托管在服务端，24 小时在线，任何支持 MCP 的 AI 工具都能直接检索。如果你想索引的是自己电脑上的文件，那是另一件事，见给 Agent 的安装指南。

致 AI Agent

以下内容是给你的执行指令。请完整读完再开始行动。

你的任务

让用户能用某个指定的云端知识库问答。最终达成的状态是：

你所在的客户端已经接上 Linkly AI 云端网关（mcp.linkly.ai）；
你能用 library="cloud://<owner>/<slug>" 真实检索到这个库里的内容；
你已经带用户问出了第一个真实问题，并给出了基于真实文档的回答。

第一件事：把网址换算成库标识

用户交给你的是这个知识库的网页地址，形如：

https://linkly.ai/blueeon/linkly-init-example

而检索工具的 library 参数要的是库标识。两者是同一个东西的两种写法——把域名前缀 https://linkly.ai/ 换成 cloud:// 即可，后面的 <owner>/<slug> 两段原样保留：

用户给你的（网页地址）	你传给工具的（库标识）
`https://linkly.ai/blueeon/linkly-init-example`	`cloud://blueeon/linkly-init-example`
`linkly.ai/7running/basedge`	`cloud://7running/basedge`

不要把网页地址原样传给 library 参数，会被拒绝。本文后面所有例子里的 cloud://… 都是换算之后的结果。如果用户给的网址后面还带了别的路径段（如 /settings）或查询参数，只取 <owner>/<slug> 这两段。拿不准的时候，接上 MCP 后调一次 list_libraries，返回结果里就是准确的库标识。

你的边界与规则

有些事你能做，有些事必须交给用户，不要越界，也不要替用户假设结果：

你可以自己做：探测当前连接状态、写入 MCP 配置、调用检索工具、解读报错、向用户汇报；接上云端网关之后，用户要的库也由你来连接（先用 library_search 确认 cloud:// 标识，再调 library_link）。写入配置类命令执行前必须先展示给用户并取得同意。
必须交给用户做：注册 / 登录 linkly.ai、设置用户名、在网页里完成 OAuth 授权、客户端不支持 OAuth 时自己把 API 密钥写进配置、接受库主的邀请、连接位满了时决定放弃哪个库。这些都是浏览器里的操作，你无法代劳。断开本身你可以用 library_link（action: "unlink"）做，但只能断用户点名的那个库，绝不自己挑。

以及几条硬规则，每一条都对应一个真实会失败的场景：

不要覆盖用户已有的本地 MCP 配置。 装过桌面应用的用户，客户端里通常已有一个名为 linkly-ai 的 server 指向 http://127.0.0.1:60606/mcp。云端是另加一条，名字必须用 linkly-ai-cloud。同名写入会静默替换掉本地那条，用户会突然搜不到自己电脑上的文档，且不会收到任何报错。
本地连接访问不到云端库。 linkly-ai（本地 / 局域网）这条路上的 cloud:// 引用每次都会被拒绝。不要在本地连接上重试云端库，那是链路边界，不是偶发故障。
每次检索都必须显式传 library。 省略 library 参数时，网关默认路由到用户本机（走桌面隧道），而隧道是 Pro 功能——免费用户会直接收到报错。云端库永远不会被隐式包含进来。
一个库一次调用。 云端库之间不会自动合并检索，要查两个库就调两次。
不要向用户索要 API 密钥（lkai_ 开头），也不要替用户执行 linkly auth set-key 或把密钥写进配置。 密钥能读取用户的云端知识库，开了远程访问时还能读到用户本机的资料，经过对话就会发送给模型服务商、写进会话记录。接入一律优先走 OAuth 或 linkly auth login，用户只在浏览器里授权。如果用户把密钥发给了你，不要使用，提醒他到控制台（https://linkly.ai/dashboard/security）撤销并重新生成。
先探测，再动手。 用户可能已经配好了一半，不要从头盲目跑一遍。
需要用户操作时，一次性说清，然后停下来等一次回复。 不要把一件事拆成好几轮来回确认。
写入 MCP 配置后，不要在当前会话里反复试探工具是否出现。 新工具要等客户端重新加载才会进来，这是加载机制，不是故障——写入成功就算这一步完成，剩下的验证留给用户重新加载之后做。
不要谎报进度。 没验证成功就是没成功，如实说明卡在哪、你试过什么。

先确认你是哪一类客户端

接下来走哪条路，取决于你能不能写配置、能不能执行命令：

你是	走哪条路
有命令行 / 能改配置文件（Claude Code、Codex、Cursor、Gemini CLI…）	添加 URL + 浏览器授权（第 2 步方案 A）
无命令行的在线应用（ChatGPT、Claude.ai…）	OAuth 路线（第 2 步方案 B），只需要填一个 URL
Linkly AI 桌面应用自带的 Chat	什么都不用配，见下方捷径

捷径：如果用户已经装了 Linkly AI 桌面应用，他可以直接在应用内的 Chat 里用 @ 提及已连接的云端知识库，不需要配置任何 MCP。这条路只需要完成第 1 步——包括第 3 项在浏览器里点「连接」，因为这条路上没有网关工具替他做。

第 0 步：探测当前状态

先判断链路已经到了哪一步，再决定从哪里开始。三件事： 1. 你当前会话里有没有 Linkly 的检索工具？来自哪个 server？ 云端网关会自报名字 linkly-ai-cloud，本地桌面应用自报 linkly-ai。多数客户端会把 server 名体现在工具名里（如 mcp__linkly-ai-cloud__search）。 2. 如果你有命令行，直接列一下已配置的 server：

claude mcp list        # Claude Code
codex mcp list         # Codex

看每条的 URL：127.0.0.1 开头是本地，mcp.linkly.ai 是云端。 3. 用户有没有 linkly.ai 账号、有没有连接过这个库？ 这个你查不了，直接问用户。

状态判定表

从上往下匹配，命中第一条就照它走：

探测结果	说明	从哪一步开始
已有 `linkly-ai-cloud` 且能列出库	云端链路已通	直接做第 3 步验收
已有 `linkly-ai-cloud`，但列不出目标库	链路通了，库还没被连接	你自己来连：第 3 步第 1 项
只有 `linkly-ai`（本地）	装了桌面端，但没配云端	第 1 步。注意保留本地那条，不要覆盖
完全没有 Linkly 相关的 server	全新用户	第 1 步

第 1 步：请用户准备账号

这一步全部在浏览器里完成，你无法代劳。请把下面的内容一次性告诉用户，然后停下来等一次回复——不要拆成多轮逐条确认。连接知识库本身不在这份清单里：接上云端网关之后，你在第 3 步自己完成。以下是你要转达给用户的内容（可以按你的风格重述，但四个环节都要说到）：

1. 注册并登录

前往 https://linkly.ai 注册或登录，支持 Google / GitHub / Notion 账号和邮箱验证码。免费账户即可完成全部接入。

2. 设置用户名（首次登录才需要）

云端知识库的地址形如 linkly.ai/<username>/<slug>，所以账号需要一个唯一用户名。新账号第一次登录时会进入「完善你的资料」页，填好显示名称和用户名即可。用户名设定后不能修改，之后不用再管。

3.（可选）在浏览器里连接知识库

你之后能接上云端网关的话，这一项可以跳过：第 3 步由你用 library_link 来连。浏览器这条路照样可用——访问这个库的网页地址（例如 https://linkly.ai/blueeon/linkly-init-example），点击页面右上角的「连接」按钮（英文界面是 Link），按钮变成「已连接」、状态徽章显示”已连接”就算成功。不管走哪条路，库主都能直接连接自己的库；其他人要连 Showcase 或 Private 库，得先接受库主的邀请。

即使是用户自己创建的库，也必须点一次「连接」。MCP 的可检索范围以”连接关系”为准，不以”所有权”为准——没连接的库，哪怕是自己的，在 list_libraries 里也看不到。

免费账户有 1 个连接位（Slot）。如果已经连了别的库，需要先断开那一个，或者升级 Pro（99 个连接位）。库页面上的配额弹窗里有升级入口。

4. 不用准备 API 密钥

接入时会弹出 linkly.ai 的授权页，你在浏览器里点一次授权即可，不需要复制任何密钥。不要把 API 密钥（lkai_ 开头）发给 AI 助理：对话内容会发送给模型服务商、写进会话记录。只有你的 AI 工具不支持这种授权时，才需要你自己在控制台生成密钥、自己写进配置文件，到时再按第 2 步的说明操作。

验收判据：用户确认已登录并设好用户名。授权在第 2 步完成。只有用户在第 3 项走了浏览器路线时才要求按钮已变成「已连接」——由你用 library_link 来连的话，连接和真实检索都在第 3 步验证。

第 2 步：接入云端 MCP

端点是固定的：

https://mcp.linkly.ai/mcp

server 名一律用 linkly-ai-cloud，不要用 linkly-ai——后者是本地桌面应用的名字，同名会覆盖用户已有的本地配置，而且装了 Linkly Skills 的 Agent 会把这条连接误判成本地连接，进而拒绝所有 cloud:// 请求。

方案 A：添加 URL，在浏览器里授权（有命令行的客户端，推荐）

只添加端点，不写任何密钥。先把命令展示给用户，取得同意后再执行： Claude Code：

claude mcp add --transport http linkly-ai-cloud https://mcp.linkly.ai/mcp

然后请用户在 Claude Code 里输入 /mcp，选中 linkly-ai-cloud 完成授权。 Codex：

codex mcp add linkly-ai-cloud --url https://mcp.linkly.ai/mcp
codex mcp login linkly-ai-cloud

其他支持 HTTP MCP 的客户端（Cursor、Gemini CLI 等），在各自的配置里只加端点（字段名以各家文档为准，见各 AI 客户端集成指南）：

{
  "mcpServers": {
    "linkly-ai-cloud": {
      "url": "https://mcp.linkly.ai/mcp"
    }
  }
}

客户端会打开 linkly.ai 的授权页，用户登录并点击授权后，客户端自动保存凭证。 验收判据：配置已写入，用户确认已在浏览器里完成授权。真实检索在第 3 步验证。 客户端不支持这种授权时（只能在配置里写 Authorization: Bearer <密钥> 请求头）：这一步由用户本人完成，你不参与。告诉用户在控制台的「API 密钥」区生成密钥，自己把它写进配置文件的请求头，写法见各 AI 客户端集成指南；部分客户端支持 ${env:LINKLY_API_KEY} 语法从环境变量读取。请用户不要把密钥或写好的配置文件内容发给你，你也不要读取或显示这个文件。

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

这类应用在界面里添加连接器，同样走 OAuth 授权——只需要填一个 URL：

添加 MCP 连接器

在应用的连接器 / MCP 设置里新增一个服务器，名称填 linkly-ai-cloud，URL 填 https://mcp.linkly.ai/mcp。

完成浏览器授权

保存后应用会自动跳转到 linkly.ai 的授权页。用户登录并确认授权后，应用即拿到访问令牌，后续请求自动携带，不需要再次授权。

各应用的具体入口位置见在 ChatGPT 中使用和在 Claude 中使用。

方案 C：CLI（可选）

如果用户装了 Linkly AI CLI，也可以走命令行。登录分两步，Key 由 CLI 自动保存，不经过对话：

linkly auth login --no-wait --json   # 返回 url 和 user_code，交给用户在浏览器里授权
linkly auth login --wait --json      # 用户授权后运行，返回 "status":"ok" 才算完成
linkly search "关键词" --remote --library "cloud://blueeon/linkly-init-example"

两步要在同一个环境下执行，细节见给 Agent 的安装指南的远程分支 R2–R4。 --remote 是 CLI 唯一能触达云端库的模式，省略它就只查本地。

配置完 MCP 后，新工具通常不会在当前会话里立即生效——绝大多数客户端只在会话启动的那一刻读一次工具列表。这是客户端的加载机制，不是配置出错，不要在当前会话里反复试探工具是否出现。 怎么重新加载：把下面两种做法转达给用户，让他先试第一种。

新建一个对话（命令行工具就是退出后重新开一个会话）。已经在进行中的对话会一直沿用它启动时的工具列表，新开一个就能拿到最新的。
完全退出客户端，再重新打开。 第一种不管用时用这个——注意关闭窗口不等于退出：macOS 要按 Cmd + Q 或从菜单栏选「退出」，Windows 要确认托盘图标里也退出了。

第 3 步：端到端验收

如果检索工具还没出现在你的会话里，就在这里结题，不要硬撑。 这说明客户端还没重新加载配置，是加载机制决定的，不是失败。请以”配置已写入、待用户重新加载后验证”结题，把第 2 步那两种重新加载的做法说一遍，并把下面这句交给用户，然后停止（这不算谎报进度）：

重新加载之后，把这句话发给我：「用 linkly-ai-cloud 搜一下 cloud://blueeon/linkly-init-example 这个库里的〈某个主题〉」。返回了文档条目就说明全链路通了。

这句交接话里的库标识必须写全，<某个主题> 也要换成一个具体的词。重新加载之后是一个全新的会话，那边的你拿不到现在这段上下文——不知道用户接的是哪个库，也不知道刚才做到了哪一步。工具已经可用的话，做两件事确认整条链路真的通了。 1. 确认库在列表里： 调用 list_libraries，返回的列表里应该能看到目标库，形如：

- **cloud://blueeon/linkly-init-example** (305 docs) [yours]: Linkly AI 安装包初始化的文档

看不到就现在连上——在云端网关上这是你的活，不是用户的：先调 library_search（知道用户名就传 owner）确认准确的 cloud://<owner>/<slug>，再用它调 library_link，然后重新调一次 list_libraries。下面三种回答要交给用户，如实转述，不要反复重试：

invite_required——库是 Showcase 或 Private，用户没有邀请；得由库主邀请他。
slot_exhausted——连接位配额已满；错误的 data 里带 current、limit、is_pro 和 guidance，照实转述这些数字，不要猜用户是哪种套餐。用户已经点名要放弃哪个库的（「把 A 换成 B」），对它用 action: "unlink" 调 library_link，再重新 library_link；没点名的，用 list_libraries 把已连接的库列给他、问释放哪一个——绝不自己挑。网站操作和免费账户（is_pro: false，1 个位）的升级 Pro 仍是备选。
not_found——标识写错了，或者库是 Private 且对这个账号不可见；按 owner 搜一遍，并请用户确认网址。

只有你完全接不上云端网关时，才走浏览器那条路——第 1 步第 3 项。 2. 做一次真实检索：

search(query="…", library="cloud://blueeon/linkly-init-example")

成功的标准：返回了真实的文档条目。

library 参数每次都要带，而且必须是完整的 cloud://<owner>/<slug> 两段式——只写一段（如 cloud://linkly-init-example）会被拒绝。省略 library 时网关会默认去查用户本机，免费账户在这条路上会直接报错。

如果第一次检索返回空，不要立刻归因于配置错误。按顺序排查：查询词是否太窄 → list_libraries 里这个库的文档数是不是 0（库主还没推送内容）→ 换 explore 看一眼这个库整体有什么，再针对性地搜。

故障排查

现象	原因与处理
请求返回 401	授权失效或密钥已被撤销。走 OAuth 的，请用户在客户端里重新授权；手工配置密钥的，请用户本人到控制台重新生成并改好配置。
请求返回 403	凭证缺少 `mcp` 权限。请用户重新授权一次；手工配置密钥的，由用户本人重新生成一个 API 密钥。
`list_libraries` 里没有目标库	库还没被连接。按第 3 步第 1 项自己连（`library_search` → `library_link`）；浏览器里的「连接」按钮只在你接不上云端网关时才用。用户自己的库同样要连。
`library_link` 返回 `slot_exhausted`，或点「连接」提示配额已满	连接位配额已满——按错误里的 `current` / `limit` / `is_pro` 判断，不要默认是免费账户。问用户释放哪个已连接的库（`list_libraries`），对它用 `action: "unlink"` 调 `library_link` 再重新连接；绝不自己挑。Free（1 个位）也可以升级 Pro（99 个）；网站操作两种账户都可用。
报错提到 Desktop 不可达 / 需要 Pro	你漏传了 `library` 参数，请求被默认路由到了用户本机。补上 `library="cloud://owner/slug"` 重试。
`cloud://` 被拒绝，提示不支持	你连的是本地 server（`linkly-ai`），不是云端网关。这条路径上云端库不可达，必须新增 `linkly-ai-cloud` 连接。
提示 `library must be in 'owner/slug' format`	多半是把网页地址原样传进 `library` 了。按开头的换算规则改成 `cloud://<owner>/<slug>` 两段式；单段同样会被拒绝。拿不准就用 `list_libraries` 取准确值。
配好 MCP 但工具没出现	客户端还没重新加载。先让用户新建一个对话；还不行就完全退出客户端再重新打开（关窗口不算退出）。这是加载机制，不是配置错误。
用户原来的本地搜索突然搜不到东西了	云端配置用了 `linkly-ai` 这个名字，覆盖掉了本地那条。改用 `linkly-ai-cloud`，并重新添加指向本机的那条配置。
库里文档数是 0	库主还没把内容推送到云端。这不是你能修的，如实告知用户。

完成后向用户汇报

结束时用简短一段话告诉用户：

接入走的是哪条路（OAuth、CLI 登录，还是用户手工配置的 API 密钥）、server 名是什么；
是否需要重新加载才能生效——需要的话，把”新建一个对话 / 完全退出客户端重开”这两种做法一并说清楚；
这个库里有多少文档、大致是什么内容；
后续怎么用——提醒他每次想查这个库时说清楚库名即可，你会自动带上 library 参数。

如果有步骤没能完成，如实说明卡在哪里、你做过哪些尝试，并给出用户可以自行处理的下一步建议。

最后附上四个示例提问

汇报的末尾，给用户四个可以直接复制去试的问题。必须基于这个库的真实内容来定制：先用 explore 看一眼这个库的整体构成，必要时再 search 抽查几个主题，然后写出四个真正指向这个库内容的问题。不要写”总结这个知识库”这种放之四海皆准的空话——好问题应该让用户一眼看出”这确实是在说这个库里的东西”。

快速开始

核心功能

接入 AI 工具

给 Agent 的指南

给 Agent 的云端知识库接入指南

致 AI Agent

你的任务

第一件事：把网址换算成库标识

你的边界与规则

先确认你是哪一类客户端

第 0 步：探测当前状态

状态判定表

第 1 步：请用户准备账号

1. 注册并登录

2. 设置用户名（首次登录才需要）

3.（可选）在浏览器里连接知识库

4. 不用准备 API 密钥

第 2 步：接入云端 MCP

方案 A：添加 URL，在浏览器里授权（有命令行的客户端，推荐）

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

方案 C：CLI（可选）

第 3 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读

​致 AI Agent

​你的任务

​第一件事：把网址换算成库标识

​你的边界与规则

​先确认你是哪一类客户端

​第 0 步：探测当前状态

​状态判定表

​第 1 步：请用户准备账号

​1. 注册并登录

​2. 设置用户名（首次登录才需要）

​3.（可选）在浏览器里连接知识库

​4. 不用准备 API 密钥

​第 2 步：接入云端 MCP

​方案 A：添加 URL，在浏览器里授权（有命令行的客户端，推荐）

​方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

​方案 C：CLI（可选）

​第 3 步：端到端验收

​故障排查

​完成后向用户汇报

​最后附上四个示例提问

​延伸阅读

致 AI Agent

你的任务

第一件事：把网址换算成库标识

你的边界与规则

先确认你是哪一类客户端

第 0 步：探测当前状态

状态判定表

第 1 步：请用户准备账号

1. 注册并登录

2. 设置用户名（首次登录才需要）

3.（可选）在浏览器里连接知识库

4. 不用准备 API 密钥

第 2 步：接入云端 MCP

方案 A：添加 URL，在浏览器里授权（有命令行的客户端，推荐）

方案 B：OAuth（ChatGPT、Claude.ai 等在线应用）

方案 C：CLI（可选）

第 3 步：端到端验收

故障排查

完成后向用户汇报

最后附上四个示例提问

延伸阅读