工具调用 API

工具调用 API（Tools Invoke API）允许客户端绕过 LLM，直接调用 Gateway 中已注册的工具（Tool）。适用于程序化集成和自动化流程。

端点

POST /v1/tools/{tool_name}/invoke

认证

与其他 API 一样，使用 Gateway Token 认证：

curl -X POST http://127.0.0.1:18789/v1/tools/read_file/invoke \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/src/main.py"}'

请求格式

{
  "path": "/src/main.py",
  "encoding": "utf-8"
}

请求体即工具的参数（Arguments），具体参数取决于调用的工具。

参数透传

请求体中的所有字段将直接作为工具参数传递。参数结构取决于具体工具的定义。

响应格式

成功响应

{
  "status": "success",
  "toolName": "read_file",
  "result": {
    "content": "print('hello world')\n",
    "encoding": "utf-8",
    "size": 22
  },
  "metadata": {
    "duration_ms": 5,
    "executedAt": "2025-01-15T10:30:00Z"
  }
}

错误响应

{
  "status": "error",
  "toolName": "read_file",
  "error": {
    "code": "file_not_found",
    "message": "File not found: /src/main.py"
  }
}

可用工具列表

查询已注册工具

# 列出所有可用工具
curl http://127.0.0.1:18789/v1/tools \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"

响应：

{
  "tools": [
    {
      "name": "read_file",
      "description": "Read the contents of a file",
      "parameters": {
        "type": "object",
        "properties": {
          "path": { "type": "string", "description": "File path" },
          "encoding": { "type": "string", "default": "utf-8" }
        },
        "required": ["path"]
      }
    },
    {
      "name": "write_file",
      "description": "Write content to a file",
      "parameters": {
        "type": "object",
        "properties": {
          "path": { "type": "string" },
          "content": { "type": "string" }
        },
        "required": ["path", "content"]
      }
    },
    {
      "name": "execute_command",
      "description": "Execute a shell command",
      "parameters": {
        "type": "object",
        "properties": {
          "command": { "type": "string" },
          "cwd": { "type": "string" },
          "timeout": { "type": "number" }
        },
        "required": ["command"]
      }
    }
  ]
}

查询工具详情

curl http://127.0.0.1:18789/v1/tools/read_file \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN"

常用工具示例

读取文件

curl -X POST http://127.0.0.1:18789/v1/tools/read_file/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path": "/home/user/project/src/main.py"}'

写入文件

curl -X POST http://127.0.0.1:18789/v1/tools/write_file/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/home/user/project/output.txt",
    "content": "Hello, World!\n"
  }'

执行命令

curl -X POST http://127.0.0.1:18789/v1/tools/execute_command/invoke \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "command": "ls -la /home/user/project",
    "timeout": 10000
  }'

安全注意

工具调用 API 直接在 Gateway 主机上执行操作。确保正确配置 沙箱 和 工具策略 以限制可执行的操作范围。

权限与安全

工具策略

工具调用遵循 Gateway 的安全策略（Tool Policy）：

策略	API 行为
允许（allowed）	直接执行，返回结果
需审批（requireApproval）	返回 403 Forbidden（API 不支持交互审批）
禁用（denied）	返回 403 Forbidden

API 不支持审批

通过 HTTP API 调用工具时，标记为 requireApproval 的工具将被拒绝执行。如需审批流程，请使用 WebSocket 协议。

沙箱限制

工具调用在沙箱（Sandbox）中执行，受以下限制：

• 文件系统访问范围
• 网络访问限制
• 执行超时
• 资源配额

批量调用

curl -X POST http://127.0.0.1:18789/v1/tools/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "calls": [
      {"tool": "read_file", "arguments": {"path": "/src/a.py"}},
      {"tool": "read_file", "arguments": {"path": "/src/b.py"}}
    ],
    "parallel": true
  }'

相关文档

• OpenAI Chat Completions API — 兼容接口
• 沙箱机制 — 工具执行隔离
• 安全概览 — 安全架构