CLI استنتاج

openclaw infer سطح headless اصلی برای گردش‌کارهای استنتاج مبتنی بر ارائه‌دهنده است.

این دستور عمداً خانواده‌های قابلیت را در معرض استفاده قرار می‌دهد، نه نام‌های خام RPC مربوط به Gateway و نه شناسه‌های خام ابزار عامل.

# تبدیل infer به یک مهارت

این را در یک عامل کپی و جای‌گذاری کنید:

Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.

یک مهارت خوبِ مبتنی بر infer باید:

• نیت‌های رایج کاربر را به زیرفرمان درست infer نگاشت کند
• چند نمونه متعارف infer برای گردش‌کارهایی که پوشش می‌دهد شامل کند
• در نمونه‌ها و پیشنهادها openclaw infer ... را ترجیح دهد
• از مستندسازی دوباره کل سطح infer داخل بدنه مهارت پرهیز کند

پوشش معمول مهارت‌های متمرکز بر infer:

• openclaw infer model run
• openclaw infer image generate
• openclaw infer audio transcribe
• openclaw infer tts convert
• openclaw infer web search
• openclaw infer embedding create

# چرا از infer استفاده کنیم

openclaw infer یک CLI یکپارچه برای وظایف استنتاج مبتنی بر ارائه‌دهنده در OpenClaw فراهم می‌کند.

مزایا:

• به‌جای ساخت wrapperهای موردی برای هر backend، از ارائه‌دهنده‌ها و مدل‌هایی استفاده کنید که از قبل در OpenClaw پیکربندی شده‌اند.
• گردش‌کارهای مدل، تصویر، رونویسی صوت، TTS، ویدیو، وب و embedding را زیر یک درخت فرمان نگه دارید.
• برای اسکریپت‌ها، خودکارسازی و گردش‌کارهای هدایت‌شده توسط عامل، از شکل خروجی پایدار --json استفاده کنید.
• وقتی وظیفه اساساً «اجرای استنتاج» است، سطح رسمی OpenClaw را ترجیح دهید.
• برای بیشتر فرمان‌های infer، از مسیر محلی عادی بدون نیاز به Gateway استفاده کنید.

برای بررسی‌های انتهابه‌انتهای ارائه‌دهنده، پس از سبز شدن آزمون‌های سطح پایین‌تر ارائه‌دهنده، openclaw infer ... را ترجیح دهید. این مسیر CLI منتشرشده، بارگذاری پیکربندی، تشخیص عامل پیش‌فرض، فعال‌سازی Pluginهای همراه، و runtime قابلیت مشترک را پیش از ارسال درخواست به ارائه‌دهنده تمرین می‌دهد.

# درخت فرمان

 openclaw infer
  list
  inspect

  model
    run
    list
    inspect
    providers
    auth login
    auth logout
    auth status

  image
    generate
    edit
    describe
    describe-many
    providers

  audio
    transcribe
    providers

  tts
    convert
    voices
    providers
    status
    enable
    disable
    set-provider

  video
    generate
    describe
    providers

  web
    search
    fetch
    providers

  embedding
    create
    providers

# وظایف رایج

این جدول وظایف رایج استنتاج را به فرمان متناظر infer نگاشت می‌کند.

وظیفه	فرمان	یادداشت‌ها
اجرای یک prompt متنی/مدل	openclaw infer model run --prompt "..." --json	به‌طور پیش‌فرض از مسیر محلی عادی استفاده می‌کند
اجرای prompt مدل روی تصاویر	openclaw infer model run --prompt "Describe this" --file ./image.png --model provider/model	برای چند ورودی تصویر، --file را تکرار کنید
تولید تصویر	openclaw infer image generate --prompt "..." --json	هنگام شروع از یک فایل موجود از image edit استفاده کنید
توصیف یک فایل تصویر	openclaw infer image describe --file ./image.png --prompt "..." --json	--model باید یک <provider/model> با قابلیت تصویر باشد
رونویسی صوت	openclaw infer audio transcribe --file ./memo.m4a --json	--model باید <provider/model> باشد
تولید گفتار	openclaw infer tts convert --text "..." --output ./speech.mp3 --json	tts status معطوف به Gateway است
تولید ویدیو	openclaw infer video generate --prompt "..." --json	از راهنمایی‌های ارائه‌دهنده مانند --resolution پشتیبانی می‌کند
توصیف یک فایل ویدیو	openclaw infer video describe --file ./clip.mp4 --json	--model باید <provider/model> باشد
جست‌وجوی وب	openclaw infer web search --query "..." --json
دریافت یک صفحه وب	openclaw infer web fetch --url https://example.com --json
ایجاد embeddingها	openclaw infer embedding create --text "..." --json

# رفتار

• openclaw infer ... سطح اصلی CLI برای این گردش‌کارها است.
• وقتی خروجی توسط فرمان یا اسکریپت دیگری مصرف می‌شود، از --json استفاده کنید.
• وقتی یک backend مشخص لازم است، از --provider یا --model provider/model استفاده کنید.
• برای image describe، audio transcribe و video describe، --model باید از قالب <provider/model> استفاده کند.
• برای image describe، یک --model صریح همان ارائه‌دهنده/مدل را مستقیم اجرا می‌کند. مدل باید در کاتالوگ مدل یا پیکربندی ارائه‌دهنده، قابلیت تصویر داشته باشد. codex/<model> یک نوبت محدود فهم تصویر در app-server مربوط به Codex را اجرا می‌کند؛ openai-codex/<model> از مسیر ارائه‌دهنده OAuth مربوط به OpenAI Codex استفاده می‌کند.
• فرمان‌های اجرای بدون وضعیت به‌طور پیش‌فرض محلی هستند.
• فرمان‌های وضعیت مدیریت‌شده توسط Gateway به‌طور پیش‌فرض از Gateway استفاده می‌کنند.
• مسیر محلی عادی نیازی به در حال اجرا بودن Gateway ندارد.
• اجرای محلی model run یک تکمیل ارائه‌دهنده سبک و تک‌باره است. این مسیر مدل و احراز هویت عامل پیکربندی‌شده را تشخیص می‌دهد، اما نوبت chat-agent را شروع نمی‌کند، ابزارها را بارگذاری نمی‌کند، یا سرورهای MCP همراه را باز نمی‌کند.
• model run --file فایل‌های تصویر را می‌پذیرد، نوع MIME آن‌ها را تشخیص می‌دهد، و آن‌ها را همراه prompt ارائه‌شده به مدل انتخاب‌شده ارسال می‌کند. برای چند تصویر، --file را تکرار کنید.
• model run --file ورودی‌های غیرتصویری را رد می‌کند. برای فایل‌های صوتی از infer audio transcribe و برای فایل‌های ویدیویی از infer video describe استفاده کنید.
• model run --gateway مسیریابی Gateway، احراز هویت ذخیره‌شده، انتخاب ارائه‌دهنده، و runtime توکار را تمرین می‌دهد، اما همچنان به‌عنوان یک probe خام مدل اجرا می‌شود: prompt ارائه‌شده و هر پیوست تصویری را بدون transcript پیشین جلسه، زمینه bootstrap/AGENTS، مونتاژ context-engine، ابزارها، یا سرورهای MCP همراه ارسال می‌کند.
• model run --gateway --model <provider/model> به اعتبارنامه Gateway مربوط به یک operator مورد اعتماد نیاز دارد، چون درخواست از Gateway می‌خواهد یک override تک‌باره ارائه‌دهنده/مدل را اجرا کند.

# مدل

از model برای استنتاج متنی مبتنی بر ارائه‌دهنده و بازرسی مدل/ارائه‌دهنده استفاده کنید.

openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
openclaw infer model run --prompt "Summarize this changelog entry" --model openai/gpt-5.4 --json
openclaw infer model run --prompt "Describe this image in one sentence" --file ./photo.jpg --model google/gemini-2.5-flash --json
openclaw infer model providers --json
openclaw infer model inspect --name gpt-5.5 --json

برای smoke-test یک ارائه‌دهنده مشخص بدون شروع Gateway یا بارگذاری سطح کامل ابزار عامل، از ارجاع‌های کامل <provider/model> استفاده کنید:

openclaw infer model run --local --model anthropic/claude-sonnet-4-6 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model cerebras/zai-glm-4.7 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model google/gemini-2.5-flash --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model groq/llama-3.1-8b-instant --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model mistral/mistral-small-latest --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model openai/gpt-4.1 --prompt "Reply with exactly: pong" --json
openclaw infer model run --local --model ollama/qwen2.5vl:7b --prompt "Describe this image." --file ./photo.jpg --json

یادداشت‌ها:

• اجرای محلی model run محدودترین smoke در CLI برای سلامت ارائه‌دهنده/مدل/احراز هویت است، چون برای ارائه‌دهنده‌های غیر Codex فقط prompt ارائه‌شده را به مدل انتخاب‌شده ارسال می‌کند.
• probeهای محلی openai-codex/* استثنای محدود هستند: OpenClaw یک دستور سیستم حداقلی اضافه می‌کند تا انتقال Codex Responses بتواند فیلد لازم instructions را پر کند، بدون افزودن زمینه کامل عامل، ابزارها، حافظه یا transcript جلسه.
• اجرای محلی model run --file همین مسیر سبک را نگه می‌دارد و محتوای تصویر را مستقیم به تک پیام کاربر پیوست می‌کند. فایل‌های تصویری رایج مانند PNG، JPEG و WebP وقتی نوع MIME آن‌ها به‌صورت image/* تشخیص داده شود کار می‌کنند؛ فایل‌های پشتیبانی‌نشده یا ناشناخته پیش از فراخوانی ارائه‌دهنده شکست می‌خورند.
• model run --file بهترین گزینه است وقتی می‌خواهید مدل متنی چندوجهی انتخاب‌شده را مستقیم آزمایش کنید. وقتی انتخاب ارائه‌دهنده فهم تصویر و مسیریابی مدل تصویر پیش‌فرض OpenClaw را می‌خواهید، از infer image describe استفاده کنید.
• مدل انتخاب‌شده باید از ورودی تصویر پشتیبانی کند؛ مدل‌های فقط متنی ممکن است درخواست را در لایه ارائه‌دهنده رد کنند.
• model run --prompt باید شامل متن غیر whitespace باشد؛ promptهای خالی پیش از فراخوانی ارائه‌دهنده‌های محلی یا Gateway رد می‌شوند.
• اجرای محلی model run وقتی ارائه‌دهنده هیچ خروجی متنی برنگرداند با کد غیرصفر خارج می‌شود، بنابراین ارائه‌دهنده‌های محلی غیرقابل‌دسترسی و تکمیل‌های خالی شبیه probeهای موفق به نظر نمی‌رسند.
• وقتی لازم است مسیریابی Gateway، راه‌اندازی agent-runtime، یا وضعیت ارائه‌دهنده مدیریت‌شده توسط Gateway را آزمایش کنید و هم‌زمان ورودی مدل را خام نگه دارید، از model run --gateway استفاده کنید. وقتی زمینه کامل عامل، ابزارها، حافظه و transcript جلسه را می‌خواهید، از openclaw agent یا سطوح chat استفاده کنید.
• model auth login، model auth logout و model auth status وضعیت احراز هویت ذخیره‌شده ارائه‌دهنده را مدیریت می‌کنند.

# تصویر

از image برای تولید، ویرایش و توصیف استفاده کنید.

openclaw infer image generate --prompt "friendly lobster illustration" --json
openclaw infer image generate --prompt "cinematic product photo of headphones" --json
openclaw infer image generate --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "simple red circle sticker on a transparent background" --json
openclaw infer image generate --prompt "slow image backend" --timeout-ms 180000 --json
openclaw infer image edit --file ./logo.png --model openai/gpt-image-1.5 --output-format png --background transparent --prompt "keep the logo, remove the background" --json
openclaw infer image edit --file ./poster.png --prompt "make this a vertical story ad" --size 2160x3840 --aspect-ratio 9:16 --resolution 4K --json
openclaw infer image describe --file ./photo.jpg --json
openclaw infer image describe --file ./receipt.jpg --prompt "Extract the merchant, date, and total" --json
openclaw infer image describe-many --file ./before.png --file ./after.png --prompt "Compare the screenshots and list visible UI changes" --json
openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --prompt "Describe the image in one sentence" --timeout-ms 300000 --json

یادداشت‌ها:

• هنگام شروع از فایل‌های ورودی موجود، از image edit استفاده کنید.

• برای ارائه‌دهندگان/مدل‌هایی که از راهنمایی‌های هندسی در ویرایش‌های تصویر مرجع پشتیبانی می‌کنند، از --size، --aspect-ratio، یا --resolution همراه با image edit استفاده کنید.

• برای خروجی PNG شفاف OpenAI با پس‌زمینه شفاف، از --output-format png --background transparent همراه با --model openai/gpt-image-1.5 استفاده کنید؛ --openai-background همچنان به‌عنوان نام مستعار ویژه OpenAI در دسترس است. ارائه‌دهندگانی که پشتیبانی از پس‌زمینه را اعلام نمی‌کنند، این راهنما را به‌عنوان یک override نادیده‌گرفته‌شده گزارش می‌کنند.

• از image providers --json استفاده کنید تا بررسی کنید کدام ارائه‌دهندگان تصویرِ همراه قابل کشف، پیکربندی‌شده و انتخاب‌شده هستند، و هر ارائه‌دهنده چه قابلیت‌های تولید/ویرایش را در اختیار می‌گذارد.

• از image generate --model <provider/model> --json به‌عنوان محدودترین smoke زنده CLI برای تغییرات تولید تصویر استفاده کنید. مثال:

  openclaw infer image providers --json
  openclaw infer image generate \
    --model google/gemini-3.1-flash-image-preview \
    --prompt "Minimal flat test image: one blue square on a white background, no text." \
    --output ./openclaw-infer-image-smoke.png \
    --json
  

  پاسخ JSON مقدارهای ok، provider، model، attempts و مسیرهای خروجی نوشته‌شده را گزارش می‌کند. وقتی --output تنظیم شده باشد، پسوند نهایی ممکن است از نوع MIME بازگردانده‌شده توسط ارائه‌دهنده پیروی کند.

• برای image describe و image describe-many، از --prompt استفاده کنید تا به مدل بینایی یک دستورالعمل ویژه کار، مانند OCR، مقایسه، بازرسی UI یا کپشن‌نویسی کوتاه بدهید.

• با مدل‌های بینایی محلی کند یا شروع‌های سرد Ollama، از --timeout-ms استفاده کنید.

• برای image describe، مقدار --model باید یک <provider/model> با قابلیت تصویر باشد.

• برای مدل‌های بینایی محلی Ollama، ابتدا مدل را pull کنید و OLLAMA_API_KEY را روی هر مقدار placeholder، برای مثال ollama-local، تنظیم کنید. Ollama را ببینید.

# صدا

از audio برای رونویسی فایل استفاده کنید.

openclaw infer audio transcribe --file ./memo.m4a --json
openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

نکات:

• audio transcribe برای رونویسی فایل است، نه مدیریت نشست بلادرنگ.
• مقدار --model باید <provider/model> باشد.

# TTS

از tts برای سنتز گفتار و وضعیت ارائه‌دهنده TTS استفاده کنید.

openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json
openclaw infer tts providers --json
openclaw infer tts status --json

نکات:

• tts status به‌طور پیش‌فرض روی Gateway قرار دارد، چون وضعیت TTS مدیریت‌شده توسط Gateway را بازتاب می‌دهد.
• برای بررسی و پیکربندی رفتار TTS، از tts providers، tts voices و tts set-provider استفاده کنید.

# ویدئو

از video برای تولید و توصیف استفاده کنید.

openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
openclaw infer video generate --prompt "slow drone shot over a forest lake" --resolution 768P --duration 6 --json
openclaw infer video describe --file ./clip.mp4 --json
openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --json

نکات:

• video generate گزینه‌های --size، --aspect-ratio، --resolution، --duration، --audio، --watermark و --timeout-ms را می‌پذیرد و آن‌ها را به runtime تولید ویدئو ارسال می‌کند.
• برای video describe، مقدار --model باید <provider/model> باشد.

# وب

از web برای گردش‌کارهای جست‌وجو و fetch استفاده کنید.

openclaw infer web search --query "OpenClaw docs" --json
openclaw infer web search --query "OpenClaw infer web providers" --json
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json
openclaw infer web providers --json

نکات:

• برای بررسی ارائه‌دهندگان در دسترس، پیکربندی‌شده و انتخاب‌شده، از web providers استفاده کنید.

# Embedding

از embedding برای ساخت بردار و بررسی ارائه‌دهنده embedding استفاده کنید.

openclaw infer embedding create --text "friendly lobster" --json
openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json
openclaw infer embedding providers --json

# خروجی JSON

فرمان‌های Infer خروجی JSON را زیر یک envelope مشترک نرمال‌سازی می‌کنند:

{
  "ok": true,
  "capability": "image.generate",
  "transport": "local",
  "provider": "openai",
  "model": "gpt-image-2",
  "attempts": [],
  "outputs": []
}

فیلدهای سطح بالا پایدار هستند:

• ok
• capability
• transport
• provider
• model
• attempts
• outputs
• error

برای فرمان‌های رسانه تولیدشده، outputs شامل فایل‌هایی است که OpenClaw نوشته است. برای خودکارسازی، به‌جای parse کردن stdout خوانا برای انسان، از path، mimeType، size و هر ابعاد ویژه رسانه در آن آرایه استفاده کنید.

# خطاهای رایج

# Bad
openclaw infer media image generate --prompt "friendly lobster"

# Good
openclaw infer image generate --prompt "friendly lobster"

# Bad
openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json

# Good
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json

# نکات

• openclaw capability ... نام مستعاری برای openclaw infer ... است.

# مرتبط

• مرجع CLI
• مدل‌ها