API 参考: 工具 (Tools)

工具注册、管理、测试和工具包端点。

注册工具

注册一个可被 AI 调用的工具。如果 name 已存在，自动执行更新。

POST /v1/tools

权限要求： write

请求体

字段	类型	必填	说明
name	string	是	工具唯一名称
description	string	是	工具描述，AI 依据此判断何时调用
appId	string	否	所属应用 ID
input_schema	object	否	JSON Schema 格式的输入参数定义
execution	object	否	执行配置
execution.type	string	--	"http" 或 "handler"
execution.method	string	--	HTTP 方法 (GET/POST/PUT/DELETE)
execution.url	string	--	请求 URL，支持 {param} 占位符
execution.headers	object	--	自定义请求头
execution.params	object	--	URL 查询参数
execution.body	object	--	请求体

请求示例

curl -X POST https://api.invoratec.cn/v1/tools \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "erp_get_inventory",
    "description": "查询 ERP 系统的库存数据",
    "appId": "my-erp",
    "input_schema": {
      "type": "object",
      "properties": {
        "warehouse_id": { "type": "string", "description": "仓库ID" }
      },
      "required": ["warehouse_id"]
    },
    "execution": {
      "type": "http",
      "method": "GET",
      "url": "https://erp.example.com/api/inventory?wh={warehouse_id}"
    }
  }'

响应 (201 Created)

{
  "_id": "665f1a2b3c4d5e6f7a8b9c0d",
  "name": "erp_get_inventory",
  "description": "查询 ERP 系统的库存数据",
  "appId": "my-erp",
  "developerId": "user_123",
  "input_schema": { ... },
  "execution": { ... },
  "enabled": true,
  "createdAt": "2026-04-12T08:00:00.000Z",
  "updatedAt": "2026-04-12T08:00:00.000Z"
}

如果工具已存在（更新），响应中额外包含 "updated": true。

错误

状态码	说明
400	name 或 description 缺失
403	缺少 write 权限

---

列出工具

GET /v1/tools

查询参数

参数	类型	说明
appId	string	按所属应用过滤

请求示例

# 列出所有工具
curl https://api.invoratec.cn/v1/tools \
  -H "X-API-Key: claw_xxxx"

# 按应用过滤
curl "https://api.invoratec.cn/v1/tools?appId=my-erp" \
  -H "X-API-Key: claw_xxxx"

响应

{
  "tools": [
    {
      "_id": "665f...",
      "name": "erp_get_inventory",
      "description": "查询 ERP 系统的库存数据",
      "appId": "my-erp",
      "enabled": true,
      "updatedAt": "2026-04-12T08:00:00.000Z"
    }
  ],
  "total": 1
}

---

获取工具详情

GET /v1/tools/{name}

路径参数

参数	类型	说明
name	string	工具名称

请求示例

curl https://api.invoratec.cn/v1/tools/erp_get_inventory \
  -H "X-API-Key: claw_xxxx"

响应

返回完整的工具文档，包含 input_schema 和 execution 配置。

错误

状态码	说明
404	工具不存在

---

更新工具

PUT /v1/tools/{name}

权限要求： write

路径参数

参数	类型	说明
name	string	工具名称

请求体

可更新以下字段：description, input_schema, execution, enabled, appId。

请求示例

curl -X PUT https://api.invoratec.cn/v1/tools/erp_get_inventory \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "查询 ERP 库存（含批次号）",
    "enabled": true
  }'

响应

返回更新后的完整工具文档。

错误

状态码	说明
403	缺少 write 权限
404	工具不存在

---

删除工具

DELETE /v1/tools/{name}

权限要求： write

请求示例

curl -X DELETE https://api.invoratec.cn/v1/tools/erp_get_inventory \
  -H "X-API-Key: claw_xxxx"

响应

{ "success": true }

---

测试工具执行

在沙箱中测试工具的执行结果。HTTP 工具会实际发送请求（超时 10 秒），handler 类型工具需要桌面代理执行。

POST /v1/tools/{name}/test

权限要求： write

路径参数

参数	类型	说明
name	string	工具名称

请求体

字段	类型	说明
input	object	传递给工具的输入参数

请求示例

curl -X POST https://api.invoratec.cn/v1/tools/erp_get_inventory/test \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "input": { "warehouse_id": "WH-001" }
  }'

响应 (成功)

{
  "status": "success",
  "result": { "items": [...], "total": 42 },
  "elapsed_ms": 230
}

响应 (失败)

{
  "status": "error",
  "error": "Connection timeout",
  "elapsed_ms": 10001
}

错误

状态码	说明
404	工具不存在
500	执行出错

---

创建工具包

将多个工具组织为一个工具包，并附加 AI 知识提示。

POST /v1/tools/packs

权限要求： write

请求体

字段	类型	必填	说明
id	string	是	工具包唯一标识符
name	string	是	英文名称
nameZh	string	否	中文名称
description	string	否	描述
tools	string[]	否	工具名称列表
knowledge	string	否	AI 知识提示文本

请求示例

curl -X POST https://api.invoratec.cn/v1/tools/packs \
  -H "X-API-Key: claw_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "erp-inventory-pack",
    "name": "ERP Inventory Pack",
    "nameZh": "ERP 库存工具包",
    "description": "库存查询和管理工具集",
    "tools": ["erp_get_inventory", "erp_update_stock"],
    "knowledge": "仓库编号以WH-开头。库存数据每5分钟同步。"
  }'

响应 (201 Created)

{
  "_id": "665f...",
  "packId": "erp-inventory-pack",
  "name": "ERP Inventory Pack",
  "nameZh": "ERP 库存工具包",
  "tools": ["erp_get_inventory", "erp_update_stock"],
  "knowledge": "仓库编号以WH-开头。库存数据每5分钟同步。",
  "status": "draft",
  "createdAt": "2026-04-12T08:00:00.000Z"
}

错误

状态码	说明
400	id 或 name 缺失
403	缺少 write 权限

---

列出工具包

GET /v1/tools/packs

请求示例

curl https://api.invoratec.cn/v1/tools/packs \
  -H "X-API-Key: claw_xxxx"

响应

{
  "packs": [
    {
      "_id": "665f...",
      "packId": "erp-inventory-pack",
      "name": "ERP Inventory Pack",
      "nameZh": "ERP 库存工具包",
      "tools": ["erp_get_inventory", "erp_update_stock"],
      "status": "draft"
    }
  ]
}