LibreFang
EN

API 参考

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

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

目录

认证

在 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）

Agent 端点

GET /api/agents

列出所有运行中的 Agent。

响应 200 OK：

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "hello-world",
    "state": "Running",
    "created_at": "2025-01-15T10:30:00Z",
    "model_provider": "groq",
    "model_name": "llama-3.3-70b-versatile"
  }
]

GET /api/agents/{id}

获取单个 Agent 的详细信息。

响应 200 OK：

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "hello-world",
  "state": "Running",
  "created_at": "2025-01-15T10:30:00Z",
  "session_id": "s1b2c3d4-...",
  "model": {
    "provider": "groq",
    "model": "llama-3.3-70b-versatile"
  },
  "capabilities": {
    "tools": ["file_read", "file_list", "web_fetch"],
    "network": []
  },
  "description": "A friendly greeting agent",
  "tags": []
}

POST /api/agents

从 TOML 清单创建新 Agent。

请求体（JSON）：

{
  "manifest_toml": "name = \"my-agent\"\nversion = \"0.1.0\"\ndescription = \"Test agent\"\nauthor = \"me\"\nmodule = \"builtin:chat\"\n\n[model]\nprovider = \"groq\"\nmodel = \"llama-3.3-70b-versatile\"\n\n[capabilities]\ntools = [\"file_read\", \"web_fetch\"]\nmemory_read = [\"*\"]\nmemory_write = [\"self.*\"]\n"
}

响应 201 Created：

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "my-agent"
}

PUT /api/agents/{id}/update

在运行时更新 Agent 配置。

请求体：

{
  "description": "Updated description",
  "system_prompt": "You are a specialized assistant.",
  "tags": ["updated", "v2"]
}

响应 200 OK：

{
  "status": "updated",
  "agent_id": "a1b2c3d4-..."
}

PUT /api/agents/{id}/mode

设置 Agent 运行模式。Stable 模式会固定当前模型并冻结技能注册表。Normal 模式恢复默认行为。

请求体：

{
  "mode": "Stable"
}

响应 200 OK：

{
  "status": "updated",
  "mode": "Stable",
  "agent_id": "a1b2c3d4-..."
}

POST /api/agents/{id}/message

向 Agent 发送消息并接收完整响应。

请求体：

{
  "message": "What files are in the current directory?"
}

响应 200 OK：

{
  "response": "Here are the files in the current directory:\n- Cargo.toml\n- README.md\n...",
  "input_tokens": 142,
  "output_tokens": 87,
  "iterations": 1
}

GET /api/agents/{id}/session

获取 Agent 的对话历史。

响应 200 OK：

{
  "session_id": "s1b2c3d4-...",
  "agent_id": "a1b2c3d4-...",
  "message_count": 4,
  "context_window_tokens": 1250,
  "messages": [
    {
      "role": "User",
      "content": "Hello"
    },
    {
      "role": "Assistant",
      "content": "Hello! How can I help you?"
    }
  ]
}

DELETE /api/agents/{id}

终止 Agent 并从注册表中移除。

响应 200 OK：

{
  "status": "killed",
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

工作流端点

GET /api/workflows

列出所有已注册的工作流。

响应 200 OK：

[
  {
    "id": "w1b2c3d4-...",
    "name": "code-review-pipeline",
    "description": "Automated code review workflow",
    "steps": 3,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST /api/workflows

创建新的工作流定义。

请求体（JSON）：

{
  "name": "code-review-pipeline",
  "description": "Review code changes with multiple agents",
  "steps": [
    {
      "name": "analyze",
      "agent_name": "coder",
      "prompt": "Analyze this code for potential issues: {&lbrace;input&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 120,
      "error_mode": "fail",
      "output_var": "analysis"
    },
    {
      "name": "security-check",
      "agent_name": "security-auditor",
      "prompt": "Review this code analysis for security vulnerabilities: {&lbrace;analysis&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 120,
      "error_mode": "skip"
    },
    {
      "name": "summarize",
      "agent_name": "writer",
      "prompt": "Write a concise code review summary based on: {&lbrace;analysis&rbrace;}",
      "mode": "sequential",
      "timeout_secs": 60,
      "error_mode": "fail"
    }
  ]
}

步骤配置选项：

字段类型描述
namestring步骤名称
agent_idstringAgent UUID（与 agent_name 二选一）
agent_namestringAgent 名称（与 agent_id 二选一）
promptstring提示词模板，支持 {&lbrace;input&rbrace;} 和 {&lbrace;output_var&rbrace;} 占位符
modestring"sequential"、"fan_out"、"collect"、"conditional"、"loop"
timeout_secsinteger每步超时时间（默认：120）
error_modestring"fail"、"skip"、"retry"
max_retriesinteger"retry" 错误模式的最大重试次数（默认：3）
output_varstring存储输出的变量名，供后续步骤使用
conditionstring用于 "conditional" 模式的条件表达式
max_iterationsinteger"loop" 模式的最大迭代次数（默认：5）
untilstring"loop" 模式的停止条件

响应 201 Created：

{
  "workflow_id": "w1b2c3d4-..."
}

POST /api/workflows/{id}/run

执行工作流。

请求体：

{
  "input": "Review this pull request: ..."
}

响应 200 OK：

{
  "run_id": "r1b2c3d4-...",
  "output": "Code review summary:\n- No critical issues found\n...",
  "status": "completed"
}

GET /api/workflows/{id}/runs

获取工作流的执行历史。

响应 200 OK：

[
  {
    "id": "r1b2c3d4-...",
    "workflow_name": "code-review-pipeline",
    "state": "Completed",
    "steps_completed": 3,
    "started_at": "2025-01-15T10:30:00Z",
    "completed_at": "2025-01-15T10:32:15Z"
  }
]

触发器端点

GET /api/triggers

列出所有触发器。可按 Agent 筛选。

查询参数：

  • agent_id（可选）：按 Agent UUID 筛选

响应 200 OK：

[
  {
    "id": "t1b2c3d4-...",
    "agent_id": "a1b2c3d4-...",
    "pattern": {"lifecycle": {}},
    "prompt_template": "Event: {&lbrace;event&rbrace;}",
    "enabled": true,
    "fire_count": 5,
    "max_fires": 0,
    "created_at": "2025-01-15T10:30:00Z"
  }
]

POST /api/triggers

创建新的事件触发器。

请求体：

{
  "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "pattern": {
    "agent_spawned": {
      "name_pattern": "*"
    }
  },
  "prompt_template": "A new agent was spawned: {&lbrace;event&rbrace;}. Review its capabilities.",
  "max_fires": 0
}

支持的模式类型：

模式描述
{"lifecycle": {}}所有生命周期事件
{"agent_spawned": {"name_pattern": "*"}}Agent 创建事件
{"agent_terminated": {}}Agent 终止事件
{"all": {}}所有事件

响应 201 Created：

{
  "trigger_id": "t1b2c3d4-...",
  "agent_id": "a1b2c3d4-..."
}

PUT /api/triggers/{id}

更新已有触发器的配置。

请求体：

{
  "prompt_template": "Updated template: {&lbrace;event&rbrace;}",
  "enabled": false,
  "max_fires": 10
}

响应 200 OK：

{
  "status": "updated",
  "trigger_id": "t1b2c3d4-..."
}

DELETE /api/triggers/{id}

删除触发器。

响应 200 OK：

{
  "status": "removed",
  "trigger_id": "t1b2c3d4-..."
}

内存端点

GET /api/memory/agents/{id}/kv

列出 Agent 的所有键值对。

响应 200 OK：

{
  "kv_pairs": [
    {"key": "preferences", "value": {"theme": "dark"}},
    {"key": "state", "value": {"step": 3}}
  ]
}

GET /api/memory/agents/{id}/kv/{key}

获取指定键值对。

响应 200 OK：

{
  "key": "preferences",
  "value": {"theme": "dark"}
}

响应 404 Not Found（键不存在）：

{
  "error": "Key 'preferences' not found"
}

PUT /api/memory/agents/{id}/kv/{key}

设置键值对。如果已存在则覆盖。

请求体：

{
  "value": {"theme": "dark", "language": "en"}
}

响应 200 OK：

{
  "status": "stored",
  "key": "preferences"
}

DELETE /api/memory/agents/{id}/kv/{key}

删除键值对。

响应 200 OK：

{
  "status": "deleted",
  "key": "preferences"
}

通道端点

GET /api/channels

列出已配置的通道适配器及其状态。支持 40 种通道适配器，包括 Telegram、Discord、Slack、WhatsApp、Matrix、Email、Teams、Mattermost、IRC、Google Chat、Twitch、Rocket.Chat、Zulip、XMPP、LINE、Viber、Messenger、Reddit、Mastodon、Bluesky 等。

响应 200 OK：

{
  "channels": [
    {
      "name": "telegram",
      "enabled": true,
      "has_token": true
    },
    {
      "name": "discord",
      "enabled": true,
      "has_token": false
    }
  ],
  "total": 2
}

模板端点

GET /api/templates

列出可用的 Agent 模板。

响应 200 OK：

{
  "templates": [
    {
      "name": "hello-world",
      "description": "A friendly greeting agent",
      "path": "/home/user/.librefang/agents/hello-world/agent.toml"
    },
    {
      "name": "coder",
      "description": "Expert coding assistant",
      "path": "/home/user/.librefang/agents/coder/agent.toml"
    }
  ],
  "total": 30
}

GET /api/templates/{name}

获取指定模板的清单和原始 TOML 内容。

响应 200 OK：

{
  "name": "hello-world",
  "manifest": {
    "name": "hello-world",
    "description": "A friendly greeting agent",
    "module": "builtin:chat",
    "tags": [],
    "model": {
      "provider": "groq",
      "model": "llama-3.3-70b-versatile"
    },
    "capabilities": {
      "tools": ["file_read", "file_list", "web_fetch"],
      "network": []
    }
  },
  "manifest_toml": "name = \"hello-world\"\nversion = \"0.1.0\"\n..."
}

系统端点

GET /api/health

公共健康检查。无需认证。返回系统状态的简化版本（不包含数据库或 agent_count 详情）。

响应 200 OK：

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0
}

status 字段在所有系统正常时为 "ok"，在数据库不可达时为 "degraded"。

GET /api/health/detail

完整健康检查，包含所有依赖状态。需要认证。与公共的 /api/health 不同，此端点包含数据库连接状态和 Agent 数量。

响应 200 OK：

{
  "status": "ok",
  "uptime_seconds": 3600,
  "panic_count": 0,
  "restart_count": 0,
  "agent_count": 3,
  "database": "connected",
  "config_warnings": []
}

GET /api/status

详细的内核状态，包含所有 Agent 信息。

响应 200 OK：

{
  "status": "running",
  "agent_count": 2,
  "data_dir": "/home/user/.librefang/data",
  "default_provider": "groq",
  "default_model": "llama-3.3-70b-versatile",
  "uptime_seconds": 3600,
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "hello-world",
      "state": "Running",
      "created_at": "2025-01-15T10:30:00Z",
      "model_provider": "groq",
      "model_name": "llama-3.3-70b-versatile"
    }
  ]
}

GET /api/version

构建和版本信息。

响应 200 OK：

{
  "name": "librefang",
  "version": "0.1.0",
  "build_date": "2025-01-15",
  "git_sha": "abc1234",
  "rust_version": "1.82.0",
  "platform": "linux",
  "arch": "x86_64"
}

POST /api/shutdown

启动优雅关闭。Agent 状态会保存到 SQLite 以便下次启动时恢复。

响应 200 OK：

{
  "status": "shutting_down"
}

GET /api/profiles

列出可用的 Agent 配置文件（常见用例的预定义配置）。

响应 200 OK：

{
  "profiles": [
    {
      "name": "coder",
      "tier": "smart",
      "description": "Expert coding assistant"
    },
    {
      "name": "researcher",
      "tier": "frontier",
      "description": "Deep research and analysis"
    }
  ]
}

GET /api/tools

列出 Agent 可使用的所有工具。

响应 200 OK：

{
  "tools": [
    "file_read",
    "file_write",
    "file_list",
    "web_fetch",
    "web_search",
    "shell_exec",
    "kv_get",
    "kv_set",
    "agent_call"
  ],
  "total": 23
}

GET /api/config

获取当前内核配置（密钥已脱敏）。

响应 200 OK：

{
  "data_dir": "/home/user/.librefang/data",
  "default_provider": "groq",
  "default_model": "llama-3.3-70b-versatile",
  "listen_addr": "127.0.0.1:4200",
  "api_key_set": true,
  "channels_configured": 2,
  "mcp_servers": 1
}

GET /api/peers

列出 OFP（LibreFang 协议）节点及其连接状态。

响应 200 OK：

{
  "peers": [
    {
      "node_id": "peer-1",
      "address": "192.168.1.100:4000",
      "state": "connected",
      "authenticated": true,
      "last_seen": "2025-01-15T10:30:00Z"
    }
  ]
}

GET /api/sessions

列出所有 Agent 的活跃会话。

响应 200 OK：

{
  "sessions": [
    {
      "id": "s1b2c3d4-...",
      "agent_id": "a1b2c3d4-...",
      "agent_name": "coder",
      "message_count": 12,
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

DELETE /api/sessions/{id}

删除指定会话及其对话历史。

响应 200 OK：

{
  "status": "deleted",
  "session_id": "s1b2c3d4-..."
}

模型目录端点

LibreFang 维护一个包含 51+ 模型、覆盖 20 个提供商的内置目录。这些端点允许浏览可用模型、检查提供商认证状态和解析模型别名。

GET /api/models

列出完整的模型目录。返回所有已知模型及其提供商、层级、上下文窗口和定价信息。

响应 200 OK：

{
  "models": [
    {
      "id": "claude-sonnet-4-20250514",
      "provider": "anthropic",
      "display_name": "Claude Sonnet 4",
      "tier": "frontier",
      "context_window": 200000,
      "input_cost_per_1m": 3.0,
      "output_cost_per_1m": 15.0,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    },
    {
      "id": "gemini-2.5-flash",
      "provider": "gemini",
      "display_name": "Gemini 2.5 Flash",
      "tier": "smart",
      "context_window": 1048576,
      "input_cost_per_1m": 0.15,
      "output_cost_per_1m": 0.6,
      "supports_tools": true,
      "supports_vision": true,
      "supports_streaming": true
    }
  ],
  "total": 51
}

GET /api/models/{id}

获取指定模型的详细信息。

响应 200 OK：

{
  "id": "llama-3.3-70b-versatile",
  "provider": "groq",
  "display_name": "Llama 3.3 70B",
  "tier": "fast",
  "context_window": 131072,
  "input_cost_per_1m": 0.59,
  "output_cost_per_1m": 0.79,
  "supports_tools": true,
  "supports_vision": false,
  "supports_streaming": true
}

响应 404 Not Found：

{
  "error": "Model 'unknown-model' not found in catalog"
}

GET /api/models/aliases

列出所有模型别名。别名提供简短名称，可解析为完整的模型 ID（例如 sonnet 解析为 claude-sonnet-4-20250514）。

响应 200 OK：

{
  "aliases": {
    "sonnet": "claude-sonnet-4-20250514",
    "opus": "claude-opus-4-20250514",
    "haiku": "claude-3-5-haiku-20241022",
    "flash": "gemini-2.5-flash",
    "gpt4": "gpt-4o",
    "llama": "llama-3.3-70b-versatile",
    "deepseek": "deepseek-chat",
    "grok": "grok-2",
    "jamba": "jamba-1.5-large"
  },
  "total": 23
}

GET /api/providers

列出所有已知 LLM 提供商及其认证状态。认证状态通过检查环境变量是否存在来检测（不会读取密钥值）。

响应 200 OK：

{
  "providers": [
    {
      "name": "anthropic",
      "display_name": "Anthropic",
      "auth_status": "configured",
      "env_var": "ANTHROPIC_API_KEY",
      "base_url": "https://api.anthropic.com",
      "model_count": 3
    },
    {
      "name": "groq",
      "display_name": "Groq",
      "auth_status": "configured",
      "env_var": "GROQ_API_KEY",
      "base_url": "https://api.groq.com/openai",
      "model_count": 4
    },
    {
      "name": "ollama",
      "display_name": "Ollama",
      "auth_status": "no_key_needed",
      "base_url": "http://localhost:11434",
      "model_count": 0
    }
  ],
  "total": 20
}

提供商配置端点

在运行时管理 LLM 提供商 API 密钥，无需编辑配置文件或重启守护进程。

POST /api/providers/{name}/key

设置提供商的 API 密钥。密钥安全存储并立即生效。

请求体：

{
  "api_key": "sk-..."
}

响应 200 OK：

{
  "status": "configured",
  "provider": "anthropic"
}

DELETE /api/providers/{name}/key

移除提供商的 API 密钥。使用该提供商的 Agent 将回退到 FallbackDriver 或失败。

响应 200 OK：

{
  "status": "removed",
  "provider": "anthropic"
}

POST /api/providers/{name}/test

通过发起最小 API 调用来测试提供商连接。验证配置的 API 密钥是否有效以及提供商端点是否可达。

响应 200 OK：

{
  "status": "ok",
  "provider": "anthropic",
  "latency_ms": 245,
  "model_tested": "claude-sonnet-4-20250514"
}

响应 401 Unauthorized：

{
  "status": "failed",
  "provider": "anthropic",
  "error": "Invalid API key"
}

技能与市场端点

管理技能注册表。技能通过 Python、Node.js、WASM 或纯提示词模块扩展 Agent 能力。所有技能安装都会经过 SHA256 验证和提示词注入扫描。

GET /api/skills

列出所有已安装的技能。

响应 200 OK：

{
  "skills": [
    {
      "name": "github",
      "version": "1.0.0",
      "runtime": "prompt_only",
      "description": "GitHub integration for issues, PRs, and repos",
      "bundled": true
    },
    {
      "name": "docker",
      "version": "1.0.0",
      "runtime": "prompt_only",
      "description": "Docker container management",
      "bundled": true
    }
  ],
  "total": 60
}

POST /api/skills/install

从本地路径或 URL 安装技能。技能清单会经过验证（SHA256 校验和）并在安装前扫描提示词注入。

请求体：

{
  "source": "/path/to/skill",
  "verify": true
}

响应 201 Created：

{
  "status": "installed",
  "skill": "my-custom-skill",
  "version": "1.0.0"
}

POST /api/skills/uninstall

卸载已安装的技能。内置技能不能被卸载。

请求体：

{
  "name": "my-custom-skill"
}

响应 200 OK：

{
  "status": "uninstalled",
  "skill": "my-custom-skill"
}

POST /api/skills/create

从模板创建新技能。

请求体：

{
  "name": "my-skill",
  "runtime": "python",
  "description": "A custom skill"
}

响应 201 Created：

{
  "status": "created",
  "skill": "my-skill",
  "path": "/home/user/.librefang/skills/my-skill"
}

GET /api/marketplace/search

搜索 FangHub 市场中的社区技能。

查询参数：

  • q（必填）：搜索关键词
  • page（可选）：页码（默认：1）

响应 200 OK：

{
  "results": [
    {
      "name": "weather-api",
      "author": "community",
      "description": "Real-time weather data integration",
      "downloads": 1250,
      "version": "2.1.0"
    }
  ],
  "total": 1,
  "page": 1
}

ClawHub 端点

浏览和安装来自 ClawHub（OpenClaw 生态系统兼容）的技能。所有安装都经过完整的安全流水线：SHA256 验证、SKILL.md 安全扫描和信任边界执行。

GET /api/clawhub/search

在 ClawHub 中搜索兼容的技能。

查询参数：

  • q（必填）：搜索关键词

响应 200 OK：

{
  "results": [
    {
      "slug": "data-pipeline",
      "name": "Data Pipeline",
      "description": "ETL data pipeline automation",
      "author": "clawhub-community",
      "version": "1.2.0"
    }
  ],
  "total": 1
}

GET /api/clawhub/browse

浏览 ClawHub 分类。

查询参数：

  • category（可选）：按分类筛选
  • page（可选）：页码（默认：1）

响应 200 OK：

{
  "skills": [
    {
      "slug": "data-pipeline",
      "name": "Data Pipeline",
      "category": "data",
      "description": "ETL data pipeline automation"
    }
  ],
  "total": 15,
  "page": 1
}

GET /api/clawhub/skill/{slug}

获取指定 ClawHub 技能的详细信息。

响应 200 OK：

{
  "slug": "data-pipeline",
  "name": "Data Pipeline",
  "description": "ETL data pipeline automation",
  "author": "clawhub-community",
  "version": "1.2.0",
  "runtime": "python",
  "readme": "# Data Pipeline\n\nAutomated ETL...",
  "sha256": "a1b2c3d4..."
}

POST /api/clawhub/install

从 ClawHub 安装技能。下载后验证 SHA256 校验和、扫描提示词注入，并自动将 SKILL.md 格式转换为 LibreFang 的 skill.toml。

请求体：

{
  "slug": "data-pipeline"
}

响应 201 Created：

{
  "status": "installed",
  "skill": "data-pipeline",
  "version": "1.2.0",
  "converted_from": "SKILL.md"
}

MCP 与 A2A 协议端点

LibreFang 支持 Model Context Protocol（MCP）用于工具互操作，以及 Agent-to-Agent（A2A）协议用于跨系统 Agent 通信。

GET /api/mcp/servers

列出已配置和已连接的 MCP 服务器及其可用工具。

响应 200 OK：

{
  "servers": [
    {
      "name": "filesystem",
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "connected": true,
      "tools": [
        {
          "name": "mcp_filesystem_read_file",
          "description": "Read a file from the filesystem"
        },
        {
          "name": "mcp_filesystem_write_file",
          "description": "Write content to a file"
        }
      ]
    }
  ],
  "total": 1
}

POST /mcp

MCP HTTP 传输端点。接受 JSON-RPC 2.0 请求，并通过 MCP 协议向外部客户端公开 LibreFang 工具。

请求体（JSON-RPC 2.0）：

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

响应 200 OK：

{
  "jsonrpc": "2.0",
  "result": {
    "tools": [
      {
        "name": "file_read",
        "description": "Read a file's contents",
        "inputSchema": {
          "type": "object",
          "properties": {
            "path": {"type": "string"}
          }
        }
      }
    ]
  },
  "id": 1
}

GET /.well-known/agent.json

A2A Agent Card 发现端点。返回服务器的 A2A Agent Card，描述其能力、支持的协议和可用 Agent。

响应 200 OK：

{
  "name": "LibreFang",
  "description": "LibreFang Agent Operating System",
  "url": "http://127.0.0.1:4200",
  "version": "0.1.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": false
  },
  "skills": [
    {
      "id": "chat",
      "name": "Chat",
      "description": "General-purpose chat with any agent"
    }
  ]
}

GET /a2a/agents

列出通过 A2A 协议可用的 Agent。

响应 200 OK：

{
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "coder",
      "description": "Expert coding assistant",
      "skills": ["code-review", "debugging", "refactoring"]
    }
  ]
}

POST /a2a/tasks/send

通过 A2A 协议向 Agent 发送任务。遵循 Google A2A 规范进行跨 Agent 任务委派。

请求体：

{
  "agent_id": "a1b2c3d4-...",
  "message": {
    "role": "user",
    "parts": [
      {"text": "Review this code for security issues"}
    ]
  }
}

响应 200 OK：

{
  "task_id": "task-1234-...",
  "status": "completed",
  "result": {
    "role": "agent",
    "parts": [
      {"text": "I found 2 potential security issues..."}
    ]
  }
}

GET /a2a/tasks/{id}

获取 A2A 任务的状态和结果。

响应 200 OK：

{
  "task_id": "task-1234-...",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z",
  "completed_at": "2025-01-15T10:30:05Z",
  "result": {
    "role": "agent",
    "parts": [
      {"text": "Analysis complete..."}
    ]
  }
}

POST /a2a/tasks/{id}/cancel

取消正在运行的 A2A 任务。

响应 200 OK：

{
  "task_id": "task-1234-...",
  "status": "cancelled"
}

审计与安全端点

LibreFang 为所有安全相关操作维护 Merkle 哈希链审计追踪。这些端点允许检查和验证审计日志的完整性。

GET /api/audit/recent

获取最近的审计日志条目。

查询参数：

  • limit（可选）：返回的条目数量（默认：50，最大：500）

响应 200 OK：

{
  "entries": [
    {
      "id": 1042,
      "timestamp": "2025-01-15T10:30:00Z",
      "event_type": "agent_spawned",
      "agent_id": "a1b2c3d4-...",
      "details": "Agent 'coder' spawned with model groq/llama-3.3-70b-versatile",
      "hash": "a1b2c3d4e5f6...",
      "prev_hash": "f6e5d4c3b2a1..."
    }
  ],
  "total": 1042
}

GET /api/audit/verify

验证 Merkle 哈希链审计追踪的完整性。遍历整个链并报告任何断裂的链接。

响应 200 OK：

{
  "status": "valid",
  "chain_length": 1042,
  "first_entry": "2025-01-10T08:00:00Z",
  "last_entry": "2025-01-15T10:30:00Z"
}

响应 200 OK（链断裂）：

{
  "status": "broken",
  "chain_length": 1042,
  "break_at": 847,
  "error": "Hash mismatch at entry 847"
}

GET /api/security

安全状态概览，展示所有 16 个安全系统的状态。

响应 200 OK：

{
  "security_systems": {
    "merkle_audit_trail": "active",
    "taint_tracking": "active",
    "wasm_dual_metering": "active",
    "security_headers": "active",
    "health_redaction": "active",
    "subprocess_sandbox": "active",
    "manifest_signing": "active",
    "gcra_rate_limiter": "active",
    "secret_zeroization": "active",
    "path_traversal_prevention": "active",
    "ssrf_protection": "active",
    "capability_inheritance_validation": "active",
    "ofp_hmac_auth": "active",
    "prompt_injection_scanning": "active",
    "loop_guard": "active",
    "session_repair": "active"
  },
  "total_systems": 16,
  "all_active": true
}

使用量与分析端点

追踪所有 Agent 的令牌使用量、成本和模型利用率。由计量引擎驱动，使用模型目录中的成本估算。

GET /api/usage

获取整体使用统计。

查询参数：

  • period（可选）：时间周期（hour、day、week、month；默认：day）

响应 200 OK：

{
  "period": "day",
  "total_input_tokens": 125000,
  "total_output_tokens": 87000,
  "total_cost_usd": 0.42,
  "request_count": 156,
  "active_agents": 5
}

GET /api/usage/summary

获取包含配额信息的使用量摘要。

响应 200 OK：

{
  "today": {
    "input_tokens": 125000,
    "output_tokens": 87000,
    "cost_usd": 0.42,
    "requests": 156
  },
  "quota": {
    "hourly_token_limit": 1000000,
    "hourly_tokens_used": 45000,
    "hourly_reset_at": "2025-01-15T11:00:00Z"
  }
}

GET /api/usage/by-model

按模型获取使用量明细。

响应 200 OK：

{
  "models": [
    {
      "model": "llama-3.3-70b-versatile",
      "provider": "groq",
      "input_tokens": 80000,
      "output_tokens": 55000,
      "cost_usd": 0.09,
      "request_count": 120
    },
    {
      "model": "gemini-2.5-flash",
      "provider": "gemini",
      "input_tokens": 45000,
      "output_tokens": 32000,
      "cost_usd": 0.33,
      "request_count": 36
    }
  ]
}

迁移端点

从 OpenClaw 或其他 Agent 框架导入数据。迁移引擎处理 YAML 到 TOML 的清单转换、SKILL.md 解析和会话历史导入。

GET /api/migrate/detect

自动检测系统上的迁移源。扫描常见位置以查找 OpenClaw 安装、配置文件和 Agent 数据。

响应 200 OK：

{
  "sources": [
    {
      "type": "openclaw",
      "path": "/home/user/.openclaw",
      "version": "2.1.0",
      "agents_found": 12,
      "skills_found": 8
    }
  ]
}

POST /api/migrate/scan

扫描指定路径以查找可导入的数据。

请求体：

{
  "path": "/home/user/.openclaw"
}

响应 200 OK：

{
  "agents": [
    {
      "name": "my-agent",
      "format": "yaml",
      "convertible": true
    }
  ],
  "skills": [
    {
      "name": "custom-skill",
      "format": "SKILL.md",
      "convertible": true
    }
  ],
  "sessions": 45
}

POST /api/migrate

执行迁移。转换清单、导入技能，并可选择导入会话历史。

请求体：

{
  "source": "/home/user/.openclaw",
  "import_agents": true,
  "import_skills": true,
  "import_sessions": false
}

响应 200 OK：

{
  "status": "completed",
  "agents_imported": 12,
  "skills_imported": 8,
  "sessions_imported": 0,
  "warnings": [
    "Skill 'legacy-plugin' uses unsupported runtime 'ruby', skipped"
  ]
}

会话管理端点

POST /api/agents/{id}/session/reset

重置 Agent 的会话，清除所有对话历史。

响应 200 OK：

{
  "status": "reset",
  "agent_id": "a1b2c3d4-...",
  "new_session_id": "s5e6f7g8-..."
}

POST /api/agents/{id}/session/compact

触发基于 LLM 的会话压缩。Agent 的对话将由 LLM 进行总结，仅保留最近的消息和生成的摘要。

响应 200 OK：

{
  "status": "compacted",
  "message": "Session compacted: 80 messages summarized, 20 kept"
}

响应 200 OK（无需压缩）：

{
  "status": "ok",
  "message": "Session does not need compaction (below threshold)"
}

POST /api/agents/{id}/stop

取消 Agent 当前的 LLM 运行。中止任何正在进行的生成。

响应 200 OK：

{
  "status": "stopped",
  "message": "Agent run cancelled"
}

PUT /api/agents/{id}/model

在运行时切换 Agent 的 LLM 模型。

请求体：

{
  "model": "claude-sonnet-4-20250514"
}

响应 200 OK：

{
  "status": "updated",
  "model": "claude-sonnet-4-20250514"
}

WebSocket 协议

连接

GET /api/agents/&lbrace;id&rbrace;/ws

升级为 WebSocket 连接，实现与 Agent 的实时双向聊天。如果 Agent ID 无效返回 400，Agent 不存在返回 404。

消息格式

所有消息均为 JSON 编码字符串。

客户端到服务器

发送消息：

{
  "type": "message",
  "content": "What is the weather like?"
}

纯文本（非 JSON）也可接受，会被视为消息处理。

聊天命令（以 / 前缀作为消息发送）：

命令描述
/new开始新会话（清除历史）
/compact触发 LLM 会话压缩
/model <name>切换 Agent 的模型
/stop取消当前 LLM 运行
/usage显示令牌使用量和成本
/think切换扩展思考模式
/models列出可用模型
/providers列出 LLM 提供商和认证状态

心跳：

{
  "type": "ping"
}

服务器到客户端

连接确认（连接后立即发送）：

{
  "type": "connected",
  "agent_id": "a1b2c3d4-..."
}

思考指示器（Agent 开始处理时发送）：

{
  "type": "thinking"
}

文本增量（LLM 生成输出时的流式令牌）：

{
  "type": "text_delta",
  "content": "The weather"
}

工具调用开始（Agent 调用工具时发送）：

{
  "type": "tool_start",
  "tool": "web_fetch"
}

完整响应（Agent 完成时发送，包含最终聚合响应）：

{
  "type": "response",
  "content": "The weather today is sunny with a high of 72F.",
  "input_tokens": 245,
  "output_tokens": 32,
  "iterations": 2,
  "cost_usd": 0.0012
}

错误：

{
  "type": "error",
  "content": "Agent not found"
}

Agent 列表更新（每 5 秒发送当前 Agent 状态）：

{
  "type": "agents_updated",
  "agents": [
    {
      "id": "a1b2c3d4-...",
      "name": "hello-world",
      "state": "Running",
      "model_provider": "groq",
      "model_name": "llama-3.3-70b-versatile"
    }
  ]
}

心跳响应（对 ping 的回应）：

{
  "type": "pong"
}

连接生命周期

  1. 客户端连接到 ws://host:port/api/agents/&lbrace;id&rbrace;/ws。
  2. 服务器发送 {"type": "connected"}。
  3. 客户端发送 {"type": "message", "content": "..."}。
  4. 服务器发送 {"type": "thinking"}，然后是零个或多个 {"type": "text_delta"} 事件，最后是 {"type": "response"}。
  5. 服务器每 5 秒定期发送 {"type": "agents_updated"}。
  6. 客户端发送 Close 帧或断开连接来结束会话。

SSE 流式传输

POST /api/agents/{id}/message/stream

发送消息并以 Server-Sent Events 流的形式接收响应。支持实时逐令牌流式传输。

请求体（JSON）：

{
  "message": "Explain quantum computing"
}

SSE 事件流：

event: chunk
data: {"content":"Quantum","done":false}

event: chunk
data: {"content":" computing","done":false}

event: chunk
data: {"content":" is a type","done":false}

event: tool_use
data: {"tool":"web_search"}

event: tool_result
data: {"tool":"web_search","input":{"query":"quantum computing basics"}}

event: done
data: {"done":true,"usage":{"input_tokens":150,"output_tokens":340}}

SSE 事件类型

事件名称描述
chunk来自 LLM 的文本增量。"done": false 表示还有更多令牌。
tool_useAgent 正在调用工具。包含工具名称。
tool_result工具调用已完成。包含工具名称和输入。
done最终事件。包含 "done": true 和令牌使用统计。

OpenAI 兼容 API

LibreFang 提供 OpenAI 兼容 API，可与支持 OpenAI API 格式的工具（Cursor、Continue、Open WebUI 等）即插即用集成。

POST /v1/chat/completions

使用 OpenAI 消息格式发送聊天完成请求。

请求体：

{
  "model": "librefang:coder",
  "messages": [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1024
}

模型解析（model 字段映射到 LibreFang Agent）：

格式示例行为
librefang:<name>librefang:coder按名称查找 Agent
UUIDa1b2c3d4-...按 ID 查找 Agent
普通字符串coder尝试作为 Agent 名称
其他gpt-4o回退到第一个注册的 Agent

图像支持 --- 消息可以包含图像内容部分：

{
  "model": "librefang:analyst",
  "messages": [
    {
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image"},
        {"type": "image_url", "image_url": {"url": "data:image/png;base64,iVBOR..."}}
      ]
    }
  ]
}

响应（非流式） 200 OK：

{
  "id": "chatcmpl-a1b2c3d4-...",
  "object": "chat.completion",
  "created": 1708617600,
  "model": "coder",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 12,
    "total_tokens": 37
  }
}

流式传输 --- 设置 "stream": true 以使用 SSE：

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Hello"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"!"},"finish_reason":null}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":25,"completion_tokens":12,"total_tokens":37}}

data: [DONE]

GET /v1/models

以 OpenAI 格式列出可用模型（Agent）。

响应 200 OK：

{
  "object": "list",
  "data": [
    {
      "id": "librefang:coder",
      "object": "model",
      "created": 1708617600,
      "owned_by": "librefang"
    },
    {
      "id": "librefang:researcher",
      "object": "model",
      "created": 1708617600,
      "owned_by": "librefang"
    }
  ]
}

错误响应

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

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

HTTP 状态码

状态码含义
200成功
201已创建（创建 Agent、创建工作流、创建触发器、安装技能）
400请求错误（无效 UUID、缺少必填字段、格式错误的 TOML/JSON）
401未授权（缺少或无效的 Authorization: Bearer 头）
404未找到（Agent、工作流、触发器、模板、模型、技能或 KV 键不存在）
429请求过多（GCRA 速率限制超限）
500服务器内部错误（Agent 循环失败、数据库错误、驱动错误）

请求 ID

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

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

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

安全头

每个响应都包含安全头：

头值
Content-Security-Policydefault-src 'self'（附带适当的指令）
X-Frame-OptionsDENY
X-Content-Type-Optionsnosniff
Strict-Transport-Securitymax-age=63072000; includeSubDomains
X-Request-Id每个请求的唯一 UUID

速率限制

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

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

{"error": "Rate limit exceeded"}

Retry-After 头表示窗口持续时间（秒）。

端点总览

共 76 个端点，分布在 15 个分组中。

方法路径描述
系统
GET/WebChat UI
GET/api/health健康检查（无需认证，已脱敏）
GET/api/health/detail完整健康检查（需认证）
GET/api/status内核状态
GET/api/version版本信息
POST/api/shutdown优雅关闭
GET/api/profiles列出 Agent 配置文件
GET/api/tools列出可用工具
GET/api/config配置（密钥已脱敏）
GET/api/peers列出 OFP 节点
Agent
GET/api/agents列出 Agent
POST/api/agents创建 Agent
GET/api/agents/&lbrace;id&rbrace;获取 Agent 详情
PUT/api/agents/&lbrace;id&rbrace;/update更新 Agent 配置
PUT/api/agents/&lbrace;id&rbrace;/mode设置 Agent 模式（Stable/Normal）
DELETE/api/agents/&lbrace;id&rbrace;终止 Agent
POST/api/agents/&lbrace;id&rbrace;/message发送消息（阻塞）
POST/api/agents/&lbrace;id&rbrace;/message/stream发送消息（SSE 流）
GET/api/agents/&lbrace;id&rbrace;/session获取对话历史
GET/api/agents/&lbrace;id&rbrace;/wsWebSocket 聊天
POST/api/agents/&lbrace;id&rbrace;/session/reset重置会话
POST/api/agents/&lbrace;id&rbrace;/session/compactLLM 会话压缩
POST/api/agents/&lbrace;id&rbrace;/stop取消当前运行
PUT/api/agents/&lbrace;id&rbrace;/model切换模型
工作流
GET/api/workflows列出工作流
POST/api/workflows创建工作流
POST/api/workflows/&lbrace;id&rbrace;/run执行工作流
GET/api/workflows/&lbrace;id&rbrace;/runs列出工作流运行记录
触发器
GET/api/triggers列出触发器
POST/api/triggers创建触发器
PUT/api/triggers/&lbrace;id&rbrace;更新触发器
DELETE/api/triggers/&lbrace;id&rbrace;删除触发器
内存
GET/api/memory/agents/&lbrace;id&rbrace;/kv列出键值对
GET/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;获取键值
PUT/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;设置键值
DELETE/api/memory/agents/&lbrace;id&rbrace;/kv/&lbrace;key&rbrace;删除键值
通道
GET/api/channels列出通道（40 种适配器）
模板
GET/api/templates列出模板
GET/api/templates/&lbrace;name&rbrace;获取模板
会话
GET/api/sessions列出会话
DELETE/api/sessions/&lbrace;id&rbrace;删除会话
模型目录
GET/api/models完整模型目录（51+ 模型）
GET/api/models/&lbrace;id&rbrace;模型详情
GET/api/models/aliases列出 23 个模型别名
GET/api/providers提供商列表及认证状态
提供商配置
POST/api/providers/&lbrace;name&rbrace;/key设置提供商 API 密钥
DELETE/api/providers/&lbrace;name&rbrace;/key移除提供商 API 密钥
POST/api/providers/&lbrace;name&rbrace;/test测试提供商连接
技能与市场
GET/api/skills列出已安装技能（60 个内置）
POST/api/skills/install安装技能
POST/api/skills/uninstall卸载技能
POST/api/skills/create创建新技能
GET/api/marketplace/search搜索 FangHub
ClawHub
GET/api/clawhub/search搜索 ClawHub
GET/api/clawhub/browse浏览 ClawHub
GET/api/clawhub/skill/&lbrace;slug&rbrace;技能详情
POST/api/clawhub/install从 ClawHub 安装
MCP 与 A2A
GET/api/mcp/serversMCP 服务器连接
POST/mcpMCP HTTP 传输（JSON-RPC 2.0）
GET/.well-known/agent.jsonA2A Agent Card
GET/a2a/agentsA2A Agent 列表
POST/a2a/tasks/send发送 A2A 任务
GET/a2a/tasks/&lbrace;id&rbrace;获取 A2A 任务状态
POST/a2a/tasks/&lbrace;id&rbrace;/cancel取消 A2A 任务
审计与安全
GET/api/audit/recent最近审计日志
GET/api/audit/verify验证 Merkle 链完整性
GET/api/security安全状态（16 个系统）
使用量与分析
GET/api/usage使用统计
GET/api/usage/summary使用量摘要及配额
GET/api/usage/by-model按模型使用量明细
迁移
GET/api/migrate/detect检测迁移源
POST/api/migrate/scan扫描可导入数据
POST/api/migrate执行迁移
OpenAI 兼容
POST/v1/chat/completionsOpenAI 兼容聊天
GET/v1/modelsOpenAI 兼容模型列表