OpenClaw App SDK คือ API ไคลเอนต์สาธารณะสำหรับแอปที่อยู่นอกกระบวนการ OpenClaw ใช้Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
@openclaw/sdk เมื่อสคริปต์ แดชบอร์ด งาน CI ส่วนขยาย IDE
หรือแอปภายนอกอื่นต้องการเชื่อมต่อกับ Gateway, เริ่มการรันของเอเจนต์,
สตรีมอีเวนต์, รอผลลัพธ์, ยกเลิกงาน หรือตรวจสอบทรัพยากรของ Gateway
App SDK แตกต่างจาก Plugin SDK
@openclaw/sdk คุยกับ Gateway จากภายนอก OpenClaw
openclaw/plugin-sdk/* ใช้สำหรับ Plugin ที่รันอยู่ภายใน OpenClaw เท่านั้น และ
ลงทะเบียนผู้ให้บริการ ช่องทาง เครื่องมือ ฮุก หรือรันไทม์ที่เชื่อถือได้สิ่งที่มีให้วันนี้
@openclaw/sdk มาพร้อมกับ:
| ส่วนติดต่อ | สถานะ | ทำอะไร |
|---|---|---|
OpenClaw | พร้อมใช้งาน | จุดเริ่มต้นไคลเอนต์หลัก ดูแลทรานสปอร์ต การเชื่อมต่อ คำขอ และอีเวนต์ |
GatewayClientTransport | พร้อมใช้งาน | ทรานสปอร์ต WebSocket ที่รองรับโดยไคลเอนต์ Gateway |
oc.agents | พร้อมใช้งาน | แสดงรายการ สร้าง อัปเดต ลบ และรับแฮนเดิลเอเจนต์ |
Agent.run() | พร้อมใช้งาน | เริ่มการรัน Gateway agent และคืนค่า Run |
oc.runs | พร้อมใช้งาน | สร้าง รับ รอ ยกเลิก และสตรีมการรัน |
Run.events() | พร้อมใช้งาน | สตรีมอีเวนต์ต่อการรันที่ถูกปรับให้อยู่ในรูปแบบมาตรฐาน พร้อมรีเพลย์สำหรับการรันที่เร็ว |
Run.wait() | พร้อมใช้งาน | เรียก agent.wait และคืนค่า RunResult ที่เสถียร |
Run.cancel() | พร้อมใช้งาน | เรียก sessions.abort ด้วยรหัสการรัน พร้อมคีย์เซสชันเมื่อมี |
oc.sessions | พร้อมใช้งาน | สร้าง แก้ไข ส่งไปยัง แพตช์ Compaction และรับแฮนเดิลเซสชัน |
Session.send() | พร้อมใช้งาน | เรียก sessions.send และคืนค่า Run |
oc.tasks | พร้อมใช้งาน | แสดงรายการ อ่าน และยกเลิกรายการบัญชีแยกประเภทงานของ Gateway |
oc.models | พร้อมใช้งาน | เรียก models.list และ RPC สถานะ models.authStatus ปัจจุบัน |
oc.tools | พร้อมใช้งาน | แสดงรายการ กำหนดขอบเขต และเรียกใช้เครื่องมือ Gateway ผ่านไปป์ไลน์นโยบาย |
oc.artifacts | พร้อมใช้งาน | แสดงรายการ รับ และดาวน์โหลดอาร์ทิแฟกต์ทรานสคริปต์ของ Gateway |
oc.approvals | พร้อมใช้งาน | แสดงรายการและแก้ไขการอนุมัติ exec ผ่าน RPC การอนุมัติของ Gateway |
oc.environments | บางส่วน | แสดงรายการตัวเลือกสภาพแวดล้อมแบบ Gateway-local และโหนด; create/delete ยังไม่ได้เชื่อมต่อ |
oc.rawEvents() | พร้อมใช้งาน | เปิดเผยอีเวนต์ Gateway ดิบสำหรับผู้บริโภคขั้นสูง |
normalizeGatewayEvent() | พร้อมใช้งาน | แปลงอีเวนต์ Gateway ดิบเป็นรูปแบบอีเวนต์ SDK ที่เสถียร |
AgentRunParams, RunResult, RunStatus, OpenClawEvent,
OpenClawEventType, GatewayEvent, OpenClawTransport,
GatewayRequestOptions, SessionCreateParams, SessionSendParams,
ArtifactSummary, ArtifactQuery, ArtifactsListResult,
ArtifactsGetResult, ArtifactsDownloadResult,
TaskSummary, TaskStatus, TasksListParams, TasksListResult,
TasksGetResult, TasksCancelResult, RuntimeSelection,
EnvironmentSelection, WorkspaceSelection, ApprovalMode และชนิดผลลัพธ์ที่เกี่ยวข้อง
เชื่อมต่อกับ Gateway
สร้างไคลเอนต์ด้วย URL ของ Gateway ที่ระบุชัดเจน หรือใส่ทรานสปอร์ตแบบกำหนดเองสำหรับ การทดสอบและรันไทม์แอปแบบฝังตัวnew OpenClaw({ gateway: "ws://..." }) เทียบเท่ากับ url ตัวเลือก
gateway: "auto" ได้รับการยอมรับโดยคอนสตรักเตอร์ แต่การค้นหา Gateway อัตโนมัติ
ยังไม่ใช่ฟีเจอร์ SDK แยกต่างหาก; ให้ส่ง url เมื่อแอปยังไม่รู้วิธีค้นหา Gateway
สำหรับการทดสอบ ให้ส่งออบเจ็กต์ที่อิมพลีเมนต์ OpenClawTransport:
รันเอเจนต์
ใช้oc.agents.get(id) เมื่อแอปต้องการแฮนเดิลเอเจนต์ จากนั้นเรียก
agent.run()
openai/gpt-5.5 จะถูกแยกเป็นการ override
provider และ model ของ Gateway timeoutMs ยังคงเป็นมิลลิวินาทีใน SDK และ
ถูกแปลงเป็นวินาทีของ timeout ของ Gateway สำหรับ RPC agent
run.wait() ใช้ RPC agent.wait ของ Gateway กำหนดเวลารอที่หมดอายุขณะที่การรัน
ยังทำงานอยู่จะคืนค่า status: "accepted" แทนการทำเหมือนว่าการรันเองหมดเวลา
timeout ของรันไทม์ การรันที่ถูก abort และการรันที่ถูกยกเลิกจะถูกปรับให้อยู่ในรูปแบบ
timed_out หรือ cancelled
สร้างและใช้เซสชันซ้ำ
ใช้เซสชันเมื่อแอปต้องการสถานะทรานสคริปต์ที่คงทนSession.send() เรียก sessions.send และคืนค่า Run แฮนเดิลเซสชันยังรองรับ:
สตรีมอีเวนต์
SDK ปรับอีเวนต์ Gateway ดิบให้อยู่ในซองOpenClawEvent ที่เสถียร:
| ชนิดอีเวนต์ | อีเวนต์ Gateway ต้นทาง |
|---|---|
run.started | จุดเริ่มต้น lifecycle ของ agent |
run.completed | จุดสิ้นสุด lifecycle ของ agent |
run.failed | ข้อผิดพลาด lifecycle ของ agent |
run.cancelled | จุดสิ้นสุด lifecycle ที่ถูก abort/ยกเลิก |
run.timed_out | จุดสิ้นสุด lifecycle เนื่องจาก timeout |
assistant.delta | delta การสตรีมของผู้ช่วย |
assistant.message | ข้อความของผู้ช่วย |
thinking.delta | สตรีมการคิดหรือแผน |
tool.call.started | จุดเริ่มต้นเครื่องมือ/รายการ/คำสั่ง |
tool.call.delta | การอัปเดตเครื่องมือ/รายการ/คำสั่ง |
tool.call.completed | การเสร็จสมบูรณ์ของเครื่องมือ/รายการ/คำสั่ง |
tool.call.failed | ความล้มเหลวหรือสถานะถูกบล็อกของเครื่องมือ/รายการ/คำสั่ง |
approval.requested | คำขออนุมัติ exec หรือ Plugin |
approval.resolved | การแก้ไขผลอนุมัติ exec หรือ Plugin |
session.created | การสร้าง sessions.changed |
session.updated | การอัปเดต sessions.changed |
session.compacted | Compaction ของ sessions.changed |
task.updated | อีเวนต์อัปเดตงาน |
artifact.updated | อีเวนต์สตรีมแพตช์ |
raw | อีเวนต์ใดๆ ที่ยังไม่มีการแมป SDK ที่เสถียร |
Run.events() กรองอีเวนต์ให้เหลือรหัสการรันเดียว และรีเพลย์อีเวนต์ที่เห็นแล้วสำหรับ
การรันที่เร็ว ซึ่งหมายความว่าโฟลว์ที่บันทึกไว้ปลอดภัย:
oc.events() สำหรับเฟรม Gateway ดิบ ให้ใช้
oc.rawEvents()
โมเดล เครื่องมือ อาร์ทิแฟกต์ และการอนุมัติ
ตัวช่วยโมเดลแมปกับเมธอด Gateway ปัจจุบัน:oc.tools.invoke() คืนค่าซองที่มีชนิด แทนการโยนข้อผิดพลาด
เมื่อถูกปฏิเสธโดยนโยบายหรือการอนุมัติ
sessionKey, runId หรือ
taskId อย่างใดอย่างหนึ่งที่ระบุชัดเจน:
openclaw tasks ด้วย:
สิ่งที่ไม่รองรับอย่างชัดเจนในวันนี้
SDK รวมชื่อสำหรับโมเดลผลิตภัณฑ์ที่เราต้องการ แต่จะไม่แกล้งทำเงียบๆ ว่า RPC ของ Gateway มีอยู่ การเรียกเหล่านี้ปัจจุบันจะโยนข้อผิดพลาด unsupported อย่างชัดเจน:workspace, runtime, environment และ approvals ต่อการรันถูกกำหนดชนิด
เป็นรูปแบบในอนาคต แต่ Gateway ปัจจุบันยังไม่รองรับการ override เหล่านั้นบน RPC
agent หากผู้เรียกส่งฟิลด์เหล่านี้ SDK จะโยนข้อผิดพลาดก่อนส่งการรัน เพื่อไม่ให้งาน
ถูกดำเนินการโดยไม่ตั้งใจด้วยพฤติกรรม workspace, runtime, environment หรือ approval
ค่าเริ่มต้น
App SDK เทียบกับ Plugin SDK
ใช้ App SDK เมื่อโค้ดอยู่นอก OpenClaw:- สคริปต์ Node ที่เริ่มหรือสังเกตการรันของเอเจนต์
- งาน CI ที่เรียก Gateway
- แดชบอร์ดและแผงผู้ดูแล
- ส่วนขยาย IDE
- บริดจ์ภายนอกที่ไม่จำเป็นต้องกลายเป็น Plugin ช่องทาง
- การทดสอบอินทิเกรชันด้วยทรานสปอร์ต Gateway ปลอมหรือจริง
- Plugin ผู้ให้บริการ
- Plugin ช่องทาง
- ฮุกเครื่องมือหรือ lifecycle
- Plugin ฮาร์เนสเอเจนต์
- ตัวช่วยรันไทม์ที่เชื่อถือได้
@openclaw/sdk โค้ด Plugin ควร import จาก
subpath openclaw/plugin-sdk/* ที่บันทึกไว้ในเอกสาร อย่าผสมสัญญาทั้งสองนี้