不自建 Agent 平台，也能给你的 SaaS 加上 AI Agent

"让每个客户都有自己的 AI 助手"听起来像一个功能，做起来却是一个平台：每个客户一个 Agent、彼此隔离的历史和记忆、执行工具的沙箱、流式输出、文件产物，还要知道每个客户花了你多少钱。

本文介绍一种做法：把 Agent 运行时当作后端服务来用。用户、权限和计费仍归你的应用；Agent 交给 FastClaw 来跑。所有示例都使用公开的 /v1 API —— 每个 FastClaw 实例都在 /skills/agent-integration/SKILL.md 提供了同一份文档。

职责划分

把这一点想清楚，剩下的都只是管道：

• 你的应用负责：登录、哪个用户能用哪个 Agent、你自己的聊天记录，以及计费。
• FastClaw 负责：Agent 配置、Agent 循环、工具与沙箱、会话、记忆和用量计量。

FastClaw 从不回调你的应用，也不需要知道用户的邮箱。你的后端调用 FastClaw；浏览器和移动端只和你的后端通信。

第 1 步：配置连接

服务端需要两个配置：

FASTCLAW_BASE_URL=https://claw.example.com   # 末尾不要带斜杠
FASTCLAW_API_KEY=fc_...                       # 控制台 → API Keys 中创建

先验证一下，再写后续代码：

curl -s "$FASTCLAW_BASE_URL/v1/agents" \
  -H "Authorization: Bearer $FASTCLAW_API_KEY"

返回 200 会列出该 Key 可用的 Agent；401 unauthorized 说明 Key 错误或已被吊销。

第 2 步：选对 Key 类型

集成场景下主要有两种 Key：

• Agent Key：被授予若干个已存在的 Agent。适合你的应用只对接固定的几个 Agent，比如客服机器人、图片编辑助手。
• User Key：可以访问所属 FastClaw 账号下的所有 Agent，并能创建和删除 Agent。适合按需创建 Agent，比如每个客户或每个工作区一个。

"每个客户一个 Agent"的场景需要 User Key —— 并且应当使用专门为此集成准备的 FastClaw 账号，每个环境各一个（myapp-prod、myapp-dev），这样这把 Key 永远碰不到其他用途的 Agent。

第 3 步：为每个客户创建 Agent

客户开启该功能时，创建他的 Agent，并把对应关系存进你自己的数据库：

const res = await fetch(`${process.env.FASTCLAW_BASE_URL}/v1/agents`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.FASTCLAW_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme 助手',
    description: '回答 Acme 项目相关的问题',
    instructions: '你是 Acme 团队的简洁助手。',
    metadata: { workspace_id: 'ws_123' },
  }),
});
const { agent } = await res.json();
// 把 agent.id 和 ws_123 一起存进你的数据库

几个值得注意的细节：

• 只有 name 是必填的。instructions 会成为 Agent 的 SOUL.md。
• model 的格式是 provider/model；不传则使用账号默认模型。之后可以用 PATCH /v1/agents/{id} 修改 —— 详见 模型。
• metadata 归你使用：最多 16 个字符串键，可通过 GET /v1/agents?metadata[workspace_id]=ws_123 过滤。它从不参与权限判断。
• 更完整的身份文件（IDENTITY.md、AGENTS.md、KNOWLEDGE.md 等）可以用 PUT /v1/agents/{id}/system-files/{name} 写入。

如果你的产品是一个共享助手，而不是每个客户一个，可以跳过这一步，在控制台里创建一次即可。后面的步骤完全相同。

第 4 步：对话，并带上终端用户

这是你的产品在每条消息上都会发出的请求：

const res = await fetch(
  `${process.env.FASTCLAW_BASE_URL}/v1/chat/completions`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.FASTCLAW_API_KEY}`,
      'Content-Type': 'application/json',
      'X-Fastclaw-Session-Key': `myapp:${conversationId}`,
      'X-Fastclaw-End-User': currentUser.id,
    },
    body: JSON.stringify({
      agent_id: agentId,
      stream: true,
      messages: [{ role: 'user', content: userMessage }],
    }),
  }
);

关键在三个字段：

• agent_id 是严格匹配的。如果这把 Key 无权使用该 Agent，你会收到 404 agent_not_found —— 绝不会被别的 Agent 代答。
• X-Fastclaw-Session-Key 决定使用哪段对话历史。它应当是确定性的，并带上你的应用前缀。不传的话，每次调用都会开启新会话。
• X-Fastclaw-End-User（或请求体里的 user 字段）是你的用户的稳定 ID。它让该用户的会话历史和个人记忆（USER.md、MEMORY.md）只属于他本人，同时共享 Agent 的人设和技能。如果所有人应当共享同一份记忆 —— 比如用户自己的私人 Agent —— 就不要传。

只发送最新的一条用户消息即可。FastClaw 会按会话 Key 自行保存历史。

每次调用前，你的后端都必须确认当前登录用户有权使用这个 Agent。FastClaw 只负责账号与 Key 之间的隔离，它并不了解你的权限模型。

第 5 步：处理流式响应

响应是标准的 OpenAI 风格 SSE，大多数 OpenAI 客户端库都能直接解析。FastClaw 额外提供了两点，便于做出更好的界面：

• 工具进度。当 Agent 开始或结束一次工具调用时，你会收到一个 delta 为空、顶层带 tool 对象的分片 —— name 如 exec、read_file，status 为 running 或 done。用你自己的话把它展示成进度步骤即可。
• 错误就是错误。如果模型 API 失败，流的最后一个分片会带上 error 对象（非流式请求则返回 502，code 为 agent_error）。请把它当作"什么都没产出"：不要计费，允许重试。

所有 /v1 错误格式一致，可以按 error.code 分支处理：invalid_request、unauthorized、forbidden、agent_quota_exceeded、agent_not_found、payment_required、rate_limited 等。

第 6 步：返回 Agent 生成的文件

会修图、会写报告的 Agent 都会产出文件。FastClaw 把它们放在 files 数组里返回 —— 非流式在顶层，流式在最后一个分片上 —— 每个文件带一个 url，用相同的 Authorization 和 X-Fastclaw-End-User 请求头下载即可。终端用户只能读取自己对话里的文件。如果只是一张小图，传 "return_files": "inline" 就能直接拿到 data_url。

由于 API 对话中的工具始终在沙箱里运行，客户让 Agent"跑一下这个脚本"时，永远碰不到你的 FastClaw 主机。

第 7 步：计量与计费

每次回复都带有 usage，汇总了这一轮中所有的模型调用（包括工具循环）：OpenAI 风格的 prompt_tokens 和 completion_tokens，以及缓存读写数量和 model_calls。按轮次记到对应客户名下即可。

做报表时，GET /v1/usage 返回按天聚合的数据，可按 agent_id 和 end_user 过滤；/v1/quota 可以为某个终端用户设置每月 Token 或请求次数上限。如果你是在为他人运营 FastClaw，管理端的计费钩子（用量导出和计费冻结）可以让外部计费系统暂停某个账号，此时它的 API 调用会返回 402 payment_required。

上线前检查清单

• FASTCLAW_BASE_URL 和 FASTCLAW_API_KEY 只存在于服务端配置中。
• 每个环境使用一个专用账号下的 User Key。
• 每次调用前，你的应用都会检查用户对该 Agent 的访问权限。
• 每段对话使用确定性的会话 Key；需要隐私隔离时一定带上终端用户。
• SSE 解析支持工具进度和 error.code 处理。
• 文件一律从 files 中获取，不要猜路径。
• 按轮次保存用量。

下一步

面向 SaaS 开发者的方案展示了这些能力如何组合成一个产品。如果你的客户主要在聊天软件里而不是你的网页上，同一批 Agent 也可以通过渠道在 Slack 或 Telegram 中回复。想在自托管和托管方案之间做选择，请看定价。