เครื่องมือเรียกใช้ API

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

• POST /tools/invoke
• พอร์ตเดียวกับ Gateway (มัลติเพล็กซ์ WS + HTTP): http://<gateway-host>:<port>/tools/invoke

ขนาด payload สูงสุดเริ่มต้นคือ 2 MB

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

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

เส้นทางการยืนยันตัวตน HTTP ที่พบบ่อย:

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

หมายเหตุ:

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

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

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

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

เมทริกซ์การยืนยันตัวตน:

• gateway.auth.mode="token" หรือ "password" + Authorization: Bearer ...
  • พิสูจน์การครอบครอง shared gateway operator secret
  • ไม่สนใจ x-openclaw-scopes ที่แคบกว่า
  • กู้คืนชุดขอบเขตผู้ปฏิบัติการค่าเริ่มต้นแบบเต็ม: operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write
  • ถือว่าการเรียกเครื่องมือโดยตรงบน endpoint นี้เป็นเทิร์นของ owner-sender
• โหมด HTTP ที่มีตัวตนที่เชื่อถือได้ (เช่น การยืนยันตัวตนผ่าน trusted proxy หรือ gateway.auth.mode="none" บน private ingress)
  • ยืนยันตัวตนภายนอกที่เชื่อถือได้หรือขอบเขตการปรับใช้บางอย่าง
  • เคารพ x-openclaw-scopes เมื่อมีส่วนหัวอยู่
  • fallback ไปยังชุดขอบเขตค่าเริ่มต้นของผู้ปฏิบัติการตามปกติเมื่อไม่มีส่วนหัว
  • จะเสียความหมายเชิงเจ้าของเฉพาะเมื่อผู้เรียกจำกัดขอบเขตให้แคบลงอย่างชัดเจนและละเว้น operator.admin

เนื้อหาคำขอ

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

ฟิลด์:

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

พฤติกรรมด้านนโยบายและการกำหนดเส้นทาง

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

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

หากเครื่องมือไม่ได้รับอนุญาตโดยนโยบาย endpoint จะคืนค่า 404

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

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

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

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

คุณสามารถปรับแต่งรายการปฏิเสธนี้ผ่าน gateway.tools:

{  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 เป็นการ override การเปิดเผย ไม่ใช่การอัปเกรดขอบเขต ใน โหมด HTTP ที่มีตัวตน cron, gateway และ nodes จะยังคงไม่พร้อมใช้งาน สำหรับผู้เรียกที่ไม่มีตัวตน owner/admin (operator.admin) แม้ว่า จะถูกระบุไว้ใน gateway.tools.allow ก็ตาม การยืนยันตัวตนแบบ shared-secret bearer ยังคงเป็นไปตาม กฎ trusted-operator แบบเต็มข้างต้น

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

• x-openclaw-message-channel: <channel> (ตัวอย่าง: slack, telegram)
• x-openclaw-account-id: <accountId> (เมื่อมีหลายบัญชี)

การตอบกลับ

• 200 → { ok: true, result }
• 400 → { ok: false, error: { type, message } } (คำขอไม่ถูกต้องหรือข้อผิดพลาดอินพุตของเครื่องมือ)
• 401 → ไม่ได้รับอนุญาต
• 429 → ถูกจำกัดอัตราการยืนยันตัวตน (Retry-After ถูกตั้งค่า)
• 404 → เครื่องมือไม่พร้อมใช้งาน (ไม่พบหรือไม่ได้อยู่ในรายการอนุญาต)
• 405 → ไม่อนุญาตให้ใช้เมธอด
• 500 → { ok: false, error: { type, message } } (ข้อผิดพลาดที่ไม่คาดคิดในการเรียกใช้เครื่องมือ ข้อความถูก sanitize แล้ว)

ตัวอย่าง

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
• เครื่องมือและ plugins