CLI สำหรับโมเดล

การอ้างอิงโมเดล (provider/model) จะเลือกผู้ให้บริการและโมเดล ไม่ใช่รันไทม์ เอเจนต์ระดับล่าง เมื่อไม่ได้ตั้งค่านโยบายรันไทม์หรือตั้งเป็น auto นโยบาย เส้นทางที่ผู้ให้บริการของ OpenAI เป็นเจ้าของอาจเลือก Codex เฉพาะสำหรับเส้นทาง Responses ของ HTTPS Platform อย่างเป็นทางการหรือเส้นทาง ChatGPT Responses ที่ตรงกันทุกประการ และไม่มีการเขียนค่าลบล้างคำขอไว้ โดยคำนำหน้า openai/* เพียงอย่างเดียวจะไม่เลือก Codex ส่วนอะแดปเตอร์ Completions, เอนด์พอยต์แบบกำหนดเอง และพฤติกรรมคำขอที่เขียนกำหนดไว้ จะยังคงทำงานบน OpenClaw เอนด์พอยต์ HTTP แบบข้อความธรรมดาที่เป็นทางการจะถูกปฏิเสธ ดู รันไทม์เอเจนต์โดยนัยของ OpenAI

การอ้างอิง Copilot แบบสมัครสมาชิก (github-copilot/*) สามารถเลือกใช้ Plugin รันไทม์ เอเจนต์ GitHub Copilot ภายนอกได้ แต่เส้นทางดังกล่าวจะต้องระบุอย่างชัดเจนเสมอ (จะไม่ถูกเลือกโดย auto) การลบล้างรันไทม์ต้องอยู่ในนโยบายผู้ให้บริการ/โมเดล ไม่ใช่กับทั้งเอเจนต์หรือเซสชัน การเลือกรันไทม์ไม่ได้กำหนดการเรียกเก็บเงิน: ข้อมูลประจำตัวคีย์ API ของ OpenAI และข้อมูลประจำตัวการสมัครสมาชิก ChatGPT/Codex ยังคงแยกจากกัน ดู รันไทม์เอเจนต์ และ รันไทม์เอเจนต์ GitHub Copilot

ลำดับการเลือก

พื้นผิวการกำหนดค่าโมเดลที่เกี่ยวข้อง:

• agents.defaults.models จัดเก็บนามแฝงและการตั้งค่ารายโมเดล การเพิ่มรายการไม่ได้จำกัดการลบล้างโมเดล
• agents.defaults.modelPolicy.allow คือรายการอนุญาตสำหรับการลบล้างที่ไม่บังคับ ใช้การอ้างอิงที่ตรงกันทุกประการหรืออักขระตัวแทนคำนำหน้าที่ลงท้าย เช่น provider/* และ provider/namespace/*; ละไว้หรือตั้งเป็น [] เพื่ออนุญาตทุกโมเดล agents.list[].modelPolicy.allow รายเอเจนต์จะแทนที่นโยบายเริ่มต้นสำหรับเอเจนต์นั้น
• agents.defaults.utilityModel คือโมเดลต้นทุนต่ำกว่าที่ไม่บังคับสำหรับงานภายในระยะสั้น เช่น ชื่อเซสชันแดชบอร์ดที่สร้างขึ้น ชื่อเธรด/หัวข้อของช่องทางที่รองรับ และคำบรรยายความคืบหน้า agents.list[].utilityModel รายเอเจนต์จะลบล้างค่านี้ เมื่อไม่ได้ตั้งค่า OpenClaw จะใช้ค่าเริ่มต้นของโมเดลขนาดเล็กที่ผู้ให้บริการหลักประกาศไว้เมื่อมี (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5) มิฉะนั้นจะใช้โมเดลหลักของเอเจนต์; ตั้งเป็นสตริงว่างเพื่อปิดใช้การกำหนดเส้นทางยูทิลิตี ชื่อที่สร้างขึ้นจะลองใหม่หนึ่งครั้งด้วยโมเดลหลักเมื่อโมเดลยูทิลิตีที่แยกต่างหากล้มเหลว สำหรับชื่อแดชบอร์ด การอนุมานยูทิลิตีอัตโนมัติและการใช้โมเดลสำรองตามปกติจะเป็นไปตามผู้ให้บริการและโปรไฟล์การยืนยันตัวตนที่มีผลกับเซสชัน ส่วนโมเดลยูทิลิตีที่ระบุอย่างชัดเจนจะคงผู้ให้บริการ/การยืนยันตัวตนที่กำหนดค่าไว้ โมเดลยูทิลิตีที่เป็นค่าว่างจะข้ามเฉพาะเส้นทางโมเดลขนาดเล็กทางเลือก ไม่ได้ข้ามการสร้างชื่อแดชบอร์ด งานยูทิลิตีเป็นการเรียกโมเดลแยกต่างหากและอาจส่งเนื้อหางานที่มีขอบเขตจำกัดไปยังผู้ให้บริการโมเดลที่เลือก
• agents.defaults.imageModel ใช้เฉพาะเมื่อโมเดลหลักไม่สามารถรับรูปภาพได้
• agents.defaults.pdfModel ใช้โดยเครื่องมือ pdf หากไม่ได้ตั้งค่า เครื่องมือจะใช้ imageModel เป็นตัวสำรอง จากนั้นจึงใช้โมเดลเซสชัน/ค่าเริ่มต้นที่ได้รับการแก้ไขแล้ว
• agents.defaults.imageGenerationModel, musicGenerationModel และ videoGenerationModel รองรับเครื่องมือสร้างสื่อที่ใช้ร่วมกัน หากไม่ได้ตั้งค่า แต่ละเครื่องมือจะอนุมานค่าเริ่มต้นของผู้ให้บริการที่มีการยืนยันตัวตนรองรับ โดยเริ่มจากผู้ให้บริการเริ่มต้นปัจจุบัน จากนั้นจึงเป็นผู้ให้บริการที่ลงทะเบียนที่เหลือสำหรับความสามารถนั้นตามลำดับรหัสผู้ให้บริการ ตั้ง agents.defaults.mediaGenerationAutoProviderFallback: false เพื่อปิดใช้การอนุมานข้ามผู้ให้บริการดังกล่าวโดยยังคงใช้โมเดลสำรองที่ระบุไว้อย่างชัดเจน
• agents.list[].model รายเอเจนต์ (รวมถึงการผูก) จะลบล้าง agents.defaults.model — ดู การกำหนดเส้นทางหลายเอเจนต์

เอกสารอ้างอิงคีย์ ค่าเริ่มต้น และตัวอย่าง JSON5 ฉบับเต็ม: เอกสารอ้างอิงการกำหนดค่า

แหล่งที่มาของการเลือกและความเข้มงวดของโมเดลสำรอง

provider/model เดียวกันจะทำงานแตกต่างกันตามแหล่งที่มา:

กฎการเลือกอื่นๆ:

• การเปลี่ยน agents.defaults.model.primary จะไม่เขียนทับการตรึงเซสชันที่มีอยู่ หากสถานะรายงาน This session is pinned to X; config primary Y will apply to new/unpinned sessions. ให้เรียกใช้ /model default เพื่อล้างการตรึง
• ตัวเลือกโมเดลเริ่มต้นและรายการอนุญาตของ CLI จะเคารพ models.mode: "replace" โดยแสดงเฉพาะ models.providers.*.models แทนแค็ตตาล็อกในตัวทั้งหมด
• ตัวเลือกโมเดลใน Control UI จะขอมุมมองโมเดลที่กำหนดค่าไว้จาก Gateway modelPolicy.allow ที่ระบุอย่างชัดเจนจะกรองมุมมองนี้ รวมถึงรายการอักขระตัวแทนคำนำหน้าที่ลงท้าย มิฉะนั้นจะแสดงโมเดลที่กำหนดค่าไว้พร้อมผู้ให้บริการที่มีการยืนยันตัวตนซึ่งใช้งานได้ แค็ตตาล็อกในตัวทั้งหมดสงวนไว้สำหรับมุมมองเรียกดูที่ระบุอย่างชัดเจน (models.list พร้อม view: "all" หรือ openclaw models list --all)
• UI คลังผู้ให้บริการใช้ models.list พร้อม view: "provider-config" เพื่อแสดงแถว models.providers.*.models ที่แหล่งข้อมูลเป็นผู้เขียน โดยไม่ใช้รายการอนุญาตของตัวเลือก

กลไกฉบับเต็ม: การสลับโมเดลเมื่อขัดข้อง

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

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

การเริ่มต้นใช้งาน

openclaw onboard

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

เมื่อไม่ได้กำหนดค่าโมเดลหลัก การตั้งค่าคีย์ API ของ OpenAI ใหม่จะเลือก openai/gpt-5.6; รหัส API โดยตรงแบบเปล่าจะได้รับการแก้ไขเป็นระดับ Sol การตั้งค่า OAuth ของ ChatGPT/Codex ใหม่จะเลือกการอ้างอิงแค็ตตาล็อก openai/gpt-5.6-sol ที่ตรงกันทุกประการ การยืนยันตัวตนซ้ำจะคงโมเดลหลักที่ระบุอย่างชัดเจนไว้ รวมถึง openai/gpt-5.5 หากบัญชีไม่สามารถใช้ GPT-5.6 ได้ ให้เลือก openai/gpt-5.5 อย่างชัดเจน; OpenClaw จะไม่ลดระดับให้โดยไม่แจ้ง

"ไม่อนุญาตให้ใช้โมเดล" (และเหตุใดการตอบกลับจึงหยุดลง)

หาก agents.defaults.modelPolicy.allow ไม่ว่าง ค่านี้จะกลายเป็นรายการอนุญาตสำหรับ /model, การลบล้างเซสชัน และ --model การเลือกโมเดลนอกเหนือจากรายการอนุญาตดังกล่าวจะส่งคืนก่อนที่จะสร้างการตอบกลับตามปกติ agents.list[].modelPolicy.allow รายเอเจนต์จะแทนที่นโยบายเริ่มต้นสำหรับเอเจนต์นั้น

รายการอนุญาต agents.defaults.modelPolicy.allow ไม่อนุญาตการลบล้างโมเดล "provider/model"เพิ่ม "provider/model", "provider/*" หรือคำนำหน้า "provider/namespace/*" ที่แคบกว่าลงใน agents.defaults.modelPolicy.allow หรือลบ/ทำรายการให้ว่างเพื่ออนุญาตทุกโมเดล

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

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

หากต้องการจำกัดผู้ให้บริการโดยไม่ต้องระบุทุกโมเดล ให้ใช้รายการอักขระตัวแทนคำนำหน้าที่ลงท้าย provider/* ซึ่งครอบคลุมทั้งผู้ให้บริการจะตรงกับทุกโมเดลภายใต้ผู้ให้บริการนั้น ส่วนคำนำหน้าที่แคบกว่า เช่น clawrouter/anthropic/* จะตรงกับเนมสเปซนั้นเท่านั้น:

{  agents: {    defaults: {      modelPolicy: {        allow: ["openai/*", "vllm/*"],      },    },  },}

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

ตัวอย่างรายการอนุญาตพร้อมนามแฝงและการตั้งค่ารายโมเดล:

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

openclaw config set agents.defaults.modelPolicy.allow '["openai/gpt-5.4","anthropic/*"]' --strict-json

/model ในแชต

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

• /model และ /model list จะแสดงตัวเลือกแบบมีหมายเลขขนาดกะทัดรัด (ตระกูลโมเดล + ผู้ให้บริการที่พร้อมใช้งาน) ส่วน /model <#> ใช้เลือกจากรายการนี้ ใน Discord ระบบจะเปิดเมนูแบบเลื่อนลงสำหรับผู้ให้บริการ/โมเดล พร้อมขั้นตอน Submit ส่วนใน Telegram การเลือกจากตัวเลือกจะมีขอบเขตเฉพาะเซสชัน และจะไม่เขียนทับค่าเริ่มต้นถาวรของเอเจนต์ใน openclaw.json โดยเด็ดขาด /models add เลิกใช้แล้ว และจะส่งข้อความตอบกลับแทนการลงทะเบียนโมเดลจากแชต
• /model จะบันทึกการเลือกใหม่ของเซสชันทันที หากเอเจนต์ไม่มีงาน การเรียกใช้ครั้งถัดไปจะใช้ค่านั้นทันที แต่หากมีการเรียกใช้ที่กำลังทำงานอยู่ การสลับจะถูกจัดคิวไว้สำหรับจุดลองใหม่ที่สะอาดถัดไป (หรือจุดหลังจากนั้น หากกิจกรรมของเครื่องมือหรือการส่งคำตอบเริ่มต้นไปแล้ว)
• /model default จะล้างการเลือกของเซสชัน เพื่อให้กลับไปรับค่าหลักที่กำหนดไว้อีกครั้ง
• การอ้างอิง /model ที่ผู้ใช้เลือกจะมีผลอย่างเคร่งครัดสำหรับเซสชันนั้น หากไม่สามารถเข้าถึงได้ การตอบกลับจะล้มเหลวอย่างชัดเจน แทนที่จะใช้ agents.defaults.model.fallbacks เป็นทางเลือกสำรองโดยไม่แจ้งให้ทราบ ค่าเริ่มต้นที่กำหนดไว้และโมเดลหลักของงาน Cron จะยังคงใช้ลำดับทางเลือกสำรอง
• /model status คือมุมมองโดยละเอียด ซึ่งแสดงตัวเลือกการยืนยันตัวตนของผู้ให้บริการแต่ละราย และเมื่อมีการกำหนดค่า จะแสดงปลายทางของผู้ให้บริการ baseUrl พร้อมโหมด api
• การอ้างอิงโมเดลจะถูกแยกวิเคราะห์โดยแบ่งที่ / ตัวแรก ให้พิมพ์ provider/model หาก ID โมเดลมี / อยู่ภายใน (รูปแบบ OpenRouter) ให้ใส่คำนำหน้าผู้ให้บริการด้วย เช่น /model openrouter/moonshotai/kimi-k2 หากละเว้นผู้ให้บริการ OpenClaw จะลองตามลำดับดังนี้: (1) จับคู่นามแฝง (2) จับคู่กับผู้ให้บริการที่กำหนดค่าไว้เพียงรายเดียวสำหรับ ID โมเดลแบบไม่มีคำนำหน้าที่ตรงกันทุกประการ (3) ใช้ผู้ให้บริการเริ่มต้นที่กำหนดไว้ (ทางเลือกสำรองที่เลิกใช้แล้ว) และหากผู้ให้บริการนั้นไม่ให้บริการโมเดลเริ่มต้นที่กำหนดไว้อีกต่อไป ระบบจะใช้ผู้ให้บริการ/โมเดลคู่แรกที่กำหนดค่าไว้แทน เพื่อหลีกเลี่ยงการแสดงค่าเริ่มต้นเก่าของผู้ให้บริการที่ถูกนำออกแล้ว
• การอ้างอิงโมเดลจะถูกปรับให้เป็นตัวพิมพ์เล็ก ส่วน ID ผู้ให้บริการต้องตรงตามที่ระบุทุกประการ ดังนั้นให้ใช้ ID ที่ Plugin ประกาศ

ลักษณะการทำงานของคำสั่งและการกำหนดค่าทั้งหมด: คำสั่งเครื่องหมายทับ

CLI

openclaw models statusopenclaw models listopenclaw models set <provider/model>openclaw models set-image <provider/model>openclaw models scanopenclaw models aliases list|add|removeopenclaw models fallbacks list|add|remove|clearopenclaw models image-fallbacks list|add|remove|clearopenclaw models auth list|add|login|paste-api-key|paste-token|setup-token|order

openclaw models ที่ไม่มีคำสั่งย่อยเป็นทางลัดสำหรับ models status ซึ่งจะแสดงวันหมดอายุของ OAuth สำหรับโปรไฟล์ในที่เก็บข้อมูลการยืนยันตัวตนด้วย (โดยค่าเริ่มต้นจะแจ้งเตือนภายใน 24h) แฟล็กทั้งหมด โครงสร้าง JSON และคำสั่งย่อยของโปรไฟล์การยืนยันตัวตน: เอกสารอ้างอิง Models CLI

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

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

การบันทึกเครื่องหมายยึดแหล่งที่มาเป็นข้อมูลหลัก: OpenClaw จะเขียนเครื่องหมายจากสแนปช็อตการกำหนดค่าแหล่งที่มาที่ใช้งานอยู่ (ก่อนการแก้ค่า) ไม่ใช่จากค่าข้อมูลลับของรันไทม์ที่แก้ค่าแล้ว ทุกครั้งที่สร้าง models.json ใหม่ รวมถึงเส้นทางที่ขับเคลื่อนด้วยคำสั่ง เช่น openclaw agent

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

• รันไทม์ของเอเจนต์ — OpenClaw, Codex และรันไทม์ลูปเอเจนต์อื่นๆ
• เอกสารอ้างอิงการกำหนดค่า — คีย์การกำหนดค่าโมเดล
• การสร้างรูปภาพ — การกำหนดค่าโมเดลรูปภาพ
• การสลับไปใช้โมเดลสำรอง — ลำดับทางเลือกสำรอง
• ผู้ให้บริการโมเดล — การกำหนดเส้นทางผู้ให้บริการและการยืนยันตัวตน
• เอกสารอ้างอิง Models CLI — เอกสารอ้างอิงคำสั่งและแฟล็กทั้งหมด
• การสร้างเพลง — การกำหนดค่าโมเดลเพลง
• การสร้างวิดีโอ — การกำหนดค่าโมเดลวิดีโอ