应用案例：用 AI Mate Space 搭建基于 LangBot 的 AI 客服

本案例演示如何把 AI Mate Space 控制台与 LangBot（开源 IM 机器人框架）对接，搭建一个接入飞书 / 钉钉 / 企业微信 / 微信 / QQ 等聊天平台的 AI 客服。

文档重点是你在控制台要做什么，以及要提供给 LangBot 的对接信息。LangBot 自身的部署与 IM 平台接入以官方文档为准，本案例只说明对接控制台所需的关键配置。

什么时候用

适合以下场景：

• 想让 AI 客服出现在企业 IM（飞书、钉钉、企业微信）或社交平台（微信、QQ、Telegram）中，用户在聊天窗口直接咨询。
• 希望由 AI Mate Space 统一管理模型接入、API Key 鉴权、Token 用量统计和会话审计，而不是把模型密钥散落在每个机器人里。
• 希望由 LangBot 负责多平台消息收发、多轮上下文、知识库检索，复用其成熟的 IM 适配能力。

不适合：只需要一个网页对话框、不接入任何 IM 平台的场景--这种情况直接用控制台的工作空间或 OpenAI 兼容 API 即可，无需 LangBot。见 工作空间协作 和 外部接入。

你将搭建什么

整体由三层组成，你在控制台负责中间这一层的全部配置：

┌──────────────────────────────────────────────────────────────┐
│  用户侧：飞书 / 钉钉 / 企业微信 / 微信 / QQ / Telegram ...      │
└───────────────────────────┬──────────────────────────────────┘
                            │ IM 消息（由 LangBot 收发）
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  LangBot（IM 前端，需单独部署）                                 │
│  - 多平台消息适配、多轮上下文、客服人设、知识库 RAG（可选）       │
│  - 通过 OpenAI 兼容协议调用你的控制台                           │
└───────────────────────────┬──────────────────────────────────┘
                            │ OpenAI 兼容 API
                            │ Authorization: Bearer sk-u-xxx
                            ▼
┌──────────────────────────────────────────────────────────────┐
│  AI Mate Space 控制台（你负责配置）                             │
│  - 模型接入与路由（供应商、模型、模型组）                        │
│  - 用户 API Key 鉴权 + 模型白名单                               │
│  - Agent 人设与技能（可选）                                     │
│  - Token 统计 / 会话日志 / 审计 / 计费                          │
│  - MCP 网关工具（可选，让客服调用业务系统）                      │
└──────────────────────────────────────────────────────────────┘

职责划分：

你需要准备

在控制台（你负责）

LangBot 与 IM 平台（另行部署）

本案例基于 LangBot v4.x 编写。v3 及更早版本采用 config.yaml 配置，字段不同，请先升级。

操作步骤

第一部分：在控制台准备模型与凭证

第 1 步：接入模型并记下显示名

确保「模型管理」中已接入至少一个对话模型（如 gpt-4o、deepseek-chat）。记下该模型的自定义显示名称（display_name），后面要提供给 LangBot。

详细操作见 02-接入模型供应商 和 03-添加与配置模型。

模型名用 display_name：调用 OpenAI 兼容 API 时，model 字段传的是控制台配置的 display_name，不是上游 model_name。这是本平台与原生 OpenAI 的关键区别，LangBot 那边填错会报「模型不存在」。

第 2 步：创建客服专用用户并配置白名单

为客服机器人单独创建一个用户（如 cs-bot-user），不要复用管理员账号：

1. 在「用户管理」新建用户，详见 10-创建用户并分配智能体。
2. 在该用户的「模型白名单」中加入客服要用的模型，详见 12-配置用户模型白名单。

白名单不能为空：非 Agent 路径下，白名单为空直接返回 403，管理员也不豁免。必须显式把模型加进白名单。

第 3 步：创建 API Key

为该用户创建一个 API Key，命名为便于识别的名字（如 langbot-cs-key）。创建后立即复制完整 Key（sk-u- 开头，仅显示一次）。

详见 11-管理用户 API Key。

第 4 步：在客户端白名单登记 LangBot

LangBot 通过 openai SDK 发起请求，其 User-Agent 包含 AsyncOpenAI。平台的客户端准入会按白名单对请求 UA 做大小写不敏感的子串匹配，白名单未包含的客户端会被直接拒绝（403）。因此需要把 LangBot 的客户端标识登记到白名单：

1. 进入「全局配置」->「客户端设置」->「客户端白名单」，详见 全局配置。
2. 添加客户端标识 AsyncOpenAI，保存。

白名单为空 = 拒绝所有第三方客户端：客户端白名单默认只含平台内置客户端，LangBot 等第三方调用必须显式登记标识，否则即使 API Key 和模型白名单都正确也会被 403 拦截。

第 5 步：验证 API 可用

在对接 LangBot 之前，先用 cURL 确认控制台侧配置无误。cURL 默认 UA 是 curl，不在白名单中，需用 -A 模拟 LangBot 的客户端身份（其 UA 含 AsyncOpenAI）：

curl -A "AsyncOpenAI/0.1" -s https://www.aimatespace.com/openai/v1/chat/completions \
  -H "Authorization: Bearer sk-u-xxx" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"你好"}]}'

model 替换为你的 display_name。这一步同时验证 API Key、模型白名单、客户端白名单三项配置，能收到正常回复再继续。

第二部分：把对接信息配置到 LangBot

完成第一部分后，你需要把下面 4 个值提供给 LangBot（由你或 LangBot 运维方在 WebUI 配置）：

LangBot v4 在 WebUI 用「供应商 + 模型」两层配置，要点如下：

1. 新建供应商（模型 → 供应商列表 → 新建）：填上表的 Base URL、API Key、请求器类型。供应商名称自定义（如 AI-Mate-Space）。

Base URL 末尾不要带 /：.../openai/v1 正确，.../openai/v1/ 会导致拼成 //chat/completions 报 404。

保存后可点「扫描模型」，LangBot 会请求 {base_url}/models 自动拉取你在白名单中配置的模型清单。

2. 添加对话模型（模型 → 对话模型 → 添加）：模型 ID 填 display_name，模型供应商选刚建的供应商。按模型能力开启「视觉能力」「工具使用能力」。

模型 ID 必须用 display_name：填错会返回「模型不存在」。可用 GET /openai/v1/models 确认正确名称。

3. 配置客服人设（流水线 → 编辑默认 Pipeline → AI 能力 → 内置 Agent → 提示词 prompt）：填客服人设，例如：

你是 AI Mate Space 的智能客服助手。请遵守以下规则：
1. 专业、友好、简洁地回答用户关于产品使用、API 接入、计费的问题。
2. 涉及订单号、账号信息时，先核对用户身份，避免泄露隐私。
3. 无法确定的问题，引导用户提交工单或转人工，不要编造答案。
4. 回复控制在 200 字以内，复杂问题分点说明。

LangBot 的 prompt 是消息对象数组，普通场景只放一条 role: system 即可。

人设放 LangBot 还是控制台 Agent？两种策略见「深入」。

4. 测试连通：在 LangBot WebUI 用刚配的模型发一条测试消息，收到回复即链路已通。报错则对照「常见问题」排查。

第三部分：接入 IM 平台

LangBot 支持飞书、钉钉、企业微信、微信、QQ、Telegram、Discord、Slack、LINE 等。各平台需在对应开发者后台创建应用、配置回调，具体步骤见 LangBot 官方文档「消息平台（Messaging Platforms）」章节。

典型流程（以飞书为例）：

1. 在飞书开放平台创建企业自建应用，获取 App ID 和 App Secret。
2. 配置事件订阅，把 LangBot 的 Webhook 地址填入飞书应用。
3. 在 LangBot WebUI「消息平台 → 飞书」填入 App ID / App Secret 并启用。
4. 在飞书中 @机器人 或私聊发消息验证。

各平台字段以 LangBot WebUI 实际显示为准。IM 平台配置以 LangBot 文档为权威。

第四部分：端到端验证

1. 在 IM 平台向客服机器人发一条咨询消息（如「怎么创建 API Key？」）。
2. 机器人应基于客服人设回复。
3. 回到控制台验证：
   • 在「会话记录」中能看到这次调用，详见 24-查会话记录。
   • 在「Token 统计」中能看到 Token 消耗，详见 25-查 Token 统计。

怎么验证成功了

常见问题

LangBot 调用返回 401 认证失败

检查 LangBot 供应商配置中的 API Key：

1. 是否是完整的 sk-u- 开头的用户 API Key，不是管理员登录密码。
2. API Key 是否被删除或禁用。
3. 对应用户账号是否被禁用。

LangBot 调用返回 403 权限不足

• 模型不在白名单：LangBot 模型 ID 填的 display_name 不在该用户的模型白名单中。去控制台把模型加入白名单。
• 白名单为空：非 Agent 路径下白名单为空直接 403，管理员也不豁免，必须显式配置。
• 客户端不在白名单：LangBot 的客户端标识 AsyncOpenAI 未登记到「全局配置 -> 客户端设置 -> 客户端白名单」。客户端白名单默认只含平台内置客户端，第三方必须显式登记，否则 403。见 全局配置。

LangBot 调用返回「模型不存在」

模型 ID 填的不是 display_name。用以下命令确认正确名称：

curl -s https://www.aimatespace.com/openai/v1/models \
  -H "Authorization: Bearer sk-u-xxx"

返回的模型名就是该填入 LangBot「模型 ID」的值。

Base URL 末尾带了 / 导致 404

https://www.aimatespace.com/openai/v1/（末尾有 /）会被部分客户端拼成 //chat/completions。去掉末尾 /。

流式响应解析异常或卡住

平台流式响应有两个特性，标准 OpenAI 客户端通常能正常处理，若异常请排查：

1. 心跳行：平台每 15 秒发送 : PING（以 : 开头的行），客户端应忽略。SSE 规范中 : 开头是注释，符合规范的解析器会自动跳过。
2. 错误事件：流式错误以 event: error 发送，且错误后不会再发 [DONE]。客户端必须处理 event: error，不能只等 [DONE]。

若 LangBot 流式异常，可先关闭流式（若支持）验证非流式是否正常，再排查流式解析。

LangBot 提示连接超时

• 确认 LangBot 所在机器能访问 https://www.aimatespace.com。
• 平台 LLM 请求超时为 60s，超长上下文可能触发上游超时。

机器人回复没有遵循客服人设

• 确认人设写在 LangBot Pipeline 的 prompt（role: system）中，且对应 Pipeline 已启用。
• 若同时用了控制台 Agent 人设，注意两者可能叠加或冲突，见「深入」的策略说明。

多轮对话后机器人「失忆」

多轮上下文由 LangBot 维护（它负责拼接历史消息）。检查 LangBot 会话管理配置，确认历史消息长度未超限。平台侧 messages 上限 500 条。

深入

客服人设放在哪一层：两种策略

人设（system prompt）可以放在 LangBot 或控制台，各有取舍：

策略 B 的做法：在控制台创建一个客服 Agent，配置系统提示词并绑定模型（见 06-创建并配置智能体），把该 Agent 分配给客服用户。调用时带 agent_id 参数。注意：

• agent_id 必须是加密字符串（EncryptedID），从控制台 Agent 详情页获取，不接受明文整数 ID。
• 带 agent_id 时鉴权规则变化：不再看用户白名单，而是按 Agent 绑定模型鉴权；Agent 未绑定模型时回退租户默认模型 / 默认模型组。
• LangBot 的 openai-chat-completions 请求器是否支持透传 extra_body / 自定义请求体，请查阅 LangBot 当前版本文档确认。

让客服调用业务系统（工具调用）

AI 客服常需要查询订单、工单状态等业务数据。两条路径：

1. 控制台 MCP 网关：在控制台注册业务系统的 MCP Server（见 15-注册上游 MCP Server），同步工具后作为服务端工具（mcp__ 前缀）自动执行。客服调用时无需 LangBot 参与，平台自动完成工具调用循环（最多 5 轮）。
2. LangBot 插件：在 LangBot 插件市场安装业务对接插件，作为客户端工具执行。

mcp__ 前缀的工具是平台服务端工具，由平台自动执行；不带 mcp__ 前缀的是客户端工具，需要 LangBot 自己执行后回传结果。

知识库 RAG

LangBot 内置 RAG，支持接入向量数据库（Chroma、Qdrant、Milvus 等）。在 LangBot Pipeline 中关联知识库后，机器人会先检索知识库再生成回复，适合接入产品文档、FAQ。

若要用平台侧 Embedding 模型，需在控制台接入一个 Embedding 模型并加入用户白名单，供 LangBot 的嵌入模型配置使用。见 外部接入 的 Embedding 端点说明。

监控与成本控制

• Token 统计：所有经平台的调用都在 Token 统计 中计量，可按用户、模型查看消耗。
• 会话日志：会话记录 保留每次请求的完整消息，可用于客服质量抽检。
• 审计与安全：审计与安全事件 记录 API Key 调用、鉴权失败等，便于排查异常访问。
• 计费：余额与充值 控制客服机器人的消费上限。

安全注意事项

1. API Key 保管：LangBot 中存储的 sk-u- Key 等同于该用户的调用凭证，妥善保管，不要提交到代码仓库。建议客服机器人用独立用户 + 独立 Key，便于随时吊销。
2. 最小权限：客服用户的模型白名单只放必要的模型，避免误用高价模型。
3. 人设防泄露：客服人设中不要写入内部敏感信息（内部系统地址、密钥等），人设可能通过特定 prompt 被用户套出。
4. 速率限制：平台聊天速率 30/min（IP 粒度），通用 60/min。若客服并发高，可在 LangBot 侧做排队。

配置速查表

• 想了解 OpenAI 兼容 API 完整参数与错误码？见 外部接入
• 想让客服调用业务系统工具？见 注册上游 MCP Server
• 想查看客服调用记录与 Token 消耗？见 查会话记录 和 查 Token 统计
• LangBot 官方文档：https://docs.langbot.app