CLI โมเดล

การอ้างอิงโมเดลจะเลือกผู้ให้บริการและโมเดล โดยปกติจะไม่เลือก runtime เอเจนต์ระดับต่ำโดยตรง การอ้างอิงเอเจนต์ OpenAI เป็นข้อยกเว้นหลัก: openai/gpt-5.5 จะทำงานผ่าน runtime app-server ของ Codex ตามค่าเริ่มต้นบนผู้ให้บริการ OpenAI อย่างเป็นทางการ การอ้างอิง Copilot แบบสมัครสมาชิก (github-copilot/*) ยังสามารถเลือกใช้ Plugin runtime เอเจนต์ GitHub Copilot ภายนอกได้ด้วย — เส้นทางนั้นยังคงต้องระบุอย่างชัดเจน (ไม่มี fallback แบบ auto) การ override runtime อย่างชัดเจนควรอยู่ในนโยบายผู้ให้บริการ/โมเดล ไม่ใช่ที่เอเจนต์หรือเซสชันทั้งหมด ในโหมด runtime ของ Codex การอ้างอิง openai/gpt-* ไม่ได้หมายถึงการคิดค่าบริการผ่าน API key; การยืนยันตัวตนอาจมาจากบัญชี Codex หรือโปรไฟล์ OAuth ของ openai ดู รันไทม์ของเอเจนต์ และ runtime เอเจนต์ GitHub Copilot

วิธีการเลือกโมเดลทำงาน

OpenClaw เลือกโมเดลตามลำดับนี้:

แหล่งที่มาของการเลือกและพฤติกรรม fallback

provider/model เดียวกันอาจหมายถึงคนละอย่าง ขึ้นอยู่กับว่ามาจากที่ใด:

• ค่าเริ่มต้นที่กำหนดค่าไว้ (agents.defaults.model.primary และโมเดลหลักเฉพาะเอเจนต์) เป็นจุดเริ่มต้นปกติและใช้ agents.defaults.model.fallbacks
• การเลือก fallback อัตโนมัติเป็นสถานะกู้คืนชั่วคราว ระบบจะจัดเก็บพร้อม modelOverrideSource: "auto" เพื่อให้ turn ถัดไปยังใช้ fallback chain ต่อได้โดยไม่ต้อง probe โมเดลหลักที่รู้ว่าใช้งานไม่ได้ทุกครั้ง; OpenClaw จะ probe โมเดลหลักเดิมอีกครั้งเป็นระยะ ล้างการเลือกอัตโนมัติเมื่อโมเดลกลับมาทำงาน และประกาศการเปลี่ยนผ่าน fallback/การกู้คืนหนึ่งครั้งต่อการเปลี่ยนสถานะ
• การเลือกของเซสชันผู้ใช้เป็นแบบแน่นอน /model, ตัวเลือกโมเดล, session_status(model=...) และ sessions.patch จะจัดเก็บ modelOverrideSource: "user"; หากผู้ให้บริการ/โมเดลที่เลือกนั้นเข้าถึงไม่ได้ OpenClaw จะแสดงความล้มเหลวให้เห็นชัดเจนแทนที่จะไหลต่อไปยังโมเดลอื่นที่กำหนดค่าไว้
• การเปลี่ยน agents.defaults.model.primary จะไม่เขียนทับการเลือกของเซสชันที่มีอยู่ หากสถานะแจ้งว่า This session is pinned to X; config primary Y will apply to new/unpinned sessions. ให้ล้างการเลือกของเซสชันปัจจุบันด้วย /model default เพื่อให้รับค่าจากโมเดลหลักที่กำหนดค่าไว้อีกครั้ง
• Cron --model / payload model คือโมเดลหลักต่อ job และยังคงใช้ fallback ที่กำหนดค่าไว้ เว้นแต่ job จะส่ง payload fallbacks อย่างชัดเจน (ใช้ fallbacks: [] สำหรับการรัน cron แบบเข้มงวด)
• ตัวเลือก default-model และ allowlist ของ CLI เคารพ models.mode: "replace" โดยแสดงรายการ models.providers.*.models ที่ระบุไว้อย่างชัดเจนแทนการโหลดแคตตาล็อกในตัวทั้งหมด
• ตัวเลือกโมเดลของ Control UI จะถาม Gateway เพื่อรับมุมมองโมเดลที่กำหนดค่าไว้: ใช้ agents.defaults.models เมื่อมีอยู่ รวมถึงรายการ provider/* แบบครอบคลุมผู้ให้บริการ มิฉะนั้นใช้ models.providers.*.models ที่ระบุไว้อย่างชัดเจนพร้อมผู้ให้บริการที่มีการยืนยันตัวตนใช้งานได้ แคตตาล็อกในตัวทั้งหมดสงวนไว้สำหรับมุมมองการเรียกดูอย่างชัดเจน เช่น models.list พร้อม view: "all" หรือ openclaw models list --all

นโยบายโมเดลแบบรวดเร็ว

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

Onboarding (แนะนำ)

หากคุณไม่ต้องการแก้ config ด้วยตนเอง ให้รัน onboarding:

openclaw onboard

เครื่องมือนี้สามารถตั้งค่าโมเดล + การยืนยันตัวตนสำหรับผู้ให้บริการทั่วไป รวมถึง OpenAI Code (Codex) subscription (OAuth) และ Anthropic (API key หรือ Claude CLI)

คีย์การกำหนดค่า (ภาพรวม)

• agents.defaults.model.primary และ agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary และ agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary และ agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary และ agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary และ agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (allowlist + alias + พารามิเตอร์ผู้ให้บริการ + รายการผู้ให้บริการไดนามิก provider/*)
• models.providers (ผู้ให้บริการแบบกำหนดเองที่เขียนลงใน models.json)

การแก้ allowlist อย่างปลอดภัย

ใช้การเขียนแบบเพิ่มเมื่ออัปเดต agents.defaults.models ด้วยตนเอง:

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge

"ไม่อนุญาตให้ใช้โมเดล" (และเหตุผลที่คำตอบหยุด)

หากตั้งค่า agents.defaults.models ไว้ ค่านั้นจะกลายเป็น allowlist สำหรับ /model และสำหรับการ override เซสชัน เมื่อผู้ใช้เลือกโมเดลที่ไม่ได้อยู่ใน allowlist นั้น OpenClaw จะส่งคืน:

Model "provider/model" is not allowed. Use /models to list providers, or /models <provider> to list models.Add it with: openclaw config set agents.defaults.models '{"provider/model":{}}' --strict-json --merge

เมื่อคำสั่งที่ถูกปฏิเสธมี runtime override เช่น /model openai/gpt-5.5 --runtime codex ให้แก้ allowlist ก่อน แล้วลองคำสั่ง /model ... --runtime ... เดิมอีกครั้ง สำหรับการดำเนินการ Codex แบบ native โมเดลที่เลือกยังคงเป็น openai/gpt-5.5; runtime codex จะเลือก harness และใช้การยืนยันตัวตน Codex แยกต่างหาก

สำหรับโมเดล local/GGUF ให้จัดเก็บการอ้างอิงแบบมี provider prefix เต็มใน allowlist เช่น ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf หรือ provider/model ที่ตรงตามที่ openclaw models list --provider <provider> แสดง ชื่อไฟล์ local แบบเปล่าๆ หรือชื่อแสดงผลไม่เพียงพอเมื่อ allowlist เปิดใช้งานอยู่

หากคุณต้องการจำกัดผู้ให้บริการโดยไม่ต้องระบุทุกโมเดลด้วยตนเอง ให้เพิ่ม รายการ provider/* ไปยัง agents.defaults.models:

{  agents: {    defaults: {      models: {        "openai/*": {},        "vllm/*": {},      },    },  },}

ด้วยนโยบายนี้ /model, /models และตัวเลือกโมเดลจะแสดงแคตตาล็อกที่ค้นพบ สำหรับผู้ให้บริการเหล่านั้นเท่านั้น โมเดลใหม่จากผู้ให้บริการที่เลือกสามารถ ปรากฏได้โดยไม่ต้องแก้ allowlist รายการ provider/model แบบ exact สามารถผสม กับรายการ provider/* ได้เมื่อคุณต้องการโมเดลเฉพาะหนึ่งรายการจากผู้ให้บริการอื่น

ตัวอย่างการกำหนดค่า allowlist:

{  agents: {    defaults: {      model: { primary: "anthropic/claude-sonnet-4-6" },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "anthropic/claude-opus-4-6": { alias: "Opus" },      },    },  },}

การสลับโมเดลในแชต (/model)

คุณสามารถสลับโมเดลสำหรับเซสชันปัจจุบันได้โดยไม่ต้องรีสตาร์ต:

/model/model list/model 3/model openai/gpt-5.4/model default/model status

พฤติกรรม/การกำหนดค่าคำสั่งฉบับเต็ม: คำสั่ง Slash

คำสั่ง CLI

openclaw models listopenclaw models statusopenclaw models set <provider/model>openclaw models set-image <provider/model> openclaw models aliases listopenclaw models aliases add <alias> <provider/model>openclaw models aliases remove <alias> openclaw models fallbacks listopenclaw models fallbacks add <provider/model>openclaw models fallbacks remove <provider/model>openclaw models fallbacks clear openclaw models image-fallbacks listopenclaw models image-fallbacks add <provider/model>openclaw models image-fallbacks remove <provider/model>openclaw models image-fallbacks clear

openclaw models (ไม่มีคำสั่งย่อย) เป็นทางลัดสำหรับ models status

models list

แสดงโมเดลที่กำหนดค่าไว้/พร้อมใช้งานด้วย auth โดยค่าเริ่มต้น แฟล็กที่มีประโยชน์:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> กรองตาม ID ของ provider เช่น moonshot ไม่ยอมรับป้ายกำกับที่แสดงจากตัวเลือกแบบโต้ตอบ

models status

แสดงโมเดลหลักที่ resolve แล้ว, fallback, โมเดลภาพ และภาพรวม auth ของ provider ที่กำหนดค่าไว้ นอกจากนี้ยังแสดงสถานะการหมดอายุของ OAuth สำหรับโปรไฟล์ที่พบในที่เก็บ auth (โดยค่าเริ่มต้นจะเตือนภายใน 24 ชั่วโมง) --plain จะพิมพ์เฉพาะโมเดลหลักที่ resolve แล้ว

ตัวอย่าง (Claude CLI):

claude auth loginopenclaw models status

การสแกน (โมเดลฟรีของ OpenRouter)

openclaw models scan ตรวจสอบ แค็ตตาล็อกโมเดลฟรี ของ OpenRouter และสามารถ probe โมเดลสำหรับการรองรับเครื่องมือและภาพได้ตามต้องการ

ผลลัพธ์การสแกนจัดอันดับตาม:

1. การรองรับภาพ
2. เวลาแฝงของเครื่องมือ
3. ขนาด context
4. จำนวนพารามิเตอร์

อินพุต:

• รายการ /models ของ OpenRouter (ตัวกรอง :free)
• probe แบบสดต้องใช้ API key ของ OpenRouter จากโปรไฟล์ auth หรือ OPENROUTER_API_KEY (ดู ตัวแปรสภาพแวดล้อม)
• ตัวกรองเสริม: --max-age-days, --min-params, --provider, --max-candidates
• การควบคุม request/probe: --timeout, --concurrency

เมื่อ probe แบบสดทำงานใน TTY คุณสามารถเลือก fallback แบบโต้ตอบได้ ในโหมดไม่โต้ตอบ ให้ส่ง --yes เพื่อยอมรับค่าเริ่มต้น ผลลัพธ์เฉพาะ metadata มีไว้เพื่อให้ข้อมูล; --set-default และ --set-image ต้องใช้ probe แบบสด เพื่อให้ OpenClaw ไม่กำหนดค่าโมเดล OpenRouter ที่ไม่มี key และใช้งานไม่ได้

รีจิสทรีโมเดล (models.json)

provider แบบกำหนดเองใน models.providers จะถูกเขียนลงใน models.json ใต้ไดเรกทอรี agent (ค่าเริ่มต้น ~/.openclaw/agents/<agentId>/agent/models.json) แค็ตตาล็อกของ provider-plugin จะถูกจัดเก็บเป็น shard แค็ตตาล็อกที่สร้างขึ้นและเป็นของ Plugin ใต้สถานะ Plugin ของ agent และโหลดโดยอัตโนมัติ ไฟล์นี้จะถูก merge โดยค่าเริ่มต้น เว้นแต่ models.mode จะถูกตั้งค่าเป็น replace

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

• runtime ของ agent — OpenClaw, Codex และ runtime ลูป agent อื่น ๆ
• อ้างอิงการกำหนดค่า — key การกำหนดค่าโมเดล
• การสร้างภาพ — การกำหนดค่าโมเดลภาพ
• failover ของโมเดล — เชน fallback
• provider ของโมเดล — การกำหนดเส้นทาง provider และ auth
• การสร้างเพลง — การกำหนดค่าโมเดลเพลง
• การสร้างวิดีโอ — การกำหนดค่าโมเดลวิดีโอ