การเติมเต็มการสนทนาของ OpenAI

Gateway สามารถให้บริการพื้นผิว Chat Completions ขนาดเล็กที่เข้ากันได้กับ OpenAI โดย ปิดใช้งานเป็นค่าเริ่มต้น

เมื่อเปิดใช้งานแล้ว ระบบจะให้บริการรายการทั้งหมดต่อไปนี้บนพอร์ตเดียวกับ Gateway (มัลติเพล็กซ์ WS + HTTP):

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

การเปิดใช้งานปลายทาง

{  gateway: {    http: {      endpoints: {        chatCompletions: { enabled: true },      },    },  },}

ตั้งค่า enabled: false (หรือละไว้) เพื่อปิดใช้งาน

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

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

• โทเค็น/รหัสผ่าน Gateway ที่ถูกต้องสำหรับปลายทางนี้เทียบเท่ากับข้อมูลรับรองของเจ้าของ/ผู้ดำเนินการ ไม่ใช่ขอบเขตแบบจำกัดเฉพาะผู้ใช้
• คำขอจะผ่านเส้นทางเอเจนต์ของระนาบควบคุมเดียวกับการดำเนินการของผู้ดำเนินการที่เชื่อถือได้ ดังนั้นหากนโยบายของเอเจนต์เป้าหมายอนุญาตเครื่องมือที่มีความละเอียดอ่อน ปลายทางนี้ก็สามารถใช้เครื่องมือเหล่านั้นได้
• ให้เปิดใช้งานเฉพาะบน local loopback/tailnet/ทางเข้าระบบส่วนตัวเท่านั้น อย่าเปิดเผยต่ออินเทอร์เน็ตสาธารณะ

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

ดู ขอบเขตของผู้ดำเนินการ, ความปลอดภัย และ การเข้าถึงระยะไกล

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

ใช้การกำหนดค่าการยืนยันตัวตนของ Gateway (ดูรายละเอียดของโหมดดังกล่าวที่ การยืนยันตัวตนผ่านพร็อกซีที่เชื่อถือได้):

หมายเหตุ:

• ผู้เรียกบนโฮสต์เดียวกันที่ข้ามพร็อกซีบน Gateway แบบ trusted-proxy สามารถย้อนกลับไปใช้ gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD โดยตรงได้ หากมีหลักฐานจากส่วนหัว Forwarded, X-Forwarded-* หรือ X-Real-IP คำขอจะยังคงอยู่บนเส้นทางพร็อกซีที่เชื่อถือได้แทน
• หากกำหนดค่า gateway.auth.rateLimit และมีความพยายามยืนยันตัวตนล้มเหลวมากเกินไป ปลายทางจะส่งคืน 429 พร้อมส่วนหัว Retry-After

กรณีที่ควรใช้ปลายทางนี้

• เลือกใช้วิธีนี้แทนการเพิ่มช่องทางในตัวใหม่ เมื่อการผสานรวมของคุณเป็นเพียงพื้นผิวผู้ดำเนินการ/ไคลเอนต์อีกแบบหนึ่งสำหรับ Gateway เดียวกัน
• สำหรับไคลเอนต์มือถือแบบเนทีฟที่เชื่อมต่อโดยตรงกับ Gateway ระยะไกล ให้เลือกใช้ WebChat หรือ โปรโตคอล Gateway พร้อมโฟลว์เริ่มต้นอุปกรณ์ที่จับคู่/โทเค็นอุปกรณ์ เพื่อให้อุปกรณ์ไม่จำเป็นต้องใช้โทเค็น/รหัสผ่าน HTTP ร่วม
• ให้สร้าง Plugin ช่องทางแทน เมื่อต้องผสานรวมเครือข่ายรับส่งข้อความภายนอกที่มีผู้ใช้ ห้อง การส่ง Webhook หรือการขนส่งขาออกเป็นของตนเอง ดู การสร้าง Plugin

สัญญาโมเดลที่ให้เอเจนต์เป็นหลัก

OpenClaw ถือว่าฟิลด์ model ของ OpenAI เป็น เป้าหมายเอเจนต์ ไม่ใช่รหัสโมเดลดิบของผู้ให้บริการ

ส่วนหัวคำขอที่เลือกใช้ได้:

/v1/models แสดงรายการเป้าหมายเอเจนต์ระดับบนสุด (openclaw, openclaw/default, openclaw/<agentId>) ไม่ใช่โมเดลแบ็กเอนด์ของผู้ให้บริการและไม่ใช่เอเจนต์ย่อย โดยเอเจนต์ย่อยยังคงเป็นโทโพโลยีการดำเนินงานภายใน หากละ x-openclaw-model เอเจนต์ที่เลือกจะทำงานด้วยโมเดลที่กำหนดค่าตามปกติ

/v1/embeddings ใช้รหัส model ของเป้าหมายเอเจนต์แบบเดียวกัน ส่ง x-openclaw-model (จากผู้เรียกที่ใช้ข้อมูลลับร่วม หรือผู้เรียกที่มีข้อมูลระบุตัวตนและมี operator.admin) เพื่อเลือกโมเดลการฝังเฉพาะ มิฉะนั้นคำขอจะใช้การตั้งค่าการฝังตามปกติของเอเจนต์ที่เลือก

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

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

หากคำขอมีสตริง user ของ OpenAI Gateway จะสร้างคีย์เซสชันที่เสถียรจากค่านั้น เพื่อให้การเรียกซ้ำสามารถใช้เซสชันเอเจนต์ร่วมกันได้ สำหรับแอปที่สร้างเอง ให้ใช้ค่า user เดียวกันซ้ำต่อเธรดการสนทนา และหลีกเลี่ยงตัวระบุระดับบัญชี เว้นแต่คุณต้องการให้หลายการสนทนา/อุปกรณ์ใช้เซสชัน OpenClaw เดียวกัน ใช้ x-openclaw-session-key เฉพาะเมื่อต้องการควบคุมการกำหนดเส้นทางอย่างชัดเจนระหว่างไคลเอนต์/เธรดหลายรายการ โดยใช้คีย์ที่แอปพลิเคชันเป็นเจ้าของและหลีกเลี่ยงเนมสเปซที่สงวนไว้ข้างต้น

ขีดจำกัดคำขอ (การกำหนดค่า)

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

{  gateway: {    http: {      endpoints: {        chatCompletions: {          enabled: true,          maxBodyBytes: 20000000,          maxImageParts: 8,          maxTotalImageBytes: 20000000,          images: {            allowUrl: false,            urlAllowlist: ["cdn.example.com", "*.assets.example.com"],            allowedMimes: [              "image/jpeg",              "image/png",              "image/gif",              "image/webp",              "image/heic",              "image/heif",            ],            maxBytes: 10485760,            maxRedirects: 3,            timeoutMs: 10000,          },        },      },    },  },}

ค่าเริ่มต้นเมื่อละไว้:

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

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

สัญญาเครื่องมือแชต

/v1/chat/completions รองรับชุดย่อยของเครื่องมือฟังก์ชันที่เข้ากันได้กับไคลเอนต์ OpenAI Chat ทั่วไป

ฟิลด์คำขอที่รองรับ

ฟิลด์การสุ่มตัวอย่างและการจำกัดโทเค็นทั้งหมดใช้ช่องทางพารามิเตอร์สตรีมของเอเจนต์เดียวกัน และจะถูกส่งต่อตามความสามารถ:

• ขีดจำกัดโทเค็น: ชื่อฟิลด์บนสายสื่อสารถูกเลือกตามทรานสปอร์ตของผู้ให้บริการ: max_completion_tokens สำหรับเอนด์พอยต์ตระกูล OpenAI และ max_tokens สำหรับผู้ให้บริการที่ยอมรับเฉพาะชื่อแบบเดิม (Mistral, Chutes)
• stop จะจับคู่กับฟิลด์หยุดของทรานสปอร์ต: stop สำหรับแบ็กเอนด์ Chat Completions และ stop_sequences สำหรับ Anthropic เนื่องจาก OpenAI Responses API ไม่มีพารามิเตอร์หยุด จึงไม่มีการใช้ stop กับโมเดลที่ใช้ Responses เป็นแบ็กเอนด์
• แบ็กเอนด์ Codex Responses ที่ใช้ ChatGPT ใช้การสุ่มตัวอย่างคงที่ฝั่งเซิร์ฟเวอร์ และนำ temperature/top_p (รวมถึง max_output_tokens, metadata, prompt_cache_retention, service_tier) ออกก่อนที่คำขอจะไปถึงแบ็กเอนด์นั้น

รูปแบบที่ไม่รองรับ

ส่งคืน 400 invalid_request_error สำหรับ:

• tools ที่ไม่ใช่อาร์เรย์ รายการเครื่องมือที่ไม่ใช่ฟังก์ชัน หรือไม่มี tool.function.name
• รูปแบบ tool_choice เช่น allowed_tools และ custom
• ค่า tool_choice.function.name ที่ไม่ตรงกับเครื่องมือที่ระบุไว้

สำหรับ tool_choice: "required" และ tool_choice ที่ตรึงฟังก์ชัน เอนด์พอยต์จะจำกัดชุดเครื่องมือฟังก์ชันของไคลเอนต์ที่เปิดเผย สั่งให้รันไทม์เรียกเครื่องมือของไคลเอนต์ก่อนตอบกลับ และส่งข้อผิดพลาดหากการตอบกลับของเอเจนต์ไม่มีการเรียกเครื่องมือไคลเอนต์แบบมีโครงสร้างที่ตรงกัน ข้อนี้ใช้กับรายการ HTTP tools ที่ผู้เรียกส่งมา ไม่ใช่เครื่องมือภายในทั้งหมดของเอเจนต์ OpenClaw

รูปแบบการตอบกลับจากเครื่องมือแบบไม่สตรีม

เมื่อเอเจนต์เรียกเครื่องมือ การตอบกลับจะใช้:

• choices[0].finish_reason = "tool_calls"
• รายการ choices[0].message.tool_calls[] ที่มี id, type: "function", function.name, function.arguments (สตริง JSON)
• คำอธิบายของผู้ช่วยก่อนการเรียกเครื่องมือใน choices[0].message.content (อาจว่างเปล่า)

รูปแบบการตอบกลับจากเครื่องมือแบบสตรีม

เมื่อ stream: true การเรียกเครื่องมือจะมาถึงเป็นส่วนย่อย SSE แบบต่อเนื่อง: เดลตาบทบาทผู้ช่วยเริ่มต้น เดลตาคำอธิบายของผู้ช่วยที่อาจมีหรือไม่มีก็ได้ ส่วนย่อย delta.tool_calls หนึ่งรายการขึ้นไปที่มีข้อมูลระบุตัวเครื่องมือและส่วนย่อยของอาร์กิวเมนต์ จากนั้นจึงเป็นส่วนย่อยสุดท้ายที่มี finish_reason: "tool_calls" และ data: [DONE]

หาก stream_options.include_usage=true ระบบจะส่งส่วนย่อยข้อมูลการใช้งานปิดท้ายก่อน [DONE]

ลูปการติดตามผลของเครื่องมือ

หลังจากได้รับ tool_calls ให้เรียกใช้ฟังก์ชันที่ร้องขอ แล้วส่งคำขอติดตามผลซึ่งรวมข้อความการเรียกเครื่องมือของผู้ช่วยก่อนหน้า พร้อมข้อความ role: "tool" อย่างน้อยหนึ่งข้อความที่มี tool_call_id ตรงกัน การดำเนินการนี้จะสานต่อลูปการให้เหตุผลของเอเจนต์เดิมเพื่อสร้างคำตอบสุดท้าย

การสตรีม (SSE)

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

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

การตั้งค่า Open WebUI อย่างรวดเร็ว

• URL ฐาน: http://127.0.0.1:18789/v1
• URL ฐานสำหรับ Docker บน macOS: http://host.docker.internal:18789/v1
• คีย์ API: โทเค็น bearer ของ Gateway ของคุณ
• โมเดล: openclaw/default

ลักษณะการทำงานที่คาดไว้: GET /v1/models แสดงรายการ openclaw/default และ Open WebUI ใช้ค่านี้เป็นรหัสโมเดลแชต สำหรับผู้ให้บริการ/โมเดลแบ็กเอนด์เฉพาะ ให้ตั้งค่าโมเดลเริ่มต้นตามปกติของเอเจนต์ หรือส่ง x-openclaw-model (ผู้เรียกที่ใช้ข้อมูลลับร่วมกัน หรือผู้เรียกที่มีข้อมูลระบุตัวตนพร้อม operator.admin)

การทดสอบเบื้องต้นอย่างรวดเร็ว:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

หากคำสั่งนี้ส่งคืน openclaw/default การตั้งค่า Open WebUI ส่วนใหญ่จะเชื่อมต่อได้ด้วย URL ฐานและโทเค็นเดียวกัน

ตัวอย่าง

เซสชันที่คงที่สำหรับการสนทนาหนึ่งรายการของแอป:

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "user": "conv:YOUR_CONVERSATION_ID",    "messages": [{"role":"user","content":"Summarize my tasks for today"}]  }'

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

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

curl -sS http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -d '{    "model": "openclaw/default",    "messages": [{"role":"user","content":"hi"}]  }'

แบบสตรีม:

curl -N http://127.0.0.1:18789/v1/chat/completions \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/gpt-5.4' \  -d '{    "model": "openclaw/research",    "stream": true,    "messages": [{"role":"user","content":"hi"}]  }'

แสดงรายการโมเดล:

curl -sS http://127.0.0.1:18789/v1/models \  -H 'Authorization: Bearer YOUR_TOKEN'

ดึงข้อมูลโมเดลหนึ่งรายการ:

curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \  -H 'Authorization: Bearer YOUR_TOKEN'

สร้างเวกเตอร์ฝังตัว:

curl -sS http://127.0.0.1:18789/v1/embeddings \  -H 'Authorization: Bearer YOUR_TOKEN' \  -H 'Content-Type: application/json' \  -H 'x-openclaw-model: openai/text-embedding-3-small' \  -d '{    "model": "openclaw/default",    "input": ["alpha", "beta"]  }'

/v1/embeddings รองรับ input ในรูปแบบสตริงหรืออาร์เรย์ของสตริง

ที่เกี่ยวข้อง

• เอกสารอ้างอิงการกำหนดค่า
• ขอบเขตสิทธิ์ของผู้ดำเนินการ
• OpenAI