API 参考

LibreFang 在守护进程运行时提供 REST API、WebSocket 端点和 SSE 流式传输。默认监听地址为 http://127.0.0.1:4545。

所有响应均包含安全头（CSP、X-Frame-Options、X-Content-Type-Options、HSTS），并受 GCRA 成本感知速率限制器保护，支持按 IP 的令牌桶追踪和过期条目自动清理。LibreFang 实现了 16 个安全系统，包括 Merkle 审计链、污点追踪、WASM 双重计量、Ed25519 清单签名、SSRF 防护、子进程沙箱和密钥归零。

目录

代理与工作流 API

Agent 端点、工作流端点、触发器端点、调度端点、目标端点、定时任务端点

系统与配置 API

模板端点、系统端点、配置管理、会话管理、任务队列、备份和恢复、迁移、绑定和命令

智能与技能 API

记忆端点、技能和市场、ClawHub、Hands、扩展、插件、媒体生成

供应商与模型 API

模型目录、提供商配置

通信与网络 API

通道端点、MCP 和 A2A 协议、审计和安全、用量和分析、预算、Webhooks、集成、配对、OAuth/OIDC、通信、审批、网络和对等节点

实时 API

WebSocket 协议、SSE 流式传输、OpenAI 兼容 API

• 认证
• 错误响应
• 端点汇总

认证

在 config.toml 中配置 API 密钥后，所有端点（除 /api/health 和 / 外）均需要 Bearer 令牌：

Authorization: Bearer <your-api-key>

设置 API 密钥

在 ~/.librefang/config.toml 中添加：

api_key = "your-secret-api-key"

无认证模式

如果 api_key 为空或未设置，则 API 无需认证即可访问。此模式下 CORS 仅限 localhost 来源。

公共端点（无需认证）

• GET /api/health
• GET / (WebChat UI)

错误响应

所有错误响应使用统一的 JSON 格式：

{
  "error": "Description of what went wrong"
}

HTTP 状态码

请求 ID

每个响应都包含 x-request-id 头，其值为用于追踪的 UUID：

x-request-id: 550e8400-e29b-41d4-a716-446655440000

在报告问题或在日志中关联请求时使用此值。

安全头

每个响应都包含安全头：

速率限制

GCRA（通用信元速率算法）速率限制器提供成本感知的令牌桶速率限制，支持按 IP 追踪和过期条目自动清理。不同端点消耗不同的令牌成本（例如 /api/agents/{id}/message 的成本高于 /api/health）。当超出限制时，服务器返回 429 Too Many Requests：

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{"error": "Rate limit exceeded"}

Retry-After 头以秒为单位指示窗口持续时间。

端点汇总

230+ 个端点，分布在 35 个分组中。