API OpenResponses

Gateway สามารถให้บริการเอนด์พอยต์ POST /v1/responses ที่เข้ากันได้กับ OpenResponses โดยเอนด์พอยต์นี้ ปิดใช้งานโดยค่าเริ่มต้น และใช้พอร์ตเดียวกับ Gateway (มัลติเพล็กซ์ WS + HTTP): http://<gateway-host>:<port>/v1/responses

คำขอจะทำงานในรูปแบบการรันเอเจนต์ Gateway ตามปกติ (ใช้เส้นทางโค้ดเดียวกับ openclaw agent) ดังนั้นการกำหนดเส้นทาง สิทธิ์ และการกำหนดค่าจึงตรงกับ Gateway ของคุณ

เปิดหรือปิดใช้งานด้วย gateway.http.endpoints.responses.enabled เมื่อเปิดใช้งาน พื้นผิวความเข้ากันได้เดียวกันนี้จะให้บริการ GET /v1/models, GET /v1/models/{id}, POST /v1/embeddings และ POST /v1/chat/completions ด้วย

การยืนยันตัวตน ความปลอดภัย และการกำหนดเส้นทาง

ลักษณะการทำงานสอดคล้องกับ OpenAI Chat Completions:

• เส้นทางการยืนยันตัวตนสอดคล้องกับ gateway.auth.mode: แบบข้อมูลลับที่ใช้ร่วมกัน (token/password) ใช้ Authorization: Bearer <token-or-password>; แบบพร็อกซีที่เชื่อถือใช้ส่วนหัวของพร็อกซีที่รับรู้ข้อมูลประจำตัว (พร็อกซี local loopback บนโฮสต์เดียวกันต้องใช้ gateway.auth.trustedProxy.allowLoopback = true พร้อมทางเลือกสำรองสำหรับการเชื่อมต่อโดยตรงบนโฮสต์เดียวกันผ่าน gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD เมื่อไม่มีส่วนหัว Forwarded/X-Forwarded-*/X-Real-IP); none บนช่องทางขาเข้าส่วนตัวไม่ต้องใช้ส่วนหัวการยืนยันตัวตน ดู การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือ
• ให้ถือว่าเอนด์พอยต์นี้มีสิทธิ์ผู้ควบคุมอย่างเต็มรูปแบบสำหรับอินสแตนซ์ Gateway
• โหมดการยืนยันตัวตนแบบข้อมูลลับที่ใช้ร่วมกันจะไม่สนใจ x-openclaw-scopes ที่ประกาศผ่าน bearer ซึ่งมีขอบเขตแคบกว่า และคืนค่าชุดขอบเขตผู้ควบคุมเริ่มต้นแบบเต็ม ได้แก่ operator.admin, operator.approvals, operator.pairing, operator.read, operator.talk.secrets, operator.write รอบการสนทนาบนเอนด์พอยต์นี้จะถือว่าเป็นรอบที่ส่งโดยเจ้าของ
• โหมด HTTP ที่มีข้อมูลประจำตัวที่เชื่อถือ (พร็อกซีที่เชื่อถือ หรือ gateway.auth.mode="none") จะใช้ x-openclaw-scopes หากมี มิฉะนั้นจะใช้ชุดขอบเขตผู้ควบคุมเริ่มต้นเป็นทางเลือกสำรอง ความหมายของการเป็นเจ้าของจะสูญหายเฉพาะเมื่อผู้เรียกจำกัดขอบเขตอย่างชัดเจนและไม่รวม operator.admin
• เลือกเอเจนต์ด้วย model: "openclaw", "openclaw/default", "openclaw/<agentId>" หรือส่วนหัว x-openclaw-agent-id
• ใช้ x-openclaw-model เพื่อแทนที่โมเดลแบ็กเอนด์ของเอเจนต์ที่เลือก (ต้องมี operator.admin บนเส้นทางการยืนยันตัวตนที่มีข้อมูลประจำตัว)
• ใช้ x-openclaw-session-key เพื่อกำหนดเส้นทางเซสชันอย่างชัดเจน (จะถูกปฏิเสธด้วย 400 invalid_request_error หากใช้เนมสเปซที่สงวนไว้ ได้แก่ subagent:, cron:, acp:)
• ใช้ x-openclaw-message-channel สำหรับบริบทช่องทางขาเข้าสังเคราะห์ที่ไม่ใช่ค่าเริ่มต้น

สำหรับคำอธิบายมาตรฐานเกี่ยวกับโมเดลที่กำหนดเป้าหมายเอเจนต์, openclaw/default, การส่งต่อ embeddings และการแทนที่โมเดลแบ็กเอนด์ โปรดดู OpenAI Chat Completions

ดู ขอบเขตผู้ควบคุม และ ความปลอดภัย

ลักษณะการทำงานของเซสชัน

โดยค่าเริ่มต้น เอนด์พอยต์นี้ ไม่เก็บสถานะสำหรับแต่ละคำขอ (ระบบจะสร้างคีย์เซสชันใหม่ในแต่ละครั้งที่เรียก)

หากคำขอมีสตริง OpenResponses user Gateway จะสร้างคีย์เซสชันแบบคงที่จากค่านั้น เพื่อให้การเรียกซ้ำสามารถใช้เซสชันเอเจนต์ร่วมกันได้

previous_response_id จะนำเซสชันของการตอบกลับก่อนหน้ากลับมาใช้ เมื่อคำขอยังคงอยู่ภายในขอบเขตเอเจนต์/ผู้ใช้/เซสชันที่ร้องขอเดียวกัน (จับคู่ด้วยประธานการยืนยันตัวตน รหัสเอเจนต์ และ x-openclaw-session-key)

รูปแบบคำขอ

รายการ (input)

message

บทบาท: system, developer, user, assistant

• system และ developer จะถูกต่อท้ายพรอมต์ระบบ
• รายการ user หรือ function_call_output ล่าสุดจะกลายเป็น "ข้อความปัจจุบัน"
• ข้อความของผู้ใช้/ผู้ช่วยก่อนหน้าจะรวมเป็นประวัติเพื่อใช้เป็นบริบท

function_call_output (เครื่องมือแบบแบ่งตามรอบ)

ส่งผลลัพธ์ของเครื่องมือกลับไปยังโมเดล:

{  "type": "function_call_output",  "call_id": "call_123",  "output": "{\"temperature\": \"72F\"}"}

reasoning และ item_reference

ยอมรับเพื่อความเข้ากันได้ของสคีมา แต่จะไม่นำไปใช้เมื่อสร้างพรอมต์

เครื่องมือ (เครื่องมือฟังก์ชันฝั่งไคลเอนต์)

ระบุเครื่องมือด้วย tools: [{ type: "function", name, description?, parameters? }]

หากเอเจนต์เรียกใช้เครื่องมือ การตอบกลับจะส่งคืนรายการเอาต์พุต function_call ส่งคำขอต่อเนื่องพร้อม function_call_output เพื่อดำเนินรอบต่อไป

สำหรับ tool_choice: "required" และ tool_choice ที่ตรึงฟังก์ชัน เอนด์พอยต์จะจำกัดชุดเครื่องมือฟังก์ชันของไคลเอนต์ที่เปิดเผย สั่งให้รันไทม์เรียกเครื่องมือของไคลเอนต์ก่อนตอบกลับ และปฏิเสธรอบหากไม่มีการเรียกเครื่องมือของไคลเอนต์แบบมีโครงสร้างที่ตรงกัน ซึ่งสอดคล้องกับสัญญาของ /v1/chat/completions คำขอที่ไม่สตรีมจะส่งคืน 502 พร้อม api_error; คำขอแบบสตรีมจะส่งเหตุการณ์ response.failed

รูปภาพ (input_image)

รองรับแหล่งข้อมูลแบบ base64 หรือ URL:

{  "type": "input_image",  "source": { "type": "url", "url": "https://example.com/image.png" }}

ประเภท MIME ที่อนุญาต (ค่าเริ่มต้น): image/jpeg, image/png, image/gif, image/webp, image/heic, image/heif ขนาดสูงสุด (ค่าเริ่มต้น): 10MB

ไฟล์ (input_file)

รองรับแหล่งข้อมูลแบบ base64 หรือ URL:

{  "type": "input_file",  "source": {    "type": "base64",    "media_type": "text/plain",    "data": "SGVsbG8gV29ybGQh",    "filename": "hello.txt"  }}

ประเภท MIME ที่อนุญาต (ค่าเริ่มต้น): text/plain, text/markdown, text/html, text/csv, application/json, application/pdf ขนาดสูงสุด (ค่าเริ่มต้น): 5MB

ลักษณะการทำงานปัจจุบัน:

• เนื้อหาไฟล์จะถูกถอดรหัสและเพิ่มลงใน พรอมต์ระบบ ไม่ใช่ข้อความของผู้ใช้ จึงคงอยู่เพียงชั่วคราว (ไม่ถูกบันทึกไว้ในประวัติเซสชัน)
• ข้อความไฟล์ที่ถอดรหัสแล้วจะถูกครอบเป็น เนื้อหาภายนอกที่ไม่น่าเชื่อถือ ก่อนเพิ่มเข้าไป เพื่อให้ไบต์ของไฟล์ถูกมองเป็นข้อมูล ไม่ใช่คำสั่งที่เชื่อถือได้ บล็อกที่แทรกจะใช้เครื่องหมายขอบเขตอย่างชัดเจน (<<&lt;EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>> / <<&lt;END_EXTERNAL_UNTRUSTED_CONTENT id=&quot;...&quot;&gt;>>) และบรรทัดข้อมูลเมตา Source: External โดยจงใจละแบนเนอร์ SECURITY NOTICE: แบบยาวเพื่อรักษางบประมาณพรอมต์ แต่เครื่องหมายขอบเขตและข้อมูลเมตายังคงมีผล
• ระบบจะแยกวิเคราะห์ข้อความจาก PDF ก่อน หากพบข้อความน้อย หน้าแรก ๆ จะถูกแรสเตอร์เป็นรูปภาพและส่งให้โมเดล และบล็อกไฟล์ที่แทรกจะใช้ตัวยึดตำแหน่ง [PDF content rendered to images]

การแยกวิเคราะห์ PDF ให้บริการโดย Plugin document-extract ที่รวมมาให้ ซึ่งใช้ clawpdf และรันไทม์ PDFium WebAssembly ที่บรรจุมาด้วยสำหรับการแยกข้อความและการเรนเดอร์หน้า

ค่าเริ่มต้นของการดึงข้อมูลจาก URL:

• files.allowUrl: true
• images.allowUrl: true
• maxUrlParts: 8 (จำนวนส่วน input_file + input_image ที่อิง URL รวมต่อคำขอ)
• คำขอได้รับการป้องกัน (การแปลงชื่อ DNS, การบล็อก IP ส่วนตัว, ขีดจำกัดการเปลี่ยนเส้นทาง, การหมดเวลา)
• รองรับรายการชื่อโฮสต์ที่อนุญาตซึ่งกำหนดหรือไม่ก็ได้สำหรับอินพุตแต่ละประเภท (files.urlAllowlist, images.urlAllowlist): โฮสต์แบบตรงทั้งหมด ("cdn.example.com") หรือโดเมนย่อยแบบไวลด์การ์ด ("*.assets.example.com" ซึ่งไม่ตรงกับโดเมนราก) รายการที่ว่างหรือไม่ได้ระบุหมายถึงไม่มีข้อจำกัดจากรายการชื่อโฮสต์ที่อนุญาต
• หากต้องการปิดการดึงข้อมูลผ่าน URL ทั้งหมด ให้ตั้งค่า files.allowUrl: false และ/หรือ images.allowUrl: false

ขีดจำกัดไฟล์และรูปภาพ (การกำหนดค่า)

สามารถปรับค่าเริ่มต้นภายใต้ gateway.http.endpoints.responses:

{  gateway: {    http: {      endpoints: {        responses: {          enabled: true,          maxBodyBytes: 20000000,          maxUrlParts: 8,          files: {            allowUrl: true,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "text/plain",              "text/markdown",              "text/html",              "text/csv",              "application/json",              "application/pdf",            ],            maxBytes: 5242880,            maxChars: 60000,            maxRedirects: 3,            timeoutMs: 10000,            pdf: {              maxPages: 4,              maxPixels: 4000000,              minTextChars: 200,            },          },          images: {            allowUrl: true,            urlAllowlist: ["images.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

ค่าเริ่มต้นเมื่อไม่ได้ระบุ:

แหล่งข้อมูล input_image แบบ HEIC/HEIF จะถูกแปลงเป็น JPEG ก่อนส่งให้ผู้ให้บริการผ่านตัวประมวลผลรูปภาพที่ใช้ร่วมกันของ OpenClaw (Rastermill) ซึ่งจะใช้ตัวแปลงของระบบ (sips, ImageMagick, GraphicsMagick หรือ ffmpeg) เป็นทางเลือกสำรองสำหรับรูปแบบที่ต้องรองรับโคเดกภายนอก

หมายเหตุด้านความปลอดภัย: รายการ URL ที่อนุญาตจะถูกบังคับใช้ก่อนดึงข้อมูลและในแต่ละช่วงของการเปลี่ยนเส้นทาง การอนุญาตชื่อโฮสต์ไม่ได้ข้ามการบล็อก IP ส่วนตัว/ภายใน สำหรับ Gateway ที่เปิดให้เข้าถึงจากอินเทอร์เน็ต ให้ใช้การควบคุมทราฟฟิกเครือข่ายขาออกร่วมกับกลไกป้องกันระดับแอปพลิเคชัน ดู ความปลอดภัย

การสตรีม (SSE)

ตั้งค่า stream: true เพื่อรับ Server-Sent Events:

• Content-Type: text/event-stream
• แต่ละบรรทัดของเหตุการณ์อยู่ในรูปแบบ event: <type> และ data: <json>
• สตรีมสิ้นสุดด้วย data: [DONE]

ประเภทเหตุการณ์ที่ส่งออกในปัจจุบัน ได้แก่ response.created, response.in_progress, response.output_item.added, response.content_part.added, response.output_text.delta, response.output_text.done, response.content_part.done, response.output_item.done, response.completed, response.failed (เมื่อเกิดข้อผิดพลาด)

การใช้งาน

usage จะมีข้อมูลเมื่อผู้ให้บริการเบื้องหลังรายงานจำนวนโทเค็น OpenClaw จะปรับชื่อแทนที่ใช้กันทั่วไปในรูปแบบ OpenAI ให้เป็นมาตรฐานก่อนที่ตัวนับเหล่านั้นจะส่งต่อไปยังส่วนแสดงสถานะ/เซสชันปลายทาง รวมถึง input_tokens / output_tokens และ prompt_tokens / completion_tokens

ข้อผิดพลาด

ข้อผิดพลาดใช้วัตถุ JSON ในลักษณะดังนี้:

{ "error": { "message": "...", "type": "invalid_request_error" } }

กรณีทั่วไป: 400 เนื้อหาคำขอไม่ถูกต้อง, 401 ไม่มีข้อมูลยืนยันตัวตนหรือข้อมูลไม่ถูกต้อง, 403 ไม่มีขอบเขตสิทธิ์ของผู้ดำเนินการ, 405 ใช้เมธอดไม่ถูกต้อง, 429 มีความพยายามยืนยันตัวตนที่ล้มเหลวมากเกินไป (พร้อม Retry-After)

ตัวอย่าง

แบบไม่สตรีม:

curl -sS http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "input": "hi"  }'

แบบสตรีม:

curl -N http://127.0.0.1:18789/v1/responses \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-agent-id: main' \  -d '{    "model": "openclaw",    "stream": true,    "input": "hi"  }'

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

• การเติมข้อความแชตของ OpenAI
• ขอบเขตสิทธิ์ของผู้ดำเนินการ
• OpenAI