Nhà cung cấp mô hình

Tham khảo cho nhà cung cấp LLM/mô hình (không phải các kênh trò chuyện như WhatsApp/Telegram). Để biết quy tắc chọn mô hình, xem Mô hình.

# Quy tắc nhanh

# Hành vi nhà cung cấp do Plugin sở hữu

Phần lớn logic đặc thù theo nhà cung cấp nằm trong các Plugin nhà cung cấp (registerProvider(...)) trong khi OpenClaw giữ vòng lặp suy luận chung. Plugin sở hữu onboarding, danh mục mô hình, ánh xạ biến môi trường xác thực, chuẩn hóa transport/cấu hình, dọn dẹp schema công cụ, phân loại chuyển đổi dự phòng, làm mới OAuth, báo cáo mức sử dụng, hồ sơ thinking/reasoning, và nhiều hơn nữa.

Danh sách đầy đủ các hook provider-SDK và ví dụ Plugin đi kèm nằm trong Plugin nhà cung cấp. Một nhà cung cấp cần executor yêu cầu hoàn toàn tùy chỉnh là một bề mặt mở rộng riêng, sâu hơn.

# Xoay vòng khóa API

# Nhà cung cấp tích hợp sẵn (danh mục pi-ai)

OpenClaw đi kèm danh mục pi-ai. Các nhà cung cấp này không yêu cầu cấu hình models.providers; chỉ cần đặt xác thực + chọn mô hình.

# OpenAI

• Nhà cung cấp: openai
• Xác thực: OPENAI_API_KEY
• Xoay vòng tùy chọn: OPENAI_API_KEYS, OPENAI_API_KEY_1, OPENAI_API_KEY_2, cộng với OPENCLAW_LIVE_OPENAI_KEY (ghi đè đơn)
• Mô hình ví dụ: openai/gpt-5.5, openai/gpt-5.4-mini
• Xác minh tính khả dụng của tài khoản/mô hình bằng openclaw models list --provider openai nếu một bản cài đặt hoặc khóa API cụ thể hoạt động khác.
• CLI: openclaw onboard --auth-choice openai-api-key
• Transport mặc định là auto (ưu tiên WebSocket, dự phòng SSE)
• Ghi đè theo từng mô hình qua agents.defaults.models["openai/<model>"].params.transport ("sse", "websocket", hoặc "auto")
• Khởi động trước WebSocket OpenAI Responses mặc định được bật qua params.openaiWsWarmup (true/false)
• Có thể bật xử lý ưu tiên OpenAI qua agents.defaults.models["openai/<model>"].params.serviceTier
• /fast và params.fastMode ánh xạ các yêu cầu Responses trực tiếp openai/* sang service_tier=priority trên api.openai.com
• Dùng params.serviceTier khi bạn muốn một tầng tường minh thay vì công tắc /fast dùng chung
• Các header quy thuộc OpenClaw ẩn (originator, version, User-Agent) chỉ áp dụng trên lưu lượng OpenAI gốc tới api.openai.com, không áp dụng cho proxy tương thích OpenAI chung
• Các tuyến OpenAI gốc cũng giữ store của Responses, gợi ý prompt-cache, và định dạng payload tương thích reasoning của OpenAI; các tuyến proxy thì không
• openai/gpt-5.3-codex-spark bị ẩn có chủ ý trong OpenClaw vì yêu cầu API OpenAI live từ chối nó và danh mục Codex hiện tại không cung cấp nó

{
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}

# Anthropic

• Nhà cung cấp: anthropic
• Xác thực: ANTHROPIC_API_KEY
• Xoay vòng tùy chọn: ANTHROPIC_API_KEYS, ANTHROPIC_API_KEY_1, ANTHROPIC_API_KEY_2, cộng với OPENCLAW_LIVE_ANTHROPIC_KEY (ghi đè đơn)
• Mô hình ví dụ: anthropic/claude-opus-4-6
• CLI: openclaw onboard --auth-choice apiKey
• Các yêu cầu Anthropic công khai trực tiếp hỗ trợ công tắc /fast dùng chung và params.fastMode, bao gồm lưu lượng được xác thực bằng khóa API và OAuth gửi tới api.anthropic.com; OpenClaw ánh xạ điều đó sang service_tier của Anthropic (auto so với standard_only)
• Cấu hình Claude CLI được ưu tiên giữ tham chiếu mô hình chuẩn và chọn backend CLI riêng: anthropic/claude-opus-4-7 với agents.defaults.agentRuntime.id: "claude-cli". Các tham chiếu cũ claude-cli/claude-opus-4-7 vẫn hoạt động để tương thích.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

# OpenAI Codex OAuth

• Nhà cung cấp: openai-codex
• Xác thực: OAuth (ChatGPT)
• Tham chiếu mô hình PI: openai-codex/gpt-5.5
• Tham chiếu harness app-server Codex gốc: openai/gpt-5.5 với agents.defaults.agentRuntime.id: "codex"
• Tài liệu harness app-server Codex gốc: Harness Codex
• Tham chiếu mô hình cũ: codex/gpt-*
• Ranh giới Plugin: openai-codex/* tải Plugin OpenAI; Plugin app-server Codex gốc chỉ được chọn bởi runtime harness Codex hoặc các tham chiếu cũ codex/*.
• CLI: openclaw onboard --auth-choice openai-codex hoặc openclaw models auth login --provider openai-codex
• Transport mặc định là auto (ưu tiên WebSocket, dự phòng SSE)
• Ghi đè theo từng mô hình PI qua agents.defaults.models["openai-codex/<model>"].params.transport ("sse", "websocket", hoặc "auto")
• params.serviceTier cũng được chuyển tiếp trên các yêu cầu Codex Responses gốc (chatgpt.com/backend-api)
• Các header quy thuộc OpenClaw ẩn (originator, version, User-Agent) chỉ được gắn trên lưu lượng Codex gốc tới chatgpt.com/backend-api, không áp dụng cho proxy tương thích OpenAI chung
• Chia sẻ cùng công tắc /fast và cấu hình params.fastMode như openai/* trực tiếp; OpenClaw ánh xạ điều đó sang service_tier=priority
• openai-codex/gpt-5.5 dùng contextWindow = 400000 gốc của danh mục Codex và runtime mặc định contextTokens = 272000; ghi đè giới hạn runtime bằng models.providers.openai-codex.models[].contextTokens
• Ghi chú chính sách: OpenAI Codex OAuth được hỗ trợ tường minh cho các công cụ/quy trình bên ngoài như OpenClaw.
• Với tuyến đăng ký cộng runtime Codex gốc phổ biến, đăng nhập bằng xác thực openai-codex nhưng cấu hình openai/gpt-5.5 cộng với agents.defaults.agentRuntime.id: "codex".
• Chỉ dùng openai-codex/gpt-5.5 khi bạn muốn tuyến Codex OAuth/đăng ký qua PI; dùng openai/gpt-5.5 không có ghi đè runtime Codex khi thiết lập khóa API và danh mục cục bộ của bạn cung cấp tuyến API công khai.
• Các tham chiếu cũ openai-codex/gpt-5.1*, openai-codex/gpt-5.2*, và openai-codex/gpt-5.3* bị ẩn vì tài khoản ChatGPT/Codex OAuth từ chối chúng; hãy dùng openai-codex/gpt-5.5 hoặc tuyến runtime Codex gốc thay thế.

{
  plugins: { entries: { codex: { enabled: true } } },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      agentRuntime: { id: "codex" },
    },
  },
}

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# Tùy chọn lưu trữ kiểu đăng ký khác

# OpenCode

• Xác thực: OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY)
• Nhà cung cấp runtime Zen: opencode
• Nhà cung cấp runtime Go: opencode-go
• Mô hình ví dụ: opencode/claude-opus-4-6, opencode-go/kimi-k2.6
• CLI: openclaw onboard --auth-choice opencode-zen hoặc openclaw onboard --auth-choice opencode-go

{
  agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}

# Google Gemini (khóa API)

• Nhà cung cấp: google
• Xác thực: GEMINI_API_KEY
• Luân phiên tùy chọn: GEMINI_API_KEYS, GEMINI_API_KEY_1, GEMINI_API_KEY_2, phương án dự phòng GOOGLE_API_KEY, và OPENCLAW_LIVE_GEMINI_KEY (ghi đè đơn lẻ)
• Mô hình ví dụ: google/gemini-3.1-pro-preview, google/gemini-3-flash-preview
• Khả năng tương thích: cấu hình OpenClaw cũ dùng google/gemini-3.1-flash-preview được chuẩn hóa thành google/gemini-3-flash-preview
• Bí danh: google/gemini-3.1-pro được chấp nhận và chuẩn hóa thành id API Gemini trực tiếp của Google, google/gemini-3.1-pro-preview
• CLI: openclaw onboard --auth-choice gemini-api-key
• Suy luận: /think adaptive dùng suy luận động của Google. Gemini 3/3.1 bỏ qua thinkingLevel cố định; Gemini 2.5 gửi thinkingBudget: -1.
• Các lần chạy Gemini trực tiếp cũng chấp nhận agents.defaults.models["google/<model>"].params.cachedContent (hoặc cached_content cũ) để chuyển tiếp handle cachedContents/... gốc của nhà cung cấp; các lượt trúng bộ nhớ đệm Gemini hiển thị dưới dạng OpenClaw cacheRead

# Google Vertex và Gemini CLI

• Nhà cung cấp: google-vertex, google-gemini-cli
• Xác thực: Vertex dùng gcloud ADC; Gemini CLI dùng luồng OAuth của nó

Gemini CLI OAuth được phát hành như một phần của Plugin google được đóng gói kèm.

brew install gemini-cli

npm install -g @google/gemini-cli

openclaw plugins enable google

openclaw models auth login --provider google-gemini-cli --set-default

Phản hồi JSON của Gemini CLI được phân tích từ response; mức sử dụng dự phòng sang stats, với stats.cached được chuẩn hóa thành OpenClaw cacheRead.

# Z.AI (GLM)

• Nhà cung cấp: zai
• Xác thực: ZAI_API_KEY
• Mô hình ví dụ: zai/glm-5.1
• CLI: openclaw onboard --auth-choice zai-api-key
  • Bí danh: z.ai/* và z-ai/* chuẩn hóa thành zai/*
  • zai-api-key tự động phát hiện endpoint Z.AI tương ứng; zai-coding-global, zai-coding-cn, zai-global, và zai-cn buộc dùng một bề mặt cụ thể

# Vercel AI Gateway

• Nhà cung cấp: vercel-ai-gateway
• Xác thực: AI_GATEWAY_API_KEY
• Mô hình ví dụ: vercel-ai-gateway/anthropic/claude-opus-4.6, vercel-ai-gateway/moonshotai/kimi-k2.6
• CLI: openclaw onboard --auth-choice ai-gateway-api-key

# Kilo Gateway

• Nhà cung cấp: kilocode
• Xác thực: KILOCODE_API_KEY
• Mô hình ví dụ: kilocode/kilo/auto
• CLI: openclaw onboard --auth-choice kilocode-api-key
• URL cơ sở: https://api.kilo.ai/api/gateway/
• Danh mục dự phòng tĩnh đi kèm kilocode/kilo/auto; cơ chế khám phá trực tiếp https://api.kilo.ai/api/gateway/models có thể mở rộng thêm danh mục thời gian chạy.
• Định tuyến upstream chính xác phía sau kilocode/kilo/auto thuộc quyền sở hữu của Kilo Gateway, không được mã hóa cứng trong OpenClaw.

Xem /providers/kilocode để biết chi tiết thiết lập.

# Các Plugin nhà cung cấp khác được đóng gói kèm

# Các điểm đặc thù nên biết

# Nhà cung cấp qua models.providers (tùy chỉnh/URL cơ sở)

Dùng models.providers (hoặc models.json) để thêm nhà cung cấp tùy chỉnh hoặc proxy tương thích OpenAI/Anthropic.

Nhiều plugin nhà cung cấp đóng gói kèm bên dưới đã công bố một danh mục mặc định. Chỉ dùng các mục models.providers.<id> rõ ràng khi bạn muốn ghi đè URL cơ sở mặc định, header hoặc danh sách mô hình.

Các kiểm tra năng lực mô hình của Gateway cũng đọc metadata models.providers.<id>.models[] rõ ràng. Nếu một mô hình tùy chỉnh hoặc proxy chấp nhận hình ảnh, đặt input: ["text", "image"] trên mô hình đó để WebChat và các đường dẫn tệp đính kèm bắt nguồn từ node truyền hình ảnh dưới dạng đầu vào mô hình gốc thay vì ref media chỉ văn bản.

# Moonshot AI (Kimi)

Moonshot được phân phối dưới dạng plugin nhà cung cấp đóng gói kèm. Mặc định hãy dùng nhà cung cấp tích hợp sẵn và chỉ thêm mục models.providers.moonshot rõ ràng khi bạn cần ghi đè URL cơ sở hoặc metadata mô hình:

• Nhà cung cấp: moonshot
• Xác thực: MOONSHOT_API_KEY
• Mô hình ví dụ: moonshot/kimi-k2.6
• CLI: openclaw onboard --auth-choice moonshot-api-key hoặc openclaw onboard --auth-choice moonshot-api-key-cn

ID mô hình Kimi K2:

• moonshot/kimi-k2.6
• moonshot/kimi-k2.5
• moonshot/kimi-k2-thinking
• moonshot/kimi-k2-thinking-turbo
• moonshot/kimi-k2-turbo

{
  agents: {
    defaults: { model: { primary: "moonshot/kimi-k2.6" } },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [{ id: "kimi-k2.6", name: "Kimi K2.6" }],
      },
    },
  },
}

# Kimi coding

Kimi Coding dùng endpoint tương thích Anthropic của Moonshot AI:

• Nhà cung cấp: kimi
• Xác thực: KIMI_API_KEY
• Mô hình ví dụ: kimi/kimi-code

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: { model: { primary: "kimi/kimi-code" } },
  },
}

Mã model tương thích cũ kimi/k2p5 vẫn được chấp nhận.

# Volcano Engine (Doubao)

Volcano Engine (火山引擎) cung cấp quyền truy cập Doubao và các model khác tại Trung Quốc.

• Nhà cung cấp: volcengine (lập trình: volcengine-plan)
• Xác thực: VOLCANO_ENGINE_API_KEY
• Model ví dụ: volcengine-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice volcengine-api-key

{
  agents: {
    defaults: { model: { primary: "volcengine-plan/ark-code-latest" } },
  },
}

Onboarding mặc định dùng bề mặt lập trình, nhưng catalog volcengine/* chung cũng được đăng ký cùng lúc.

Trong bộ chọn model khi onboarding/cấu hình, lựa chọn xác thực Volcengine ưu tiên cả các hàng volcengine/* và volcengine-plan/*. Nếu các model đó chưa được tải, OpenClaw sẽ quay về catalog chưa lọc thay vì hiển thị bộ chọn rỗng theo phạm vi nhà cung cấp.

# BytePlus (Quốc tế)

BytePlus ARK cung cấp quyền truy cập các model giống Volcano Engine cho người dùng quốc tế.

• Nhà cung cấp: byteplus (lập trình: byteplus-plan)
• Xác thực: BYTEPLUS_API_KEY
• Model ví dụ: byteplus-plan/ark-code-latest
• CLI: openclaw onboard --auth-choice byteplus-api-key

{
  agents: {
    defaults: { model: { primary: "byteplus-plan/ark-code-latest" } },
  },
}

Onboarding mặc định dùng bề mặt lập trình, nhưng catalog byteplus/* chung cũng được đăng ký cùng lúc.

Trong bộ chọn model khi onboarding/cấu hình, lựa chọn xác thực BytePlus ưu tiên cả các hàng byteplus/* và byteplus-plan/*. Nếu các model đó chưa được tải, OpenClaw sẽ quay về catalog chưa lọc thay vì hiển thị bộ chọn rỗng theo phạm vi nhà cung cấp.

# Synthetic

Synthetic cung cấp các model tương thích Anthropic phía sau nhà cung cấp synthetic:

• Nhà cung cấp: synthetic
• Xác thực: SYNTHETIC_API_KEY
• Model ví dụ: synthetic/hf:MiniMaxAI/MiniMax-M2.5
• CLI: openclaw onboard --auth-choice synthetic-api-key

{
  agents: {
    defaults: { model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" } },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [{ id: "hf:MiniMaxAI/MiniMax-M2.5", name: "MiniMax M2.5" }],
      },
    },
  },
}

# MiniMax

MiniMax được cấu hình qua models.providers vì nó dùng endpoint tùy chỉnh:

• MiniMax OAuth (Toàn cầu): --auth-choice minimax-global-oauth
• MiniMax OAuth (CN): --auth-choice minimax-cn-oauth
• Khóa API MiniMax (Toàn cầu): --auth-choice minimax-global-api
• Khóa API MiniMax (CN): --auth-choice minimax-cn-api
• Xác thực: MINIMAX_API_KEY cho minimax; MINIMAX_OAUTH_TOKEN hoặc MINIMAX_API_KEY cho minimax-portal

Xem /providers/minimax để biết chi tiết thiết lập, tùy chọn model và đoạn cấu hình.

Phân tách năng lực do plugin sở hữu:

• Mặc định văn bản/trò chuyện vẫn dùng minimax/MiniMax-M2.7
• Tạo ảnh là minimax/image-01 hoặc minimax-portal/image-01
• Hiểu ảnh là MiniMax-VL-01 do plugin sở hữu trên cả hai đường dẫn xác thực MiniMax
• Tìm kiếm web vẫn dùng id nhà cung cấp minimax

# LM Studio

LM Studio được phân phối dưới dạng plugin nhà cung cấp đi kèm, dùng API native:

• Nhà cung cấp: lmstudio
• Xác thực: LM_API_TOKEN
• URL cơ sở suy luận mặc định: http://localhost:1234/v1

Sau đó đặt một model (thay bằng một trong các ID do http://localhost:1234/api/v1/models trả về):

{
  agents: {
    defaults: { model: { primary: "lmstudio/openai/gpt-oss-20b" } },
  },
}

OpenClaw dùng /api/v1/models và /api/v1/models/load native của LM Studio để khám phá + tự động tải, với /v1/chat/completions cho suy luận theo mặc định. Nếu bạn muốn LM Studio JIT loading, TTL và tự động loại bỏ sở hữu vòng đời model, hãy đặt models.providers.lmstudio.params.preload: false. Xem /providers/lmstudio để biết cách thiết lập và khắc phục sự cố.

# Ollama

Ollama được phân phối dưới dạng plugin nhà cung cấp đi kèm và dùng API native của Ollama:

• Nhà cung cấp: ollama
• Xác thực: Không bắt buộc (máy chủ cục bộ)
• Model ví dụ: ollama/llama3.3
• Cài đặt: https://ollama.com/download

# Install Ollama, then pull a model:
ollama pull llama3.3

{
  agents: {
    defaults: { model: { primary: "ollama/llama3.3" } },
  },
}

Ollama được phát hiện cục bộ tại http://127.0.0.1:11434 khi bạn chọn tham gia bằng OLLAMA_API_KEY, và plugin nhà cung cấp đi kèm thêm Ollama trực tiếp vào openclaw onboard và bộ chọn model. Xem /providers/ollama để biết onboarding, chế độ đám mây/cục bộ và cấu hình tùy chỉnh.

# vLLM

vLLM được phân phối dưới dạng plugin nhà cung cấp đi kèm cho các máy chủ cục bộ/tự lưu trữ tương thích OpenAI:

• Nhà cung cấp: vllm
• Xác thực: Tùy chọn (phụ thuộc vào máy chủ của bạn)
• URL cơ sở mặc định: http://127.0.0.1:8000/v1

Để chọn tham gia tự động khám phá cục bộ (bất kỳ giá trị nào cũng được nếu máy chủ của bạn không bắt buộc xác thực):

export VLLM_API_KEY="vllm-local"

Sau đó đặt một model (thay bằng một trong các ID do /v1/models trả về):

{
  agents: {
    defaults: { model: { primary: "vllm/your-model-id" } },
  },
}

Xem /providers/vllm để biết chi tiết.

# SGLang

SGLang được phân phối dưới dạng plugin nhà cung cấp đi kèm cho các máy chủ tự lưu trữ nhanh tương thích OpenAI:

• Nhà cung cấp: sglang
• Xác thực: Tùy chọn (phụ thuộc vào máy chủ của bạn)
• URL cơ sở mặc định: http://127.0.0.1:30000/v1

Để chọn tham gia tự động khám phá cục bộ (bất kỳ giá trị nào cũng được nếu máy chủ của bạn không bắt buộc xác thực):

export SGLANG_API_KEY="sglang-local"

Sau đó đặt một model (thay bằng một trong các ID do /v1/models trả về):

{
  agents: {
    defaults: { model: { primary: "sglang/your-model-id" } },
  },
}

Xem /providers/sglang để biết chi tiết.

# Proxy cục bộ (LM Studio, vLLM, LiteLLM, v.v.)

Ví dụ (tương thích OpenAI):

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/my-local-model" },
      models: { "lmstudio/my-local-model": { alias: "Local" } },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://localhost:1234/v1",
        apiKey: "${LM_API_TOKEN}",
        api: "openai-completions",
        timeoutSeconds: 300,
        models: [
          {
            id: "my-local-model",
            name: "Local Model",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

# Ví dụ CLI

openclaw onboard --auth-choice opencode-zen
openclaw models set opencode/claude-opus-4-6
openclaw models list

Xem thêm: Cấu hình để có ví dụ cấu hình đầy đủ.

# Liên quan

• Tham chiếu cấu hình - khóa cấu hình model
• Chuyển đổi dự phòng model - chuỗi dự phòng và hành vi thử lại
• Model - cấu hình model và bí danh
• Nhà cung cấp - hướng dẫn thiết lập theo từng nhà cung cấp