跳转至

配置 — 环境、密钥和包含

进程环境、密钥解析、认证存储与配置组合：env、secrets.*、auth.* 与 $include。

完整的键索引及其他顶级配置域，请参阅 配置参考。

环境

env（内联环境变量）

{
  env: {
    vars: {
      OPENROUTER_API_KEY: "sk-or-...",
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
  • 仅当进程环境中缺少对应键时，才会应用内联环境变量。
  • .env 文件：当前工作目录（CWD）下的 .env 以及 ~/.openclaw/.env（两者均不会覆盖已有变量）。
  • shellEnv：从你的登录 shell 配置文件中导入缺失的预期键。
  • 完整的优先级规则请参阅 环境。

环境变量替换

在任何配置字符串中，使用 ${VAR_NAME} 引用环境变量：

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}
  • 仅匹配大写名称：[A-Z_][A-Z0-9_]*。
  • 缺失或为空的变量会保持未解析状态并原样显示，同时发出警告；需要该值的消费方将无法使用它。
  • 使用 $${VAR} 进行转义，可得到字面量 ${VAR}。
  • 可与 $include 配合使用。

默认值

使用 ${VAR_NAME:-fallback} 添加回退值。当变量未设置或为空时，将使用该回退值：

{
  mcp: {
    servers: {
      nautobot: {
        env: { NAUTOBOT_TIMEOUT: "${NAUTOBOT_TIMEOUT:-60}" },
      },
    },
  },
}
  • 带回退值的引用始终能够解析，因此永远不会发出缺失变量警告。
  • 允许空回退值：${VAR:-} 会解析为空字符串。
  • 回退值是字面文本，不能包含 $ 或 {。因此，像 ${A:-${B}} 这样的嵌套引用不是回退表达式；整个表达式保持字面量，只有内部的 ${B} 会被替换。
  • 仅支持 :- 运算符。其他 shell 运算符（:=、:?、:+、-、#、%、/、^）会作为字面文本原样保留。Bash 风格的 - 运算符被有意省略：OpenClaw 将未设置与为空视为同一状态，因此 - 无法与 :- 区分开来。
  • 转义仍然优先：$${VAR:-x} 会生成字面量 ${VAR:-x}，且不会从环境中读取任何内容。
  • 作者编写的回退值在配置写回时得以保留；OpenClaw 会恢复 ${VAR:-fallback}，而不是将解析出的值内联写入。
  • 回退值是配置文本，不是密钥存储。请将凭据放入 env.vars 或 SecretRef，并直接引用它们。

密钥

密钥引用是附加性的：明文值仍然有效。

secrets.egressProxy（密钥出口代理）

默认关闭、由 Gateway 负责的替换机制，用于替换代理 exec 子进程使用的共享存储 secret 条目：

{
  secrets: {
    egressProxy: {
      enabled: false,
      allowedHosts: ["api.example.com"],
      bypassHosts: ["pinned-api.example.com"],
    },
  },
}
  • enabled：在 Gateway 启动时启动回环代理和临时 CA。默认值为 false。修改该配置需要重启 Gateway。
  • allowedHosts：可选的精确主机名流量允许列表，用于代理请求和 CONNECT 隧道。存在时，仅列出的主机、绑定到已注册密钥的主机以及 bypassHosts 中的主机可达。空数组仅允许已绑定或已绕过的主机。修改该配置需要重启 Gateway。
  • bypassHosts：可选的精确主机名列表，用于证书固定客户端所使用的已认证盲 CONNECT 隧道。在被绕过的主机上，哨兵值不会被替换，并会在不暴露明文的情况下导致厂商认证失败。

有关子进程环境接入、认证、失败关闭行为及限制，请参阅 密钥出口代理。

SecretRef（密钥引用）

使用一种对象结构：

{ source: "env" | "file" | "exec" | "store", provider: "default", id: "..." }

校验规则：

  • provider 模式：^[a-z][a-z0-9_-]{0,63}$
  • source: "env" 的 id 模式：^[A-Z][A-Z0-9_]{0,127}$
  • source: "file" 的 id：绝对 JSON 指针（例如 "/providers/openai/apiKey"）
  • source: "exec" 的 id 模式：^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$（支持 AWS 风格的 secret#json_key 选择器）
  • source: "exec" 的 id 不得包含以斜杠分隔的 . 或 .. 路径段（例如 a/../b 会被拒绝）

支持的凭证表面

  • 权威矩阵：SecretRef 凭证表面
  • secrets apply 作用于受支持的 openclaw.json 凭证路径。
  • 每个代理的 auth-profile 引用均包含在运行时解析和审计覆盖范围内。

密钥提供方配置

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

说明：

  • file 提供方支持 mode: "json" 和 mode: "singleValue"（在 singleValue 模式下，id 必须为 "value"）。
  • 当 Windows ACL 验证不可用时，file 和 exec 提供方的路径将失败关闭（fail-closed）。请使用 OpenClaw 能够验证 ACL 的路径；不存在提供方级别的绕过方式。
  • exec 提供方要求 command 使用绝对路径，并通过 stdin/stdout 传递协议负载。
  • 符号链接命令路径会被拒绝。请改为配置解析后的绝对二进制路径；该路径不得是组可写或全局可写的，并且在 POSIX 系统上必须归当前用户所有。
  • 如果配置了 trustedDirs，命令路径（在 ~ 展开后）必须位于已批准的目录内；符号链接命令会在此检查之前就被拒绝，因此 trustedDirs 约束的实际上是所配置的路径本身。
  • exec 子进程环境默认是最小化的；请使用 passEnv 显式传递所需变量。
  • 密钥引用在激活时会解析为内存快照，之后请求路径仅读取该快照。
  • 活动表面过滤在激活期间生效：已启用表面上未解析的引用会导致启动或重载失败，而未激活的表面则会被跳过并输出诊断信息。

身份验证存储

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:personal": { provider: "openai", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      openai: ["openai:personal"],
    },
  },
}
  • 每个代理的配置文件存储在 <agentDir>/openclaw-agent.sqlite（auth_profile_store）。
  • 已存储的身份验证配置文件支持值级别引用（api_key 使用 keyRef，token 使用 tokenRef），用于静态凭据模式。
  • 旧版扁平 auth-profiles.json 映射（例如 { "provider": { "apiKey": "..." } }）不是运行时格式；openclaw doctor --fix 会将其重写为规范的 provider:default API 密钥配置文件，并创建 .legacy-flat.*.bak 备份。
  • OAuth 模式配置文件（auth.profiles.<id>.mode = "oauth"）不支持基于 SecretRef 的身份验证配置文件凭据。
  • 静态运行时凭据来自内存中已解析的快照；发现旧版静态 auth.json 条目时会将其清除。
  • 旧版 OAuth 从 ~/.openclaw/credentials/oauth.json 导入。
  • 参见 OAuth。
  • 机密运行时行为以及 audit/configure/apply 工具：机密管理。

配置包含（$include）

将配置拆分为多个文件：

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

合并行为：

  • 单个文件：替换包含它的对象。
  • 文件数组：按顺序深度合并（后者覆盖前者）。
  • 同级键：在包含项之后合并（覆盖包含的值）。
  • 嵌套包含：最多 10 层。
  • 路径：相对于包含文件解析，但必须保持在顶层配置目录（openclaw.json 的 dirname）内。绝对路径/../ 形式仅在其仍解析到该边界内时才允许。设置 OPENCLAW_INCLUDE_ROOTS（绝对路径）以允许配置目录之外的其他根目录。
  • 限制：路径不得包含空字节，并且在解析前后都必须严格短于 4096 个字符；每个包含文件上限为 2 MB。
  • 对于 OpenClaw 拥有的写入，如果其变更键全部由对象键路径处的单个文件包含项拥有，则会写入直通到最深层拥有该键的包含项。这支持顶层部分和嵌套对象映射条目（包括数字对象键），同时保持 openclaw.json 不变。写入直通仅针对顶层配置目录内的包含文件；通过 OPENCLAW_INCLUDE_ROOTS 允许的包含项对于 OpenClaw 拥有的写入保持只读。
  • 根包含项（配置中根对象声明 $include 的每个部分）、实际数组条目包含项、包含数组、同级覆盖、被多个逻辑路径共享的文件、跨越所有权边界的更改、位于已合并的同一路径或祖先拥有者之下的嵌套包含项，以及其自身文件仍声明嵌套 $include 指令的包含项，对于 OpenClaw 拥有的写入均为只读；这些写入会失败关闭，而不是将配置扁平化。
  • openclaw doctor --fix 通过同一边界写入；混合根拥有的修复与包含项拥有的修复的运行会被整体拒绝；被拒绝的写入会使所有文件保持不变（同一运行中较早的写入仍会保存），并且 Doctor 会指出需要手动修复的边界，并且当根文件声明该边界的 $include 时，还会指出包含的文件（代理名册边界仅命名而不带文件）。
  • 错误：针对文件缺失、解析错误、循环包含、无效路径格式和长度过长提供清晰消息。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw