FastClaw / API 与集成
用户与 Key
生产接入 FastClaw 的关键不是只发一个 API key，而是设计 app_user、end user、Agent ACL、quota 和会话隔离。
密钥类型
FastClaw key 有 admin、user、agent 三类。admin 适合后台运维，user 适合某个控制台用户，agent key 适合只暴露单个 Agent 能力。
| 类型 | 适合场景 | 风险 |
|---|---|---|
| admin | 服务端管理、内部任务 | 权限最大，不应出现在客户端 |
| user | 上游服务端按用户代理调用 | 需要 ACL 和 quota |
| agent | 只调用特定 Agent | 仍要防止泄露和滥用 |
app_user 模型
docs/upstream-api.md 支持显式 POST /v1/users 绑定 external_id，也支持 chat 时通过 user 或 X-Fastclaw-End-User 懒创建。
1
上游登录
你的产品完成自己的登录与计费。
2
映射用户
把产品用户 ID 传给 FastClaw 的 user 或 X-Fastclaw-End-User。
3
隔离会话
FastClaw 按 end user 分区 session、memory、USER.md。
4
查询用量
通过 /v1/usage 和 quota 接入自己的账单或限制。
Session Key
X-Fastclaw-Session-Key 用于让同一上游会话稳定落到同一个 FastClaw session。没有显式 session key 时，服务端会生成或按默认规则映射。
推荐实践
把 session key 设计成产品会话 ID，不要用用户 ID 本身；同一个用户可能同时打开多个不同上下文。