---
read_when:
    - การเรียกใช้เครื่องมือโดยไม่ดำเนินรอบการทำงานของเอเจนต์แบบเต็มรูปแบบ
    - การสร้างระบบอัตโนมัติที่ต้องบังคับใช้นโยบายเครื่องมือ
summary: เรียกใช้เครื่องมือเดียวโดยตรงผ่านเอนด์พอยต์ HTTP ของ Gateway
title: เครื่องมือเรียกใช้ API
x-i18n:
    generated_at: "2026-07-12T16:13:29Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 6d07f765d63255e718d5e558b662589e77b2992538f43288cd83e6e3f2a06dda
    source_path: gateway/tools-invoke-http-api.md
    workflow: 16
---

Gateway ของ OpenClaw เปิดเผยปลายทาง HTTP สำหรับเรียกใช้เครื่องมือเดียวโดยตรง ปลายทางนี้เปิดใช้งานอยู่เสมอ และใช้การยืนยันตัวตนของ Gateway ร่วมกับนโยบายเครื่องมือ เช่นเดียวกับพื้นผิว `/v1/*` ที่เข้ากันได้กับ OpenAI การยืนยันตัวตนแบบ bearer ด้วยข้อมูลลับที่ใช้ร่วมกันจะถือว่าเป็นการเข้าถึงโดยผู้ปฏิบัติการที่เชื่อถือได้สำหรับ Gateway ทั้งหมด

- `POST /tools/invoke`
- ใช้พอร์ตเดียวกับ Gateway (มัลติเพล็กซ์ WS + HTTP): `http://<gateway-host>:<port>/tools/invoke`
- ขนาดเนื้อหาคำขอสูงสุดโดยค่าเริ่มต้น: 2 MB

## การยืนยันตัวตน

ใช้การกำหนดค่าการยืนยันตัวตนของ Gateway

เส้นทางการยืนยันตัวตน HTTP ที่ใช้ทั่วไป:

- การยืนยันตัวตนด้วยข้อมูลลับที่ใช้ร่วมกัน (`gateway.auth.mode="token"` หรือ `"password"`): `Authorization: Bearer <token-or-password>`
- การยืนยันตัวตน HTTP ที่มีข้อมูลอัตลักษณ์ที่เชื่อถือได้ (`gateway.auth.mode="trusted-proxy"`): กำหนดเส้นทางผ่านพร็อกซีที่รับรู้อัตลักษณ์ซึ่งกำหนดค่าไว้ และให้พร็อกซีแทรกส่วนหัวอัตลักษณ์ที่จำเป็น
- การเปิดการยืนยันตัวตนบนทางเข้าที่เป็นส่วนตัว (`gateway.auth.mode="none"`): ไม่ต้องมีส่วนหัวการยืนยันตัวตน

หมายเหตุ:

- `mode="token"` ใช้ `gateway.auth.token` (หรือ `OPENCLAW_GATEWAY_TOKEN`)
- `mode="password"` ใช้ `gateway.auth.password` (หรือ `OPENCLAW_GATEWAY_PASSWORD`)
- `mode="trusted-proxy"` กำหนดให้คำขอ HTTP มาจากแหล่งพร็อกซีที่เชื่อถือได้ซึ่งกำหนดค่าไว้ พร็อกซี local loopback บนโฮสต์เดียวกันต้องกำหนด `gateway.auth.trustedProxy.allowLoopback = true` อย่างชัดเจน
- ผู้เรียกภายในโฮสต์เดียวกันที่ข้ามพร็อกซีสามารถใช้ `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` เป็นทางเลือกสำรองโดยตรงภายในเครื่องได้ แต่หากมีหลักฐานจากส่วนหัว `Forwarded`, `X-Forwarded-*` หรือ `X-Real-IP` คำขอจะยังคงใช้เส้นทางพร็อกซีที่เชื่อถือได้แทน
- หากกำหนดค่า `gateway.auth.rateLimit` และเกิดความล้มเหลวในการยืนยันตัวตนมากเกินไป ปลายทางจะส่งคืน `429` พร้อม `Retry-After`

## ขอบเขตความปลอดภัย (สำคัญ)

ให้ถือว่าปลายทางนี้เป็นพื้นผิวที่มี **สิทธิ์การเข้าถึงเต็มรูปแบบของผู้ปฏิบัติการ** สำหรับอินสแตนซ์ Gateway

- การยืนยันตัวตนแบบ HTTP bearer ที่นี่ไม่ใช่โมเดลขอบเขตสิทธิ์แบบจำกัดเฉพาะผู้ใช้แต่ละราย
- ควรถือว่าโทเค็น/รหัสผ่าน Gateway ที่ใช้ได้สำหรับปลายทางนี้เป็นข้อมูลรับรองของเจ้าของ/ผู้ปฏิบัติการ
- สำหรับโหมดการยืนยันตัวตนด้วยข้อมูลลับที่ใช้ร่วมกัน (`token` และ `password`) ปลายทางจะคืนค่าขอบเขตสิทธิ์เริ่มต้นแบบเต็มของผู้ปฏิบัติการตามปกติ แม้ว่าผู้เรียกจะส่งส่วนหัว `x-openclaw-scopes` ที่จำกัดกว่า
- การยืนยันตัวตนด้วยข้อมูลลับที่ใช้ร่วมกันยังถือว่าการเรียกใช้เครื่องมือโดยตรงบนปลายทางนี้เป็นเทิร์นจากผู้ส่งที่เป็นเจ้าของ
- โหมด HTTP ที่มีข้อมูลอัตลักษณ์ที่เชื่อถือได้ (การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้ หรือ `gateway.auth.mode="none"` บนทางเข้าที่เป็นส่วนตัว) จะใช้ `x-openclaw-scopes` หากมี มิฉะนั้นจะใช้ชุดขอบเขตสิทธิ์เริ่มต้นตามปกติของผู้ปฏิบัติการ
- ให้ปลายทางนี้อยู่บนลูปแบ็ก/เทลเน็ต/ทางเข้าที่เป็นส่วนตัวเท่านั้น อย่าเปิดเผยโดยตรงสู่อินเทอร์เน็ตสาธารณะ

ตารางการยืนยันตัวตน:

| โหมดการยืนยันตัวตน                                                                    | ลักษณะการทำงาน                                                                                                                                                                                                                                                                                                                                 |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `token` หรือ `password` + `Authorization: Bearer ...`                                  | พิสูจน์ว่าครอบครองข้อมูลลับที่ใช้ร่วมกันของผู้ปฏิบัติการ Gateway ไม่สนใจ `x-openclaw-scopes` ที่จำกัดกว่า คืนค่าชุดขอบเขตสิทธิ์เริ่มต้นแบบเต็มของผู้ปฏิบัติการ ได้แก่ `operator.admin`, `operator.approvals`, `operator.pairing`, `operator.read`, `operator.talk.secrets`, `operator.write` ถือว่าการเรียกใช้เครื่องมือโดยตรงเป็นเทิร์นจากผู้ส่งที่เป็นเจ้าของ |
| HTTP ที่มีข้อมูลอัตลักษณ์ที่เชื่อถือได้ (การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้ หรือ `mode="none"` บนทางเข้าที่เป็นส่วนตัว) | ยืนยันตัวตนของอัตลักษณ์ภายนอกที่เชื่อถือได้หรือขอบเขตการติดตั้งใช้งาน ใช้ `x-openclaw-scopes` หากมี และใช้ชุดขอบเขตสิทธิ์เริ่มต้นตามปกติของผู้ปฏิบัติการเมื่อไม่มีส่วนหัวดังกล่าว จะสูญเสียความหมายของการเป็นเจ้าของเฉพาะเมื่อผู้เรียกจำกัดขอบเขตสิทธิ์อย่างชัดเจนและไม่รวม `operator.admin` เท่านั้น |

## เนื้อหาคำขอ

```json
{
  "tool": "sessions_list",
  "action": "json",
  "args": {},
  "sessionKey": "main",
  "dryRun": false
}
```

ฟิลด์:

- `tool` / `name` (สตริง, จำเป็น): ชื่อเครื่องมือที่จะเรียกใช้ `name` มีลำดับความสำคัญสูงกว่าหากส่งมาทั้งคู่
- `action` (สตริง, ไม่บังคับ): ผสานเข้าใน `args.action` หากสคีมาของเครื่องมือรองรับพร็อพเพอร์ตี `action` และ `args` ยังไม่ได้กำหนดค่าไว้
- `args` (ออบเจ็กต์, ไม่บังคับ): อาร์กิวเมนต์เฉพาะของเครื่องมือ
- `sessionKey` (สตริง, ไม่บังคับ): คีย์เซสชันเป้าหมาย หากละไว้หรือเป็น `"main"` Gateway จะใช้คีย์เซสชันหลักที่กำหนดค่าไว้ (ใช้ `session.mainKey` และเอเจนต์เริ่มต้น หรือ `global` ในขอบเขตเซสชันส่วนกลาง)
- `agentId` (สตริง, ไม่บังคับ): แปลงเป็นคีย์เซสชันสำหรับเอเจนต์นั้น ส่งข้อผิดพลาด `400` หากขัดแย้งกับ `sessionKey` ที่ระบุไว้อย่างชัดเจนและแมปกับเอเจนต์อื่นอยู่แล้ว
- `idempotencyKey` (สตริง, ไม่บังคับ): ใช้สร้างรหัสการเรียกเครื่องมือที่คงที่สำหรับการเรียกใช้นี้
- `dryRun` (บูลีน, ไม่บังคับ): สงวนไว้สำหรับการใช้งานในอนาคต ปัจจุบันจะถูกละเว้น

## ลักษณะการทำงานของนโยบายและการกำหนดเส้นทาง

ความพร้อมใช้งานของเครื่องมือจะถูกกรองผ่านสายโซ่นโยบายเดียวกับที่เอเจนต์ของ Gateway ใช้:

- `tools.profile` / `tools.byProvider.profile`
- `tools.allow` / `tools.byProvider.allow`
- `agents.<id>.tools.allow` / `agents.<id>.tools.byProvider.allow`
- นโยบายกลุ่ม (หากคีย์เซสชันแมปกับกลุ่มหรือช่องทาง)
- นโยบายเอเจนต์ย่อย (เมื่อเรียกใช้ด้วยคีย์เซสชันของเอเจนต์ย่อย)

หากนโยบายไม่อนุญาตเครื่องมือ ปลายทางจะส่งคืน **404**

หมายเหตุสำคัญเกี่ยวกับขอบเขต:

- การอนุมัติ `exec` เป็นมาตรการป้องกันสำหรับผู้ปฏิบัติการ ไม่ใช่ขอบเขตการให้สิทธิ์แยกต่างหากสำหรับปลายทาง HTTP นี้ หากสามารถเข้าถึงเครื่องมือได้ที่นี่ผ่านการยืนยันตัวตนของ Gateway และนโยบายเครื่องมือ `/tools/invoke` จะไม่เพิ่มข้อความแจ้งขออนุมัติแยกสำหรับแต่ละการเรียก
- หากเข้าถึง `exec` ได้ที่นี่ ให้ถือว่าเป็นพื้นผิวเชลล์ที่แก้ไขข้อมูลได้ การปฏิเสธ `write`, `edit`, `apply_patch` หรือเครื่องมือเขียนระบบไฟล์ผ่าน HTTP ไม่ได้ทำให้การเรียกใช้เชลล์เป็นแบบอ่านอย่างเดียว
- อย่าแบ่งปันข้อมูลรับรองแบบ bearer ของ Gateway กับผู้เรียกที่ไม่น่าเชื่อถือ หากต้องการแยกขอบเขตความเชื่อถือ ให้เรียกใช้ Gateway แยกกัน (โดยควรใช้ผู้ใช้ระบบปฏิบัติการ/โฮสต์แยกกัน)

HTTP ของ Gateway ยังใช้รายการปฏิเสธแบบตายตัวโดยค่าเริ่มต้น (แม้ว่านโยบายเซสชันจะอนุญาตเครื่องมือนั้น):

| เครื่องมือ        | เหตุผล                                                       |
| ---------------- | ------------------------------------------------------------ |
| `exec`           | การเรียกใช้คำสั่งโดยตรง (พื้นผิว RCE)                       |
| `spawn`          | การสร้างโพรเซสลูกโดยพลการ (พื้นผิว RCE)                     |
| `shell`          | การเรียกใช้คำสั่งเชลล์ (พื้นผิว RCE)                        |
| `fs_write`       | การแก้ไขไฟล์บนโฮสต์โดยพลการ                                 |
| `fs_delete`      | การลบไฟล์บนโฮสต์โดยพลการ                                    |
| `fs_move`        | การย้าย/เปลี่ยนชื่อไฟล์บนโฮสต์โดยพลการ                      |
| `apply_patch`    | การใช้แพตช์สามารถเขียนทับไฟล์ใด ๆ ได้                       |
| `sessions_spawn` | การจัดการเซสชัน การสร้างเอเจนต์จากระยะไกลถือเป็น RCE        |
| `sessions_send`  | การแทรกข้อความข้ามเซสชัน                                    |
| `cron`           | ระนาบควบคุมระบบอัตโนมัติแบบถาวร                             |
| `gateway`        | ระนาบควบคุม Gateway ป้องกันการกำหนดค่าใหม่ผ่าน HTTP         |
| `nodes`          | รีเลย์คำสั่ง Node สามารถเข้าถึง `system.run` บนโฮสต์ที่จับคู่ไว้ |

`cron`, `gateway` และ `nodes` จำกัดเฉพาะเจ้าของด้วยเช่นกัน แม้อยู่นอกรายการปฏิเสธเริ่มต้นนี้ ผู้เรียกที่ไม่ใช่เจ้าของจะไม่สามารถเรียกใช้เครื่องมือเหล่านี้บนพื้นผิวนี้ได้

ปรับแต่งรายการปฏิเสธทั่วไปผ่าน `gateway.tools`:

```json5
{
  gateway: {
    tools: {
      // Additional tools to block over HTTP /tools/invoke
      deny: ["browser"],
      // Remove tools from the default deny list for owner/admin callers
      allow: ["gateway"],
    },
  },
}
```

`gateway.tools.allow` เป็นการเขียนทับการเปิดเผย ไม่ใช่การยกระดับขอบเขตสิทธิ์ ในโหมด HTTP ที่มีข้อมูลอัตลักษณ์ `cron`, `gateway` และ `nodes` จะยังคงไม่พร้อมใช้งานสำหรับผู้เรียกที่ไม่มีอัตลักษณ์เจ้าของ/ผู้ดูแลระบบ (`operator.admin`) แม้จะระบุไว้ใน `gateway.tools.allow` การยืนยันตัวตนแบบ bearer ด้วยข้อมูลลับที่ใช้ร่วมกันยังคงเป็นไปตามกฎผู้ปฏิบัติการที่เชื่อถือได้แบบเต็มตามที่อธิบายไว้ข้างต้น

เพื่อช่วยให้นโยบายกลุ่มแปลงบริบทได้ คุณสามารถกำหนดค่าต่อไปนี้ได้โดยไม่บังคับ:

- `x-openclaw-message-channel: <channel>` (ตัวอย่าง: `slack`, `telegram`)
- `x-openclaw-account-id: <accountId>` (เมื่อมีหลายบัญชี)
- `x-openclaw-message-to: <target>` (เป้าหมายการส่งสำหรับนโยบายเครื่องมือข้อความ)
- `x-openclaw-thread-id: <threadId>` (บริบทเธรดสำหรับนโยบายเครื่องมือข้อความ)

## การตอบกลับ

| สถานะ | ความหมาย                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------ |
| `200`  | `{ ok: true, result }`                                                                          |
| `400`  | `{ ok: false, error: { type, message } }` (คำขอไม่ถูกต้องหรือข้อผิดพลาดของอินพุตเครื่องมือ)     |
| `401`  | ไม่ได้รับอนุญาต                                                                                  |
| `403`  | `{ ok: false, error: { type, message, requiresApproval? } }` (การเรียกเครื่องมือถูกนโยบายบล็อก) |
| `404`  | เครื่องมือไม่พร้อมใช้งาน (ไม่พบหรือไม่อยู่ในรายการที่อนุญาต)                                  |
| `405`  | ไม่อนุญาตให้ใช้เมธอดนี้                                                                          |
| `408`  | หมดเวลาขณะอ่านเนื้อหาคำขอ                                                                       |
| `413`  | เนื้อหาคำขอเกินขนาดเพย์โหลดสูงสุด                                                               |
| `429`  | การยืนยันตัวตนถูกจำกัดอัตรา (มีการกำหนด `Retry-After`)                                         |
| `500`  | `{ ok: false, error: { type, message } }` (ข้อผิดพลาดที่ไม่คาดคิดในการเรียกใช้เครื่องมือ ข้อความผ่านการกรองแล้ว) |

## ตัวอย่าง

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

## เนื้อหาที่เกี่ยวข้อง

- [โปรโตคอล Gateway](/th/gateway/protocol)
- [เครื่องมือและ Plugin](/th/tools)