Câu hỏi thường gặp: mô hình và xác thực

Mô hình mặc định của OpenClaw là bất kỳ mô hình nào bạn đặt tại:

agents.defaults.model.primary

Mô hình được tham chiếu dưới dạng provider/model (ví dụ: openai/gpt-5.5 hoặc anthropic/claude-sonnet-4-6). Nếu bạn bỏ qua nhà cung cấp, OpenClaw trước tiên sẽ thử một bí danh, sau đó là một kết quả khớp nhà cung cấp đã cấu hình duy nhất cho đúng id mô hình đó, rồi chỉ sau đó mới quay về nhà cung cấp mặc định đã cấu hình như một đường dẫn tương thích đã lỗi thời. Nếu nhà cung cấp đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw sẽ quay về nhà cung cấp/mô hình đã cấu hình đầu tiên thay vì hiển thị một mặc định nhà cung cấp đã bị gỡ bỏ và lỗi thời. Bạn vẫn nên đặt provider/model một cách tường minh.

Mặc định được khuyến nghị: dùng mô hình thế hệ mới nhất mạnh nhất có trong ngăn xếp nhà cung cấp của bạn. Với tác tử có bật công cụ hoặc nhận đầu vào không đáng tin cậy: ưu tiên sức mạnh mô hình hơn chi phí. Với trò chuyện thường nhật/rủi ro thấp: dùng các mô hình dự phòng rẻ hơn và định tuyến theo vai trò tác tử.

MiniMax có tài liệu riêng: MiniMax và Mô hình cục bộ.

Nguyên tắc chung: dùng mô hình tốt nhất bạn có thể chi trả cho công việc rủi ro cao, và một mô hình rẻ hơn cho trò chuyện thường nhật hoặc tóm tắt. Bạn có thể định tuyến mô hình theo từng tác tử và dùng tác tử con để song song hóa các tác vụ dài (mỗi tác tử con tiêu thụ token). Xem Mô hình và Tác tử con.

Cảnh báo mạnh: các mô hình yếu hơn/quá lượng tử hóa dễ bị prompt injection và hành vi không an toàn hơn. Xem Bảo mật.

Thêm ngữ cảnh: Mô hình.

Dùng lệnh mô hình hoặc chỉ sửa các trường model. Tránh thay thế toàn bộ cấu hình.

Các lựa chọn an toàn:

• /model trong trò chuyện (nhanh, theo từng phiên)
• openclaw models set ... (chỉ cập nhật cấu hình mô hình)
• openclaw configure --section model (tương tác)
• sửa agents.defaults.model trong ~/.openclaw/openclaw.json

Tránh dùng config.apply với một đối tượng một phần trừ khi bạn có ý định thay thế toàn bộ cấu hình. Với chỉnh sửa RPC, trước tiên hãy kiểm tra bằng config.schema.lookup và ưu tiên config.patch. Payload tra cứu cung cấp cho bạn đường dẫn đã chuẩn hóa, tài liệu/ràng buộc schema nông và tóm tắt con trực tiếp. cho các cập nhật một phần. Nếu bạn đã ghi đè cấu hình, hãy khôi phục từ bản sao lưu hoặc chạy lại openclaw doctor để sửa chữa.

Tài liệu: Mô hình, Cấu hình, Cấu hình, Doctor.

Có. Ollama là đường dẫn dễ nhất cho mô hình cục bộ.

Thiết lập nhanh nhất:

1. Cài đặt Ollama từ https://ollama.com/download
2. Kéo một mô hình cục bộ như ollama pull gemma4
3. Nếu bạn cũng muốn dùng mô hình đám mây, chạy ollama signin
4. Chạy openclaw onboard và chọn Ollama
5. Chọn Local hoặc Cloud + Local

Ghi chú:

• Cloud + Local cung cấp cho bạn mô hình đám mây cùng với các mô hình Ollama cục bộ
• các mô hình đám mây như kimi-k2.5:cloud không cần kéo cục bộ
• để chuyển đổi thủ công, dùng openclaw models list và openclaw models set ollama/<model>

Ghi chú bảo mật: các mô hình nhỏ hơn hoặc bị lượng tử hóa mạnh dễ bị prompt injection hơn. Chúng tôi đặc biệt khuyến nghị mô hình lớn cho bất kỳ bot nào có thể dùng công cụ. Nếu bạn vẫn muốn dùng mô hình nhỏ, hãy bật sandboxing và danh sách cho phép công cụ nghiêm ngặt.

Tài liệu: Ollama, Mô hình cục bộ, Nhà cung cấp mô hình, Bảo mật, Sandboxing.

• Các triển khai này có thể khác nhau và có thể thay đổi theo thời gian; không có khuyến nghị nhà cung cấp cố định.
• Kiểm tra cài đặt runtime hiện tại trên từng gateway bằng openclaw models status.
• Với các tác tử nhạy cảm về bảo mật/có bật công cụ, hãy dùng mô hình thế hệ mới nhất mạnh nhất có sẵn.

Dùng lệnh /model như một tin nhắn độc lập:

/model sonnet
/model opus
/model gpt
/model gpt-mini
/model gemini
/model gemini-flash
/model gemini-flash-lite

Đây là các bí danh tích hợp. Có thể thêm bí danh tùy chỉnh qua agents.defaults.models.

Bạn có thể liệt kê các mô hình có sẵn bằng /model, /model list hoặc /model status.

/model (và /model list) hiển thị một bộ chọn nhỏ gọn, có đánh số. Chọn theo số:

/model 3

Bạn cũng có thể ép dùng một hồ sơ xác thực cụ thể cho nhà cung cấp (theo từng phiên):

/model opus@anthropic:default
/model opus@anthropic:work

Mẹo: /model status hiển thị tác tử nào đang hoạt động, tệp auth-profiles.json nào đang được dùng và hồ sơ xác thực nào sẽ được thử tiếp theo. Nó cũng hiển thị endpoint nhà cung cấp đã cấu hình (baseUrl) và chế độ API (api) khi có sẵn.

Làm sao để bỏ ghim một hồ sơ tôi đã đặt bằng @profile?

Chạy lại /model không có hậu tố @profile:

/model anthropic/claude-opus-4-6

Nếu bạn muốn quay về mặc định, hãy chọn nó từ /model (hoặc gửi /model <default provider/model>). Dùng /model status để xác nhận hồ sơ xác thực nào đang hoạt động.

Có. Hãy xem lựa chọn mô hình và lựa chọn runtime là hai việc riêng biệt:

• Tác tử lập trình Codex gốc: đặt agents.defaults.model.primary thành openai/gpt-5.5. Đăng nhập bằng openclaw models auth login --provider openai-codex khi bạn muốn dùng xác thực gói đăng ký ChatGPT/Codex.
• Tác vụ OpenAI API trực tiếp bên ngoài vòng lặp tác tử: cấu hình OPENAI_API_KEY cho hình ảnh, embedding, giọng nói, realtime và các bề mặt OpenAI API không thuộc tác tử khác.
• Xác thực khóa API tác tử OpenAI: dùng /model openai/gpt-5.5 với hồ sơ khóa API openai-codex có thứ tự.
• Tác tử con: định tuyến tác vụ lập trình đến một tác tử chỉ dùng Codex với mô hình riêng và mặc định agentRuntime.

Xem Mô hình và Lệnh slash.

Dùng công tắc theo phiên hoặc mặc định cấu hình:

• Theo từng phiên: gửi /fast on khi phiên đang dùng openai/gpt-5.5.
• Mặc định theo mô hình: đặt agents.defaults.models["openai/gpt-5.5"].params.fastMode thành true.

Ví dụ:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

Với OpenAI, chế độ nhanh ánh xạ tới service_tier = "priority" trên các yêu cầu Responses gốc được hỗ trợ. Ghi đè /fast của phiên sẽ thắng mặc định cấu hình.

Xem Thinking và chế độ nhanh và Chế độ nhanh OpenAI.

Nếu agents.defaults.models được đặt, nó sẽ trở thành danh sách cho phép cho /model và mọi ghi đè phiên. Chọn một mô hình không nằm trong danh sách đó sẽ 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

Lỗi đó được trả về thay vì một phản hồi bình thường. Cách sửa: thêm mô hình vào agents.defaults.models, gỡ danh sách cho phép, hoặc chọn một mô hình từ /model list. Nếu lệnh cũng bao gồm --runtime codex, trước tiên hãy thêm mô hình rồi thử lại cùng lệnh /model provider/model --runtime codex.

Điều này nghĩa là nhà cung cấp chưa được cấu hình (không tìm thấy cấu hình nhà cung cấp MiniMax hoặc hồ sơ xác thực), nên không thể phân giải mô hình.

Danh sách kiểm tra cách sửa:

1. Nâng cấp lên bản phát hành OpenClaw hiện tại (hoặc chạy từ nguồn main), rồi khởi động lại gateway.

2. Đảm bảo MiniMax đã được cấu hình (trình hướng dẫn hoặc JSON), hoặc xác thực MiniMax tồn tại trong env/hồ sơ xác thực để nhà cung cấp khớp có thể được chèn vào (MINIMAX_API_KEY cho minimax, MINIMAX_OAUTH_TOKEN hoặc OAuth MiniMax đã lưu cho minimax-portal).

3. Dùng đúng id mô hình (phân biệt chữ hoa chữ thường) cho đường dẫn xác thực của bạn: minimax/MiniMax-M2.7 hoặc minimax/MiniMax-M2.7-highspeed cho thiết lập khóa API, hoặc minimax-portal/MiniMax-M2.7 / minimax-portal/MiniMax-M2.7-highspeed cho thiết lập OAuth.

4. Chạy:

   openclaw models list
   

   và chọn từ danh sách (hoặc /model list trong trò chuyện).

Xem MiniMax và Mô hình.

Có. Dùng MiniMax làm mặc định và chuyển mô hình theo từng phiên khi cần. Dự phòng là cho lỗi, không phải "tác vụ khó", nên hãy dùng /model hoặc một tác tử riêng.

Tùy chọn A: chuyển theo từng phiên

{
  env: { MINIMAX_API_KEY: "sk-...", OPENAI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "minimax" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
    },
  },
}

Sau đó:

/model gpt

Tùy chọn B: tác tử riêng

• Tác tử A mặc định: MiniMax
• Tác tử B mặc định: OpenAI
• Định tuyến theo tác tử hoặc dùng /agent để chuyển

Tài liệu: Mô hình, Định tuyến đa tác tử, MiniMax, OpenAI.

Có. OpenClaw đi kèm một vài cách viết tắt mặc định (chỉ áp dụng khi mô hình tồn tại trong agents.defaults.models):

• opus → anthropic/claude-opus-4-6
• sonnet → anthropic/claude-sonnet-4-6
• gpt → openai/gpt-5.5
• gpt-mini → openai/gpt-5.4-mini
• gpt-nano → openai/gpt-5.4-nano
• gemini → google/gemini-3.1-pro-preview
• gemini-flash → google/gemini-3-flash-preview
• gemini-flash-lite → google/gemini-3.1-flash-lite-preview

Nếu bạn đặt bí danh riêng với cùng tên, giá trị của bạn sẽ thắng.

Bí danh đến từ agents.defaults.models.<modelId>.alias. Ví dụ:

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

Sau đó /model sonnet (hoặc /<alias> khi được hỗ trợ) phân giải thành ID mô hình đó.

OpenRouter (trả tiền theo token; nhiều mô hình):

{
  agents: {
    defaults: {
      model: { primary: "openrouter/anthropic/claude-sonnet-4-6" },
      models: { "openrouter/anthropic/claude-sonnet-4-6": {} },
    },
  },
  env: { OPENROUTER_API_KEY: "sk-or-..." },
}

Z.AI (mô hình GLM):

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-5" },
      models: { "zai/glm-5": {} },
    },
  },
  env: { ZAI_API_KEY: "..." },
}

Nếu bạn tham chiếu một provider/model nhưng thiếu khóa provider bắt buộc, bạn sẽ gặp lỗi xác thực lúc chạy (ví dụ: No API key found for provider "zai").

Không tìm thấy khóa API cho provider sau khi thêm agent mới

Điều này thường có nghĩa là agent mới có kho xác thực trống. Xác thực áp dụng theo từng agent và được lưu trong:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Các cách khắc phục:

• Chạy openclaw agents add <id> và cấu hình xác thực trong trình hướng dẫn.
• Hoặc chỉ sao chép các hồ sơ api_key / token tĩnh có thể di chuyển từ kho xác thực của agent chính sang kho xác thực của agent mới.
• Với hồ sơ OAuth, hãy đăng nhập từ agent mới khi agent đó cần tài khoản riêng; nếu không, OpenClaw có thể đọc qua agent mặc định/chính mà không cần sao chép refresh token.

Không dùng lại agentDir giữa các agent; việc đó gây xung đột xác thực/phiên.

Chuyển đổi dự phòng diễn ra qua hai giai đoạn:

1. Luân phiên hồ sơ xác thực trong cùng một provider.
2. Dự phòng model sang model tiếp theo trong agents.defaults.model.fallbacks.

Cooldown áp dụng cho các hồ sơ bị lỗi (backoff lũy thừa), vì vậy OpenClaw có thể tiếp tục phản hồi ngay cả khi một provider bị giới hạn tốc độ hoặc tạm thời gặp lỗi.

Nhóm giới hạn tốc độ bao gồm nhiều hơn các phản hồi 429 đơn thuần. OpenClaw cũng xem các thông báo như Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded, resource exhausted, và các giới hạn cửa sổ sử dụng định kỳ (weekly/monthly limit reached) là các giới hạn tốc độ đủ điều kiện để chuyển đổi dự phòng.

Một số phản hồi trông giống lỗi thanh toán không phải là 402, và một số phản hồi HTTP 402 cũng vẫn nằm trong nhóm tạm thời đó. Nếu một provider trả về nội dung thanh toán rõ ràng trên 401 hoặc 403, OpenClaw vẫn có thể giữ nội dung đó trong luồng thanh toán, nhưng các bộ khớp văn bản riêng theo provider vẫn chỉ giới hạn trong provider sở hữu chúng (ví dụ OpenRouter Key limit exceeded). Nếu một thông báo 402 thay vào đó trông giống giới hạn cửa sổ sử dụng có thể thử lại hoặc giới hạn chi tiêu của tổ chức/không gian làm việc (daily limit reached, resets tomorrow, organization spending limit exceeded), OpenClaw xử lý nó là rate_limit, không phải vô hiệu hóa thanh toán dài hạn.

Lỗi tràn ngữ cảnh thì khác: các dấu hiệu như request_too_large, input exceeds the maximum number of tokens, input token count exceeds the maximum number of input tokens, input is too long for the model, hoặc ollama error: context length exceeded vẫn đi theo đường Compaction/thử lại thay vì chuyển sang dự phòng model.

Văn bản lỗi máy chủ chung được cố ý thu hẹp hơn so với "bất cứ thứ gì có unknown/error trong đó". OpenClaw có xử lý các dạng tạm thời theo phạm vi provider như Anthropic trần An unknown error occurred, OpenRouter trần Provider returned error, lỗi lý do dừng như Unhandled stop reason: error, payload JSON api_error có văn bản máy chủ tạm thời (internal server error, unknown error, 520, upstream error, backend error), và lỗi provider đang bận như ModelNotReadyException là tín hiệu timeout/quá tải đủ điều kiện chuyển đổi dự phòng khi ngữ cảnh provider khớp. Văn bản dự phòng nội bộ chung như LLM request failed with an unknown error. vẫn được xử lý thận trọng và tự nó không kích hoạt dự phòng model.

Điều đó nghĩa là hệ thống đã cố dùng ID hồ sơ xác thực anthropic:default, nhưng không tìm thấy thông tin xác thực cho hồ sơ đó trong kho xác thực dự kiến.

Danh sách kiểm tra khắc phục:

• Xác nhận nơi lưu hồ sơ xác thực (đường dẫn mới so với đường dẫn cũ)
  • Hiện tại: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Cũ: ~/.openclaw/agent/* (được di trú bởi openclaw doctor)
• Xác nhận biến môi trường của bạn được Gateway nạp
  • Nếu bạn đặt ANTHROPIC_API_KEY trong shell nhưng chạy Gateway qua systemd/launchd, Gateway có thể không kế thừa biến đó. Đặt biến trong ~/.openclaw/.env hoặc bật env.shellEnv.
• Đảm bảo bạn đang chỉnh đúng agent
  • Thiết lập nhiều agent nghĩa là có thể có nhiều tệp auth-profiles.json.
• Kiểm tra nhanh trạng thái model/xác thực
  • Dùng openclaw models status để xem các model đã cấu hình và liệu các provider đã được xác thực hay chưa.

Danh sách kiểm tra khắc phục cho "Không tìm thấy thông tin xác thực cho hồ sơ anthropic"

Điều này nghĩa là lần chạy được ghim vào một hồ sơ xác thực Anthropic, nhưng Gateway không tìm thấy hồ sơ đó trong kho xác thực của nó.

• Dùng Claude CLI

  • Chạy openclaw models auth login --provider anthropic --method cli --set-default trên máy chủ gateway.

• Nếu bạn muốn dùng khóa API thay thế

  • Đặt ANTHROPIC_API_KEY trong ~/.openclaw/.env trên máy chủ gateway.

  • Xóa mọi thứ tự đã ghim buộc dùng một hồ sơ bị thiếu:

    openclaw models auth order clear --provider anthropic
    

• Xác nhận bạn đang chạy lệnh trên máy chủ gateway

  • Ở chế độ từ xa, hồ sơ xác thực nằm trên máy gateway, không phải laptop của bạn.

Nếu cấu hình model của bạn bao gồm Google Gemini làm dự phòng (hoặc bạn đã chuyển sang một dạng viết tắt Gemini), OpenClaw sẽ thử nó trong quá trình dự phòng model. Nếu bạn chưa cấu hình thông tin xác thực Google, bạn sẽ thấy No API key found for provider "google".

Cách khắc phục: cung cấp xác thực Google, hoặc xóa/tránh các model Google trong agents.defaults.model.fallbacks / alias để dự phòng không định tuyến tới đó.

Yêu cầu LLM bị từ chối: cần chữ ký thinking (Google Antigravity)

Nguyên nhân: lịch sử phiên chứa các khối thinking không có chữ ký (thường từ một stream bị hủy/dở dang). Google Antigravity yêu cầu chữ ký cho các khối thinking.

Cách khắc phục: OpenClaw hiện loại bỏ các khối thinking chưa ký cho Google Antigravity Claude. Nếu lỗi vẫn xuất hiện, hãy bắt đầu một phiên mới hoặc đặt /thinking off cho agent đó.

Hồ sơ xác thực là một bản ghi thông tin xác thực có tên (OAuth hoặc khóa API) gắn với một provider. Hồ sơ nằm trong:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Để kiểm tra hồ sơ đã lưu mà không xuất bí mật, hãy chạy openclaw models auth list (tùy chọn --provider <id> hoặc --json). Xem CLI model để biết chi tiết.

OpenClaw dùng các ID có tiền tố provider như:

• anthropic:default (phổ biến khi không có danh tính email)
• anthropic:<email> cho danh tính OAuth
• ID tùy chỉnh do bạn chọn (ví dụ: anthropic:work)

Có. Cấu hình hỗ trợ metadata tùy chọn cho hồ sơ và thứ tự theo từng provider (auth.order.<provider>). Việc này không lưu bí mật; nó ánh xạ ID tới provider/chế độ và đặt thứ tự luân phiên.

OpenClaw có thể tạm thời bỏ qua một hồ sơ nếu hồ sơ đó đang trong cooldown ngắn (giới hạn tốc độ/timeout/lỗi xác thực) hoặc trạng thái disabled dài hơn (thanh toán/không đủ tín dụng). Để kiểm tra điều này, hãy chạy openclaw models status --json và kiểm tra auth.unusableProfiles. Tinh chỉnh: auth.cooldowns.billingBackoffHours*.

Cooldown giới hạn tốc độ có thể theo phạm vi model. Một hồ sơ đang cooldown cho một model vẫn có thể dùng được cho model cùng cấp trên cùng provider, trong khi các cửa sổ thanh toán/vô hiệu hóa vẫn chặn toàn bộ hồ sơ.

Bạn cũng có thể đặt ghi đè thứ tự theo từng agent (được lưu trong auth-state.json của agent đó) qua CLI:

# Defaults to the configured default agent (omit --agent)
openclaw models auth order get --provider anthropic

# Lock rotation to a single profile (only try this one)
openclaw models auth order set --provider anthropic anthropic:default

# Or set an explicit order (fallback within provider)
openclaw models auth order set --provider anthropic anthropic:work anthropic:default

# Clear override (fall back to config auth.order / round-robin)
openclaw models auth order clear --provider anthropic

Để nhắm tới một agent cụ thể:

openclaw models auth order set --provider anthropic --agent main anthropic:default

Để xác minh thực tế sẽ thử những gì, dùng:

openclaw models status --probe

Nếu một hồ sơ đã lưu bị bỏ khỏi thứ tự rõ ràng, probe sẽ báo cáo excluded_by_auth_order cho hồ sơ đó thay vì thử âm thầm.

OpenClaw hỗ trợ cả hai:

• OAuth thường tận dụng quyền truy cập theo đăng ký (khi áp dụng).
• Khóa API dùng thanh toán theo từng token.

Trình hướng dẫn hỗ trợ rõ ràng Anthropic Claude CLI, OpenAI Codex OAuth và khóa API.