Chuyển đến nội dung chính

​
openclaw models

Khám phá, quét và cấu hình mô hình (mô hình mặc định, phương án dự phòng, hồ sơ xác thực). Liên quan:

​
Các lệnh thường dùng

Các lệnh con status và auth chấp nhận --agent <id> để nhắm đến một tác tử đã cấu hình; list, scan, aliases và fallbacks/image-fallbacks luôn sử dụng tác tử mặc định đã cấu hình, còn set/set-image từ chối hoàn toàn --agent. Khi bị bỏ qua, các lệnh nhận biết --agent sẽ sử dụng OPENCLAW_AGENT_DIR nếu được đặt, nếu không sẽ sử dụng tác tử mặc định đã cấu hình.

​
Trạng thái

openclaw models status hiển thị mô hình mặc định/phương án dự phòng đã phân giải cùng phần tổng quan xác thực. Đối với các runtime tác tử do Plugin sở hữu như Codex, lệnh này cũng kiểm tra xem Plugin sở hữu có được bật và đã vượt qua bước xác minh tải trọng khởi động hay không. Một tuyến có thông tin xác thực hợp lệ nhưng runtime không khả dụng sẽ báo cáo status: unavailable thay vì usable; đầu ra JSON bao gồm riêng authStatus, runtimeStatus và chẩn đoán runtime có giới hạn. Khi có ảnh chụp nhanh mức sử dụng của nhà cung cấp, phần trạng thái OAuth/khóa API sẽ bao gồm các cửa sổ sử dụng và ảnh chụp nhanh hạn ngạch của nhà cung cấp. Các nhà cung cấp cửa sổ sử dụng hiện tại: Anthropic, GitHub Copilot, Gemini CLI, OpenAI, MiniMax, Xiaomi và z.ai. Xác thực mức sử dụng đến từ các hook dành riêng cho nhà cung cấp khi có; nếu không, OpenClaw sẽ dự phòng bằng thông tin xác thực OAuth/khóa API phù hợp từ hồ sơ xác thực, môi trường hoặc cấu hình. Trong đầu ra --json, auth.providers là phần tổng quan nhà cung cấp có xét đến môi trường/cấu hình/kho lưu trữ, còn auth.oauth chỉ là tình trạng hồ sơ trong kho xác thực. Tùy chọn: Các hàng thăm dò có thể đến từ hồ sơ xác thực, thông tin xác thực môi trường hoặc models.json. Các nhóm trạng thái thăm dò: ok, auth, rate_limit, billing, timeout, format, unknown, no_model. Các mã chi tiết/lý do dự kiến khi một lần thăm dò không bao giờ đến được lệnh gọi mô hình:
  • excluded_by_auth_order: có hồ sơ được lưu trữ, nhưng auth.order.<provider> được chỉ định rõ ràng đã bỏ qua hồ sơ đó, vì vậy lần thăm dò báo cáo việc loại trừ thay vì thử hồ sơ.
  • missing_credential, invalid_expires, expired, unresolved_ref: hồ sơ hiện diện nhưng không đủ điều kiện hoặc không thể phân giải.
  • ineligible_profile: hồ sơ không tương thích với cấu hình nhà cung cấp vì một lý do khác.
  • no_model: có xác thực nhà cung cấp, nhưng OpenClaw không thể phân giải ứng viên mô hình có thể thăm dò cho nhà cung cấp đó.
Để khắc phục sự cố OAuth của OpenAI ChatGPT/Codex, openclaw models status, openclaw models auth list --provider openai và openclaw config get agents.defaults.model --json là cách nhanh nhất để xác nhận liệu một tác tử có hồ sơ OAuth openai khả dụng cho openai/* thông qua runtime Codex gốc hay không. Xem Thiết lập nhà cung cấp OpenAI.

​
Danh sách

openclaw models list là chỉ đọc: lệnh này đọc cấu hình, hồ sơ xác thực, trạng thái danh mục hiện có và các hàng danh mục do nhà cung cấp sở hữu, nhưng không bao giờ ghi lại models.json. Tùy chọn: --all (danh mục đầy đủ), --local (lọc chỉ các mô hình cục bộ), --provider <id>, --json, --plain. Ghi chú:
  • Cột Auth là chỉ đọc. Đối với các tuyến mô hình do nhà cung cấp sở hữu như OpenAI, cột này đối chiếu tuyến API/URL cơ sở của từng hàng với các hồ sơ đủ điều kiện trong auth.order hiệu dụng, thông tin xác thực môi trường/cấu hình và các SecretRef trong phạm vi lệnh đã phân giải. Một hàng OpenAI cụ thể vẫn ở trạng thái không xác định khi chính sách tuyến của nó không khả dụng, thay vì mượn xác thực cấp nhà cung cấp; các phép kiểm tra cũ chỉ ở cấp nhà cung cấp và các nhà cung cấp khác vẫn giữ hành vi cấp nhà cung cấp. Siêu dữ liệu xác thực tổng hợp của Plugin chỉ là gợi ý về khả năng runtime, không phải bằng chứng xác thực tài khoản gốc, vì vậy các tuyến phụ thuộc vào tài khoản vẫn ở trạng thái không xác định nếu không có bằng chứng tích cực từ sổ đăng ký. Lệnh này không tải runtime của nhà cung cấp, đọc bí mật trong chuỗi khóa, gọi API của nhà cung cấp hoặc chứng minh mức độ sẵn sàng thực thi chính xác.
  • models list --all --provider <id> có thể bao gồm các hàng danh mục tĩnh do nhà cung cấp sở hữu từ manifest Plugin hoặc siêu dữ liệu danh mục nhà cung cấp đi kèm, ngay cả khi bạn chưa xác thực với nhà cung cấp đó. Các hàng đó vẫn hiển thị là không khả dụng cho đến khi xác thực phù hợp được cấu hình.
  • models list duy trì khả năng phản hồi của mặt phẳng điều khiển khi việc khám phá danh mục nhà cung cấp bị chậm. Các chế độ xem mặc định và đã cấu hình sẽ chuyển sang các hàng mô hình đã cấu hình hoặc tổng hợp sau một khoảng chờ ngắn, đồng thời để quá trình khám phá hoàn tất trong nền. Sử dụng --all khi bạn cần danh mục đầy đủ đã khám phá một cách chính xác và sẵn sàng chờ quá trình khám phá nhà cung cấp.
  • models list --all phạm vi rộng hợp nhất các hàng danh mục manifest lên trên các hàng sổ đăng ký mà không tải các hook bổ sung runtime của nhà cung cấp. Các đường dẫn nhanh của manifest được lọc theo nhà cung cấp chỉ sử dụng những nhà cung cấp được đánh dấu static; những nhà cung cấp được đánh dấu refreshable tiếp tục dựa trên sổ đăng ký/bộ nhớ đệm và nối thêm các hàng manifest dưới dạng bổ sung, còn những nhà cung cấp được đánh dấu runtime tiếp tục sử dụng khám phá qua sổ đăng ký/runtime.
  • models list giữ riêng biệt siêu dữ liệu mô hình gốc và các giới hạn runtime. Trong đầu ra bảng, Ctx hiển thị contextTokens/contextWindow khi giới hạn runtime hiệu dụng khác với cửa sổ ngữ cảnh gốc; các hàng JSON bao gồm contextTokens khi nhà cung cấp công khai giới hạn đó.
  • Đối với các tuyến do nhà cung cấp sở hữu, models list chiếu một hàng nhà cung cấp/mô hình logic lên tuyến đã chọn. Input và Ctx chỉ đến từ một hàng danh mục tuyến vật lý khớp chính xác, với các giá trị ghi đè logic được cấu hình rõ ràng được áp dụng sau cùng; lựa chọn tuyến chưa được phân giải hiển thị các trường khả năng không xác định thay vì mượn siêu dữ liệu của tuyến cùng cấp.
  • models list --provider <id> lọc theo ID nhà cung cấp, chẳng hạn như moonshot hoặc openai. Tùy chọn này không chấp nhận các nhãn hiển thị từ trình chọn nhà cung cấp tương tác, chẳng hạn như Moonshot AI.
  • Tham chiếu mô hình được phân tích bằng cách tách tại / đầu tiên. Nếu ID mô hình chứa / (kiểu OpenRouter), hãy bao gồm tiền tố nhà cung cấp (ví dụ: openrouter/moonshotai/kimi-k2).
  • Nếu bạn bỏ qua nhà cung cấp, trước tiên OpenClaw phân giải đầu vào dưới dạng bí danh, sau đó dưới dạng kết quả khớp nhà cung cấp đã cấu hình duy nhất cho đúng ID mô hình đó, và chỉ khi đó mới chuyển sang nhà cung cấp mặc định đã cấu hình kèm cảnh báo ngừng hỗ trợ. Nếu nhà cung cấp đó không còn công khai mô hình mặc định đã cấu hình, OpenClaw sẽ chuyển sang nhà cung cấp/mô hình được cấu hình đầu tiên thay vì hiển thị một mặc định nhà cung cấp đã bị xóa và lỗi thời.
  • models status có thể hiển thị marker(<value>) trong đầu ra xác thực cho các phần giữ chỗ không phải bí mật (ví dụ: OPENAI_API_KEY, secretref-managed, minimax-oauth, oauth:chutes, ollama-local) thay vì che chúng như bí mật.

​
Đặt mô hình mặc định / mô hình hình ảnh

set ghi agents.defaults.model.primary; set-image ghi agents.defaults.imageModel.primary. Cả hai đều chấp nhận provider/model hoặc một bí danh đã cấu hình. set cũng sửa chữa các bản cài đặt Plugin runtime Codex/Copilot khi mô hình mới được chọn cần đến chúng; set-image thì không. Cả hai lệnh đều không chấp nhận --agent; chúng luôn ghi các giá trị mặc định của tác tử.

​
Quét

models scan đọc danh mục :free công khai của OpenRouter và xếp hạng các ứng viên để sử dụng làm phương án dự phòng. Bản thân danh mục này là công khai, vì vậy các lần quét chỉ siêu dữ liệu không cần khóa OpenRouter. Theo mặc định, OpenClaw cố gắng thăm dò khả năng hỗ trợ công cụ và hình ảnh bằng các lệnh gọi mô hình trực tiếp. Nếu không có khóa OpenRouter được cấu hình, lệnh sẽ chuyển sang đầu ra chỉ siêu dữ liệu và giải thích rằng các mô hình :free vẫn yêu cầu OPENROUTER_API_KEY để thăm dò và suy luận. Tùy chọn:
  • --no-probe (chỉ siêu dữ liệu; không tra cứu cấu hình/bí mật)
  • --min-params <b>
  • --max-age-days <days>
  • --provider <name>
  • --max-candidates <n>
  • --timeout <ms> (thời gian chờ cho yêu cầu danh mục và từng lần thăm dò)
  • --concurrency <n>
  • --yes
  • --no-input
  • --set-default
  • --set-image
  • --json
--set-default và --set-image yêu cầu thăm dò trực tiếp; kết quả quét chỉ siêu dữ liệu chỉ mang tính cung cấp thông tin và không được áp dụng vào cấu hình.

​
Bí danh

Bí danh được lưu trữ theo từng mục mô hình dưới dạng agents.defaults.models.<key>.alias. add trước tiên phân giải <model-or-alias> thành khóa nhà cung cấp/mô hình chuẩn, vì vậy việc đặt bí danh cho một bí danh sẽ trỏ lại bí danh đó thay vì tạo chuỗi. Việc thêm bí danh không thay đổi agents.defaults.modelPolicy.allow hoặc hạn chế các giá trị ghi đè mô hình.

​
Phương án dự phòng

Quản lý agents.defaults.model.fallbacks. openclaw models image-fallbacks list|add|remove|clear quản lý danh sách agents.defaults.imageModel.fallbacks song song với cùng cấu trúc lệnh con.

​
Hồ sơ xác thực

models auth add là trình hỗ trợ xác thực tương tác. Tùy thuộc vào nhà cung cấp bạn chọn, trình này có thể khởi chạy luồng xác thực của nhà cung cấp (OAuth/khóa API) hoặc hướng dẫn bạn dán token theo cách thủ công. models auth list liệt kê các hồ sơ xác thực đã lưu cho agent được chọn mà không in ra token, khóa API hoặc dữ liệu bí mật OAuth. Sử dụng --provider <id> để lọc theo một nhà cung cấp, chẳng hạn như openai, và --json để dùng trong tập lệnh. models auth login chạy luồng xác thực của Plugin nhà cung cấp (OAuth/khóa API). Sử dụng openclaw plugins list để xem những nhà cung cấp nào đã được cài đặt. login chấp nhận --profile-id <id> đối với các nhà cung cấp hỗ trợ hồ sơ có tên trong khi đăng nhập (sử dụng tùy chọn này để tách biệt nhiều lần đăng nhập cho cùng một nhà cung cấp), --method <id> để chọn một phương thức xác thực cụ thể, --device-code làm lối tắt cho --method device-code, --set-default để áp dụng mô hình mặc định do nhà cung cấp đề xuất, và --force để xóa các hồ sơ hiện có của nhà cung cấp đó trước tiên (sử dụng khi hồ sơ OAuth trong bộ nhớ đệm bị kẹt hoặc khi bạn muốn chuyển đổi tài khoản). models auth login-github-copilot là lối tắt cho models auth login --provider github-copilot --method device (luồng thiết bị GitHub); lệnh này chấp nhận --yes để ghi đè lên hồ sơ hiện có mà không cần nhắc xác nhận. Sử dụng openclaw models auth --agent <id> <subcommand> để ghi kết quả xác thực vào kho lưu trữ của một agent đã cấu hình cụ thể. Cờ --agent cấp cha được add, list, login, paste-api-key, setup-token, paste-token, login-github-copilot, và order get/set/clear tuân theo. Đối với các mô hình OpenAI, --provider openai mặc định sử dụng đăng nhập tài khoản ChatGPT/Codex. Chỉ sử dụng --method api-key khi bạn muốn thêm hồ sơ khóa API OpenAI, thường để dự phòng cho các giới hạn của gói đăng ký Codex. Chạy openclaw doctor --fix để di chuyển trạng thái xác thực/hồ sơ dùng tiền tố OpenAI Codex cũ sang openai. Ví dụ:
Lưu ý:
  • paste-api-key chấp nhận các khóa API được tạo ở nơi khác, nhắc nhập giá trị khóa và ghi khóa đó vào mã định danh hồ sơ mặc định <provider>:manual, trừ khi bạn truyền --profile-id. Trong quy trình tự động hóa, hãy chuyển khóa qua stdin, ví dụ printf "%s\n" "$OPENAI_API_KEY" | openclaw models auth paste-api-key --provider openai.
  • setup-token và paste-token vẫn là các lệnh token chung dành cho những nhà cung cấp cung cấp phương thức xác thực bằng token.
  • setup-token yêu cầu TTY tương tác và chạy phương thức xác thực bằng token của nhà cung cấp (mặc định sử dụng phương thức setup-token của nhà cung cấp đó nếu có).
  • paste-token yêu cầu --provider, mặc định nhắc nhập giá trị token và ghi token đó vào mã định danh hồ sơ mặc định <provider>:manual, trừ khi bạn truyền --profile-id. Trong quy trình tự động hóa, hãy chuyển token qua stdin thay vì truyền dưới dạng đối số để thông tin xác thực của nhà cung cấp không xuất hiện trong lịch sử shell hoặc danh sách tiến trình.
  • paste-token --expires-in <duration> lưu thời điểm hết hạn tuyệt đối của token từ một khoảng thời gian tương đối như 365d hoặc 12h.
  • Đối với openai, khóa API OpenAI và dữ liệu token ChatGPT/OAuth là các dạng xác thực khác nhau. Sử dụng paste-api-key cho khóa API OpenAI sk-... và chỉ sử dụng paste-token cho dữ liệu xác thực bằng token.
  • Anthropic: setup-token/paste-token là các đường dẫn xác thực OpenClaw được hỗ trợ cho anthropic, nhưng OpenClaw ưu tiên tái sử dụng Claude CLI (claude -p) trên máy chủ khi có sẵn.
  • auth order get/set/clear quản lý phần ghi đè thứ tự hồ sơ xác thực theo từng agent cho một nhà cung cấp, được lưu trong auth-state.json (tách biệt với khóa cấu hình auth.order.<provider>). set nhận một hoặc nhiều mã định danh hồ sơ theo thứ tự ưu tiên; clear quay về sử dụng thứ tự cấu hình/luân phiên.

​
Liên quan