--- read_when: - 配置 `tools.*` 策略、允许列表或实验性功能 - 注册自定义提供商或覆盖基础 URL - 设置 OpenAI 兼容的自托管端点 sidebarTitle: Tools and custom providers summary: 工具配置（策略、实验性开关、由提供商支持的工具）和自定义提供商/base-URL 设置 title: 配置 — 工具和自定义提供商 x-i18n: generated_at: "2026-05-11T20:28:07Z" model: gpt-5.5 provider: openai source_hash: c9ab0ec823da1e2e8598d9efb998a207c4486ba82dcf4dd65422c6bf90581b46 source_path: gateway/config-tools.md workflow: 16 --- `tools.*` 配置键和自定义提供商 / 基础 URL 设置。关于智能体、渠道和其他顶层配置键，请参阅[配置参考](/zh-CN/gateway/configuration-reference)。 ## 工具 ### 工具配置档 `tools.profile` 会在 `tools.allow`/`tools.deny` 之前设置基础允许列表： 本地新手引导会在未设置时将新的本地配置默认设为 `tools.profile: "coding"`（已有的显式配置档会保留）。 | 配置档 | 包含 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | 仅 `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | | `full` | 无限制（与未设置相同） | ### 工具组 | 组 | 工具 | | ------------------ | ----------------------------------------------------------------------------------------------------------------------- | | `group:runtime` | `exec`, `process`, `code_execution`（`bash` 可作为 `exec` 的别名） | | `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | | `group:memory` | `memory_search`, `memory_get` | | `group:web` | `web_search`, `x_search`, `web_fetch` | | `group:ui` | `browser`, `canvas` | | `group:automation` | `heartbeat_respond`, `cron`, `gateway` | | `group:messaging` | `message` | | `group:nodes` | `nodes` | | `group:agents` | `agents_list`, `update_plan` | | `group:media` | `image`, `image_generate`, `music_generate`, `video_generate`, `tts` | | `group:openclaw` | 所有内置工具（不包括提供商插件） | ### `tools.allow` / `tools.deny` 全局工具允许 / 拒绝策略（拒绝优先）。不区分大小写，支持 `*` 通配符。即使 Docker 沙箱关闭也会应用。 ```json5 { tools: { deny: ["browser", "canvas"] }, } ``` `write` 和 `apply_patch` 是独立的工具 ID。`allow: ["write"]` 也会为兼容模型启用 `apply_patch`，但 `deny: ["write"]` 不会拒绝 `apply_patch`。要阻止所有文件变更，请拒绝 `group:fs`，或显式列出每个会变更文件的工具： ```json5 { tools: { deny: ["write", "edit", "apply_patch"] }, } ``` ### `tools.byProvider` 进一步限制特定提供商或模型的工具。顺序：基础配置档 → 提供商配置档 → 允许 / 拒绝。 ```json5 { tools: { profile: "coding", byProvider: { "google-antigravity": { profile: "minimal" }, "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] }, }, }, } ``` ### `tools.toolsBySender` 限制特定请求者身份可用的工具。这是在渠道访问控制之上的纵深防御；sender 值必须来自渠道适配器，而不是消息文本。 ```json5 { tools: { toolsBySender: { "channel:discord:1234567890123": { alsoAllow: ["group:fs"] }, "id:guest-user-id": { deny: ["group:runtime", "group:fs"] }, "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] }, }, }, } ``` 键使用显式前缀：`channel::`、`id:`、`e164:`、`username:`、`name:` 或 `"*"`。渠道 ID 是规范的 OpenClaw ID；`teams` 等别名会规范化为 `msteams`。旧版无前缀键仅按 `id:` 接受。匹配顺序为 channel+id、id、e164、username、name，然后是通配符。 当匹配时，按智能体设置的 `agents.list[].tools.toolsBySender` 会覆盖全局 sender 匹配，即使策略是空的 `{}`。 ### `tools.elevated` 控制沙箱外的提权 exec 访问： ```json5 { tools: { elevated: { enabled: true, allowFrom: { whatsapp: ["+15555550123"], discord: ["1234567890123", "987654321098765432"], }, }, }, } ``` - 按智能体覆盖（`agents.list[].tools.elevated`）只能进一步限制。 - `/elevated on|off|ask|full` 会按会话存储状态；内联指令仅应用于单条消息。 - 提权 `exec` 会绕过沙箱隔离，并使用配置的逃逸路径（默认是 `gateway`，当 exec 目标是 `node` 时为 `node`）。 ### `tools.exec` ```json5 { tools: { exec: { backgroundMs: 10000, timeoutSec: 1800, cleanupMs: 1800000, notifyOnExit: true, notifyOnExitEmptySuccess: false, commandHighlighting: false, applyPatch: { enabled: false, allowModels: ["gpt-5.5"], }, }, }, } ``` ### `tools.loopDetection` Tool-loop 安全检查默认**禁用**。设置 `enabled: true` 以激活检测。设置可以在 `tools.loopDetection` 中全局定义，并可在 `agents.list[].tools.loopDetection` 为每个智能体覆盖。 ```json5 { tools: { loopDetection: { enabled: true, historySize: 30, warningThreshold: 10, criticalThreshold: 20, globalCircuitBreakerThreshold: 30, detectors: { genericRepeat: true, knownPollNoProgress: true, pingPong: true, }, }, }, } ``` 为循环分析保留的最大工具调用历史记录。 用于警告的重复无进展模式阈值。 用于阻断关键循环的更高重复阈值。 任何无进展运行的硬停止阈值。 对重复的相同工具/相同参数调用发出警告。 对已知轮询工具（`process.poll`、`command_status` 等）发出警告/阻断。 对交替无进展的成对模式发出警告/阻断。 如果 `warningThreshold >= criticalThreshold` 或 `criticalThreshold >= globalCircuitBreakerThreshold`，验证会失败。 ### `tools.web` ```json5 { tools: { web: { search: { enabled: true, apiKey: "brave_api_key", // or BRAVE_API_KEY env maxResults: 5, timeoutSeconds: 30, cacheTtlMinutes: 15, }, fetch: { enabled: true, provider: "firecrawl", // optional; omit for auto-detect maxChars: 50000, maxCharsCap: 50000, maxResponseBytes: 2000000, timeoutSeconds: 30, cacheTtlMinutes: 15, maxRedirects: 3, readability: true, userAgent: "custom-ua", }, }, }, } ``` ### `tools.media` 配置入站媒体理解（图像/音频/视频）： ```json5 { tools: { media: { concurrency: 2, asyncCompletion: { directSend: false, // deprecated: completions stay agent-mediated }, audio: { enabled: true, maxBytes: 20971520, scope: { default: "deny", rules: [{ action: "allow", match: { chatType: "direct" } }], }, models: [ { provider: "openai", model: "gpt-4o-mini-transcribe" }, { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }, ], }, image: { enabled: true, timeoutSeconds: 180, models: [{ provider: "ollama", model: "gemma4:26b", timeoutSeconds: 300 }], }, video: { enabled: true, maxBytes: 52428800, models: [{ provider: "google", model: "gemini-3-flash-preview" }], }, }, }, } ``` **提供商条目**（`type: "provider"` 或省略）： - `provider`：API 提供商 ID（`openai`、`anthropic`、`google`/`gemini`、`groq` 等） - `model`：模型 ID 覆盖 - `profile` / `preferredProfile`：`auth-profiles.json` 配置文件选择 **CLI 条目**（`type: "cli"`）： - `command`：要运行的可执行文件 - `args`：模板化参数（支持 `{{MediaPath}}`、`{{Prompt}}`、`{{MaxChars}}` 等；`openclaw doctor --fix` 会将已弃用的 `{input}` 占位符迁移到 `{{MediaPath}}`） **通用字段：** - `capabilities`：可选列表（`image`、`audio`、`video`）。默认值：`openai`/`anthropic`/`minimax` → 图像，`google` → 图像+音频+视频，`groq` → 音频。 - `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖项。 - 当智能体调用显式的 `image` 工具时，`tools.media.image.timeoutSeconds` 和匹配的图像模型 `timeoutSeconds` 条目也会生效。 - 失败会回退到下一个条目。 提供商身份验证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。 **异步完成字段：** - `asyncCompletion.directSend`：已弃用的兼容标志。已完成的异步媒体任务仍由请求者会话中介处理，因此智能体会收到结果、决定如何告知用户，并在来源投递需要时使用消息工具。 ### `tools.agentToAgent` ```json5 { tools: { agentToAgent: { enabled: false, allow: ["home", "work"], }, }, } ``` ### `tools.sessions` 控制会话工具（`sessions_list`、`sessions_history`、`sessions_send`）可以定位哪些会话。 默认值：`tree`（当前会话 + 由它生成的会话，例如子智能体）。 ```json5 { tools: { sessions: { // "self" | "tree" | "agent" | "all" visibility: "tree", }, }, } ``` - `self`：仅当前会话键。 - `tree`：当前会话 + 由当前会话生成的会话（子智能体）。 - `agent`：属于当前智能体 ID 的任何会话（如果你在同一智能体 ID 下按发送者运行会话，可能包含其他用户）。 - `all`：任何会话。跨智能体定位仍然需要 `tools.agentToAgent`。 - 沙箱限制：当当前会话是沙箱隔离的，并且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制为 `tree`。 ### `tools.sessions_spawn` 控制 `sessions_spawn` 的内联附件支持。 ```json5 { tools: { sessions_spawn: { attachments: { enabled: false, // opt-in: set true to allow inline file attachments maxTotalBytes: 5242880, // 5 MB total across all files maxFiles: 50, maxFileBytes: 1048576, // 1 MB per file retainOnSessionKeep: false, // keep attachments when cleanup="keep" }, }, }, } ``` - 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝它们。 - 文件会在子工作区的 `.openclaw/attachments//` 中实体化，并带有 `.manifest.json`。 - 附件内容会自动从转录持久化中脱敏。 - Base64 输入会通过严格的字母表/填充检查和解码前大小保护进行验证。 - 目录权限为 `0700`，文件权限为 `0600`。 - 清理遵循 `cleanup` 策略：`delete` 始终移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留附件。 ### `tools.experimental` 实验性内置工具标志。默认关闭，除非适用严格 agentic GPT-5 自动启用规则。 ```json5 { tools: { experimental: { planTool: true, // enable experimental update_plan }, }, } ``` - `planTool`：为非平凡的多步骤工作跟踪启用结构化 `update_plan` 工具。 - 默认值：`false`，除非 `agents.defaults.embeddedPi.executionContract`（或单个智能体覆盖项）为 OpenAI 或 OpenAI Codex GPT-5 系列运行设置为 `"strict-agentic"`。设置为 `true` 可在该范围外强制开启此工具，设置为 `false` 可即使在严格 agentic GPT-5 运行中也保持关闭。 - 启用后，系统提示词还会添加使用指南，让模型只在实质性工作中使用它，并且最多保持一个步骤为 `in_progress`。 ### `agents.defaults.subagents` ```json5 { agents: { defaults: { subagents: { allowAgents: ["research"], model: "minimax/MiniMax-M2.7", maxConcurrent: 8, runTimeoutSeconds: 900, announceTimeoutMs: 120000, archiveAfterMinutes: 60, }, }, }, } ``` - `model`：派生子智能体的默认模型。如果省略，子智能体会继承调用方的模型。 - `allowAgents`：当请求方智能体未设置自己的 `subagents.allowAgents` 时，`sessions_spawn` 的目标智能体 ID 默认允许列表（`["*"]` = 任意；默认：仅同一智能体）。 - `runTimeoutSeconds`：当工具调用省略 `runTimeoutSeconds` 时，`sessions_spawn` 的默认超时（秒）。`0` 表示无超时。 - `announceTimeoutMs`：Gateway 网关 `agent` 宣告投递尝试的每次调用超时（毫秒）。默认值：`120000`。瞬态重试可能使总宣告等待时间长于一次配置的超时。 - 子智能体工具策略：`tools.subagents.tools.allow` / `tools.subagents.tools.deny`。 --- ## 自定义提供商和 base URL OpenClaw 使用内置模型目录。通过配置中的 `models.providers` 或 `~/.openclaw/agents//agent/models.json` 添加自定义提供商。 ```json5 { models: { mode: "merge", // merge (default) | replace providers: { "custom-proxy": { baseUrl: "http://localhost:4000/v1", apiKey: "LITELLM_KEY", api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai models: [ { id: "llama-3.1-8b", name: "Llama 3.1 8B", reasoning: false, input: ["text"], cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 128000, contextTokens: 96000, maxTokens: 32000, }, ], }, }, }, } ``` - 对于自定义身份验证需求，使用 `authHeader: true` + `headers`。 - 使用 `OPENCLAW_AGENT_DIR`（或 `PI_CODING_AGENT_DIR`，一个旧版环境变量别名）覆盖智能体配置根目录。 - 匹配提供商 ID 的合并优先级： - 非空的智能体 `models.json` `baseUrl` 值优先。 - 非空的智能体 `apiKey` 值仅在该提供商未在当前配置/身份验证配置文件上下文中由 SecretRef 管理时优先。 - 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（env 引用使用 `ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。 - 由 SecretRef 管理的提供商 header 值会从源标记刷新（env 引用使用 `secretref-env:ENV_VAR_NAME`，file/exec 引用使用 `secretref-managed`）。 - 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。 - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置和隐式目录值中的较高值。 - 匹配模型的 `contextTokens` 会在存在显式运行时上限时保留它；用它在不更改原生模型元数据的情况下限制有效上下文。 - 当你希望配置完全重写 `models.json` 时，使用 `models.mode: "replace"`。 - 标记持久化以源为准：标记从活动源配置快照（解析前）写入，而不是从已解析的运行时密钥值写入。 ### 提供商字段详情 - `models.mode`：提供商目录行为（`merge` 或 `replace`）。 - `models.providers`：按提供商 ID 键控的自定义提供商映射。 - 安全编辑：对于增量更新，使用 `openclaw config set models.providers. '' --strict-json --merge` 或 `openclaw config set models.providers..models '' --strict-json --merge`。除非传入 `--replace`，否则 `config set` 会拒绝破坏性替换。 - `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于自托管 `/v1/chat/completions` 后端，例如 MLX、vLLM、SGLang 和大多数 OpenAI 兼容本地服务器，使用 `openai-completions`。具有 `baseUrl` 但没有 `api` 的自定义提供商默认使用 `openai-completions`；仅当后端支持 `/v1/responses` 时才设置 `openai-responses`。 - `models.providers.*.apiKey`：提供商凭证（优先使用 SecretRef/env 替换）。 - `models.providers.*.auth`：身份验证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。 - `models.providers.*.contextWindow`：当模型条目未设置 `contextWindow` 时，此提供商下模型的默认原生上下文窗口。 - `models.providers.*.contextTokens`：当模型条目未设置 `contextTokens` 时，此提供商下模型的默认有效运行时上下文上限。 - `models.providers.*.maxTokens`：当模型条目未设置 `maxTokens` 时，此提供商下模型的默认输出 token 上限。 - `models.providers.*.timeoutSeconds`：可选的每提供商模型 HTTP 请求超时（秒），包括连接、header、body 和总请求中止处理。 - `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，向请求注入 `options.num_ctx`（默认：`true`）。 - `models.providers.*.authHeader`：在需要时强制通过 `Authorization` header 传输凭证。 - `models.providers.*.baseUrl`：上游 API base URL。 - `models.providers.*.headers`：用于代理/租户路由的额外静态 header。 `models.providers.*.request`：模型提供商 HTTP 请求的传输覆盖项。 - `request.headers`：额外 header（与提供商默认值合并）。值接受 SecretRef。 - `request.auth`：身份验证策略覆盖项。模式：`"provider-default"`（使用提供商内置身份验证）、`"authorization-bearer"`（带 `token`）、`"header"`（带 `headerName`、`value`、可选 `prefix`）。 - `request.proxy`：HTTP 代理覆盖项。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（带 `url`）。两种模式都接受可选的 `tls` 子对象。 - `request.tls`：直接连接的 TLS 覆盖项。字段：`ca`、`cert`、`key`、`passphrase`（全部接受 SecretRef）、`serverName`、`insecureSkipVerify`。 - `request.allowPrivateNetwork`：为 `true` 时，当 DNS 解析到私有、CGNAT 或类似地址段时，允许通过提供商 HTTP fetch 防护访问 `baseUrl` 的 HTTPS（操作员为受信任自托管 OpenAI 兼容端点选择加入）。除非显式设置为 `false`，否则诸如 `localhost`、`127.0.0.1` 和 `[::1]` 的 loopback 模型提供商流 URL 会自动允许；LAN、tailnet 和私有 DNS 主机仍需选择加入。WebSocket 对 header/TLS 使用同一 `request`，但不使用该 fetch SSRF 门控。默认值 `false`。 - `models.providers.*.models`：显式提供商模型目录条目。 - `models.providers.*.models.*.input`：模型输入模态。纯文本模型使用 `["text"]`，原生图像/视觉模型使用 `["text", "image"]`。只有在所选模型标记为支持图像时，图像附件才会注入到智能体轮次中。 - `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。这会覆盖该模型的提供商级 `contextWindow`。 - `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。这会覆盖提供商级 `contextTokens`；当你希望有效上下文预算小于模型原生 `contextWindow` 时使用它；当两个值不同时，`openclaw models list` 会同时显示这两个值。 - `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于带有非空非原生 `baseUrl`（主机不是 `api.openai.com`）的 `api: "openai-completions"`，OpenClaw 会在运行时将其强制设为 `false`。空的/省略的 `baseUrl` 保持默认 OpenAI 行为。 - `models.providers.*.models.*.compat.requiresStringContent`：用于仅字符串 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为普通字符串。 - `models.providers.*.models.*.compat.strictMessageKeys`：用于严格 OpenAI 兼容聊天端点的可选兼容性提示。为 `true` 时，OpenClaw 会在发送请求前将外发 Chat Completions 消息对象裁剪为 `role` 和 `content`。 - `models.providers.*.models.*.compat.thinkingFormat`：可选的思考负载提示。对于顶层 `enable_thinking` 使用 `"qwen"`；对于支持请求级 chat-template kwargs 的 Qwen 系列 OpenAI 兼容服务器（例如 vLLM），对 `chat_template_kwargs.enable_thinking` 使用 `"qwen-chat-template"`。 - `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动设备发现设置根。 - `plugins.entries.amazon-bedrock.config.discovery.enabled`：开启/关闭隐式设备发现。 - `plugins.entries.amazon-bedrock.config.discovery.region`：用于设备发现的 AWS 区域。 - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：用于定向设备发现的可选提供商 ID 过滤器。 - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：设备发现刷新的轮询间隔。 - `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：已发现模型的回退上下文窗口。 - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：已发现模型的回退最大输出 token 数。 交互式自定义提供商新手引导会为常见视觉模型 ID 推断图像输入，例如 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V 和 GLM-4V，并对已知的纯文本系列跳过额外问题。未知模型 ID 仍会提示确认是否支持图像。非交互式新手引导使用相同的推断；传入 `--custom-image-input` 可强制使用支持图像的元数据，传入 `--custom-text-input` 可强制使用纯文本元数据。 ### 提供商示例 内置的 `cerebras` provider 插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置它。仅在覆盖默认值时使用显式 provider 配置。 ```json5 { 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)" }, ], }, }, }, } ``` 对 Cerebras 使用 `cerebras/zai-glm-4.7`；对 Z.AI 直连使用 `zai/glm-4.7`。 ```json5 { env: { KIMI_API_KEY: "sk-..." }, agents: { defaults: { model: { primary: "kimi/kimi-for-coding" }, models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } }, }, }, } ``` Anthropic 兼容的内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。 参见 [本地模型](/zh-CN/gateway/local-models)。简要说明：在高性能硬件上通过 LM Studio Responses API 运行大型本地模型；保留托管模型合并作为回退。 ```json5 { 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, }, ], }, }, }, } ``` 设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅包含 M2.7。在 Anthropic 兼容的流式传输路径上，除非你显式设置 `thinking`，否则 OpenClaw 默认禁用 MiniMax 思考。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 ```json5 { 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, }, ], }, }, }, } ``` 对于中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。 原生 Moonshot 端点会在共享的 `openai-completions` 传输协议上声明流式传输用量兼容性，并且 OpenClaw 会根据端点能力而非仅根据内置 provider ID 来启用该行为。 ```json5 { agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" }, models: { "opencode/claude-opus-4-6": { alias: "Opus" } }, }, }, } ``` 设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对 Zen 目录使用 `opencode/...` 引用，对 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。 ```json5 { 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 应省略 `/v1`（Anthropic 客户端会追加它）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。 ```json5 { agents: { defaults: { model: { primary: "zai/glm-4.7" }, models: { "zai/glm-4.7": {} }, }, }, } ``` 设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 是可接受的别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。 - 通用端点：`https://api.z.ai/api/paas/v4` - 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4` - 对于通用端点，定义一个带基础 URL 覆盖的自定义 provider。 --- ## 相关内容 - [配置 — agents](/zh-CN/gateway/config-agents) - [配置 — channels](/zh-CN/gateway/config-channels) - [配置参考](/zh-CN/gateway/configuration-reference) — 其他顶层键 - [工具和插件](/zh-CN/tools)