配置 — 工具与自定义提供方

• 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：每个条目的覆盖值。
• 匹配的图像模型中的 timeoutSeconds 条目在代理调用显式 image 工具时同样适用。对于图像理解，此超时应用于请求本身，不会因之前的准备工作而缩短。
• 失败时回退到下一个条目。

• self：仅当前会话密钥。
• tree：当前会话及由当前会话派生的会话（子代理）。对于读取操作，还包括当前会话通过环境感知群组机制监视的同一代理群组会话。
• agent：属于当前代理 ID 的任何会话（如果在同一代理 ID 下为每个发送者运行独立会话，则可能包括其他用户）。
• all：任何会话。跨代理目标仍需要 tools.agentToAgent。
• 沙箱限制：当当前会话处于沙箱中，且 agents.defaults.sandbox.sessionToolsVisibility="spawned"（默认值）时，即使 tools.sessions.visibility="all"，可见性也会被强制设为 tree。
• 当不是 all 时，sessions_list 会包含一个简要的 visibility 字段，用于描述生效模式，并警告当前范围之外的某些会话可能会被省略。

• 需要将 enabled 设为 true 才可使用附件。
• 子代理附件会被物化到子工作区的 .openclaw/attachments/<uuid>/，并带有 .manifest.json。
• ACP 附件仅限图像，并会在通过相同的文件数量、单文件字节数和总字节数限制后以内联方式转发到 ACP 运行时。
• 附件内容会在转录持久化中自动脱敏。
• Base64 输入会通过严格的字母表/填充检查以及解码前大小保护进行验证。
• 子代理附件文件权限为目录 0700、文件 0600。
• 子代理清理遵循 cleanup 策略：delete 始终移除附件；keep 仅在 retainOnSessionKeep: true 时保留它们。

• 使用 authHeader: true + headers 满足自定义身份验证需求。
• 使用 OPENCLAW_AGENT_DIR 覆盖 agent 配置根目录。
• 对匹配提供商 ID 的合并优先级：
  • 非空的 agent models.json baseUrl 值优先。
  • 仅当该提供商在当前配置／auth-profile 上下文中不是由 SecretRef 管理时，非空的 agent apiKey 值才优先。
  • 由 SecretRef 管理的提供商 apiKey 值会根据源标记刷新（环境变量引用使用 ENV_VAR_NAME，文件／exec／store 引用使用 secretref-managed），而不是持久化已解析的密钥。
  • 由 SecretRef 管理的提供商标头值会根据源标记刷新（环境变量引用使用 secretref-env:ENV_VAR_NAME，文件／exec／store 引用使用 secretref-managed）。
  • 空值或缺失的 agent apiKey／baseUrl 会回退到配置中的 models.providers。
  • 匹配模型的 contextWindow／maxTokens：存在明确配置值且该值有效（正的有限数值）时，明确配置值优先；否则使用隐式／生成的目录值。
  • 匹配模型的 contextTokens 遵循相同的“明确值优先，否则使用隐式值”规则；使用它可以限制有效上下文，而不改变原生模型元数据。
  • 提供商插件目录会作为由插件拥有的生成目录分片存储在 agent 的插件状态下。
  • 当你希望配置完全重写 models.json 并跳过合并由插件拥有的目录分片时，使用 models.mode: "replace"。
  • 标记持久化以源为准：标记会根据活动源配置快照（解析前）写入，而不是根据已解析的运行时密钥值写入。

• models.mode：提供商目录行为（merge 或 replace）。
• models.providers：按 provider id 键入的自定义 provider 映射。
  • 安全编辑：使用 openclaw config set models.providers.<id> '<json>' --strict-json --merge 或 openclaw config set models.providers.<id>.models '<json-array>' --strict-json --merge 进行增量更新。config set 会拒绝破坏性替换，除非你传入 --replace。

• 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）。对于自托管的 /v1/chat/completions 后端，例如 MLX、vLLM、SGLang 以及大多数 OpenAI 兼容的本地服务器，请使用 openai-completions。带有 baseUrl 但没有 api 的自定义 provider 默认使用 openai-completions；仅当后端支持 /v1/responses 时才设置 openai-responses。
• models.providers.*.apiKey：provider 凭证（优先使用 SecretRef/env 替换）。
• models.providers.*.auth：认证策略（api-key、token、oauth、aws-sdk）。
• models.providers.*.contextWindow：当模型条目未设置 contextWindow 时，该 provider 下模型的默认原生上下文窗口。
• models.providers.*.contextTokens：当模型条目未设置 contextTokens 时，该 provider 下模型的默认有效运行时上下文上限。
• models.providers.*.maxTokens：当模型条目未设置 maxTokens 时，该 provider 下模型的默认输出 token 上限。
• models.providers.*.timeoutSeconds：可选的按 provider 配置的模型 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：额外头（与 provider 默认值合并）。值支持 SecretRef。
• request.auth：认证策略覆盖。模式："provider-default"（使用 provider 内建认证）、"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 时，允许模型 provider HTTP 请求通过 provider HTTP fetch 保护器访问私有、CGNAT 或类似网段。自定义/本地 provider 的 base URL 已经信任精确配置的来源，但元数据/链路本地来源仍会在没有显式允许的情况下被阻止。将其设为 false 可退出精确来源信任。WebSocket 会使用同一个 request 处理头/TLS，但不会使用该 fetch SSRF 门禁。默认值：false。

• models.providers.*.models：显式的 provider 模型目录条目。
• models.providers.*.models.*.input：模型输入模态。纯文本模型使用 ["text"]，原生图像/视觉模型使用 ["text", "image"]。只有在所选模型被标记为支持图像时，图像附件才会注入 agent 回合。
• models.providers.*.models.*.contextWindow：原生模型上下文窗口元数据。此项会覆盖该模型的 provider 级别 contextWindow。
• models.providers.*.models.*.contextTokens：可选的运行时上下文上限。此项会覆盖 provider 级别的 contextTokens；当你希望有效上下文预算小于模型原生的 contextWindow 时使用此项；当两者不同时，openclaw models list 会显示这两个值。

​

自定义 provider 能力声明

• 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：用于定向发现的可选 provider-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 认证选项会探测你的密钥，并自动检测它属于哪个端点（如果检测结果不明确，则回退到提示，并默认使用全球端点）。也可使用专用的中国区和编程计划认证选项进行显式选择。
• 对于通用端点，请定义一个带有基础 URL 覆盖的自定义提供商。