openclaw models

การค้นหา การสแกน และการกำหนดค่าโมเดล (โมเดลเริ่มต้น โมเดลสำรอง โปรไฟล์การตรวจสอบสิทธิ์)

เนื้อหาที่เกี่ยวข้อง:

• ผู้ให้บริการและโมเดล: โมเดล
• แนวคิดการเลือกโมเดลและคำสั่งแบบสแลช /models: แนวคิดเกี่ยวกับโมเดล
• การตั้งค่าการตรวจสอบสิทธิ์ของผู้ให้บริการ: เริ่มต้นใช้งาน

คำสั่งทั่วไป

openclaw models statusopenclaw models listopenclaw models set <model-or-alias>openclaw models set-image <model-or-alias>openclaw models scan

คำสั่งย่อย status และ auth รองรับ --agent <id> เพื่อระบุเอเจนต์ที่กำหนดค่าไว้ ส่วน list, scan, aliases และ fallbacks/image-fallbacks จะใช้เอเจนต์เริ่มต้นที่กำหนดค่าไว้เสมอ และ set/set-image จะปฏิเสธ --agent โดยสิ้นเชิง หากละไว้ คำสั่งที่รองรับ --agent จะใช้ OPENCLAW_AGENT_DIR หากมีการตั้งค่าไว้ มิฉะนั้นจะใช้เอเจนต์เริ่มต้นที่กำหนดค่าไว้

สถานะ

openclaw models status แสดงค่าเริ่มต้น/ค่าทดแทนที่ผ่านการแก้ไขแล้ว พร้อมภาพรวมการตรวจสอบสิทธิ์ สำหรับรันไทม์เอเจนต์ที่ Plugin เป็นเจ้าของ เช่น Codex คำสั่งนี้ยังตรวจสอบด้วยว่า Plugin เจ้าของเปิดใช้งานอยู่และผ่านการตรวจสอบเพย์โหลดเมื่อเริ่มต้นระบบหรือไม่ เส้นทางที่มีข้อมูลประจำตัวถูกต้องแต่รันไทม์ใช้งานไม่ได้จะรายงาน status: unavailable แทน usable ส่วนเอาต์พุต JSON จะมี authStatus, runtimeStatus และข้อมูลวินิจฉัยรันไทม์แบบจำกัดขอบเขตแยกกัน เมื่อมีสแนปช็อตการใช้งานของผู้ให้บริการ ส่วนสถานะ OAuth/API key จะแสดงช่วงเวลาการใช้งานและสแนปช็อตโควตาของผู้ให้บริการด้วย ผู้ให้บริการช่วงเวลาการใช้งานในปัจจุบัน ได้แก่ Anthropic, GitHub Copilot, Gemini CLI, OpenAI, MiniMax, Xiaomi และ z.ai ข้อมูลการตรวจสอบสิทธิ์สำหรับการใช้งานมาจากฮุกเฉพาะของผู้ให้บริการเมื่อมี มิฉะนั้น OpenClaw จะใช้ข้อมูลประจำตัว OAuth/API key ที่ตรงกันจากโปรไฟล์การตรวจสอบสิทธิ์ ตัวแปรสภาพแวดล้อม หรือการกำหนดค่าแทน

ในเอาต์พุต --json นั้น auth.providers คือภาพรวมผู้ให้บริการที่รับรู้ตัวแปรสภาพแวดล้อม/การกำหนดค่า/ที่จัดเก็บ ส่วน auth.oauth คือสถานะความสมบูรณ์ของโปรไฟล์ในที่จัดเก็บการตรวจสอบสิทธิ์เท่านั้น

ตัวเลือก:

แถวการตรวจสอบอาจมาจากโปรไฟล์การตรวจสอบสิทธิ์ ข้อมูลประจำตัวในตัวแปรสภาพแวดล้อม หรือ models.json กลุ่มสถานะการตรวจสอบ ได้แก่ ok, auth, rate_limit, billing, timeout, format, unknown, no_model

รหัสรายละเอียด/เหตุผลที่คาดว่าจะพบเมื่อการตรวจสอบไม่เคยไปถึงการเรียกโมเดล:

• excluded_by_auth_order: มีโปรไฟล์ที่จัดเก็บไว้ แต่ auth.order.<provider> ที่ระบุอย่างชัดเจนไม่ได้รวมโปรไฟล์นี้ไว้ การตรวจสอบจึงรายงานการคัดออกแทนที่จะลองใช้โปรไฟล์
• missing_credential, invalid_expires, expired, unresolved_ref: มีโปรไฟล์อยู่ แต่ไม่มีสิทธิ์ใช้งานหรือไม่สามารถแก้ไขค่าได้
• ineligible_profile: โปรไฟล์เข้ากันไม่ได้กับการกำหนดค่าผู้ให้บริการด้วยเหตุผลอื่น
• no_model: มีการตรวจสอบสิทธิ์ของผู้ให้บริการอยู่ แต่ OpenClaw ไม่สามารถระบุโมเดลตัวเลือกที่ตรวจสอบได้สำหรับผู้ให้บริการรายนั้น

สำหรับการแก้ไขปัญหา OAuth ของ OpenAI ChatGPT/Codex นั้น openclaw models status, openclaw models auth list --provider openai และ openclaw config get agents.defaults.model --json เป็นวิธีที่เร็วที่สุดในการยืนยันว่าเอเจนต์มีโปรไฟล์ OAuth openai ที่ใช้งานได้สำหรับ openai/* ผ่านรันไทม์ Codex แบบเนทีฟหรือไม่ ดู การตั้งค่าผู้ให้บริการ OpenAI

รายการ

openclaw models list เป็นแบบอ่านอย่างเดียว โดยจะอ่านการกำหนดค่า โปรไฟล์การตรวจสอบสิทธิ์ สถานะแคตตาล็อกที่มีอยู่ และแถวแคตตาล็อกที่ผู้ให้บริการเป็นเจ้าของ แต่จะไม่เขียน models.json ใหม่

ตัวเลือก: --all (แคตตาล็อกทั้งหมด), --local (กรองเฉพาะโมเดลในเครื่อง), --provider <id>, --json, --plain

หมายเหตุ:

• คอลัมน์ Auth เป็นแบบอ่านอย่างเดียว สำหรับเส้นทางโมเดลที่ผู้ให้บริการเป็นเจ้าของ เช่น OpenAI คอลัมน์นี้จะจับคู่เส้นทาง API/base URL ของแต่ละแถวกับโปรไฟล์ที่มีสิทธิ์ใน auth.order ที่มีผล ข้อมูลประจำตัวจากตัวแปรสภาพแวดล้อม/การกำหนดค่า และ SecretRef ที่แก้ไขค่าแล้วภายในขอบเขตคำสั่ง แถว OpenAI ที่ระบุชัดเจนจะยังคงมีสถานะไม่ทราบเมื่อไม่มีนโยบายเส้นทาง แทนที่จะยืมการตรวจสอบสิทธิ์ระดับผู้ให้บริการ ส่วนการตรวจสอบแบบเดิมเฉพาะระดับผู้ให้บริการและผู้ให้บริการรายอื่นจะยังคงใช้พฤติกรรมระดับผู้ให้บริการ เมทาดาทาการตรวจสอบสิทธิ์สังเคราะห์ของ Plugin เป็นเพียงข้อมูลบ่งชี้ความสามารถของรันไทม์ ไม่ใช่หลักฐานการตรวจสอบสิทธิ์บัญชีแบบเนทีฟ ดังนั้นเส้นทางที่ขึ้นอยู่กับบัญชีจะยังคงมีสถานะไม่ทราบหากไม่มีหลักฐานเชิงบวกจากรีจิสทรี คำสั่งนี้จะไม่โหลดรันไทม์ผู้ให้บริการ อ่านข้อมูลลับจากพวงกุญแจ เรียก API ของผู้ให้บริการ หรือพิสูจน์ความพร้อมในการเรียกใช้จริงโดยสมบูรณ์
• models list --all --provider <id> อาจรวมแถวแคตตาล็อกแบบคงที่ที่ผู้ให้บริการเป็นเจ้าของจากแมนิเฟสต์ Plugin หรือเมทาดาทาแคตตาล็อกผู้ให้บริการแบบรวม แม้ว่ายังไม่ได้ตรวจสอบสิทธิ์กับผู้ให้บริการรายนั้น แถวเหล่านั้นจะยังคงแสดงว่าใช้งานไม่ได้จนกว่าจะกำหนดค่าการตรวจสอบสิทธิ์ที่ตรงกัน
• models list ช่วยให้ระนาบควบคุมยังคงตอบสนองได้ขณะที่การค้นพบแคตตาล็อกผู้ให้บริการทำงานช้า มุมมองเริ่มต้นและมุมมองที่กำหนดค่าไว้จะใช้แถวโมเดลที่กำหนดค่าหรือสังเคราะห์เป็นค่าทดแทนหลังจากรอช่วงสั้น ๆ และปล่อยให้การค้นพบทำงานต่อในเบื้องหลัง ใช้ --all เมื่อต้องการแคตตาล็อกที่ค้นพบทั้งหมดอย่างแม่นยำและยอมรอให้การค้นพบผู้ให้บริการเสร็จสิ้น
• models list --all แบบกว้างจะผสานแถวแคตตาล็อกในแมนิเฟสต์ทับแถวรีจิสทรีโดยไม่โหลดฮุกเสริมรันไทม์ของผู้ให้บริการ เส้นทางลัดของแมนิเฟสต์ที่กรองตามผู้ให้บริการจะใช้เฉพาะผู้ให้บริการที่ทำเครื่องหมาย static ส่วนผู้ให้บริการที่ทำเครื่องหมาย refreshable จะยังคงใช้รีจิสทรี/แคชเป็นฐานและเพิ่มแถวแมนิเฟสต์เป็นข้อมูลเสริม ขณะที่ผู้ให้บริการที่ทำเครื่องหมาย runtime จะยังคงใช้การค้นพบผ่านรีจิสทรี/รันไทม์
• models list แยกเมทาดาทาโมเดลแบบเนทีฟออกจากขีดจำกัดรันไทม์ ในเอาต์พุตตาราง Ctx จะแสดง contextTokens/contextWindow เมื่อขีดจำกัดรันไทม์ที่มีผลแตกต่างจากหน้าต่างบริบทแบบเนทีฟ ส่วนแถว JSON จะมี contextTokens เมื่อผู้ให้บริการเปิดเผยขีดจำกัดดังกล่าว
• สำหรับเส้นทางที่ผู้ให้บริการเป็นเจ้าของ models list จะฉายแถวผู้ให้บริการ/โมเดลเชิงตรรกะหนึ่งแถวไปยังเส้นทางที่เลือก Input และ Ctx จะมาจากแถวแคตตาล็อกของเส้นทางจริงที่ตรงกันทุกประการเท่านั้น โดยนำค่าที่กำหนดทับเชิงตรรกะซึ่งกำหนดไว้อย่างชัดเจนมาใช้เป็นลำดับสุดท้าย หากยังระบุเส้นทางที่เลือกไม่ได้ ฟิลด์ความสามารถจะแสดงเป็นไม่ทราบแทนที่จะยืมเมทาดาทาจากเส้นทางข้างเคียง
• models list --provider <id> กรองตาม ID ผู้ให้บริการ เช่น moonshot หรือ openai โดยไม่รองรับป้ายชื่อที่แสดงในตัวเลือกผู้ให้บริการแบบโต้ตอบ เช่น Moonshot AI
• การแยกวิเคราะห์การอ้างอิงโมเดลจะแบ่งที่ / ตัวแรก หาก ID โมเดลมี / (รูปแบบ OpenRouter) ให้ใส่คำนำหน้าผู้ให้บริการด้วย (ตัวอย่าง: openrouter/moonshotai/kimi-k2)
• หากละผู้ให้บริการไว้ OpenClaw จะแก้ไขอินพุตเป็นนามแฝงก่อน จากนั้นจับคู่ผู้ให้บริการที่กำหนดค่าไว้ซึ่งไม่ซ้ำกันสำหรับ ID โมเดลนั้นโดยตรง และเมื่อยังไม่พบจึงจะใช้ผู้ให้บริการเริ่มต้นที่กำหนดค่าไว้เป็นค่าทดแทนพร้อมคำเตือนการเลิกใช้งาน หากผู้ให้บริการรายนั้นไม่เปิดเผยโมเดลเริ่มต้นที่กำหนดค่าไว้อีกต่อไป OpenClaw จะใช้ผู้ให้บริการ/โมเดลคู่แรกที่กำหนดค่าไว้เป็นค่าทดแทน แทนที่จะแสดงค่าเริ่มต้นเก่าของผู้ให้บริการที่ถูกนำออก
• models status อาจแสดง marker(<value>) ในเอาต์พุตการตรวจสอบสิทธิ์สำหรับตัวยึดตำแหน่งที่ไม่ใช่ข้อมูลลับ (เช่น OPENAI_API_KEY, secretref-managed, minimax-oauth, oauth:chutes, ollama-local) แทนการปกปิดค่าเหล่านั้นเสมือนเป็นข้อมูลลับ

ตั้งค่าโมเดลเริ่มต้น/โมเดลรูปภาพ

openclaw models set <model-or-alias>openclaw models set-image <model-or-alias>

set เขียน agents.defaults.model.primary ส่วน set-image เขียน agents.defaults.imageModel.primary ทั้งสองรองรับ provider/model หรือนามแฝงที่กำหนดค่าไว้ set ยังซ่อมแซมการติดตั้ง Plugin รันไทม์ Codex/Copilot เมื่อโมเดลที่เพิ่งเลือกต้องใช้ Plugin ดังกล่าว แต่ set-image จะไม่ทำเช่นนั้น ทั้งสองคำสั่งไม่รองรับ --agent และจะเขียนค่าเริ่มต้นของเอเจนต์เสมอ

สแกน

models scan อ่านแคตตาล็อกสาธารณะ :free ของ OpenRouter และจัดอันดับตัวเลือกสำหรับใช้เป็นค่าทดแทน ตัวแคตตาล็อกเป็นข้อมูลสาธารณะ ดังนั้นการสแกนเฉพาะเมทาดาทาจึงไม่ต้องใช้คีย์ OpenRouter

โดยค่าเริ่มต้น OpenClaw จะพยายามตรวจสอบการรองรับเครื่องมือและรูปภาพด้วยการเรียกโมเดลจริง หากไม่มีการกำหนดค่าคีย์ OpenRouter คำสั่งจะเปลี่ยนไปใช้เอาต์พุตเฉพาะเมทาดาทาและอธิบายว่าโมเดล :free ยังคงต้องใช้ OPENROUTER_API_KEY สำหรับการตรวจสอบและการอนุมาน

ตัวเลือก:

• --no-probe (เฉพาะเมทาดาทา ไม่ค้นหาการกำหนดค่า/ข้อมูลลับ)
• --min-params <b>
• --max-age-days <days>
• --provider <name>
• --max-candidates <n>
• --timeout <ms> (ระยะหมดเวลาสำหรับคำขอแคตตาล็อกและต่อการตรวจสอบ)
• --concurrency <n>
• --yes
• --no-input
• --set-default
• --set-image
• --json

--set-default และ --set-image ต้องใช้การตรวจสอบแบบสด ผลการสแกนเฉพาะเมทาดาทามีไว้เพื่อให้ข้อมูลและจะไม่ถูกนำไปใช้กับการกำหนดค่า

นามแฝง

openclaw models aliases list [--json] [--plain]openclaw models aliases add <alias> <model-or-alias>openclaw models aliases remove <alias>

นามแฝงจะถูกจัดเก็บแยกตามรายการโมเดลเป็น agents.defaults.models.<key>.alias โดย add จะแก้ไข <model-or-alias> เป็นคีย์ผู้ให้บริการ/โมเดลมาตรฐานก่อน ดังนั้นการตั้งนามแฝงให้กับนามแฝงจะเปลี่ยนเป้าหมายของนามแฝงนั้นแทนการสร้างสายโซ่ การเพิ่มนามแฝงจะไม่เปลี่ยน agents.defaults.modelPolicy.allow หรือจำกัดการกำหนดทับโมเดล

ค่าทดแทน

openclaw models fallbacks list [--json] [--plain]openclaw models fallbacks add <model-or-alias>openclaw models fallbacks remove <model-or-alias>openclaw models fallbacks clear

จัดการ agents.defaults.model.fallbacks ส่วน openclaw models image-fallbacks list|add|remove|clear จะจัดการรายการ agents.defaults.imageModel.fallbacks แบบขนานโดยใช้รูปแบบคำสั่งย่อยเดียวกัน

โปรไฟล์การตรวจสอบสิทธิ์

openclaw models auth addopenclaw models auth list [--provider <id>] [--json]openclaw models auth login --provider <id>openclaw models auth login --provider openai --profile-id openai:workopenclaw models auth login-github-copilotopenclaw models auth paste-api-key --provider <id>openclaw models auth setup-token --provider <id>openclaw models auth paste-token --provider <id>openclaw models auth order get --provider <id>openclaw models auth order set --provider <id> <profileIds...>openclaw models auth order clear --provider <id>

models auth add คือตัวช่วยการยืนยันตัวตนแบบโต้ตอบ โดยสามารถเริ่มขั้นตอนการยืนยันตัวตนของผู้ให้บริการ (OAuth/คีย์ API) หรือแนะนำขั้นตอนการวางโทเค็นด้วยตนเอง ขึ้นอยู่กับผู้ให้บริการที่เลือก

models auth list แสดงรายการโปรไฟล์การยืนยันตัวตนที่บันทึกไว้สำหรับเอเจนต์ที่เลือก โดยไม่แสดงโทเค็น คีย์ API หรือข้อมูลลับ OAuth ใช้ --provider <id> เพื่อกรองให้เหลือผู้ให้บริการรายเดียว เช่น openai และใช้ --json สำหรับการเขียนสคริปต์

models auth login เรียกใช้ขั้นตอนการยืนยันตัวตนของ Plugin ผู้ให้บริการ (OAuth/คีย์ API) ใช้ openclaw plugins list เพื่อดูว่าติดตั้งผู้ให้บริการใดไว้บ้าง login รองรับ --profile-id <id> สำหรับผู้ให้บริการที่รองรับโปรไฟล์แบบมีชื่อระหว่างการเข้าสู่ระบบ (ใช้เพื่อแยกการเข้าสู่ระบบหลายรายการของผู้ให้บริการรายเดียวกัน), --method <id> เพื่อเลือกวิธีการยืนยันตัวตนที่เจาะจง, --device-code เป็นทางลัดสำหรับ --method device-code, --set-default เพื่อใช้โมเดลเริ่มต้นที่ผู้ให้บริการแนะนำ และ --force เพื่อลบโปรไฟล์ที่มีอยู่ของผู้ให้บริการรายนั้นก่อน (ใช้เมื่อโปรไฟล์ OAuth ที่แคชไว้ค้างอยู่หรือต้องการเปลี่ยนบัญชี)

models auth login-github-copilot เป็นทางลัดสำหรับ models auth login --provider github-copilot --method device (ขั้นตอนผ่านอุปกรณ์ GitHub) โดยรองรับ --yes เพื่อเขียนทับโปรไฟล์ที่มีอยู่โดยไม่ถามยืนยัน

ใช้ openclaw models auth --agent <id> <subcommand> เพื่อเขียนผลลัพธ์การยืนยันตัวตนไปยังที่เก็บของเอเจนต์ที่กำหนดค่าไว้โดยเฉพาะ แฟล็ก --agent ของคำสั่งแม่มีผลกับ add, list, login, paste-api-key, setup-token, paste-token, login-github-copilot และ order get/set/clear

สำหรับโมเดล OpenAI ค่าเริ่มต้นของ --provider openai คือการเข้าสู่ระบบด้วยบัญชี ChatGPT/Codex ใช้ --method api-key เฉพาะเมื่อต้องการเพิ่มโปรไฟล์คีย์ API ของ OpenAI ซึ่งโดยทั่วไปใช้เป็นข้อมูลสำรองเมื่อถึงขีดจำกัดการสมัครใช้งาน Codex เรียกใช้ openclaw doctor --fix เพื่อย้ายสถานะการยืนยันตัวตน/โปรไฟล์ที่ใช้คำนำหน้า OpenAI Codex แบบเดิมไปยัง openai

ตัวอย่าง:

openclaw models auth login --provider openai --set-defaultopenclaw models auth login --provider openai --method api-keyopenclaw models auth paste-api-key --provider openaiopenclaw models auth list --provider openai

หมายเหตุ:

• paste-api-key รองรับคีย์ API ที่สร้างจากที่อื่น โดยจะแจ้งให้ป้อนค่าคีย์และเขียนลงในรหัสโปรไฟล์เริ่มต้น <provider>:manual เว้นแต่จะระบุ --profile-id สำหรับระบบอัตโนมัติ ให้ส่งคีย์ผ่าน stdin ตัวอย่างเช่น printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai
• setup-token และ paste-token ยังคงเป็นคำสั่งโทเค็นทั่วไปสำหรับผู้ให้บริการที่มีวิธีการยืนยันตัวตนด้วยโทเค็น
• setup-token ต้องใช้ TTY แบบโต้ตอบและเรียกใช้วิธีการยืนยันตัวตนด้วยโทเค็นของผู้ให้บริการ (โดยใช้วิธี setup-token ของผู้ให้บริการรายนั้นเป็นค่าเริ่มต้น หากมีวิธีดังกล่าว)
• paste-token ต้องใช้ --provider โดยค่าเริ่มต้นจะแจ้งให้ป้อนค่าโทเค็นและเขียนลงในรหัสโปรไฟล์เริ่มต้น <provider>:manual เว้นแต่จะระบุ --profile-id สำหรับระบบอัตโนมัติ ให้ส่งโทเค็นผ่าน stdin แทนการส่งเป็นอาร์กิวเมนต์ เพื่อไม่ให้ข้อมูลประจำตัวของผู้ให้บริการปรากฏในประวัติเชลล์หรือรายการโพรเซส
• paste-token --expires-in <duration> จัดเก็บเวลาหมดอายุแบบสัมบูรณ์ของโทเค็นจากระยะเวลาสัมพัทธ์ เช่น 365d หรือ 12h
• สำหรับ openai คีย์ API ของ OpenAI และข้อมูลโทเค็น ChatGPT/OAuth เป็นรูปแบบการยืนยันตัวตนที่แตกต่างกัน ใช้ paste-api-key สำหรับคีย์ API ของ OpenAI แบบ sk-... และใช้ paste-token เฉพาะสำหรับข้อมูลการยืนยันตัวตนด้วยโทเค็น
• Anthropic: setup-token/paste-token เป็นเส้นทางการยืนยันตัวตนของ OpenClaw ที่รองรับสำหรับ anthropic แต่ OpenClaw แนะนำให้ใช้ Claude CLI (claude -p) บนโฮสต์ซ้ำเมื่อพร้อมใช้งาน
• auth order get/set/clear จัดการการกำหนดลำดับโปรไฟล์การยืนยันตัวตนแบบแทนที่สำหรับผู้ให้บริการรายหนึ่งต่อเอเจนต์ โดยจัดเก็บไว้ใน auth-state.json (แยกจากคีย์การกำหนดค่า auth.order.<provider>) set รับรหัสโปรไฟล์อย่างน้อยหนึ่งรายการตามลำดับความสำคัญ ส่วน clear จะย้อนกลับไปใช้ลำดับจากการกำหนดค่า/แบบวนรอบ

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

• ข้อมูลอ้างอิง CLI
• การเลือกโมเดล
• การสลับโมเดลเมื่อขัดข้อง