配置 — 工具和自定义提供商

• provider：API 提供商 ID（openai、anthropic、google/gemini、groq 等）
• model：模型 ID 覆盖
• profile / preferredProfile：auth-profiles.json 配置文件选择

• command：要运行的可执行文件
• args：模板化参数（支持 {{AttachmentPath}}、{{AttachmentUrl}}、{{AttachmentContentType}}、{{AttachmentDir}}、{{AttachmentIndex}}、{{Prompt}}、{{MaxChars}} 等；openclaw doctor --fix 会将已弃用的 {input} 占位符迁移到 {{AttachmentPath}}）。较旧的 {{MediaPath}}、{{MediaUrl}}、{{MediaType}} 和 {{MediaDir}} 别名在其兼容期内仍可使用，但已弃用。

• capabilities：包含 image、audio 和 video 中一项或多项的列表。
• prompt、maxChars、maxBytes、timeoutSeconds、language：每个条目的覆盖配置。
• 当智能体调用显式 image 工具时，匹配的图像模型 timeoutSeconds 条目也会应用。对于图像理解，此超时应用于请求本身，不会因之前的准备工作而缩短。
• 失败时回退到下一个条目。

• self：仅当前会话键。
• tree：当前会话 + 当前会话生成的会话（子智能体）。对于读取操作，它还包括当前会话通过环境群组感知所监视的同一智能体群组会话。
• agent：属于当前智能体 ID 的任何会话（如果在同一智能体 ID 下运行按发送者划分的会话，可能包含其他用户）。
• all：任何会话。跨智能体定向仍需要 tools.agentToAgent。
• 沙箱限制：当前会话处于沙箱隔离状态且 agents.defaults.sandbox.sessionToolsVisibility="spawned"（默认值）时，即使 tools.sessions.visibility="all"，可见性也会被强制设为 tree。
• 当不是 all 时，sessions_list 会包含一个精简的 visibility 字段，用于描述生效模式，并警告当前范围之外的某些会话可能会被省略。

• 附件需要 enabled: true。
• 子智能体附件会通过 .manifest.json 实体化到子工作区的 .openclaw/attachments/<uuid>/ 中。
• ACP 附件仅支持图像，在通过相同的文件数量、单文件字节数和总字节数限制后，会以内联方式转发到 ACP 运行时。
• 附件内容会自动从持久化的转录记录中隐去。
• Base64 输入会接受严格的字母表/填充检查以及解码前大小防护。
• 子智能体附件的文件权限：目录为 0700，文件为 0600。
• 子智能体清理遵循 cleanup 策略：delete 始终删除附件；仅当 retainOnSessionKeep: true 时，keep 才保留附件。

• 自定义身份验证需求请使用 authHeader: true + headers。
• 使用 OPENCLAW_AGENT_DIR 覆盖智能体配置根目录。
• 匹配提供商 ID 时的合并优先级：
  • 智能体中非空的 models.json baseUrl 值优先。
  • 仅当该提供商在当前配置/身份验证配置文件上下文中不由 SecretRef 管理时，智能体中非空的 apiKey 值才优先。
  • 由 SecretRef 管理的提供商 apiKey 值会从来源标记（环境引用使用 ENV_VAR_NAME，文件/exec 引用使用 secretref-managed）刷新，而不会持久化已解析的密钥。
  • 由 SecretRef 管理的提供商标头值会从来源标记（环境引用使用 secretref-env:ENV_VAR_NAME，文件/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.<id> '<json>' --strict-json --merge 或 openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge 进行增量更新。除非传递 --replace，否则 config set 会拒绝破坏性替换。

• models.providers.*.api：请求适配器（openai-completions、openai-responses、openai-chatgpt-responses、anthropic-messages、google-generative-ai、google-vertex、github-copilot、bedrock-converse-stream、ollama、azure-openai-responses）。对于 MLX、vLLM、SGLang 等自托管 /v1/chat/completions 后端以及大多数兼容 OpenAI 的本地服务器，请使用 openai-completions。具有 baseUrl 但没有 api 的自定义提供商默认为 openai-completions；仅当后端支持 /v1/responses 时才设置 openai-responses。
• models.providers.*.apiKey：提供商凭据（优先使用 SecretRef/环境变量替换）。
• 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 请求超时时间（秒），涵盖连接、标头、正文和整个请求的中止处理。
• models.providers.*.injectNumCtxForOpenAICompat：对于 Ollama + openai-completions，在请求中注入 options.num_ctx（默认值：true）。
• models.providers.*.authHeader：需要时，强制通过 Authorization 标头传输凭据。
• models.providers.*.baseUrl：上游 API 基础 URL。
• models.providers.*.headers：用于代理/租户路由的额外静态标头。

• request.headers：额外标头（与提供商默认值合并）。值接受 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 时，允许模型提供商 HTTP 请求通过提供商 HTTP 获取保护机制访问私有、CGNAT 或类似范围。自定义/本地提供商基础 URL 已信任已配置的确切源，但元数据/链路本地源除外；若未显式选择启用，这些源仍会被阻止。将其设置为 false 可选择退出确切源信任。WebSocket 对标头/TLS 使用相同的 request，但不使用该获取 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 会同时显示它们。

​

自定义提供商能力声明

• 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 数。

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

• 通用端点：https://api.z.ai/api/paas/v4
• 编码端点：https://api.z.ai/api/coding/paas/v4
• 默认的 zai-api-key 身份验证选项会探测你的密钥，并自动检测它所属的端点（如果检测结果不明确，则回退为提示，默认选择 Global）。此外还提供专用的 CN 和 Coding-Plan 身份验证选项，可供显式选择。
• 对于通用端点，请定义自定义提供商并覆盖基础 URL。