--- read_when: - یکپارچه‌سازی ابزارهایی که انتظار استفاده از OpenAI Chat Completions را دارند summary: یک نقطه پایانی HTTP سازگار با OpenAI به نشانی `/v1/chat/completions` از Gateway ارائه کنید title: تکمیل‌های گفت‌وگوی OpenAI x-i18n: generated_at: "2026-07-12T10:03:12Z" model: gpt-5.6 postprocess_version: locale-links-v1 provider: openai source_hash: 9b1fffd2ce3da881ecd91adbb7c5d10b1d7adbd99af9b2ea4544b62ecbaf1f32 source_path: gateway/openai-http-api.md workflow: 16 --- Gateway می‌تواند یک سطح کوچک و سازگار با OpenAI برای Chat Completions ارائه کند. این قابلیت **به‌طور پیش‌فرض غیرفعال است**. پس از فعال‌سازی، همهٔ موارد زیر را روی همان درگاه Gateway ارائه می‌کند (تسهیم WS و HTTP): | روش | مسیر | | ------ | ---------------------- | | POST | `/v1/chat/completions` | | GET | `/v1/models` | | GET | `/v1/models/{id}` | | POST | `/v1/embeddings` | | POST | `/v1/responses` | درخواست‌ها مانند اجرای عادی عامل Gateway اجرا می‌شوند (همان مسیر کد `openclaw agent`)، بنابراین مسیریابی، مجوزها و پیکربندی با Gateway شما یکسان هستند. ## فعال‌سازی نقطهٔ پایانی ```json5 { gateway: { http: { endpoints: { chatCompletions: { enabled: true }, }, }, }, } ``` برای غیرفعال‌سازی، `enabled: false` را تنظیم کنید (یا آن را حذف کنید). ## مرز امنیتی (مهم) این نقطهٔ پایانی را به‌منزلهٔ **دسترسی کامل اپراتور** به نمونهٔ Gateway در نظر بگیرید: - توکن/گذرواژهٔ معتبر Gateway برای این نقطهٔ پایانی معادل اعتبارنامهٔ مالک/اپراتور است، نه یک دامنهٔ محدود برای هر کاربر. - درخواست‌ها از همان مسیر عاملِ صفحهٔ کنترلِ اقدامات اپراتور مورد اعتماد عبور می‌کنند؛ بنابراین اگر خط‌مشی عامل مقصد ابزارهای حساس را مجاز بداند، این نقطهٔ پایانی می‌تواند از آن‌ها استفاده کند. - آن را فقط روی local loopback، tailnet یا ورودی خصوصی نگه دارید. آن را در معرض اینترنت عمومی قرار ندهید. ماتریس احراز هویت: | مسیر احراز هویت | رفتار | | ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode="token"` یا `"password"` به‌همراه `Authorization: Bearer ...` | در اختیار داشتن راز مشترک Gateway را اثبات می‌کند. هر سرآیند `x-openclaw-scopes` را نادیده می‌گیرد و مجموعهٔ کامل دامنه‌های پیش‌فرض اپراتور را بازیابی می‌کند: `operator.admin`، `operator.approvals`، `operator.pairing`، `operator.read`، `operator.talk.secrets`، `operator.write`. نوبت‌های گفت‌وگو را نوبت‌های فرستاده‌شده توسط مالک تلقی می‌کند. | | HTTP مورد اعتماد و حامل هویت (احراز هویت پراکسی مورد اعتماد، یا `gateway.auth.mode="none"` روی ورودی خصوصی) | در صورت وجود، `x-openclaw-scopes` را رعایت می‌کند؛ در صورت نبود آن، به مجموعهٔ دامنه‌های پیش‌فرض اپراتور برمی‌گردد. فقط زمانی معنای مالک را از دست می‌دهد که فراخواننده دامنه‌ها را صریحاً محدود و `operator.admin` را حذف کند. برای کنترل‌های سطح مالک مانند `x-openclaw-model` به `operator.admin` نیاز دارد. | به [دامنه‌های اپراتور](/fa/gateway/operator-scopes)، [امنیت](/fa/gateway/security) و [دسترسی راه دور](/fa/gateway/remote) مراجعه کنید. ## احراز هویت از پیکربندی احراز هویت Gateway استفاده می‌کند (برای جزئیات این حالت، به [احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) مراجعه کنید): | حالت | روش احراز هویت | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `gateway.auth.mode="token"` | `Authorization: Bearer `. از طریق `gateway.auth.token` یا `OPENCLAW_GATEWAY_TOKEN` تنظیم می‌شود. | | `gateway.auth.mode="password"` | `Authorization: Bearer `. از طریق `gateway.auth.password` یا `OPENCLAW_GATEWAY_PASSWORD` تنظیم می‌شود. | | `gateway.auth.mode="trusted-proxy"` | از طریق پراکسی پیکربندی‌شده و آگاه از هویت مسیریابی کنید؛ این پراکسی سرآیندهای هویتی مورد نیاز را تزریق می‌کند. پراکسی‌های local loopback روی همان میزبان به تنظیم صریح `gateway.auth.trustedProxy.allowLoopback = true` نیاز دارند. | | `gateway.auth.mode="none"` | به سرآیند احراز هویت نیاز ندارد (فقط ورودی خصوصی). | نکات: - فراخواننده‌های روی همان میزبان که در Gateway دارای `trusted-proxy` پراکسی را دور می‌زنند، می‌توانند مستقیماً به `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD` بازگردند. وجود هرگونه شواهد در سرآیندهای `Forwarded`، `X-Forwarded-*` یا `X-Real-IP` باعث می‌شود درخواست به‌جای آن در مسیر پراکسی مورد اعتماد باقی بماند. - اگر `gateway.auth.rateLimit` پیکربندی شده باشد و تعداد زیادی تلاش احراز هویت ناموفق باشد، نقطهٔ پایانی پاسخ `429` را با سرآیند `Retry-After` برمی‌گرداند. ## زمان استفاده از این نقطهٔ پایانی - وقتی یکپارچه‌سازی شما صرفاً سطح اپراتور/کارخواه دیگری برای همان Gateway است، این روش را به افزودن یک کانال داخلی جدید ترجیح دهید. - برای کارخواه‌های بومی تلفن همراه که مستقیماً به Gateway راه دور متصل می‌شوند، [WebChat](/fa/web/webchat) یا [پروتکل Gateway](/fa/gateway/protocol) را با جریان راه‌اندازی اولیهٔ دستگاه جفت‌شده/توکن دستگاه ترجیح دهید تا دستگاه به توکن/گذرواژهٔ مشترک HTTP نیاز نداشته باشد. - هنگام یکپارچه‌سازی یک شبکهٔ پیام‌رسان خارجی با کاربران، اتاق‌ها، تحویل Webhook یا انتقال خروجیِ مختص به خود، به‌جای آن یک Plugin کانال بسازید. به [ساخت Pluginها](/fa/plugins/building-plugins) مراجعه کنید. ## قرارداد مدل مبتنی بر عامل OpenClaw فیلد `model` در OpenAI را یک **مقصد عامل** در نظر می‌گیرد، نه شناسهٔ خام مدل ارائه‌دهنده. | مقدار `model` | مسیریابی به | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | `openclaw` | عامل پیش‌فرض پیکربندی‌شده | | `openclaw/default` | عامل پیش‌فرض پیکربندی‌شده (نام مستعار پایدار؛ حتی اگر شناسهٔ واقعی عامل پیش‌فرض میان محیط‌ها تغییر کند، می‌توان با خیال آسوده آن را به‌صورت ثابت در کد قرار داد) | | `openclaw/` یا `openclaw:` | عامل مشخص | | `agent:` | عامل مشخص (نام مستعار سازگاری) | سرآیندهای اختیاری درخواست: | سرآیند | اثر | | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `x-openclaw-model: ` | مدل پشتیبان را برای عامل انتخاب‌شده بازنویسی می‌کند. فراخواننده‌های حامل راز مشترک می‌توانند مستقیماً از آن استفاده کنند؛ فراخواننده‌های حامل هویت (پراکسی مورد اعتماد، یا ورودی خصوصی بدون احراز هویت همراه با `x-openclaw-scopes`) به `operator.admin` نیاز دارند، وگرنه پاسخ `403 missing scope: operator.admin` دریافت می‌شود. | | `x-openclaw-agent-id: ` | بازنویسی سازگاری برای انتخاب عامل. | | `x-openclaw-session-key: ` | مسیریابی صریح نشست. اگر از فضای نام داخلی رزروشده (`subagent:`، `cron:`، `acp:`) استفاده کند، با `400 invalid_request_error` رد می‌شود. | | `x-openclaw-message-channel: ` | زمینهٔ کانال ورودی مصنوعی را برای اعلان‌ها/خط‌مشی‌های آگاه از کانال تنظیم می‌کند. | `/v1/models` مقصدهای عامل سطح بالا (`openclaw`، `openclaw/default`، `openclaw/`) را فهرست می‌کند، نه مدل‌های ارائه‌دهندهٔ پشتیبان و نه زیرعامل‌ها؛ زیرعامل‌ها به‌عنوان توپولوژی اجرای داخلی باقی می‌مانند. اگر `x-openclaw-model` را حذف کنید، عامل انتخاب‌شده با مدل عادی پیکربندی‌شدهٔ خود اجرا می‌شود. `/v1/embeddings` از همان شناسه‌های `model` مقصد عامل استفاده می‌کند. برای انتخاب یک مدل تعبیه‌سازی مشخص، `x-openclaw-model` را ارسال کنید (از سوی فراخوانندهٔ دارای راز مشترک، یا فراخوانندهٔ حامل هویت با `operator.admin`)؛ در غیر این صورت، درخواست از تنظیمات عادی تعبیه‌سازی عامل انتخاب‌شده استفاده می‌کند. ## رفتار نشست به‌طور پیش‌فرض، نقطهٔ پایانی **برای هر درخواست بدون حالت** است (در هر فراخوانی یک کلید نشست جدید تولید می‌شود). اگر درخواست شامل رشتهٔ `user` در OpenAI باشد، Gateway یک کلید نشست پایدار از آن استخراج می‌کند تا فراخوانی‌های تکراری بتوانند نشست عامل مشترکی داشته باشند. برای برنامه‌های سفارشی، در هر رشتهٔ مکالمه از همان مقدار `user` استفاده کنید؛ مگر اینکه بخواهید چند مکالمه/دستگاه یک نشست OpenClaw را به اشتراک بگذارند، از شناسه‌های سطح حساب استفاده نکنید. فقط زمانی از `x-openclaw-session-key` استفاده کنید که به کنترل صریح مسیریابی میان چند کارخواه/رشته نیاز دارید؛ از کلیدهای متعلق به برنامه استفاده کنید که از فضاهای نام رزروشدهٔ بالا اجتناب می‌کنند. ## محدودیت‌های درخواست (پیکربندی) مقادیر پیش‌فرض را می‌توان زیر `gateway.http.endpoints.chatCompletions` تنظیم کرد: ```json5 { 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, }, }, }, }, }, } ``` مقادیر پیش‌فرض در صورت حذف: | کلید | مقدار پیش‌فرض | | --------------------- | --------------------------------------------------------------------------- | | `maxBodyBytes` | 20MB | | `maxImageParts` | 8 (حداکثر بخش‌های `image_url` خوانده‌شده از آخرین پیام کاربر) | | `maxTotalImageBytes` | 20MB (مجموع بایت‌های رمزگشایی‌شده در همهٔ بخش‌های `image_url` یک درخواست) | | `images.allowUrl` | `false` (بخش‌های `image_url` با منشأ URL، مگر در صورت فعال‌سازی، رد می‌شوند) | | `images.maxBytes` | 10MB برای هر تصویر | | `images.maxRedirects` | 3 | | `images.timeoutMs` | 10s | منابع `image_url` با قالب HEIC/HEIF پذیرفته می‌شوند و پیش از تحویل به ارائه‌دهنده، از طریق پردازشگر تصویر مشترک OpenClaw ‏(Rastermill) به JPEG تبدیل و نرمال‌سازی می‌شوند؛ این پردازشگر برای قالب‌هایی که به پشتیبانی کدک خارجی نیاز دارند، به یک تبدیل‌کنندهٔ سیستمی (`sips`، ImageMagick، GraphicsMagick یا ffmpeg) متوسل می‌شود. نکته امنیتی: قرار دادن یک نام میزبان در فهرست مجاز، مسدودسازی IPهای خصوصی/داخلی را دور نمی‌زند. برای Gatewayهای در معرض اینترنت، علاوه بر محافظ‌های سطح برنامه، کنترل‌های خروجی شبکه را نیز اعمال کنید. به [امنیت](/fa/gateway/security) مراجعه کنید. ## قرارداد ابزار گفت‌وگو `/v1/chat/completions` از زیرمجموعه‌ای از ابزارهای تابعی پشتیبانی می‌کند که با کلاینت‌های رایج گفت‌وگوی OpenAI سازگار است. ### فیلدهای درخواست پشتیبانی‌شده | فیلد | توضیحات | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `tools` | آرایه‌ای از `{ "type": "function", "function": { ... } }` | | `tool_choice` | `"auto"`، `"none"`، `"required"`، یا `{ "type": "function", "function": { "name": "..." } }` | | `messages[*].role: "tool"` | نوبت‌های پیگیری | | `messages[*].tool_call_id` | نتیجه ابزار را به یک فراخوانی ابزار قبلی متصل می‌کند | | `max_completion_tokens` | عدد؛ سقف مجموع توکن‌های تکمیل در هر فراخوانی (شامل توکن‌های استدلال). نام فعلی فیلد؛ وقتی این فیلد و `max_tokens` هر دو ارسال شوند، از این فیلد استفاده می‌شود. | | `max_tokens` | عدد؛ نام مستعار قدیمی که در صورت وجود هم‌زمان `max_completion_tokens` نادیده گرفته می‌شود. | | `temperature` | عددی بین ۰ تا ۲؛ به‌صورت بهترین تلاش به ارائه‌دهنده بالادستی ارسال می‌شود. در صورت خارج بودن از محدوده، `400 invalid_request_error`. | | `top_p` | عددی بین ۰ تا ۱؛ به‌صورت بهترین تلاش. در صورت خارج بودن از محدوده، `400 invalid_request_error`. | | `frequency_penalty` | عددی بین ‎-۲٫۰ تا ۲٫۰؛ به‌صورت بهترین تلاش. در صورت خارج بودن از محدوده، `400 invalid_request_error`. | | `presence_penalty` | عددی بین ‎-۲٫۰ تا ۲٫۰؛ به‌صورت بهترین تلاش. در صورت خارج بودن از محدوده، `400 invalid_request_error`. | | `seed` | عدد صحیح؛ به‌صورت بهترین تلاش. برای مقادیر غیرصحیح، `400 invalid_request_error`. | | `stop` | رشته یا آرایه‌ای شامل حداکثر ۴ رشته؛ به‌صورت بهترین تلاش. برای بیش از ۴ توالی یا ورودی‌های غیررشته‌ای/خالی، `400 invalid_request_error`. | همه فیلدهای نمونه‌گیری و سقف توکن از همان کانال پارامترهای جریان عامل عبور می‌کنند و به‌صورت بهترین تلاش ارسال می‌شوند: - سقف توکن: نام فیلد روی سیم توسط انتقال‌دهنده ارائه‌دهنده انتخاب می‌شود: `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: ` است - جریان با `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`). آزمون سریع اولیه: ```bash curl -sS http://127.0.0.1:18789/v1/models \ -H 'Authorization: Bearer YOUR_TOKEN' ``` اگر این فرمان `openclaw/default` را برگرداند، بیشتر پیکربندی‌های Open WebUI می‌توانند با همان نشانی پایه و توکن متصل شوند. ## نمونه‌ها نشست پایدار برای یک مکالمه برنامه: ```bash 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` دوباره استفاده کنید. بدون جریان: ```bash 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"}] }' ``` جریانی: ```bash 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"}] }' ``` فهرست‌کردن مدل‌ها: ```bash curl -sS http://127.0.0.1:18789/v1/models \ -H 'Authorization: Bearer YOUR_TOKEN' ``` دریافت یک مدل: ```bash curl -sS http://127.0.0.1:18789/v1/models/openclaw%2Fdefault \ -H 'Authorization: Bearer YOUR_TOKEN' ``` ایجاد تعبیه‌ها: ```bash 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` به‌شکل یک رشته یا آرایه‌ای از رشته‌ها پشتیبانی می‌کند. ## مرتبط - [مرجع پیکربندی](/fa/gateway/configuration-reference) - [دامنه‌های عملگر](/fa/gateway/operator-scopes) - [OpenAI](/fa/providers/openai)