CLI mô hình

Tham chiếu mô hình chọn một nhà cung cấp và mô hình. Chúng thường không chọn runtime tác tử cấp thấp. Tham chiếu tác tử OpenAI là ngoại lệ chính: openai/gpt-5.5 chạy qua runtime máy chủ ứng dụng Codex theo mặc định trên nhà cung cấp OpenAI chính thức. Tham chiếu Copilot đăng ký (github-copilot/*) cũng có thể được chọn dùng Plugin runtime tác tử GitHub Copilot bên ngoài — đường dẫn đó luôn tường minh (không có dự phòng auto). Ghi đè runtime tường minh thuộc về chính sách nhà cung cấp/mô hình, không phải toàn bộ tác tử hoặc phiên. Ở chế độ runtime Codex, tham chiếu openai/gpt-* không hàm ý tính phí bằng khóa API; xác thực có thể đến từ tài khoản Codex hoặc hồ sơ OAuth openai. Xem Runtime tác tử và Runtime tác tử GitHub Copilot.

Cách chọn mô hình hoạt động

OpenClaw chọn mô hình theo thứ tự này:

Nguồn lựa chọn và hành vi dự phòng

Cùng một provider/model có thể mang ý nghĩa khác nhau tùy nơi nó đến từ:

• Mặc định đã cấu hình (agents.defaults.model.primary và mô hình chính riêng cho tác tử) là điểm bắt đầu thông thường và dùng agents.defaults.model.fallbacks.
• Lựa chọn dự phòng tự động là trạng thái khôi phục tạm thời. Chúng được lưu với modelOverrideSource: "auto" để các lượt sau có thể tiếp tục dùng chuỗi dự phòng mà không thăm dò mô hình chính đã biết lỗi mỗi lần; OpenClaw định kỳ thăm dò lại mô hình chính ban đầu, xóa lựa chọn tự động khi nó khôi phục, và thông báo các chuyển tiếp dự phòng/khôi phục một lần cho mỗi lần thay đổi trạng thái.
• Lựa chọn phiên người dùng là chính xác. /model, bộ chọn mô hình, session_status(model=...), và sessions.patch lưu modelOverrideSource: "user"; nếu nhà cung cấp/mô hình đã chọn đó không truy cập được, OpenClaw sẽ lỗi hiển thị rõ thay vì rơi tiếp sang mô hình đã cấu hình khác.
• Việc thay đổi agents.defaults.model.primary không ghi lại các lựa chọn phiên hiện có. Nếu trạng thái nói This session is pinned to X; config primary Y will apply to new/unpinned sessions., hãy xóa lựa chọn phiên hiện tại bằng /model default để nó kế thừa lại mô hình chính đã cấu hình.
• Cron --model / payload model là mô hình chính theo từng công việc. Nó vẫn dùng các dự phòng đã cấu hình trừ khi công việc cung cấp payload fallbacks tường minh (dùng fallbacks: [] cho một lần chạy cron nghiêm ngặt).
• Bộ chọn mô hình mặc định CLI và danh sách cho phép tôn trọng models.mode: "replace" bằng cách liệt kê models.providers.*.models tường minh thay vì tải toàn bộ danh mục tích hợp sẵn.
• Bộ chọn mô hình của Control UI hỏi Gateway về chế độ xem mô hình đã cấu hình: agents.defaults.models khi có, bao gồm các mục provider/* toàn nhà cung cấp, nếu không thì models.providers.*.models tường minh cộng với các nhà cung cấp có xác thực dùng được. Toàn bộ danh mục tích hợp sẵn được dành cho các chế độ xem duyệt tường minh như models.list với view: "all" hoặc openclaw models list --all.

Chính sách mô hình nhanh

• Đặt mô hình chính của bạn là mô hình thế hệ mới nhất mạnh nhất mà bạn có quyền dùng.
• Dùng dự phòng cho các tác vụ nhạy cảm về chi phí/độ trễ và trò chuyện ít rủi ro hơn.
• Với tác tử có công cụ hoặc đầu vào không đáng tin cậy, tránh các tầng mô hình cũ/yếu hơn.

Onboarding (khuyến nghị)

Nếu bạn không muốn sửa cấu hình thủ công, hãy chạy onboarding:

openclaw onboard

Nó có thể thiết lập mô hình + xác thực cho các nhà cung cấp phổ biến, bao gồm đăng ký OpenAI Code (Codex) (OAuth) và Anthropic (khóa API hoặc Claude CLI).

Khóa cấu hình (tổng quan)

• agents.defaults.model.primary và agents.defaults.model.fallbacks
• agents.defaults.imageModel.primary và agents.defaults.imageModel.fallbacks
• agents.defaults.pdfModel.primary và agents.defaults.pdfModel.fallbacks
• agents.defaults.imageGenerationModel.primary và agents.defaults.imageGenerationModel.fallbacks
• agents.defaults.videoGenerationModel.primary và agents.defaults.videoGenerationModel.fallbacks
• agents.defaults.models (danh sách cho phép + bí danh + tham số nhà cung cấp + mục nhà cung cấp động provider/*)
• models.providers (nhà cung cấp tùy chỉnh được ghi vào models.json)

Sửa danh sách cho phép an toàn

Dùng ghi bổ sung khi cập nhật thủ công agents.defaults.models:

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

"Mô hình không được phép" (và vì sao phản hồi dừng)

Nếu agents.defaults.models được đặt, nó trở thành danh sách cho phép cho /model và cho ghi đè phiên. Khi người dùng chọn một mô hình không nằm trong danh sách cho phép đó, OpenClaw trả về:

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

Khi lệnh bị từ chối bao gồm một ghi đè runtime như /model openai/gpt-5.5 --runtime codex, hãy sửa danh sách cho phép trước, rồi thử lại cùng lệnh /model ... --runtime .... Với thực thi Codex gốc, mô hình đã chọn vẫn là openai/gpt-5.5; runtime codex chọn harness và dùng xác thực Codex riêng.

Với mô hình cục bộ/GGUF, lưu tham chiếu đầy đủ có tiền tố nhà cung cấp trong danh sách cho phép, ví dụ ollama/gemma4:26b, lmstudio/Gemma4-26b-a4-it-gguf, hoặc provider/model chính xác được hiển thị bởi openclaw models list --provider <provider>. Chỉ tên tệp cục bộ hoặc tên hiển thị không đủ khi danh sách cho phép đang hoạt động.

Nếu bạn muốn giới hạn nhà cung cấp mà không liệt kê thủ công mọi mô hình, hãy thêm các mục provider/* vào agents.defaults.models:

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

Với chính sách đó, /model, /models, và các bộ chọn mô hình hiển thị danh mục đã khám phá chỉ cho các nhà cung cấp đó. Mô hình mới từ các nhà cung cấp đã chọn có thể xuất hiện mà không cần sửa danh sách cho phép. Có thể trộn các mục provider/model chính xác với các mục provider/* khi bạn cần một mô hình cụ thể từ nhà cung cấp khác.

Ví dụ cấu hình danh sách cho phép:

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

Chuyển mô hình trong chat (/model)

Bạn có thể chuyển mô hình cho phiên hiện tại mà không cần khởi động lại:

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

Hành vi/cấu hình lệnh đầy đủ: Lệnh gạch chéo.

Lệnh 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 (không có lệnh con) là lối tắt cho models status.

models list

Hiển thị mặc định các mô hình đã cấu hình/có sẵn xác thực. Các cờ hữu ích:

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9Ii0tcHJvdmlkZXIgPGlk " type="string"> Lọc theo ID nhà cung cấp, ví dụ moonshot. Nhãn hiển thị từ trình chọn tương tác không được chấp nhận.

models status

Hiển thị mô hình chính đã phân giải, các dự phòng, mô hình ảnh và tổng quan xác thực của các nhà cung cấp đã cấu hình. Nó cũng hiển thị trạng thái hết hạn OAuth cho các hồ sơ tìm thấy trong kho xác thực (mặc định cảnh báo trong vòng 24 giờ). --plain chỉ in mô hình chính đã phân giải.

Ví dụ (Claude CLI):

claude auth loginopenclaw models status

Quét (mô hình miễn phí OpenRouter)

openclaw models scan kiểm tra danh mục mô hình miễn phí của OpenRouter và có thể tùy chọn thăm dò các mô hình để hỗ trợ công cụ và hình ảnh.

Kết quả quét được xếp hạng theo:

1. Hỗ trợ hình ảnh
2. Độ trễ công cụ
3. Kích thước ngữ cảnh
4. Số lượng tham số

Đầu vào:

• Danh sách /models OpenRouter (bộ lọc :free)
• Thăm dò trực tiếp yêu cầu khóa API OpenRouter từ hồ sơ xác thực hoặc OPENROUTER_API_KEY (xem Biến môi trường)
• Bộ lọc tùy chọn: --max-age-days, --min-params, --provider, --max-candidates
• Điều khiển yêu cầu/thăm dò: --timeout, --concurrency

Khi thăm dò trực tiếp chạy trong TUI, bạn có thể chọn các dự phòng một cách tương tác. Ở chế độ không tương tác, truyền --yes để chấp nhận mặc định. Kết quả chỉ metadata mang tính thông tin; --set-default và --set-image yêu cầu thăm dò trực tiếp để OpenClaw không cấu hình một mô hình OpenRouter không có khóa và không sử dụng được.

Sổ đăng ký mô hình (models.json)

Các nhà cung cấp tùy chỉnh trong models.providers được ghi vào models.json trong thư mục agent (mặc định ~/.openclaw/agents/<agentId>/agent/models.json). Danh mục Plugin nhà cung cấp được lưu dưới dạng các mảnh danh mục đã tạo thuộc sở hữu Plugin trong trạng thái Plugin của agent và được tải tự động. Tệp này được hợp nhất theo mặc định trừ khi models.mode được đặt thành replace.

Liên quan

• Runtime agent — OpenClaw, Codex và các runtime vòng lặp agent khác
• Tham chiếu cấu hình — các khóa cấu hình mô hình
• Tạo hình ảnh — cấu hình mô hình hình ảnh
• Chuyển đổi dự phòng mô hình — chuỗi dự phòng
• Nhà cung cấp mô hình — định tuyến nhà cung cấp và xác thực
• Tạo nhạc — cấu hình mô hình nhạc
• Tạo video — cấu hình mô hình video