Skip to Content
Open Platform

FunClaw 开放平台

接口范围

FunClaw 对外稳定 API 只使用以下命名空间：

/api/open/v1/**

应用开发者和 AI Agent 应按本页及各接入指南中列出的开放 API 编写调用代码，以对应接口的认证、输入和响应合同为准。

  • 数字员工服务：独立应用和第三方系统调用获授权的平台员工。
  • 平台能力：各项业务能力的独立执行契约。
  • 本页的 Data API：组织应用的数据集和记录读写。

内部接口命名空间：

/api/v1/**

/api/v1/** 仅服务 FunClaw 前台、控制台和内部业务链路，不能作为外部应用或 AI Agent 的调用依据。

认证

开放 API 不接受匿名请求。不同接口使用各自的凭证，均通过 Authorization: Bearer ... 传递。

应用服务凭证

数字员工服务使用平台登记应用的服务凭证：

Authorization: Bearer <完整的 fc_app_ 应用服务凭证>

在 Console“应用管理”登记应用，启用 API 接入，在“员工授权”分配指定员工，在“服务凭证”生成 Key。应用身份由凭证解析，调用 /api/open/v1/applications/me、/employees、/tasks 等应用服务接口，无需借用组织身份。

应用服务凭证只保存在应用后端。完整 Key 仅签发时显示一次，可签发多份用于轮换；每次请求检查凭证、应用和 API 接入状态。员工任务另校验员工使用授权，具体流程见快速接入。

组织应用 API Key

Data API 和现有 /api/open/v1/organizations/{orgId}/capabilities/... 业务能力按各自文档使用组织应用级 Key：

Authorization: Bearer <org-application-api-key>

组织应用 API Key 获取链路：

  1. 用户注册或登录 FunClaw。
  2. 用户加入组织。
  3. 组织 Admin 为组织下已授权的应用分配 API Key。
  4. 外部应用使用 Bearer Key 调用开放 API。
  5. 平台根据 Key 识别组织、应用和权限范围。

组织应用 API Key 代表指定组织下指定应用的开放接口访问能力。它与 fc_app_ 应用服务凭证分别使用，不能假设互换。应用直接使用新平台服务时，也应遵循该服务的授权合同。

用户登录与组织访问

FunClaw SSO 登录识别用户，并校验组织/空间中的应用访问资格；应用服务凭证识别应用后端。应用拥有服务凭证不代表任意用户可进入该应用，也不自动取得所有组织资产权限。业务用户、角色和本地数据权限由独立应用管理。

禁止调用

AI Agent 和外部应用必须遵守以下限制：

  • 不调用 /api/v1/**。
  • 不把内部 Swagger 当作开放 API 契约。
  • 不直接连接 PostgreSQL、MongoDB 或对象存储。
  • 不使用自定义认证头替代 Authorization。
  • 不构造本页未列出的接口路径。

对象模型

Organization / 组织

数据、应用、成员和权限的租户边界。

Member / 成员

组织内的用户身份。组织 Admin 可以管理本组织应用的 API Key。

Application / 应用

平台统一登记的独立应用或第三方系统，可使用应用服务凭证成为员工任务的 caller。组织/空间对应用的使用授权单独控制用户访问与资源上下文。

Digital Employee / 数字员工

平台提供的执行主体，可分别授权给组织和应用使用。应用任务通过 Assignment 执行，输入和结果归属调用应用；员工执行工具由平台配置。

Data Source / 数据源

数据生产者，例如外部应用、内部业务模块、Agent、Workflow、系统任务或人工导入。

Dataset / 数据集

一类由平台治理的数据资产。Dataset 定义数据归属、可见性、Schema 描述和读写权限。

Data Record / 数据记录

Dataset 下的一条数据。平台管理记录的归属、幂等键、状态、审计和 payload 引用。

Payload / 数据正文

业务方写入的原始内容。平台不依赖 payload 内部字段完成权限、幂等和审计。

平台能力

平台能力是可独立调用的业务服务，按各项能力文档的凭证与权限执行。当前可用能力和调用方式见平台能力。

应用委托员工执行时，先取得该员工的使用授权；员工执行工具由平台配置，无需应用重复授权 TikHub 等员工工具。应用后端直接调用平台服务时，配置应用自己的平台能力授权。详见数字员工服务的能力授权。

Data API

开放数据 API 路径：

POST /api/open/v1/data/datasets/{datasetId}/records:upsert
POST /api/open/v1/data/datasets/{datasetId}/records:batchUpsert
GET  /api/open/v1/data/datasets/{datasetId}/records
GET  /api/open/v1/data/datasets/{datasetId}/records/{recordId}
GET  /api/open/v1/data/datasets/{datasetId}/records/by-external-key/{externalKey}

响应格式

响应结构以具体接口为准。数字员工服务返回直接 JSON：员工列表为 {items: [...]}，任务状态为包含 id/status 的对象，任务结果为 {assignmentId, applicationId, output}。不要为这些接口增加 data 层解析。字段见调用接口。

下面的三段式结构用于本页 Data API：

{
  "code": 200,
  "message": "success",
  "data": {}
}

code 使用 HTTP 状态码数字，并且必须与 HTTP Status 保持一致。

成功响应：

{
  "code": 200,
  "message": "success",
  "data": {
    "recordId": "record-id"
  }
}

错误响应：

{
  "code": 400,
  "message": "externalKey is required",
  "data": null
}

写入记录请求结构：

{
  "externalKey": "source-system:business-id",
  "payload": {
    "any": "business-defined-content"
  },
  "schemaVersion": "v1",
  "occurredAt": "2026-05-09T00:00:00Z"
}

批量写入请求结构：

{
  "records": [
    {
      "externalKey": "source-system:business-id-1",
      "payload": {
        "any": "business-defined-content"
      },
      "schemaVersion": "v1",
      "occurredAt": "2026-05-09T00:00:00Z"
    }
  ]
}

读取记录响应结构：

{
  "code": 200,
  "message": "success",
  "data": {
    "recordId": "record-id",
    "datasetId": "dataset-id",
    "sourceId": "source-id",
    "externalKey": "source-system:business-id",
    "status": "ACTIVE",
    "payloadHash": "sha256...",
    "payload": {
      "any": "business-defined-content"
    },
    "createdAt": "2026-05-09T00:00:00Z",
    "updatedAt": "2026-05-09T00:00:00Z"
  }
}

幂等规则

externalKey 必填。

同一组织、同一 Dataset 下，externalKey 必须唯一：

orgId + datasetId + externalKey

重复写入相同 externalKey 时，平台执行 upsert，不创建重复记录。

payloadHash 由平台根据 payload 计算。调用方不需要传入 payloadHash。

错误响应

Data API 错误响应使用下述三段式结构。数字员工服务以 HTTP 状态判断错误，不承诺相同的错误包装，详见HTTP 错误。

{
  "code": 400,
  "message": "externalKey is required",
  "data": null
}

常见错误码：

200 success
400 bad request / validation failed
401 unauthorized
403 forbidden
404 not found
409 conflict
429 rate limited
500 internal server error
Last updated on
概览