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ơ auth-profiles.json

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

• command: tệp thực thi cần chạy
• args: đối số theo mẫu (hỗ trợ {{MediaPath}}, {{Prompt}}, {{MaxChars}}, v.v.; openclaw doctor --fix di chuyển các placeholder {input} không còn dùng sang {{MediaPath}})

Các trường chung:

• capabilities: danh sách tùy chọn (image, audio, video). Mặc định: openai/anthropic/minimax → hình ảnh, google → hình ảnh+âm thanh+video, groq → âm thanh.
• prompt, maxChars, maxBytes, timeoutSeconds, language: ghi đè theo từng mục nhập.
• tools.media.image.timeoutSeconds và các mục nhập timeoutSeconds của mô hình hình ảnh tương ứng cũng áp dụng khi agent gọi công cụ image tường minh.
• Lỗi sẽ chuyển sang mục nhập tiếp theo.

Xác thực nhà cung cấp tuân theo thứ tự 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 không còn dùng. Các tác vụ media 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à dùng công cụ nhắn tin khi việc gửi từ nguồn yêu cầu điều đó.

• 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 sinh ra (subagent).
• agent: mọi phiên thuộc về 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 theo từng người gửi dưới cùng một mã định danh agent).
• all: mọi phiên. Việc nhắm mục tiêu liên agent vẫn yêu cầu tools.agentToAgent.
• Kẹp sandbox: khi phiên hiện tại được sandbox và agents.defaults.sandbox.sessionToolsVisibility="spawned", khả năng hiển thị bị buộc thành tree ngay cả khi tools.sessions.visibility="all".

• Tệp đính kèm chỉ được hỗ trợ cho runtime: "subagent". Runtime ACP từ chối chúng.
• Tệp được hiện thực hóa vào workspace con tại .openclaw/attachments/<uuid>/ với một .manifest.json.
• Nội dung tệp đính kèm được tự động biên tập khỏi phần lưu transcript.
• Dữ liệu nhập Base64 được xác thực bằng kiểm tra bảng chữ cái/phần đệm nghiêm ngặt và một cơ chế bảo vệ kích thước trước khi giải mã.
• Quyền tệp là 0700 cho thư mục và 0600 cho tệp.
• Dọn dẹp 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.

• Dùng authHeader: true + headers cho nhu cầu xác thực tùy chỉnh.
• Ghi đè gốc cấu hình agent bằng OPENCLAW_AGENT_DIR (hoặc PI_CODING_AGENT_DIR, một bí danh biến môi trường cũ).
• Thứ tự ưu tiên hợp nhất cho các ID nhà cung cấp khớp nhau:
  • Các giá trị baseUrl không rỗng trong models.json của agent được ưu tiên.
  • Các giá trị apiKey không rỗng trong agent 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/auth-profile 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ừ marker nguồn (ENV_VAR_NAME cho tham chiếu env, secretref-managed cho tham chiếu file/exec) thay vì lưu các bí mật đã phân giải.
  • Các giá trị header của nhà cung cấp do SecretRef quản lý được làm mới từ marker nguồn (secretref-env:ENV_VAR_NAME cho tham chiếu env, secretref-managed cho tham chiếu file/exec).
  • apiKey/baseUrl trong agent trống hoặc bị thiếu sẽ fallback về models.providers trong cấu hình.
  • contextWindow/maxTokens của mô hình khớp dùng giá trị cao hơn giữa cấu hình tường minh và giá trị danh mục ngầm định.
  • contextTokens của mô hình khớp giữ nguyên giới hạn runtime tường minh khi có; dùng nó để giới hạn ngữ cảnh hiệu dụng mà không thay đổi metadata mô hình gốc.
  • Dùng models.mode: "replace" khi bạn muốn cấu hình viết lại hoàn toàn models.json.
  • Việc lưu marker lấy nguồn làm thẩm quyền: marker được ghi từ snapshot 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 runtime đã phân giải.

• models.mode: hành vi danh mục nhà cung cấp (merge hoặc replace).
• models.providers: map nhà cung cấp tùy chỉnh, được khóa bằng id nhà cung cấp.
  • Chỉnh sửa an toàn: 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 cho các cập nhật bổ sung. config set từ chối các thay thế phá hủy trừ khi bạn truyền --replace.

• models.providers.*.api: adapter yêu cầu (openai-completions, openai-responses, anthropic-messages, google-generative-ai, v.v.). Với các backend tự lưu trữ /v1/chat/completions như MLX, vLLM, SGLang và hầu hết máy chủ cục bộ tương thích OpenAI, dùng openai-completions. Một nhà cung cấp tùy chỉnh có baseUrl nhưng không có api mặc định là openai-completions; chỉ đặt openai-responses khi backend hỗ trợ /v1/responses.
• models.providers.*.apiKey: thông tin xác thực nhà cung cấp (ưu tiên thay thế SecretRef/env).
• 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 dưới 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 runtime hiệu dụng mặc định cho các mô hình dưới 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 dưới 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 theo từng nhà cung cấp, tính bằng giây, bao gồm xử lý hủy yêu cầu khi kết nối, header, body và tổng thời gian yêu cầu.
• models.providers.*.injectNumCtxForOpenAICompat: với Ollama + openai-completions, chèn options.num_ctx vào yêu cầu (mặc định: true).
• models.providers.*.authHeader: buộc truyền thông tin xác thực trong header Authorization khi cần.
• models.providers.*.baseUrl: URL cơ sở API upstream.
• models.providers.*.headers: các header tĩnh bổ sung cho định tuyến proxy/tenant.

models.providers.*.request: ghi đè truyền tải cho yêu cầu HTTP nhà cung cấp mô hình.

• request.headers: header bổ sung (hợp nhất với 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. Chế độ: "provider-default" (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. Chế độ: "env-proxy" (dùng biến env HTTP_PROXY/HTTPS_PROXY), "explicit-proxy" (với url). Cả hai chế độ chấp nhận một đối tượng con tls tùy chọn.
• request.tls: ghi đè TLS cho kết nối trực tiếp. Trường: ca, cert, key, passphrase (tất cả chấp nhận SecretRef), serverName, insecureSkipVerify.
• request.allowPrivateNetwork: khi true, cho phép HTTPS tới baseUrl khi DNS phân giải thành dải private, CGNAT hoặc tương tự, thông qua cơ chế bảo vệ HTTP fetch của nhà cung cấp (operator chủ động chọn dùng cho các endpoint tự lưu trữ tương thích OpenAI đáng tin cậy). Các URL stream nhà cung cấp mô hình local loopback như localhost, 127.0.0.1 và [::1] được tự động cho phép trừ khi mục này được đặt tường minh thành false; máy chủ LAN, tailnet và DNS riêng vẫn yêu cầu chọn dùng. WebSocket dùng cùng request cho header/TLS nhưng không dùng cổng SSRF fetch đó. Mặc định false.

• models.providers.*.models: mục danh mục mô hình nhà cung cấp tường minh.
• models.providers.*.models.*.input: phương thức đầu vào mô hình. Dùng ["text"] cho mô hình chỉ 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 agent khi mô hình được chọn được đánh dấu có khả năng xử lý hình ảnh.
• models.providers.*.models.*.contextWindow: metadata cửa sổ ngữ cảnh gốc của mô hình. Mục 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 runtime tùy chọn. Mục này ghi đè contextTokens cấp nhà cung cấp; 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ó baseUrl không rỗng và không phải gốc (host không phải api.openai.com), OpenClaw buộc giá trị này thành false tại runtime. baseUrl trống/bị bỏ qua giữ hành vi OpenAI mặc định.
• models.providers.*.models.*.compat.requiresStringContent: gợi ý tương thích tùy chọn cho endpoint chat tương thích OpenAI chỉ nhận chuỗi. Khi true, OpenClaw làm phẳng các mảng messages[].content chỉ có văn bản thuần thành chuỗi đơn giản trước khi gửi yêu cầu.

• plugins.entries.amazon-bedrock.config.discovery: gốc cài đặt 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 cho khám phá.
• plugins.entries.amazon-bedrock.config.discovery.providerFilter: bộ lọc provider-id tùy chọn cho khám phá có mục tiêu.
• plugins.entries.amazon-bedrock.config.discovery.refreshInterval: khoảng thời gian polling để làm mới khám phá.
• plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: cửa sổ ngữ cảnh fallback cho các mô hình được khám phá.
• plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: số token đầu ra tối đa fallback cho các mô hình được khám phá.

Plugin nhà cung cấp cerebras đi kèm có thể cấu hình mục này qua openclaw onboard --auth-choice cerebras-api-key. Chỉ dùng cấu hình nhà cung cấp tường minh khi ghi đè 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)" },
        ],
      },
    },
  },
}

Dùng cerebras/zai-glm-4.7 cho Cerebras; zai/glm-4.7 cho Z.AI trực tiếp.

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

Tương thích với Anthropic, 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 tắt: 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; giữ các mô hình được lưu trữ đã hợp nhất để dự phòng.

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}

Đặt MINIMAX_API_KEY. Lối 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 chỉ dùng M2.7. Trên đường truyền phát trực tuyến tương thích với Anthropic, OpenClaw mặc định tắt tính năng suy nghĩ của MiniMax trừ khi bạn tự đặt rõ thinking. /fast on hoặc params.fastMode: true viết lại 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 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 mức sử dụng phát trực tuyến trên phương thức vận chuyển openai-completions dùng chung, và OpenClaw xác định điều đó dựa trên khả năng của điểm cuối thay vì chỉ dựa vào id 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ối 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ở nên bỏ /v1 (ứng dụng khách Anthropic sẽ thêm nó). Lối 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. z.ai/* và z-ai/* được chấp nhận làm bí danh. Lối 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 (mặc định): https://api.z.ai/api/coding/paas/v4
• Đố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 phần ghi đè URL cơ sở.