嵌入指南 · 开发文档 · Fellow

状态：Preview（Interaction） — Widget、短期 Access Token 与 Thread / Run 嵌入链路可用于受控试用；Integration App 的管理与发布能力仍为 Experimental。请按实际 Gateway、Console 与 SDK 版本验证字段和行为。

本指南面向 SDK Widget 嵌入（如官网客服、CRM 内嵌助手），架构如下：

浏览器
  │  FellowChatWidget + access_token
  ▼
你的后端  /api/.../access-token  (持 fkey_，仅服务端)
  │  POST /api/apps/token
  ▼
Fellow Gateway  (Integration App 鉴权 + CORS)
  │  Thread / Run
  ▼
runtimeUserId 的 harness

原则：fkey_ 只在你的服务端；浏览器只用短期 access_token。

1. Console · Integration App

项	说明
Runtime 用户	绑定客服/助手使用的 Agent 与 Skills
default_agent	Run 未指定 agent 时使用
allowed_origins	与浏览器 Origin 完全一致（含 `https`，无尾斜杠）
scopes	至少 threads + runs（含 consent 若需要）

本地开发额外添加：http://localhost:5174（或实际 dev 端口）。

2. 环境变量（部署侧）

变量	说明
`FELLOW_APP_API_KEY`	`fkey_…`，仅服务端
`FELLOW_APP_ID`	`app_…`，多 App 时建议指定
`FELLOW_API_URL`	Gateway API，如 `https://app.fellow.work/api`（服务端 token 路由读取，经 `api_base_url` 传给 Widget）
`FELLOW_CLIENT_ORIGIN`	与 `allowed_origins` 一致（代理场景必填）

3. 后端 Token 交换

const { access_token } = await fellowClient.createAccessToken({
  origin: 'https://your-app.com',
  external_user_id: visitorId, // 同一访客复用 thread
});

将 access_token 返回给前端；不要返回 fkey_。

4. 前端挂载

import { FellowChatWidget } from '@fellow.work/client/react';

// baseUrl 来自服务端 token 交换响应中的 api_base_url（推荐），或直接传入 Gateway 地址
<FellowChatWidget
  baseUrl={apiBaseUrl}
  accessToken={token}
/>

Widget 默认在 Shadow DOM 内自带样式，不要在宿主页面 import @fellow.work/client/ui.css。

5. 部署前检查

@fellow.work/client 已安装
allowed_origins 含生产域名
default_agent 在 runtime 用户下可用
Gateway 公网可达
服务端 env 已配置 FELLOW_APP_API_KEY

6. Smoke Test

打开页面 → Widget 按钮出现
发消息 → Agent 正常回复
刷新 → 同一 external_user_id 复用 thread
Network：access-token 200；Gateway 请求带 Bearer eyJ…
Console → 接入应用 → 对话列表可见 thread

常见问题

现象	排查
Widget 不显示	token 交换失败或 origin 不在 allowed_origins
CORS 错误	`allowed_origins` 与请求 Origin 不一致
403 on Gateway	Scope 不足或 App 已 disabled