تکمیل‌های گفت‌وگوی OpenAI

Gateway می‌تواند یک سطح کوچک و سازگار با OpenAI برای Chat Completions ارائه کند. این قابلیت به‌طور پیش‌فرض غیرفعال است.

پس از فعال‌سازی، همهٔ موارد زیر را روی همان درگاه 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 نیاز نداشته باشد.
• هنگام یکپارچه‌سازی یک شبکهٔ پیام‌رسان خارجی با کاربران، اتاق‌ها، تحویل Webhook یا انتقال خروجیِ مختص به خود، به‌جای آن یک Plugin کانال بسازید. به ساخت 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 پذیرفته می‌شوند و پیش از تحویل به ارائه‌دهنده، از طریق پردازشگر تصویر مشترک OpenClaw ‏(Rastermill) به JPEG تبدیل و نرمال‌سازی می‌شوند؛ این پردازشگر برای قالب‌هایی که به پشتیبانی کدک خارجی نیاز دارند، به یک تبدیل‌کنندهٔ سیستمی (sips، ImageMagick، GraphicsMagick یا ffmpeg) متوسل می‌شود.

نکته امنیتی: قرار دادن یک نام میزبان در فهرست مجاز، مسدودسازی IPهای خصوصی/داخلی را دور نمی‌زند. برای Gatewayهای در معرض اینترنت، علاوه بر محافظ‌های سطح برنامه، کنترل‌های خروجی شبکه را نیز اعمال کنید. به امنیت مراجعه کنید.

قرارداد ابزار گفت‌وگو

/v1/chat/completions از زیرمجموعه‌ای از ابزارهای تابعی پشتیبانی می‌کند که با کلاینت‌های رایج گفت‌وگوی OpenAI سازگار است.

فیلدهای درخواست پشتیبانی‌شده

همه فیلدهای نمونه‌گیری و سقف توکن از همان کانال پارامترهای جریان عامل عبور می‌کنند و به‌صورت بهترین تلاش ارسال می‌شوند:

• سقف توکن: نام فیلد روی سیم توسط انتقال‌دهنده ارائه‌دهنده انتخاب می‌شود: max_completion_tokens برای نقاط پایانی خانواده OpenAI و max_tokens برای ارائه‌دهندگانی که فقط نام قدیمی را می‌پذیرند (Mistral، Chutes).
• stop به فیلد توقف انتقال‌دهنده نگاشت می‌شود: stop برای بک‌اندهای Chat Completions و stop_sequences برای Anthropic. API پاسخ‌های OpenAI پارامتر توقف ندارد، بنابراین 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 را تنظیم کنید:

• Content-Type: text/event-stream
• هر خط رویداد به‌شکل data: <json> است
• جریان با data: [DONE] پایان می‌یابد

راه‌اندازی سریع Open WebUI

• نشانی پایه: http://127.0.0.1:18789/v1
• نشانی پایه Docker در macOS: http://host.docker.internal:18789/v1
• کلید API: توکن حامل 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 می‌توانند با همان نشانی پایه و توکن متصل شوند.

نمونه‌ها

نشست پایدار برای یک مکالمه برنامه:

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