FastClaw / API 与集成

上游 API

FastClaw 为上游应用提供 /v1/* API，核心是 OpenAI-compatible chat completions，再加 agents、users、usage、quota。

API 边界

docs/upstream-api.md 明确说 /v1/* 是给上游应用使用的稳定接口；/api/* 和 CLI 更偏 operator/admin workflow。

接口	用途
POST /v1/chat/completions	OpenAI-compatible 对话，支持 stream 和非 stream
GET /v1/agents	列出当前 key 可访问的 Agent
POST /v1/users	显式创建或绑定 app_user
GET /v1/usage	查询用量
/v1/quota	查询或消费配额相关能力

认证

上游 API 使用 Authorization: Bearer fcak_...。API key 类型包括 admin、user、agent。文档强调不要把 key 暴露给浏览器或移动端。

curl http://localhost:18953/v1/chat/completions \
  -H "Authorization: Bearer fcak_xxx" \
  -H "Content-Type: application/json" \
  -d '{"agent_id":"agt_xxx","messages":[{"role":"user","content":"你好"}]}'

Chat 扩展字段

除了 OpenAI messages/model/stream，FastClaw 还支持 agent_id、user、params、images、imageUrls、attachments，以及 X-Fastclaw-Session-Key 和 X-Fastclaw-End-User 等 header。

agent_id：选择处理请求的 Agent。
user 或 X-Fastclaw-End-User：映射上游产品里的终端用户。
attachments：服务端会 materialize 到 /workspace，并把路径注入消息。
X-Fastclaw-Session-Key：让上游应用稳定复用同一会话。