> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Gọi Công Cụ

# Gọi Công Cụ (HTTP)

OpenClaw’s Gateway exposes a simple HTTP endpoint for invoking a single tool directly. It is always enabled, but gated by Gateway auth and tool policy.

* `POST /tools/invoke`
* Cùng cổng với Gateway (ghép kênh WS + HTTP): `http://<gateway-host>:<port>/tools/invoke`

Kích thước payload tối đa mặc định là 2 MB.

## Xác thực

Uses the Gateway auth configuration. Send a bearer token:

* `Authorization: Bearer <token>`

Ghi chú:

* Khi `gateway.auth.mode="token"`, sử dụng `gateway.auth.token` (hoặc `OPENCLAW_GATEWAY_TOKEN`).
* Khi `gateway.auth.mode="password"`, sử dụng `gateway.auth.password` (hoặc `OPENCLAW_GATEWAY_PASSWORD`).
* Nếu `gateway.auth.rateLimit` được cấu hình và xảy ra quá nhiều lần xác thực thất bại, endpoint sẽ trả về `429` kèm `Retry-After`.

## Nội dung yêu cầu

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

Các trường:

* `tool` (string, bắt buộc): tên công cụ cần gọi.
* `action` (string, tùy chọn): được ánh xạ vào args nếu schema của công cụ hỗ trợ `action` và payload args không bao gồm trường này.
* `args` (object, tùy chọn): các tham số dành riêng cho công cụ.
* `sessionKey` (string, optional): target session key. If omitted or `"main"`, the Gateway uses the configured main session key (honors `session.mainKey` and default agent, or `global` in global scope).
* `dryRun` (boolean, tùy chọn): dành cho sử dụng trong tương lai; hiện tại bị bỏ qua.

## Hành vi chính sách + định tuyến

Khả dụng của công cụ được lọc thông qua cùng chuỗi chính sách được Gateway agents sử dụng:

* `tools.profile` / `tools.byProvider.profile`
* `tools.allow` / `tools.byProvider.allow`
* `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
* chính sách nhóm (nếu khóa phiên ánh xạ tới một nhóm hoặc kênh)
* chính sách subagent (khi gọi bằng khóa phiên subagent)

Nếu một công cụ không được cho phép theo chính sách, endpoint sẽ trả về **404**.

Để giúp các chính sách nhóm phân giải ngữ cảnh, bạn có thể tùy chọn thiết lập:

* `x-openclaw-message-channel: <channel>` (ví dụ: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (khi tồn tại nhiều tài khoản)
* `gateway`
* `whatsapp_login`

Bạn có thể tùy chỉnh danh sách chặn này thông qua `gateway.tools`:

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  gateway: {
    tools: {
      // Các công cụ bổ sung cần chặn qua HTTP /tools/invoke
      deny: ["browser"],
      // Xóa công cụ khỏi danh sách chặn mặc định
      allow: ["gateway"],
    },
  },
}
```

Để giúp các chính sách nhóm phân giải ngữ cảnh, bạn có thể tùy chọn thiết lập:

* `x-openclaw-message-channel: <channel>` (ví dụ: `slack`, `telegram`)
* `x-openclaw-account-id: <accountId>` (khi tồn tại nhiều tài khoản)

## Phản hồi

* `200` → `{ ok: true, result }`
* `400` → `{ ok: false, error: { type, message } }` (yêu cầu không hợp lệ hoặc lỗi dữ liệu đầu vào của công cụ)
* `401` → không được ủy quyền
* `429` → bị giới hạn tần suất xác thực (`Retry-After` được thiết lập)
* `404` → công cụ không khả dụng (không tìm thấy hoặc không nằm trong danh sách cho phép)
* `405` → phương thức không được phép
* `500` → `{ ok: false, error: { type, message } }` (lỗi thực thi công cụ không mong muốn; thông báo đã được làm sạch)

## Ví dụ

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "tool": "sessions_list",
    "action": "json",
    "args": {}
  }'
```