Models CLI

Xem /concepts/model-failover để hiểu về xoay vòng auth profile, cooldown, và cách chúng tương tác với fallback. Tổng quan nhanh về provider + ví dụ: /concepts/model-providers.

Cách chọn model hoạt động

OpenClaw chọn model theo thứ tự sau:

  1. Model Primary (agents.defaults.model.primary hoặc agents.defaults.model).
  2. Fallbacks trong agents.defaults.model.fallbacks (theo thứ tự).
  3. Provider auth failover xảy ra bên trong provider trước khi chuyển sang model tiếp theo.

Liên quan:

  • agents.defaults.models là allowlist/catalog các model mà OpenClaw có thể dùng (cộng thêm alias).
  • agents.defaults.imageModel chỉ được dùng khi model primary không nhận ảnh.
  • Mỗi agent có thể override agents.defaults.model qua agents.list[].model cộng với binding (xem /concepts/multi-agent).

Gợi ý chọn model nhanh (theo kinh nghiệm)

  • GLM: tốt hơn một chút cho coding/tool calling.
  • MiniMax: tốt hơn cho viết lách và cảm xúc.

Setup wizard (khuyên dùng)

Nếu các bạn không muốn chỉnh config thủ công, chạy wizard onboarding:

openclaw onboard

Nó có thể setup model + auth cho các provider phổ biến, bao gồm OpenAI Code (Codex) subscription (OAuth) và Anthropic (khuyên dùng API key; cũng hỗ trợ claude setup-token).

Config keys (tổng quan)

  • agents.defaults.model.primary và agents.defaults.model.fallbacks
  • agents.defaults.imageModel.primary và agents.defaults.imageModel.fallbacks
  • agents.defaults.models (allowlist + alias + tham số provider)
  • models.providers (custom provider được ghi vào models.json)

Model ref được chuẩn hóa thành chữ thường. Alias provider như z.ai/* được chuẩn hóa thành zai/*.

Ví dụ cấu hình provider (bao gồm OpenCode Zen) xem tại /gateway/configuration.

”Model is not allowed” (và tại sao reply bị dừng)

Nếu agents.defaults.models được set, nó sẽ trở thành allowlist cho /model và cho session override. Khi user chọn một model không có trong allowlist đó, OpenClaw sẽ trả về:

Model "provider/model" is not allowed. Use /model to list available models.

Điều này xảy ra trước khi reply bình thường được tạo, nên message có thể cảm giác như nó “không phản hồi”. Cách fix là:

  • Thêm model vào agents.defaults.models, hoặc
  • Xóa allowlist (bỏ agents.defaults.models), hoặc
  • Chọn model từ /model list.

Ví dụ config allowlist:

{
  agent: {
    model: { primary: "anthropic/claude-sonnet-4-5" },
    models: {
      "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
      "anthropic/claude-opus-4-5": { alias: "Opus" },
    },
  },
}

Đổi model trong chat (/model)

Các bạn có thể đổi model cho session hiện tại mà không cần restart:

/model
/model list
/model 3
/model openai/gpt-5.2
/model status

Lưu ý:

  • /model (và /model list) là picker dạng số, gọn gàng (model family + provider có sẵn).
  • /model <#> chọn từ picker đó.
  • /model status là view chi tiết (auth candidate và, khi được config, provider endpoint baseUrl + chế độ api).
  • Model ref được parse bằng cách tách ở dấu / đầu tiên. Dùng provider/model khi gõ /model <ref>.
  • Nếu model ID chứa / (kiểu OpenRouter), các bạn phải thêm prefix provider (ví dụ: /model openrouter/moonshotai/kimi-k2).
  • Nếu bỏ qua provider, OpenClaw coi input là alias hoặc model cho default provider (chỉ hoạt động khi không có / trong model ID).

Hành vi/config đầy đủ của lệnh: Slash commands.

Lệnh 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 (không có subcommand) là shortcut cho models status.

models list

Hiển thị các model đã config theo mặc định. Flag hữu ích:

  • --all: catalog đầy đủ
  • --local: chỉ local provider
  • --provider <name>: lọc theo provider
  • --plain: một model mỗi dòng
  • --json: output dạng machine-readable

models status

Hiển thị model primary đã resolve, fallback, image model, và tổng quan auth của các provider đã config. Nó cũng hiển thị trạng thái hết hạn OAuth cho các profile tìm thấy trong auth store (cảnh báo trong vòng 24h theo mặc định). --plain chỉ in model primary đã resolve.

Trạng thái OAuth luôn được hiển thị (và bao gồm trong output --json). Nếu một provider đã config không có credential, models status in phần Missing auth.

JSON bao gồm auth.oauth (cửa sổ cảnh báo + profile) và auth.providers (auth hiệu lực cho mỗi provider).

Dùng --check cho automation (exit 1 khi missing/expired, 2 khi sắp hết hạn).

Auth Anthropic được khuyên dùng là Claude Code CLI setup-token (chạy ở đâu cũng được; paste trên gateway host nếu cần):

claude setup-token
openclaw models status

Scanning (OpenRouter free models)

openclaw models scan kiểm tra catalog model miễn phí của OpenRouter và có thể probe model để kiểm tra hỗ trợ tool và image.

Flag chính:

  • --no-probe: bỏ qua live probe (chỉ metadata)
  • --min-params <b>: kích thước tham số tối thiểu (tỷ)
  • --max-age-days <days>: bỏ qua model cũ hơn
  • --provider <name>: lọc prefix provider
  • --max-candidates <n>: kích thước danh sách fallback
  • --set-default: set agents.defaults.model.primary thành lựa chọn đầu tiên
  • --set-image: set agents.defaults.imageModel.primary thành lựa chọn image đầu tiên

Probe yêu cầu OpenRouter API key (từ auth profile hoặc OPENROUTER_API_KEY). Không có key thì dùng --no-probe để chỉ liệt kê candidate.

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

  1. Hỗ trợ image
  2. Độ trễ tool
  3. Kích thước context
  4. Số lượng tham số

Input:

  • Danh sách /models của OpenRouter (lọc :free)
  • Yêu cầu OpenRouter API key từ auth profile hoặc OPENROUTER_API_KEY (xem /environment)
  • Filter tùy chọn: --max-age-days, --min-params, --provider, --max-candidates
  • Điều khiển probe: --timeout, --concurrency

Khi chạy trong TTY, các bạn có thể chọn fallback tương tác. Ở chế độ non-interactive, truyền --yes để chấp nhận mặc định.

Models registry (models.json)

Custom provider trong models.providers được ghi vào models.json trong thư mục agent (mặc định ~/.openclaw/agents/<agentId>/models.json). File này được merge theo mặc định trừ khi models.mode được set thành replace.