CLI โมเดล

การอ้างอิงโมเดลจะเลือกผู้ให้บริการและโมเดล โดยปกติจะไม่ได้เลือกรันไทม์เอเจนต์ระดับล่าง ตัวอย่างเช่น openai/gpt-5.5 สามารถทำงานผ่านเส้นทางผู้ให้บริการ OpenAI ปกติ หรือผ่านรันไทม์เซิร์ฟเวอร์แอป Codex ได้ ขึ้นอยู่กับ agents.defaults.agentRuntime.id ในโหมดรันไทม์ Codex การอ้างอิง openai/gpt-* ไม่ได้หมายถึงการคิดค่าใช้จ่ายด้วยคีย์ API การยืนยันตัวตนอาจมาจากบัญชี Codex หรือโปรไฟล์ยืนยันตัวตน openai-codex ดู รันไทม์ของเอเจนต์

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

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

# แหล่งที่มาของการเลือกและพฤติกรรมตัวสำรอง

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

• ค่าเริ่มต้นที่กำหนดค่าไว้ (agents.defaults.model.primary และโมเดลหลักเฉพาะเอเจนต์) คือจุดเริ่มต้นปกติและใช้ agents.defaults.model.fallbacks
• การเลือกตัวสำรองอัตโนมัติเป็นสถานะกู้คืนชั่วคราว โดยจัดเก็บพร้อม modelOverrideSource: "auto" เพื่อให้รอบถัดไปใช้ห่วงโซ่ตัวสำรองต่อไปได้โดยไม่ต้องลองโมเดลหลักที่รู้ว่าเสียก่อน
• การเลือกเซสชันของผู้ใช้เป็นแบบเจาะจง /model, ตัวเลือกโมเดล, session_status(model=...) และ sessions.patch จะจัดเก็บ modelOverrideSource: "user" หากผู้ให้บริการ/โมเดลที่เลือกนั้นเข้าถึงไม่ได้ OpenClaw จะล้มเหลวให้เห็นชัดแทนที่จะถอยไปยังโมเดลอื่นที่กำหนดค่าไว้
• Cron --model / เพย์โหลด model เป็นโมเดลหลักรายงาน ยังใช้ตัวสำรองที่กำหนดค่าไว้ เว้นแต่งานจะระบุเพย์โหลด fallbacks อย่างชัดเจน (ใช้ fallbacks: [] สำหรับการรัน Cron แบบเข้มงวด)
• ตัวเลือกโมเดลเริ่มต้นและรายการอนุญาตของ CLI จะเคารพ models.mode: "replace" โดยแสดง models.providers.*.models ที่ระบุชัดเจน แทนการโหลดแค็ตตาล็อกในตัวทั้งหมด
• ตัวเลือกโมเดลใน Control UI จะถาม Gateway เพื่อดูมุมมองโมเดลที่กำหนดค่าไว้: agents.defaults.models เมื่อมีอยู่ ไม่เช่นนั้นใช้ models.providers.*.models ที่ระบุชัดเจนพร้อมผู้ให้บริการที่มีการยืนยันตัวตนใช้งานได้ แค็ตตาล็อกในตัวทั้งหมดสงวนไว้สำหรับมุมมองเรียกดูแบบชัดเจน เช่น models.list พร้อม view: "all" หรือ openclaw models list --all

# นโยบายโมเดลแบบย่อ

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

# การเริ่มต้นใช้งาน (แนะนำ)

หากคุณไม่ต้องการแก้ไขการกำหนดค่าด้วยมือ ให้รันการเริ่มต้นใช้งาน:

openclaw onboard

สามารถตั้งค่าโมเดล + การยืนยันตัวตนสำหรับผู้ให้บริการทั่วไป รวมถึง การสมัครใช้งาน OpenAI Code (Codex) (OAuth) และ Anthropic (คีย์ API หรือ 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 (รายการอนุญาต + นามแฝง + พารามิเตอร์ผู้ให้บริการ)
• models.providers (ผู้ให้บริการกำหนดเองที่เขียนลงใน models.json)

# การแก้ไขรายการอนุญาตอย่างปลอดภัย

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

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

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

หากตั้งค่า agents.defaults.models ไว้ ค่านี้จะกลายเป็น รายการอนุญาต สำหรับ /model และสำหรับการแทนที่ในเซสชัน เมื่อผู้ใช้เลือกโมเดลที่ไม่ได้อยู่ในรายการอนุญาตนั้น 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

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

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

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

{
  agent: {
    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 status

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

# คำสั่ง CLI

openclaw models list
openclaw models status
openclaw models set <provider/model>
openclaw models set-image <provider/model>

openclaw models aliases list
openclaw models aliases add <alias> <provider/model>
openclaw models aliases remove <alias>

openclaw models fallbacks list
openclaw models fallbacks add <provider/model>
openclaw models fallbacks remove <provider/model>
openclaw models fallbacks clear

openclaw models image-fallbacks list
openclaw 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 พร้อมใช้งานตามค่าเริ่มต้น แฟล็กที่มีประโยชน์:

--allboolean

แคตตาล็อกแบบเต็ม รวมแถวแคตตาล็อกแบบสแตติกที่มาพร้อมระบบและเป็นของผู้ให้บริการก่อนที่จะกำหนดค่า auth ดังนั้นมุมมองสำหรับการสำรวจอย่างเดียวจึงสามารถแสดงโมเดลที่ยังไม่พร้อมใช้งานจนกว่าคุณจะเพิ่มข้อมูลรับรองของผู้ให้บริการที่ตรงกัน

--localboolean

ผู้ให้บริการภายในเครื่องเท่านั้น

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

--plainboolean

หนึ่งโมเดลต่อบรรทัด

--jsonboolean

เอาต์พุตที่เครื่องอ่านได้

# models status

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

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

claude auth login
openclaw models status

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

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

--no-probeboolean

ข้าม live probes (เฉพาะ metadata)

"--min-params

"--max-age-days

"--provider

"--max-candidates

--set-defaultboolean

ตั้งค่า agents.defaults.model.primary เป็นรายการที่เลือกแรก

--set-imageboolean

ตั้งค่า agents.defaults.imageModel.primary เป็นรายการรูปภาพที่เลือกแรก

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

1. การรองรับรูปภาพ
2. Latency ของเครื่องมือ
3. ขนาดบริบท
4. จำนวนพารามิเตอร์

อินพุต:

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

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

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

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

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

• รันไทม์ของ agent — PI, Codex และรันไทม์ลูป agent อื่น ๆ
• เอกสารอ้างอิงการกำหนดค่า — คีย์ config ของโมเดล
• การสร้างรูปภาพ — การกำหนดค่าโมเดลรูปภาพ
• Model failover — เชน fallback
• ผู้ให้บริการโมเดล — การกำหนดเส้นทางผู้ให้บริการและ auth
• การสร้างเพลง — การกำหนดค่าโมเดลเพลง
• การสร้างวิดีโอ — การกำหนดค่าโมเดลวิดีโอ