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

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 หากมี มิฉะนั้นจะใช้ชุดขอบเขตสิทธิ์เริ่มต้นตามปกติของผู้ปฏิบัติการ
• ให้ปลายทางนี้อยู่บนลูปแบ็ก/เทลเน็ต/ทางเข้าที่เป็นส่วนตัวเท่านั้น อย่าเปิดเผยโดยตรงสู่อินเทอร์เน็ตสาธารณะ

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

เนื้อหาคำขอ

{  "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 ยังใช้รายการปฏิเสธแบบตายตัวโดยค่าเริ่มต้น (แม้ว่านโยบายเซสชันจะอนุญาตเครื่องมือนั้น):

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

ปรับแต่งรายการปฏิเสธทั่วไปผ่าน 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 เป็นการเขียนทับการเปิดเผย ไม่ใช่การยกระดับขอบเขตสิทธิ์ ในโหมด 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> (บริบทเธรดสำหรับนโยบายเครื่องมือข้อความ)

การตอบกลับ

ตัวอย่าง

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