OpenAI

OpenAI APIهای توسعه‌دهنده را برای مدل‌های GPT ارائه می‌کند، و Codex نیز به‌عنوان عامل کدنویسیِ طرح ChatGPT از طریق کلاینت‌های Codex متعلق به OpenAI در دسترس است. OpenClaw این سطح‌ها را جدا نگه می‌دارد تا پیکربندی قابل پیش‌بینی بماند.

OpenClaw از openai/* به‌عنوان مسیر متعارف مدل OpenAI استفاده می‌کند. نوبت‌های عامل تعبیه‌شده روی مدل‌های OpenAI به‌طور پیش‌فرض از طریق runtime بومی app-server در Codex اجرا می‌شوند؛ احراز هویت مستقیم با کلید API برای سطح‌های غیرعاملی OpenAI مانند تصویرها، embeddings، گفتار، و realtime همچنان در دسترس است.

• مدل‌های عامل - مدل‌های openai/* از طریق runtime در Codex؛ برای استفاده از اشتراک ChatGPT/Codex با احراز هویت openai-codex وارد شوید، یا وقتی عمداً احراز هویت با کلید API می‌خواهید، یک پروفایل کلید API برای openai-codex پیکربندی کنید.
• APIهای غیرعاملی OpenAI - دسترسی مستقیم به OpenAI Platform با صورت‌حساب مبتنی بر مصرف از طریق OPENAI_API_KEY یا راه‌اندازی کلید API در OpenAI.
• پیکربندی قدیمی - ارجاع‌های مدل openai-codex/* توسط openclaw doctor --fix به openai/* به‌همراه runtime در Codex ترمیم می‌شوند.

OpenAI صراحتاً از استفاده از OAuth اشتراکی در ابزارها و workflowهای بیرونی مانند OpenClaw پشتیبانی می‌کند.

ارائه‌دهنده، مدل، runtime، و کانال لایه‌های جداگانه‌ای هستند. اگر این برچسب‌ها با هم مخلوط می‌شوند، پیش از تغییر پیکربندی، runtimeهای عامل را بخوانید.

# انتخاب سریع

# نقشه نام‌گذاری

نام‌ها شبیه‌اند اما قابل جایگزینی با هم نیستند:

این یعنی یک پیکربندی می‌تواند عمداً هم ارجاع‌های مدل openai/* و هم پروفایل‌های احراز هویت openai-codex داشته باشد. openclaw doctor --fix ارجاع‌های مدل قدیمی openai-codex/* را به مسیر متعارف مدل OpenAI بازنویسی می‌کند.

# پوشش قابلیت‌های OpenClaw

# Embeddings حافظه

OpenClaw می‌تواند از OpenAI، یا یک endpoint سازگار با OpenAI برای embedding، جهت indexing و embeddings پرس‌وجو در memory_search استفاده کند:

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}

برای endpointهای سازگار با OpenAI که به برچسب‌های embedding نامتقارن نیاز دارند، queryInputType و documentInputType را زیر memorySearch تنظیم کنید. OpenClaw این‌ها را به‌عنوان فیلدهای درخواست مخصوص ارائه‌دهنده با نام input_type ارسال می‌کند: embeddings پرس‌وجو از queryInputType استفاده می‌کنند؛ chunkهای حافظه index‌شده و indexing دسته‌ای از documentInputType استفاده می‌کنند. برای مثال کامل، مرجع پیکربندی حافظه را ببینید.

# شروع به کار

روش احراز هویت ترجیحی خود را انتخاب کنید و مراحل راه‌اندازی را دنبال کنید.

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

openclaw models auth login --provider openai-codex --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai-codex

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

openclaw models status --agent <id>
openclaw models auth list --agent <id> --provider openai-codex

openclaw doctor --fix
openclaw config validate

openclaw models auth login --provider openai-codex
openclaw models status --probe --probe-provider openai-codex

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# احراز هویت بومی app-server Codex

مهار بومی app-server Codex از مرجع‌های مدل openai/* به‌همراه پیکربندی runtime حذف‌شده یا agentRuntime.id: "codex" استفاده می‌کند، اما احراز هویت آن همچنان مبتنی بر حساب است. OpenClaw احراز هویت را به این ترتیب انتخاب می‌کند:

1. یک پروفایل احراز هویت صریح OpenClaw openai-codex که به عامل متصل است.
2. حساب موجود app-server، مانند ورود محلی ChatGPT در Codex CLI.
3. فقط برای راه‌اندازی‌های app-server محلی stdio، CODEX_API_KEY، سپس OPENAI_API_KEY، وقتی app-server هیچ حسابی گزارش نمی‌کند و همچنان به احراز هویت OpenAI نیاز دارد.

این یعنی ورود اشتراک محلی ChatGPT/Codex فقط به این دلیل که فرایند gateway همچنین برای مدل‌های مستقیم OpenAI یا embeddingها OPENAI_API_KEY دارد جایگزین نمی‌شود. fallback کلید API محیطی فقط مسیر محلی stdio بدون حساب است؛ به اتصال‌های WebSocket app-server ارسال نمی‌شود. وقتی یک پروفایل Codex از نوع اشتراکی انتخاب شود، OpenClaw همچنین CODEX_API_KEY و OPENAI_API_KEY را از فرزند stdio app-server ایجادشده بیرون نگه می‌دارد و اعتبارنامه‌های انتخاب‌شده را از طریق RPC ورود app-server ارسال می‌کند.

# تولید تصویر

Plugin همراه openai تولید تصویر را از طریق ابزار image_generate ثبت می‌کند. این هم تولید تصویر با کلید API OpenAI و هم تولید تصویر OAuth Codex را از طریق همان مرجع مدل openai/gpt-image-2 پشتیبانی می‌کند.

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

gpt-image-2 پیش‌فرض هم برای تولید متن‌به‌تصویر OpenAI و هم برای ویرایش تصویر است. gpt-image-1.5، gpt-image-1، و gpt-image-1-mini همچنان به‌عنوان بازنویسی‌های صریح مدل قابل استفاده‌اند. از openai/gpt-image-1.5 برای خروجی PNG/WebP با پس‌زمینه شفاف استفاده کنید؛ API فعلی gpt-image-2 background: "transparent" را رد می‌کند.

برای یک درخواست پس‌زمینه شفاف، عامل‌ها باید image_generate را با model: "openai/gpt-image-1.5"، outputFormat: "png" یا "webp"، و background: "transparent" فراخوانی کنند؛ گزینه قدیمی ارائه‌دهنده openai.background هنوز پذیرفته می‌شود. OpenClaw همچنین از مسیرهای عمومی OpenAI و OAuth OpenAI Codex محافظت می‌کند و درخواست‌های شفاف پیش‌فرض openai/gpt-image-2 را به gpt-image-1.5 بازنویسی می‌کند؛ Azure و endpointهای سفارشی سازگار با OpenAI نام‌های deployment/model پیکربندی‌شده خود را نگه می‌دارند.

همین تنظیم برای اجراهای CLI بدون رابط نیز ارائه شده است:

openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

هنگام شروع از یک فایل ورودی، همان پرچم‌های --output-format و --background را با openclaw infer image edit استفاده کنید. --openai-background همچنان به‌عنوان نام مستعار ویژه OpenAI در دسترس است.

برای نصب‌های OAuth Codex، همان مرجع openai/gpt-image-2 را نگه دارید. وقتی یک پروفایل OAuth openai-codex پیکربندی شده باشد، OpenClaw آن توکن دسترسی OAuth ذخیره‌شده را resolve می‌کند و درخواست‌های تصویر را از طریق پشتانه Codex Responses ارسال می‌کند. ابتدا OPENAI_API_KEY را امتحان نمی‌کند یا برای آن درخواست بی‌صدا به یک کلید API fallback نمی‌کند. وقتی مسیر مستقیم OpenAI Images API را می‌خواهید، models.providers.openai را به‌طور صریح با یک کلید API، URL پایه سفارشی، یا endpoint Azure پیکربندی کنید. اگر آن endpoint تصویر سفارشی روی یک LAN/نشانی خصوصی مورد اعتماد است، همچنین browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true را تنظیم کنید؛ OpenClaw endpointهای تصویر خصوصی/داخلی سازگار با OpenAI را مسدود نگه می‌دارد مگر اینکه این opt-in وجود داشته باشد.

تولید:

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

تولید یک PNG شفاف:

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

ویرایش:

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

# تولید ویدیو

Plugin همراه openai تولید ویدیو را از طریق ابزار video_generate ثبت می‌کند.

{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

# مشارکت پرامپت GPT-5

OpenClaw یک مشارکت پرامپت مشترک GPT-5 برای اجراهای خانواده GPT-5 در میان ارائه‌دهنده‌ها اضافه می‌کند. این بر اساس شناسه مدل اعمال می‌شود، بنابراین openai/gpt-5.5، مرجع‌های قدیمی پیش از تعمیر مانند openai-codex/gpt-5.5، openrouter/openai/gpt-5.5، opencode/gpt-5.5، و دیگر مرجع‌های سازگار GPT-5 همان overlay را دریافت می‌کنند. مدل‌های قدیمی‌تر GPT-4.x دریافت نمی‌کنند.

مهار بومی همراه Codex همان رفتار GPT-5 و overlay Heartbeat را از طریق دستورالعمل‌های توسعه‌دهنده app-server Codex استفاده می‌کند، بنابراین نشست‌های openai/gpt-5.x که از طریق agentRuntime.id: "codex" اجبار شده‌اند همان راهنمایی پیگیری و Heartbeat پیش‌دستانه را حفظ می‌کنند، حتی اگر Codex مالک بقیه پرامپت مهار باشد.

راهنمای GPT-5 یک قرارداد رفتاری برچسب‌دار برای پایداری پرسونا، ایمنی اجرا، انضباط ابزار، شکل خروجی، بررسی‌های تکمیل، و راستی‌آزمایی اضافه می‌کند. رفتار پاسخ‌دهی مختص کانال و پیام بی‌صدا در پرامپت سیستمی مشترک OpenClaw و سیاست تحویل خروجی باقی می‌ماند. راهنمای GPT-5 همیشه برای مدل‌های منطبق فعال است. لایهٔ سبک تعامل دوستانه جدا و قابل پیکربندی است.

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

# صدا و گفتار

{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}

{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}

# نقاط پایانی Azure OpenAI

ارائه‌دهندهٔ همراه openai می‌تواند با بازنویسی URL پایه، یک منبع Azure OpenAI را برای تولید تصویر هدف بگیرد. در مسیر تولید تصویر، OpenClaw نام‌های میزبان Azure را روی models.providers.openai.baseUrl تشخیص می‌دهد و به‌صورت خودکار به شکل درخواست Azure تغییر می‌دهد.

از Azure OpenAI استفاده کنید وقتی:

• از قبل اشتراک، سهمیه، یا قرارداد سازمانی Azure OpenAI دارید
• به اقامت دادهٔ منطقه‌ای یا کنترل‌های انطباقی که Azure فراهم می‌کند نیاز دارید
• می‌خواهید ترافیک را داخل یک tenancy موجود Azure نگه دارید

# پیکربندی

برای تولید تصویر Azure از طریق ارائه‌دهندهٔ همراه openai، models.providers.openai.baseUrl را به منبع Azure خود اشاره دهید و apiKey را به کلید Azure OpenAI تنظیم کنید (نه کلید OpenAI Platform):

{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}

OpenClaw این پسوندهای میزبان Azure را برای مسیر تولید تصویر Azure تشخیص می‌دهد:

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

برای درخواست‌های تولید تصویر روی میزبان Azure تشخیص‌داده‌شده، OpenClaw:

• سرآیند api-key را به‌جای Authorization: Bearer ارسال می‌کند
• از مسیرهای محدود به استقرار (/openai/deployments/{deployment}/...) استفاده می‌کند
• ?api-version=... را به هر درخواست اضافه می‌کند
• از مهلت زمانی پیش‌فرض ۶۰۰ ثانیه برای فراخوانی‌های تولید تصویر Azure استفاده می‌کند. مقادیر timeoutMs هر فراخوانی همچنان این پیش‌فرض را بازنویسی می‌کنند.

URLهای پایهٔ دیگر (OpenAI عمومی، پروکسی‌های سازگار با OpenAI) شکل استاندارد درخواست تصویر OpenAI را حفظ می‌کنند.

# نسخهٔ API

برای ثابت کردن یک نسخهٔ پیش‌نمایش یا GA مشخص Azure برای مسیر تولید تصویر Azure، AZURE_OPENAI_API_VERSION را تنظیم کنید:

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

وقتی متغیر تنظیم نشده باشد، پیش‌فرض 2024-12-01-preview است.

# نام مدل‌ها نام استقرارها هستند

Azure OpenAI مدل‌ها را به استقرارها متصل می‌کند. برای درخواست‌های تولید تصویر Azure که از طریق ارائه‌دهندهٔ همراه openai مسیریابی می‌شوند، فیلد model در OpenClaw باید نام استقرار Azure باشد که در پرتال Azure پیکربندی کرده‌اید، نه شناسهٔ مدل عمومی OpenAI.

اگر استقراری با نام gpt-image-2-prod ایجاد کنید که gpt-image-2 را ارائه می‌دهد:

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

همان قانون نام استقرار برای فراخوانی‌های تولید تصویر که از طریق ارائه‌دهندهٔ همراه openai مسیریابی می‌شوند نیز اعمال می‌شود.

# دسترس‌پذیری منطقه‌ای

تولید تصویر Azure در حال حاضر فقط در زیرمجموعه‌ای از مناطق در دسترس است (برای مثال eastus2، swedencentral، polandcentral، westus3، uaenorth). پیش از ایجاد یک استقرار، فهرست منطقه‌ای فعلی Microsoft را بررسی کنید و تأیید کنید مدل مشخص در منطقهٔ شما ارائه می‌شود.

# تفاوت‌های پارامتر

Azure OpenAI و OpenAI عمومی همیشه پارامترهای تصویر یکسانی را نمی‌پذیرند. Azure ممکن است گزینه‌هایی را که OpenAI عمومی مجاز می‌داند رد کند (برای مثال برخی مقادیر background روی gpt-image-2) یا آن‌ها را فقط روی نسخه‌های مشخص مدل ارائه دهد. این تفاوت‌ها از Azure و مدل زیربنایی می‌آیند، نه OpenClaw. اگر یک درخواست Azure با خطای اعتبارسنجی شکست خورد، مجموعهٔ پارامترهای پشتیبانی‌شده توسط استقرار و نسخهٔ API مشخص خود را در پرتال Azure بررسی کنید.

# پیکربندی پیشرفته

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.5": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { responsesServerCompaction: false },
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}

# مرتبط