Cấu hình — công cụ và nhà cung cấp tùy chỉnh

Mục nhập nhà cung cấp (type: "provider" hoặc bỏ qua):

• provider: mã định danh nhà cung cấp API (openai, anthropic, google/gemini, groq, v.v.)
• model: ghi đè mã định danh mô hình
• profile / preferredProfile: lựa chọn hồ sơ trong auth-profiles.json

Mục nhập CLI (type: "cli"):

• command: tệp thực thi cần chạy
• args: các đối số theo mẫu (hỗ trợ {{MediaPath}}, {{Prompt}}, {{MaxChars}}, v.v.; openclaw doctor --fix di chuyển các phần giữ chỗ {input} đã lỗi thời sang {{MediaPath}})

Các trường chung:

• capabilities: danh sách tùy chọn (image, audio, video). Mỗi Plugin nhà cung cấp khai báo tập khả năng mặc định riêng; ví dụ, nhà cung cấp openai đi kèm mặc định hỗ trợ hình ảnh+âm thanh, anthropic/minimax hỗ trợ hình ảnh, google hỗ trợ hình ảnh+âm thanh+video và groq hỗ trợ âm thanh.
• prompt, maxChars, maxBytes, timeoutSeconds, language: các giá trị ghi đè theo từng mục nhập.
• tools.media.image.timeoutSeconds và các mục timeoutSeconds tương ứng của mô hình hình ảnh cũng áp dụng khi agent gọi trực tiếp công cụ image. Đối với khả năng hiểu hình ảnh, thời gian chờ này áp dụng cho chính yêu cầu và không bị giảm bởi công việc chuẩn bị trước đó.
• Khi xảy ra lỗi, hệ thống chuyển sang mục nhập tiếp theo.

Việc xác thực nhà cung cấp tuân theo thứ tự tiêu chuẩn: auth-profiles.json → biến môi trường → models.providers.*.apiKey.

Các trường hoàn tất bất đồng bộ:

• asyncCompletion.directSend: cờ tương thích đã lỗi thời. Các tác vụ phương tiện bất đồng bộ đã hoàn tất vẫn được điều phối qua phiên của bên yêu cầu để agent nhận kết quả, quyết định cách thông báo cho người dùng và sử dụng công cụ tin nhắn khi nguồn yêu cầu gửi trực tiếp.

• self: chỉ khóa phiên hiện tại.
• tree: phiên hiện tại + các phiên do phiên hiện tại tạo ra (các agent con).
• agent: bất kỳ phiên nào thuộc mã định danh agent hiện tại (có thể bao gồm người dùng khác nếu bạn chạy phiên riêng theo người gửi dưới cùng một mã định danh agent).
• all: bất kỳ phiên nào. Việc nhắm đến agent khác vẫn yêu cầu tools.agentToAgent.
• Giới hạn của sandbox: khi phiên hiện tại chạy trong sandbox và agents.defaults.sandbox.sessionToolsVisibility="spawned" (giá trị mặc định), phạm vi hiển thị bị buộc thành tree ngay cả khi tools.sessions.visibility="all".
• Khi không phải all, sessions_list bao gồm một trường visibility thu gọn mô tả chế độ có hiệu lực và cảnh báo rằng một số phiên có thể bị bỏ qua nếu nằm ngoài phạm vi hiện tại.

• Tệp đính kèm yêu cầu enabled: true.
• Tệp đính kèm của agent con được tạo thành tệp trong không gian làm việc con tại .openclaw/attachments/<uuid>/ cùng với tệp .manifest.json.
• Tệp đính kèm ACP chỉ hỗ trợ hình ảnh và được chuyển tiếp nội tuyến đến môi trường thực thi ACP sau khi đáp ứng các giới hạn về số lượng tệp, số byte trên mỗi tệp và tổng số byte.
• Nội dung tệp đính kèm tự động được biên tập ẩn khỏi dữ liệu bản ghi hội thoại được lưu trữ.
• Dữ liệu đầu vào Base64 được xác thực nghiêm ngặt về bảng ký tự/phần đệm và có cơ chế bảo vệ kích thước trước khi giải mã.
• Quyền tệp đính kèm của agent con là 0700 cho thư mục và 0600 cho tệp.
• Việc dọn dẹp agent con tuân theo chính sách cleanup: delete luôn xóa tệp đính kèm; keep chỉ giữ lại chúng khi retainOnSessionKeep: true.

• Sử dụng authHeader: true + headers cho các nhu cầu xác thực tùy chỉnh.
• Ghi đè thư mục gốc cấu hình tác nhân bằng OPENCLAW_AGENT_DIR.
• Thứ tự ưu tiên khi hợp nhất đối với các ID nhà cung cấp trùng khớp:
  • Các giá trị baseUrl không rỗng trong models.json của tác nhân được ưu tiên.
  • Các giá trị apiKey không rỗng của tác nhân chỉ được ưu tiên khi nhà cung cấp đó không do SecretRef quản lý trong ngữ cảnh cấu hình/hồ sơ xác thực hiện tại.
  • Các giá trị apiKey của nhà cung cấp do SecretRef quản lý được làm mới từ dấu mốc nguồn (ENV_VAR_NAME cho tham chiếu biến môi trường, secretref-managed cho tham chiếu tệp/lệnh thực thi) thay vì lưu lâu dài các bí mật đã được phân giải.
  • Các giá trị tiêu đề của nhà cung cấp do SecretRef quản lý được làm mới từ dấu mốc nguồn (secretref-env:ENV_VAR_NAME cho tham chiếu biến môi trường, secretref-managed cho tham chiếu tệp/lệnh thực thi).
  • apiKey/baseUrl của tác nhân bị thiếu hoặc rỗng sẽ dự phòng về models.providers trong cấu hình.
  • Với contextWindow/maxTokens của mô hình trùng khớp: giá trị cấu hình tường minh được ưu tiên khi có mặt và hợp lệ (một số hữu hạn dương); nếu không, giá trị danh mục ngầm định/được tạo sẽ được sử dụng.
  • contextTokens của mô hình trùng khớp tuân theo cùng quy tắc ưu tiên giá trị tường minh, nếu không thì dùng giá trị ngầm định; hãy sử dụng trường này để giới hạn ngữ cảnh hiệu dụng mà không thay đổi siêu dữ liệu gốc của mô hình.
  • Các danh mục của Plugin nhà cung cấp được lưu dưới dạng các phân mảnh danh mục được tạo và thuộc quyền sở hữu của Plugin trong trạng thái Plugin của tác nhân.
  • Sử dụng models.mode: "replace" khi bạn muốn cấu hình ghi lại hoàn toàn models.json và bỏ qua việc hợp nhất các phân mảnh danh mục thuộc quyền sở hữu của Plugin.
  • Việc lưu dấu mốc lấy nguồn làm căn cứ có thẩm quyền: các dấu mốc được ghi từ ảnh chụp nhanh cấu hình nguồn đang hoạt động (trước khi phân giải), không phải từ các giá trị bí mật đã được phân giải khi chạy.

• models.mode: hành vi của danh mục nhà cung cấp (merge hoặc replace).
• models.providers: ánh xạ nhà cung cấp tùy chỉnh được lập khóa theo ID nhà cung cấp.
  • Chỉnh sửa an toàn: sử dụng openclaw config set models.providers.<id> '<json>' --strict-json --merge hoặc openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge để cập nhật theo kiểu bổ sung. config set từ chối các thao tác thay thế có tính phá hủy trừ khi bạn truyền --replace.

• models.providers.*.api: bộ điều hợp yêu cầu (openai-completions, openai-responses, openai-chatgpt-responses, anthropic-messages, google-generative-ai, google-vertex, github-copilot, bedrock-converse-stream, ollama, azure-openai-responses). Đối với các phần phụ trợ /v1/chat/completions tự lưu trữ như MLX, vLLM, SGLang và hầu hết máy chủ cục bộ tương thích OpenAI, hãy sử dụng openai-completions. Nhà cung cấp tùy chỉnh có baseUrl nhưng không có api mặc định sử dụng openai-completions; chỉ đặt openai-responses khi phần phụ trợ hỗ trợ /v1/responses.
• models.providers.*.apiKey: thông tin xác thực của nhà cung cấp (ưu tiên thay thế bằng SecretRef/biến môi trường).
• models.providers.*.auth: chiến lược xác thực (api-key, token, oauth, aws-sdk).
• models.providers.*.contextWindow: cửa sổ ngữ cảnh gốc mặc định cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt contextWindow.
• models.providers.*.contextTokens: giới hạn ngữ cảnh hiệu dụng mặc định khi chạy cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt contextTokens.
• models.providers.*.maxTokens: giới hạn token đầu ra mặc định cho các mô hình thuộc nhà cung cấp này khi mục mô hình không đặt maxTokens.
• models.providers.*.timeoutSeconds: thời gian chờ yêu cầu HTTP mô hình tùy chọn cho từng nhà cung cấp, tính bằng giây, bao gồm xử lý kết nối, tiêu đề, nội dung và hủy toàn bộ yêu cầu.
• models.providers.*.injectNumCtxForOpenAICompat: đối với Ollama + openai-completions, chèn options.num_ctx vào yêu cầu (mặc định: true).
• models.providers.*.authHeader: bắt buộc truyền thông tin xác thực trong tiêu đề Authorization khi cần.
• models.providers.*.baseUrl: URL cơ sở của API thượng nguồn.
• models.providers.*.headers: các tiêu đề tĩnh bổ sung để định tuyến qua proxy/đối tượng thuê.

models.providers.*.request: các thiết lập ghi đè phương thức truyền cho yêu cầu HTTP đến nhà cung cấp mô hình.

• request.headers: các tiêu đề bổ sung (được hợp nhất với giá trị mặc định của nhà cung cấp). Giá trị chấp nhận SecretRef.
• request.auth: ghi đè chiến lược xác thực. Các chế độ: "provider-default" (sử dụng xác thực tích hợp của nhà cung cấp), "authorization-bearer" (với token), "header" (với headerName, value, prefix tùy chọn).
• request.proxy: ghi đè proxy HTTP. Các chế độ: "env-proxy" (sử dụng biến môi trường HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (với url). Cả hai chế độ đều chấp nhận đối tượng con tls tùy chọn.
• request.tls: ghi đè TLS cho kết nối trực tiếp. Các trường: ca, cert, key, passphrase (tất cả đều chấp nhận SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: khi là true, cho phép yêu cầu HTTP đến nhà cung cấp mô hình truy cập các dải mạng riêng, CGNAT hoặc tương tự thông qua lớp bảo vệ truy xuất HTTP của nhà cung cấp. URL cơ sở của nhà cung cấp tùy chỉnh/cục bộ đã tin cậy chính xác nguồn gốc được cấu hình, ngoại trừ nguồn gốc siêu dữ liệu/liên kết cục bộ vẫn bị chặn nếu không có lựa chọn tham gia tường minh. Đặt thành false để không sử dụng cơ chế tin cậy nguồn gốc chính xác. WebSocket sử dụng cùng request cho tiêu đề/TLS nhưng không sử dụng cổng kiểm soát SSRF khi truy xuất đó. Mặc định là false.

• models.providers.*.models: các mục danh mục mô hình tường minh của nhà cung cấp.
• models.providers.*.models.*.input: các phương thức đầu vào của mô hình. Sử dụng ["text"] cho mô hình chỉ xử lý văn bản và ["text", "image"] cho mô hình hình ảnh/thị giác gốc. Tệp đính kèm hình ảnh chỉ được chèn vào lượt của tác nhân khi mô hình đã chọn được đánh dấu là có khả năng xử lý hình ảnh.
• models.providers.*.models.*.contextWindow: siêu dữ liệu cửa sổ ngữ cảnh gốc của mô hình. Giá trị này ghi đè contextWindow cấp nhà cung cấp cho mô hình đó.
• models.providers.*.models.*.contextTokens: giới hạn ngữ cảnh tùy chọn khi chạy. Giá trị này ghi đè contextTokens cấp nhà cung cấp; sử dụng khi bạn muốn ngân sách ngữ cảnh hiệu dụng nhỏ hơn contextWindow gốc của mô hình; openclaw models list hiển thị cả hai giá trị khi chúng khác nhau.
• models.providers.*.models.*.compat.supportsDeveloperRole: gợi ý tương thích tùy chọn. Với api: "openai-completions" cùng baseUrl không rỗng và không phải bản địa (máy chủ không phải api.openai.com), OpenClaw buộc giá trị này thành false khi chạy. baseUrl rỗng/bị lược bỏ giữ nguyên hành vi mặc định của OpenAI.
• models.providers.*.models.*.compat.requiresStringContent: gợi ý tương thích tùy chọn cho các điểm cuối trò chuyện tương thích OpenAI chỉ chấp nhận chuỗi. Khi là true, OpenClaw làm phẳng các mảng messages[].content chỉ chứa văn bản thành chuỗi thuần trước khi gửi yêu cầu.
• models.providers.*.models.*.compat.strictMessageKeys: gợi ý tương thích tùy chọn cho các điểm cuối trò chuyện tương thích OpenAI nghiêm ngặt. Khi là true, OpenClaw rút gọn các đối tượng thông điệp Chat Completions gửi đi chỉ còn role và content trước khi gửi yêu cầu.
• models.providers.*.models.*.compat.thinkingFormat: gợi ý tùy chọn về tải trọng suy luận. Sử dụng "together" cho reasoning.enabled kiểu Together, "qwen" cho enable_thinking cấp cao nhất hoặc "qwen-chat-template" cho chat_template_kwargs.enable_thinking trên các máy chủ tương thích OpenAI thuộc họ Qwen có hỗ trợ các đối số từ khóa mẫu trò chuyện ở cấp yêu cầu, chẳng hạn như vLLM. Các mô hình Qwen trên vLLM đã cấu hình cung cấp lựa chọn nhị phân /think (off, on) cho các định dạng này.
• models.providers.*.models.*.compat.requiresReasoningContentOnAssistantMessages: gợi ý tương thích tùy chọn cho các phần phụ trợ Chat Completions kiểu DeepSeek yêu cầu thông điệp trợ lý trước đó giữ lại reasoning_content khi phát lại. Khi là true, OpenClaw giữ nguyên trường đó trong các thông điệp trợ lý gửi đi. Sử dụng tùy chọn này khi kết nối proxy tùy chỉnh tương thích DeepSeek vốn từ chối yêu cầu sau khi nội dung suy luận bị loại bỏ. Mặc định là false.

• plugins.entries.amazon-bedrock.config.discovery: thư mục gốc thiết lập tự động khám phá Bedrock.
• plugins.entries.amazon-bedrock.config.discovery.enabled: bật/tắt khám phá ngầm định.
• plugins.entries.amazon-bedrock.config.discovery.region: khu vực AWS dùng để khám phá.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: bộ lọc ID nhà cung cấp tùy chọn để khám phá có mục tiêu.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: khoảng thời gian thăm dò để làm mới kết quả khám phá.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: cửa sổ ngữ cảnh dự phòng cho các mô hình được khám phá.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: số token đầu ra tối đa dự phòng cho các mô hình được khám phá.

Plugin nhà cung cấp cerebras bên ngoài chính thức có thể cấu hình mục này thông qua openclaw onboard --auth-choice cerebras-api-key. Chỉ sử dụng cấu hình nhà cung cấp tường minh khi ghi đè các giá trị mặc định.

{  env: { CEREBRAS_API_KEY: "sk-..." },  agents: {    defaults: {      model: {        primary: "cerebras/zai-glm-4.7",        fallbacks: ["cerebras/gpt-oss-120b"],      },      models: {        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },      },    },  },  models: {    mode: "merge",    providers: {      cerebras: {        baseUrl: "https://api.cerebras.ai/v1",        apiKey: "${CEREBRAS_API_KEY}",        api: "openai-completions",        models: [          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },        ],      },    },  },}

Sử dụng cerebras/zai-glm-4.7 cho Cerebras; zai/glm-4.7 để kết nối trực tiếp với Z.AI.

{  env: { KIMI_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "kimi/kimi-for-coding" },      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },    },  },}

Tương thích Anthropic, là nhà cung cấp tích hợp sẵn. Lối tắt: openclaw onboard --auth-choice kimi-code-api-key.

Xem Mô hình cục bộ. Tóm lại: chạy một mô hình cục bộ lớn qua LM Studio Responses API trên phần cứng mạnh; vẫn hợp nhất các mô hình được lưu trữ để dự phòng.

{  agents: {    defaults: {      model: { primary: "minimax/MiniMax-M3" },      models: {        "minimax/MiniMax-M3": { alias: "Minimax" },      },    },  },  models: {    mode: "merge",    providers: {      minimax: {        baseUrl: "https://api.minimax.io/anthropic",        apiKey: "${MINIMAX_API_KEY}",        api: "anthropic-messages",        models: [          {            id: "MiniMax-M3",            name: "MiniMax M3",            reasoning: true,            input: ["text", "image"],            cost: { input: 0.6, output: 2.4, cacheRead: 0.12, cacheWrite: 0 },            contextWindow: 1000000,            maxTokens: 131072,          },        ],      },    },  },}

Đặt MINIMAX_API_KEY. Lệnh tắt: openclaw onboard --auth-choice minimax-global-api hoặc openclaw onboard --auth-choice minimax-cn-api. Danh mục mô hình mặc định dùng M3 và cũng bao gồm các biến thể M2.7. Trên luồng phát trực tuyến tương thích với Anthropic, OpenClaw mặc định vô hiệu hóa chế độ suy luận của MiniMax M2.x, trừ khi bạn tự đặt rõ ràng thinking; MiniMax-M3 (và M3.x) mặc định vẫn sử dụng cơ chế suy luận thích ứng hoặc không truyền tham số của nhà cung cấp. /fast on hoặc params.fastMode: true chuyển MiniMax-M2.7 thành MiniMax-M2.7-highspeed.

{  env: { MOONSHOT_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "moonshot/kimi-k2.6" },      models: { "moonshot/kimi-k2.6": { alias: "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",            reasoning: false,            input: ["text", "image"],            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },            contextWindow: 262144,            maxTokens: 262144,          },        ],      },    },  },}

Đối với điểm cuối tại Trung Quốc: baseUrl: "https://api.moonshot.cn/v1" hoặc openclaw onboard --auth-choice moonshot-api-key-cn.

Các điểm cuối Moonshot gốc công bố khả năng tương thích với thông tin mức sử dụng khi phát trực tuyến trên phương thức truyền tải openai-completions dùng chung, và OpenClaw kích hoạt tính năng này dựa trên khả năng của điểm cuối thay vì chỉ dựa vào mã định danh nhà cung cấp tích hợp sẵn.

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

Đặt OPENCODE_API_KEY (hoặc OPENCODE_ZEN_API_KEY). Dùng tham chiếu opencode/... cho danh mục Zen hoặc tham chiếu opencode-go/... cho danh mục Go. Lệnh tắt: openclaw onboard --auth-choice opencode-zen hoặc openclaw onboard --auth-choice opencode-go.

{  env: { SYNTHETIC_API_KEY: "sk-..." },  agents: {    defaults: {      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "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",            reasoning: true,            input: ["text"],            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },            contextWindow: 192000,            maxTokens: 65536,          },        ],      },    },  },}

URL cơ sở không nên chứa /v1 (trình khách Anthropic sẽ tự nối thêm). Lệnh tắt: openclaw onboard --auth-choice synthetic-api-key.

{  agents: {    defaults: {      model: { primary: "zai/glm-4.7" },      models: { "zai/glm-4.7": {} },    },  },}

Đặt ZAI_API_KEY. Tham chiếu mô hình sử dụng mã định danh nhà cung cấp chuẩn zai/*. Lệnh tắt: openclaw onboard --auth-choice zai-api-key.

• Điểm cuối chung: https://api.z.ai/api/paas/v4
• Điểm cuối lập trình: https://api.z.ai/api/coding/paas/v4
• Lựa chọn xác thực zai-api-key mặc định sẽ kiểm tra khóa của bạn và tự động phát hiện khóa đó thuộc điểm cuối nào (nếu không thể xác định chắc chắn, hệ thống sẽ chuyển sang lời nhắc và mặc định chọn Toàn cầu). Các lựa chọn xác thực chuyên biệt cho CN và Coding-Plan cũng có sẵn để bạn chọn rõ ràng.
• Đối với điểm cuối chung, hãy định nghĩa một nhà cung cấp tùy chỉnh với URL cơ sở được ghi đè.