Skip to Content
数字员工服务快速接入

快速接入数字员工

这份指南使用应用后端身份跑通一个通用文本任务。示例中的 URL、员工 UUID 和凭证需要替换成自己的配置。

1. 在 Console 配置

在“应用管理”中登记应用，打开应用详情：

  1. 保持应用全局状态启用，在“概览”开启 API 接入。
  2. 在“员工授权”新增授权，选择员工；同时授予“创建任务”和“读取使用配置”，或选择“全部操作”。设置所需有效期。
  3. 在“服务凭证”生成应用服务凭证，保存一次性显示的完整 fc_app_ Key。

平台管理员还需确保员工在线、Adapter 支持应用任务，并在员工的“执行能力”中配置任务实际需要的工具。通用文本任务不要求 TikHub；采集任务使用 TikHub 时，授权配置在员工处。

应用只有 API 调用需求时，可以登记为 API 应用。需要从 FunClaw 授权跳转的独立网站，另外配置“登录配置”和组织/空间应用使用权限。

2. 配置应用后端

在应用服务端配置环境变量。以下使用 Bash 和 curl；FUNCLAW_API_ORIGIN 应指向 API 服务，而非 Front 或 Console 页面。

export FUNCLAW_API_ORIGIN='http://localhost:8081'
export FUNCLAW_APPLICATION_API_KEY='<完整的 fc_app_ 应用服务凭证>'

凭证只供应用后端使用，不放入 NEXT_PUBLIC_*、浏览器代码、任务 input 或日志。完整凭证仅在签发时显示一次；丢失后重新签发。

先检查身份，再查询可使用的员工：

curl --fail-with-body "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY"
 
curl --fail-with-body "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me/employees" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY"

身份接口直接返回 {applicationId, clientId, code, displayName}；员工列表返回 {items: [...]}。选择同时具有 TASK_CREATE 和 READ 的员工，保存其 id。响应字段见调用接口。

3. 提交任务

export EMPLOYEE_ID='<员工列表返回的 id>'
 
curl --fail-with-body "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me/tasks" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: summary:example-001' \
  --data "{\"employeeId\":\"$EMPLOYEE_ID\",\"title\":\"概括产品介绍\",\"instructions\":\"概括 input.text，结果写入 output.summary。读取 FUNCLAW_APPLICATION_TASK_INPUT_PATH 中的输入信封，把包含原 inputHash 和 output 的 JSON 对象写入 FUNCLAW_APPLICATION_TASK_RESULT_PATH。\",\"input\":{\"text\":\"FunClaw 为独立应用提供数字员工任务执行服务。\"}}"

成功返回 HTTP 201，响应中的 id 是后续查询使用的任务 ID。初始状态通常为 PENDING。

相同业务请求发生网络超时或重试时，复用同一个 Idempotency-Key 和相同请求内容。修改员工、标题、指令或输入后使用新键。同一个键不能代表不同任务。

4. 查询状态与结果

export TASK_ID='<提交响应的 id>'
 
curl --fail-with-body "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me/tasks/$TASK_ID" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY"

应用后端定期查询，直到 status 为 COMPLETED、FAILED 或 CANCELLED。建议从 3–5 秒轮询开始，遇到临时网络故障退避重试；页面关闭不应终止应用后台对已提交任务的跟踪。

COMPLETED 后读取结果：

curl --fail-with-body "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me/tasks/$TASK_ID/result" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY"

结果直接返回 JSON 对象，例如：

{
  "assignmentId": "00000000-0000-4000-8000-000000000001",
  "applicationId": "00000000-0000-4000-8000-000000000002",
  "output": {
    "summary": "FunClaw 为独立应用提供数字员工服务。"
  }
}

校验任务 ID、应用 ID 和约定的结果字段后，完成本应用的业务处理。output 的业务结构由应用与员工执行逻辑约定，平台不自动生成上述摘要字段。

5. 按需取消

curl --fail-with-body -X POST \
  "$FUNCLAW_API_ORIGIN/api/open/v1/applications/me/tasks/$TASK_ID:cancel" \
  -H "Authorization: Bearer $FUNCLAW_APPLICATION_API_KEY"

运行中任务的取消需要 Adapter 确认。取消请求成功后继续查询，直到任务进入终态。网络请求超时仅代表客户端停止等待，不能据此判断任务已经取消。

接下来阅读输入与结果，为具体业务约定执行指令、结果字段与回执。

Last updated on
概览调用接口