openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-05-01 21:17:01 +00:00
parent 3f023fece8
commit 193ea580f3
2 changed files with 186 additions and 179 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

266
docs/zh-CN/gateway/configuration.md
View File

@ -3,38 +3,37 @@ read_when:
- 首次设置 OpenClaw
- 正在查找常见配置模式
- 导航到特定配置章节
summary: 配置概览：常见任务、快速设置，以及完整参考链接
summary: 配置概览：常见任务、快速设置，以及完整参考文档链接
title: 配置
x-i18n:
generated_at: "2026-05-01T11:40:30Z"
generated_at: "2026-05-01T21:15:43Z"
model: gpt-5.5
provider: openai
source_hash: 6697f8800f29fbdf369f95bd442842d0bb6a341dcf8efa4698a2f43c8acc8981
source_hash: d5ad1685170923f26166fb2f74891468d16c6f86af5cc5f5f1da7a6dce65eb98
source_path: gateway/configuration.md
workflow: 16
---
OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
活动配置路径必须是常规文件。对于 OpenClaw 拥有的写入操作，不支持符号链接的 `openclaw.json`
布局；原子写入可能会替换
该路径，而不是保留符号链接。如果你将配置保存在
OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 supports comments and trailing commas">**JSON5**</Tooltip> 配置。
活动配置路径必须是常规文件。对于 OpenClaw 自有写入，不支持符号链接的 `openclaw.json`
布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在
默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因包括：
如果文件缺失，OpenClaw 会使用安全默认值。添加配置的常见原因：
- 连接渠道并控制谁可以给 bot 发消息
- 连接渠道并控制谁可以向机器人发消息
- 设置模型、工具、沙箱隔离或自动化（cron、钩子）
- 调整会话、媒体、网络或 UI
请参阅[完整参考](/zh-CN/gateway/configuration-reference)，了解每个可用字段。
查看[完整参考](/zh-CN/gateway/configuration-reference)，了解所有可用字段。
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取精确到字段级别的
文档。将本页用于面向任务的指导，并使用
[配置参考](/zh-CN/gateway/configuration-reference) 查看更完整的
智能体和自动化在编辑配置前，应使用 `config.schema.lookup` 获取准确的字段级
文档。使用本页获取面向任务的指导，并使用
[配置参考](/zh-CN/gateway/configuration-reference)查看更完整的
字段映射和默认值。
<Tip>
**刚开始配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [配置示例](/zh-CN/gateway/configuration-examples) 指南，获取可完整复制粘贴的配置。
**刚开始配置？** 从 `openclaw onboard` 开始进行交互式设置，或查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取可完整复制粘贴的配置。
</Tip>
## 最小配置
@ -52,8 +51,8 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支
<Tabs>
<Tab title="交互式向导">
```bash
openclaw onboard # 完整新手引导流程
openclaw configure # 配置向导
openclaw onboard # full onboarding flow
openclaw configure # config wizard
```
</Tab>
<Tab title="CLI（单行命令）">
@ -64,29 +63,29 @@ OpenClaw 从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支
```
</Tab>
<Tab title="控制 UI">
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，然后使用 **配置** 标签页。
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，并使用 **配置** 标签页。
控制 UI 会根据实时配置 schema 渲染表单，包括字段
`title` / `description` 文档元数据，以及可用时的插件和渠道 schema，
并提供 **原始 JSON** 编辑器作为备用入口。对于下钻
并提供 **原始 JSON** 编辑器作为逃生通道。对于下钻
UI 和其他工具，Gateway 网关还会公开 `config.schema.lookup`，用于
获取一个路径范围内的 schema 节点及其直接子项摘要。
获取一个限定路径的 schema 节点及其直接子项摘要。
</Tab>
<Tab title="直接编辑">
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监听该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
</Tab>
</Tabs>
## 严格验证
<Warning>
OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。
OpenClaw 只接受完全匹配 schema 的配置。未知键、格式错误的类型或无效值会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器可以附加 JSON Schema 元数据。
</Warning>
`openclaw config schema` 会打印控制 UI
和验证使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点及
`openclaw config schema` 会打印控制 UI 和验证使用的规范 JSON Schema。
`config.schema.lookup` 会获取单个限定路径的节点及其
子项摘要，供下钻工具使用。字段 `title`/`description` 文档元数据
会贯穿嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
`oneOf`/`allOf` 分支。当清单注册表加载后，运行时插件和渠道 schema 会合并进来。
`oneOf`/`allOf` 分支。加载清单注册表后，运行时插件和渠道 schema 会合并进来。
验证失败时：
@ -95,22 +94,23 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- 运行 `openclaw doctor` 查看确切问题
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
每次成功启动后，Gateway 网关都会保留一份受信任的最后已知正常副本。
如果之后 `openclaw.json` 验证失败（或删除了 `gateway.mode`、急剧变小，
或者前面误插入了一行日志），OpenClaw 会将损坏文件
保留为 `.clobbered.*`，恢复最后已知正常副本，并记录恢复
原因。下一次智能体轮次还会收到系统事件警告，避免主
智能体盲目重写已恢复的配置。当候选配置包含已遮盖的密钥占位符（例如 `***`）时，会跳过提升为最后已知正常配置。
当每个验证问题都限定在 `plugins.entries.<id>...` 范围内时，OpenClaw
不会执行整文件恢复。它会保持当前配置活动，并
暴露插件本地失败，避免插件 schema 或宿主版本不匹配
回滚无关的用户设置。
Gateway 网关会在每次成功启动后保留一份可信的最近一次良好副本。
如果之后 `openclaw.json` 验证失败（或删除了 `gateway.mode`、大幅缩小，
或前面被插入了杂散日志行），OpenClaw 会将损坏文件保留为
`.clobbered.*`，恢复最近一次良好副本，并记录恢复
原因。下一轮智能体回合也会收到系统事件警告，这样主
智能体就不会盲目重写已恢复的配置。当候选配置包含已遮盖的密钥占位符（例如 `***`）时，
会跳过提升为最近一次良好副本。
当每个验证问题都限定在 `plugins.entries.<id>...` 下时，OpenClaw
不会执行整文件恢复。它会保持当前配置处于活动状态，并
暴露插件本地失败，因此插件 schema 或主机版本不匹配
不会回滚无关的用户设置。
## 常见任务
<AccordionGroup>
<Accordion title="设置渠道（WhatsApp、Telegram、Discord 等）">
每个渠道在 `channels.<provider>` 下都有自己的配置区段。请参阅对应的渠道页面获取设置步骤：
每个渠道在 `channels.<provider>` 下都有自己的配置节。请查看对应渠道页面了解设置步骤：
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
@ -140,7 +140,7 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
</Accordion>
<Accordion title="选择并配置模型">
<Accordion title="选择和配置模型">
设置主模型和可选回退模型：
```json5
@ -161,30 +161,30 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
```
- `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。除非传入 `--replace`，否则会移除条目的普通替换会被拒绝。
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不移除现有模型。除非传入 `--replace`，否则会拒绝会移除条目的普通替换。
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
- `agents.defaults.imageMaxDimensionPx` 控制转录记录/工具图片缩放（默认 `1200`）；较低的值通常会降低大量截图运行中的视觉 token 用量。
- 请参阅 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并参阅[模型故障转移](/zh-CN/concepts/model-failover)了解凭证轮换和回退行为。
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像降采样（默认 `1200`）；较低值通常会减少截图密集运行中的视觉 token 用量。
- 查看 [Models CLI](/zh-CN/concepts/models) 了解如何在聊天中切换模型，并查看 [Model Failover](/zh-CN/concepts/model-failover) 了解身份验证轮换和回退行为。
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/config-tools#custom-providers-and-base-urls)。
</Accordion>
<Accordion title="控制谁可以给 bot 发消息">
<Accordion title="控制谁可以向机器人发消息">
私信访问通过每个渠道的 `dmPolicy` 控制：
- `"pairing"`（默认）：未知发送者会收到一次性配对码用于批准
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对允许存储中的发送者）
- `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
- `"allowlist"`：仅允许 `allowFrom`（或已配对允许存储）中的发送者
- `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`）
- `"disabled"`：忽略所有私信
对于群组，使用 `groupPolicy` + `groupAllowFrom` 或渠道专用允许列表。
请参阅[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)了解每个渠道的细节。
查看[完整参考](/zh-CN/gateway/config-channels#dm-and-group-access)，了解每个渠道的详细信息。
</Accordion>
<Accordion title="设置群聊提及门控">
群组消息默认**需要提及**。为每个智能体配置触发模式，并让可见房间回复保持在默认消息工具路径上，除非你有意使用旧版自动最终回复：
群组消息默认**需要提及**。为每个智能体配置触发模式，并将可见房间回复保持在默认消息工具路径上，除非你有意想使用旧版自动最终回复：
```json5
{
@ -214,13 +214,13 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
- **文本模式**：`mentionPatterns` 中的安全正则模式
- **可见回复**：`messages.visibleReplies` 可以在全局要求通过消息工具发送；`messages.groupChat.visibleReplies` 会针对群组/渠道覆盖该设置。
- 请参阅[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)了解可见回复模式、每渠道覆盖以及自聊模式。
- **可见回复**：`messages.visibleReplies` 可以全局要求通过消息工具发送；`messages.groupChat.visibleReplies` 会为群组/渠道覆盖该设置。
- 查看[完整参考](/zh-CN/gateway/config-channels#group-chat-mention-gating)，了解可见回复模式、每渠道覆盖和自聊模式。
</Accordion>
<Accordion title="按智能体限制 Skills">
使用 `agents.defaults.skills` 作为共享基线，然后用
使用 `agents.defaults.skills` 设置共享基线，然后通过
`agents.list[].skills` 覆盖特定智能体：
```json5
@ -239,15 +239,15 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
```
- 省略 `agents.defaults.skills` 时，默认不限制 Skills。
- 省略 `agents.list[].skills` 时，会继承默认值。
- 省略 `agents.list[].skills` 以继承默认值。
- 设置 `agents.list[].skills: []` 表示没有 Skills。
- 请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及
- 查看 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和
[配置参考](/zh-CN/gateway/config-agents#agents-defaults-skills)。
</Accordion>
<Accordion title="调整 Gateway 网关渠道健康监控">
控制 Gateway 网关对看似停滞的渠道进行重启的积极程度：
控制 Gateway 网关重启看起来停滞的渠道的激进程度：
```json5
{
@ -271,14 +271,13 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 可为某个渠道或账号禁用自动重启，而不禁用全局监控。
- 请参阅[健康检查](/zh-CN/gateway/health)进行运维调试，并参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled` 禁用某个渠道或账号的自动重启，而不禁用全局监控。
- 查看 [Health Checks](/zh-CN/gateway/health) 了解操作调试，并查看[完整参考](/zh-CN/gateway/configuration-reference#gateway)了解所有字段。
</Accordion>
<Accordion title="调整 Gateway 网关 WebSocket 握手超时">
为本地客户端提供更多时间，以便在
负载较高或低功耗主机上完成预认证 WebSocket 握手：
在负载较高或性能较低的主机上，给本地客户端更多时间来完成身份验证前的 WebSocket 握手：
```json5
{
@ -290,7 +289,7 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- 默认值为 `15000` 毫秒。
- `OPENCLAW_HANDSHAKE_TIMEOUT_MS` 仍会优先用于一次性服务或 shell 覆盖。
- 优先修复启动/事件循环停顿；这个旋钮用于预热期间健康但较慢的主机。
- 优先修复启动/事件循环停顿；此旋钮用于预热期间健康但较慢的主机。
</Accordion>
@ -316,9 +315,9 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
```
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
- `threadBindings`：用于线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 请参阅[会话管理](/zh-CN/concepts/session)，了解作用域、身份链接和发送策略。
- 请参阅[完整参考](/zh-CN/gateway/config-agents#session)，了解所有字段。
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
- 关于作用域、身份链接和发送策略，请参阅[会话管理](/zh-CN/concepts/session)。
- 所有字段请参阅[完整参考](/zh-CN/gateway/config-agents#session)。
</Accordion>
@ -338,9 +337,9 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
}
```
请先构建镜像——从源码检出运行 `scripts/sandbox-setup.sh`，或从 npm 安装时参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。
先构建镜像——从源码检出运行 `scripts/sandbox-setup.sh`，或从 npm 安装时，参阅[沙箱隔离 § 镜像和设置](/zh-CN/gateway/sandboxing#images-and-setup)中的内联 `docker build` 命令。
请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)获取完整指南，并参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)了解所有选项。
完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/config-agents#agentsdefaultssandbox)。
</Accordion>
@ -373,35 +372,35 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
这会执行以下操作：
- 允许 Gateway 网关通过外部中继发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的注册作用域发送授权。Gateway 网关不需要部署范围的中继令牌。
- 将每个基于中继的注册绑定到 iOS 应用所配对的 Gateway 网关身份，这样其他 Gateway 网关无法复用已存储的注册。
- 让本地/手动 iOS 构建继续使用直连 APNs。基于中继的发送仅适用于通过中继注册的官方分发构建。
- 必须匹配内置到官方/TestFlight iOS 构建中的中继基础 URL，确保注册和发送流量到达同一个中继部署。
- 让 Gateway 网关通过外部中继发送 `push.test`、唤醒提示和重连唤醒。
- 使用由已配对 iOS 应用转发的、注册作用域内的发送授权。Gateway 网关不需要部署范围的中继令牌。
- 将每个基于中继的注册绑定到 iOS 应用配对的 Gateway 网关身份，因此另一个 Gateway 网关无法复用已存储的注册。
- 让本地/手动 iOS 构建继续使用直接 APNs。基于中继的发送仅适用于通过中继注册的官方分发构建。
- 必须匹配内置到官方/TestFlight iOS 构建中的中继基准 URL，这样注册和发送流量才会到达同一个中继部署。
端到端流程：
1. 安装使用相同中继基础 URL 编译的官方/TestFlight iOS 构建。
1. 安装使用相同中继基准 URL 编译的官方/TestFlight iOS 构建。
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
3. 将 iOS 应用与 Gateway 网关配对，并让节点和操作员会话都连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向中继注册，然后将基于中继的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
3. 将 iOS 应用与 Gateway 网关配对，并让节点会话和操作者会话都连接。
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 加应用收据向中继注册，然后将基于中继的 `push.apns.register` 载荷发布到已配对的 Gateway 网关。
5. Gateway 网关存储中继句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
运维说明：
- 如果将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布绑定到该 Gateway 网关的新中继注册。
- 如果发布的新 iOS 构建指向不同的中继部署，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它可以发布绑定到该 Gateway 网关的新中继注册。
- 如果你发布了指向不同中继部署的新 iOS 构建，应用会刷新其缓存的中继注册，而不是复用旧的中继来源。
兼容性说明：
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然是仅限 local loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍是仅限 local loopback 的开发逃生口；不要在配置中持久化 HTTP 中继 URL。
请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)了解端到端流程，并参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)了解中继安全模型。
端到端流程请参阅 [iOS 应用](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，中继安全模型请参阅[身份验证和信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。
</Accordion>
<Accordion title="设置 Heartbeat（周期性签到）">
<Accordion title="设置 Heartbeat（定期签到）">
```json5
{
agents: {
@ -417,8 +416,8 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
- `directPolicy`：面向私信式 Heartbeat 目标的 `allow`（默认）或 `block`
- 请参阅 [Heartbeat](/zh-CN/gateway/heartbeat) 获取完整指南。
- `directPolicy`：用于私信样式 Heartbeat 目标的 `allow`（默认）或 `block`
- 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
</Accordion>
@ -439,11 +438,11 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
- 请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)获取功能概览和 CLI 示例。
- 功能概览和 CLI 示例请参阅 [Cron 作业](/zh-CN/automation/cron-jobs)。
</Accordion>
<Accordion title="设置 Webhook（钩子）">
<Accordion title="设置 webhook（钩子）">
在 Gateway 网关上启用 HTTP webhook 端点：
```json5
@ -468,20 +467,20 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
```
安全说明：
- 将所有钩子/webhook 负载内容都视为不受信任的输入。
- 使用专用的 `hooks.token`；不要复用共享 Gateway 网关令牌。
- 钩子认证仅支持标头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口保留在专用子路径上，例如 `/hooks`。
- 将所有 hook/webhook 载荷内容视为不可信输入。
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关令牌。
- Hook 身份验证仅使用标头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串令牌会被拒绝。
- `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径上，例如 `/hooks`。
- 除非进行严格限定范围的调试，否则请保持不安全内容绕过标志禁用（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
- 如果启用 `hooks.allowRequestSessionKey`，还要设置 `hooks.allowedSessionKeyPrefixes`，以约束调用方选择的会话键。
- 对于钩子驱动的智能体，优先使用强大的现代模型层级和严格工具策略（例如仅消息发送，并尽可能结合沙箱隔离）。
- 如果你启用 `hooks.allowRequestSessionKey`，还应设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方选择的会话键。
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并尽可能加上沙箱隔离）。
请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)，了解所有映射选项和 Gmail 集成。
所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
</Accordion>
<Accordion title="配置多智能体路由">
使用独立工作区和会话运行多个隔离智能体：
运行多个隔离智能体，并使用独立的工作区和会话：
```json5
{
@ -498,11 +497,11 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
}
```
请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)，了解绑定规则和每智能体访问配置文件。
绑定规则和每智能体访问配置文件请参阅 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/config-agents#multi-agent-routing)。
</Accordion>
<Accordion title="将配置拆分为多个文件（$include）">
<Accordion title="将配置拆分到多个文件（$include）">
使用 `$include` 组织大型配置：
```json5
@ -518,25 +517,26 @@ OpenClaw 只接受完全匹配 schema 的配置。未知键名、格式错误的
- **单个文件**：替换包含它的对象
- **文件数组**：按顺序深度合并（后者优先）
- **同级键**：在 include 后合并（覆盖已 include 的值）
- **嵌套 include**：最多支持 10 层深度
- **相对路径**：相对于发起 include 的文件解析
- **OpenClaw 所有的写入**：当一次写入只更改一个由单文件 include 支持的顶层区段时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被 include 的文件，并保持 `openclaw.json` 不变
- **不支持的写穿**：对于 OpenClaw 所有的写入，根 include、include 数组以及带同级覆盖的 include 会以失败关闭方式处理，而不是展平配置
- **错误处理**：针对缺失文件、解析错误和循环 include 提供清晰错误
- **同级键**：在 include 之后合并（覆盖已包含的值）
- **嵌套 include**：支持最多 10 层深度
- **相对路径**：相对于发起包含的文件解析
- **OpenClaw 拥有的写入**：当某次写入只更改一个顶层部分，且该部分由单文件 include 支持，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
- **不支持的透传写入**：根 include、include 数组，以及带有同级覆盖的 include，会对 OpenClaw 拥有的写入失败关闭，而不是将配置扁平化
- **约束范围**：`$include` 路径必须解析到包含 `openclaw.json` 的目录下。若要在多台机器或多个用户之间共享一棵目录树，请将 `OPENCLAW_INCLUDE_ROOTS` 设置为由路径组成的列表（POSIX 上用 `:`，Windows 上用 `;`），这些额外目录可供 include 引用。符号链接会被解析并重新检查，因此即使某个路径在字面上位于配置目录中，只要其真实目标逃逸出所有允许的根目录，仍会被拒绝。
- **错误处理**：针对缺失文件、解析错误和循环 include 给出清晰错误
</Accordion>
</AccordionGroup>
## 配置热重载
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——大多数设置无需手动重启。
Gateway 网关会监视 `~/.openclaw/openclaw.json`，并自动应用更改——大多数设置不需要手动重启。
直接文件编辑在验证通过前会被视为不受信任。监视器会等待编辑器临时写入/重命名抖动平稳下来，读取最终文件，并通过恢复上一个已知良好配置来拒绝无效的外部编辑。OpenClaw 所有的配置写入在写入前也使用相同的 schema 门禁；破坏性覆盖（例如移除 `gateway.mode`，或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。
直接文件编辑在通过验证前会被视为不可信。监视器会等待编辑器临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复最后已知良好的配置来拒绝无效的外部编辑。OpenClaw 拥有的配置写入在写入前使用相同的 schema 门禁；破坏性覆盖（例如删除 `gateway.mode` 或将文件缩小超过一半）会被拒绝，并保存为 `.rejected.*` 以供检查。
插件本地验证失败是例外：如果所有问题都位于 `plugins.entries.<id>...` 下，重载会保留当前配置并报告插件问题，而不是恢复 `.last-good`。
如果在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)获取恢复检查清单。
如果你在日志中看到 `Config auto-restored from last-known-good` 或 `config reload restored last-known-good config`，请检查 `openclaw.json` 旁边匹配的 `.clobbered.*` 文件，修复被拒绝的载荷，然后运行 `openclaw config validate`。恢复检查清单请参阅 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
### 重载模式
@ -557,45 +557,51 @@ Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——
### 哪些会热应用，哪些需要重启
大多数字段无需停机即可热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
大多数字段会在不停机的情况下热应用。在 `hybrid` 模式中，需要重启的更改会自动处理。
| 类别 | 字段 | 需要重启？ |
| 类别 | 字段 | 是否需要重启？ |
| ------------------- | ----------------------------------------------------------------- | --------------- |
| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 |
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
| 会话和消息 | `session`、`messages` | 否 |
| 工具和媒体 | `tools`、`browser`、`skills`、`mcp`、`audio`、`talk` | 否 |
| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
| Gateway 网关服务器 | `gateway.*`（端口、绑定、认证、tailscale、TLS、HTTP） | **是** |
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
| 渠道 | `channels.*`, `web` (WhatsApp) — 所有内置和插件渠道 | 否 |
| 智能体与模型 | `agent`, `agents`, `models`, `routing` | 否 |
| 自动化 | `hooks`, `cron`, `agent.heartbeat` | 否 |
| 会话与消息 | `session`, `messages` | 否 |
| 工具与媒体 | `tools`, `browser`, `skills`, `mcp`, `audio`, `talk` | 否 |
| UI 与其他 | `ui`, `logging`, `identity`, `bindings` | 否 |
| Gateway 网关服务器 | `gateway.*` (port, bind, auth, tailscale, TLS, HTTP) | **是** |
| 基础设施 | `discovery`, `canvasHost`, `plugins` | **是** |
<Note>
`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。
`gateway.reload` 和 `gateway.remote` 是例外 — 修改它们**不会**触发重启。
</Note>
### 重载规划
编辑通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局来规划重新加载，而不是根据展开后的内存视图。这样即使单个顶层区段位于自己的包含文件中，例如 `plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也保持可预测。如果源布局存在歧义，重新加载规划会默认失败并保持关闭。
当你编辑通过 `$include` 引用的源文件时，OpenClaw 会根据源文件编写时的布局来规划重载，而不是根据扁平化的内存视图。
这样即使某个顶层区段位于自己的 include 文件中，例如
`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也能保持可预测。
如果源布局有歧义，重载规划会失败并采用保守处理。
## 配置 RPC（程序化更新）
对于通过 Gateway 网关 API 写入配置的工具，优先使用此流程：
对于通过 Gateway 网关 API 写入配置的工具，建议使用以下流程：
- `config.schema.lookup` 用于检查一个子树（浅层 schema 节点 + 子项摘要）
- `config.get` 用于获取当前快照和 `hash`
- `config.patch` 用于部分更新（JSON merge patch：对象合并，`null` 删除，数组替换）
- `config.apply` 仅在你打算替换整个配置时使用
- `update.run` 用于显式自我更新并重启
- `update.status` 用于检查最新的更新重启哨兵，并在重启后验证正在运行的版本
- `config.get` 用于获取当前快照以及 `hash`
- `config.patch` 用于局部更新（JSON merge patch：对象合并，`null` 删除，数组替换）
- 只有在你打算替换整个配置时才使用 `config.apply`
- `update.run` 用于显式自更新并重启
- `update.status` 用于检查最新的更新重启 sentinel，并在重启后验证正在运行的版本
智能体应将 `config.schema.lookup` 作为获取精确字段级文档和约束的第一入口。当它们需要更完整的配置映射、默认值，或指向专用子系统参考的链接时，请使用 [配置参考](/zh-CN/gateway/configuration-reference)。
智能体应将 `config.schema.lookup` 视为获取精确字段级文档和约束的第一站。
当需要更完整的配置映射、默认值或指向专用子系统参考的链接时，使用 [配置参考](/zh-CN/gateway/configuration-reference)。
<Note>
控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 每 60 秒 3 个请求进行速率限制。重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。`update.status` 是只读的，但属于管理员作用域，因为重启哨兵可能包含更新步骤摘要和命令输出尾部。
控制平面写入（`config.apply`、`config.patch`、`update.run`）会按 `deviceId+clientIp` 限制为每 60 秒 3 个请求。
重启请求会合并，然后在重启周期之间强制执行 30 秒冷却时间。
`update.status` 是只读的，但属于管理员范围，因为重启 sentinel 可能包含更新步骤摘要和命令输出尾部。
</Note>
部分 patch 示例：
局部补丁示例：
```bash
openclaw gateway call config.get --params '{}' # capture payload.hash
@ -605,11 +611,12 @@ openclaw gateway call config.patch --params '{
}'
```
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。当配置已存在时，两个方法都必须提供 `baseHash`。
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。
当配置已经存在时，这两个方法都要求提供 `baseHash`。
## 环境变量
OpenClaw 会从父进程读取环境变量，另外还会读取：
OpenClaw 从父进程以及以下位置读取环境变量：
- 当前工作目录中的 `.env`（如果存在）
- `~/.openclaw/.env`（全局回退）
@ -626,7 +633,7 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
```
<Accordion title="Shell 环境导入（可选）">
如果启用且预期键名未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：
如果启用且未设置预期键名，OpenClaw 会运行你的登录 shell，并且只导入缺失的键：
```json5
{
@ -640,7 +647,7 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
</Accordion>
<Accordion title="配置值中的环境变量替换">
可在任意配置字符串值中用 `${VAR_NAME}` 引用环境变量：
在任何配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
```json5
{
@ -653,13 +660,13 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
- 只匹配大写名称：`[A-Z_][A-Z0-9_]*`
- 缺失或为空的变量会在加载时抛出错误
- 使用 `$${VAR}` 转义以输出字面量
- 适用于 `$include` 文件内部
- 使用 `$${VAR}` 转义以输出字面值
- 可在 `$include` 文件中使用
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
</Accordion>
<Accordion title="Secret 引用（env、file、exec）">
<Accordion title="Secret refs（env、file、exec）">
对于支持 SecretRef 对象的字段，你可以使用：
```json5
@ -692,21 +699,22 @@ OpenClaw 会从父进程读取环境变量，另外还会读取：
}
```
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）位于 [Secrets Management](/zh-CN/gateway/secrets)。支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
SecretRef 详情（包括用于 `env`/`file`/`exec` 的 `secrets.providers`）见 [Secrets Management](/zh-CN/gateway/secrets)。
支持的凭据路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
</Accordion>
完整优先级和来源请参见 [环境](/zh-CN/help/environment)。
完整的优先级和来源见 [Environment](/zh-CN/help/environment)。
## 完整参考
如需完整的逐字段参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。
完整的逐字段参考请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
---
_相关：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
_相关：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
## 相关
- [配置参考](/zh-CN/gateway/configuration-reference)
- [配置示例](/zh-CN/gateway/configuration-examples)
- [Configuration examples](/zh-CN/gateway/configuration-examples)
- [Gateway 网关 runbook](/zh-CN/gateway)

99
docs/zh-CN/help/environment.md
View File

@ -1,36 +1,36 @@
---
read_when:
- 你需要知道会加载哪些环境变量，以及加载顺序
- 你正在调试 Gateway 网关中缺失的 API 密钥
- 你正在编写提供商凭证或部署环境的文档
summary: OpenClaw 加载环境变量的位置以及优先级顺序
- 你需要知道哪些环境变量会被加载，以及加载顺序
- 你正在排查 Gateway 网关中缺失的 API 密钥
- 你正在编写提供商身份验证或部署环境文档
summary: OpenClaw 加载环境变量的位置及优先级顺序
title: 环境变量
x-i18n:
generated_at: "2026-04-28T11:55:18Z"
generated_at: "2026-05-01T21:15:43Z"
model: gpt-5.5
provider: openai
source_hash: d19b9053207a088b3eb39d03e36fc2d415295feb80da51bd71339884466b101b
source_hash: 66787dd6f87dcaf81f721465e88dda519421b1a598179f71bce0239bb4791c46
source_path: help/environment.md
workflow: 16
---
OpenClaw 会从多个来源读取环境变量。规则是**绝不覆盖现有值**。
OpenClaw 会从多个来源读取环境变量。规则是 **绝不覆盖已有值**。
## 优先级（最高 → 最低）
1. **进程环境**（Gateway 网关进程已经从父 shell/守护进程继承的内容）。
1. **进程环境**（Gateway 网关进程已从父级命令行解释器/守护进程继承的内容）。
2. **当前工作目录中的 `.env`**（dotenv 默认行为；不会覆盖）。
3. **全局 `.env`**，位于 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`；不会覆盖）。
3. **全局 `.env`**，位于 `~/.openclaw/.env`（也就是 `$OPENCLAW_STATE_DIR/.env`；不会覆盖）。
4. **配置 `env` 块**，位于 `~/.openclaw/openclaw.json`（仅在缺失时应用）。
5. **可选登录 shell 导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅应用于缺失的预期键名。
5. **可选登录命令行环境导入**（`env.shellEnv.enabled` 或 `OPENCLAW_LOAD_SHELL_ENV=1`），仅对缺失的预期键名应用。
在使用默认状态目录的 Ubuntu 全新安装中，OpenClaw 还会在全局 `.env` 之后，将 `~/.config/openclaw/gateway.env` 作为兼容性回退项。如果两个文件都存在且内容不一致，OpenClaw 会保留 `~/.openclaw/.env` 并打印警告。
在使用默认状态目录的 Ubuntu 全新安装中，OpenClaw 还会在全局 `.env` 之后将 `~/.config/openclaw/gateway.env` 视为兼容性回退。如果两个文件都存在且内容不一致，OpenClaw 会保留 `~/.openclaw/.env` 并打印警告。
如果配置文件完全缺失，则跳过第 4 步；如果已启用 shell 导入，它仍会运行。
如果配置文件完全缺失，则跳过第 4 步；如果已启用，命令行环境导入仍会运行。
## 配置 `env` 块
有两种等效方式可以设置内联环境变量（两者都不会覆盖）：
设置内联环境变量有两种等效方式（两者都不会覆盖已有值）：
```json5
{
@ -43,9 +43,9 @@ OpenClaw 会从多个来源读取环境变量。规则是**绝不覆盖现有值
}
```
## Shell 环境导入
## 命令行环境导入
`env.shellEnv` 会运行你的登录 shell，并且只导入**缺失**的预期键名：
`env.shellEnv` 会运行你的登录命令行解释器，并仅导入**缺失的**预期键名：
```json5
{
@ -58,28 +58,28 @@ OpenClaw 会从多个来源读取环境变量。规则是**绝不覆盖现有值
}
```
环境变量等效项：
环境变量等价项：
- `OPENCLAW_LOAD_SHELL_ENV=1`
- `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`
## 运行时注入的环境变量
OpenClaw 还会将上下文标记注入到派生的子进程中：
OpenClaw 还会向派生的子进程注入上下文标记：
- `OPENCLAW_SHELL=exec`：为通过 `exec` 工具运行的命令设置。
- `OPENCLAW_SHELL=acp`：为 ACP 运行时后端进程派生设置（例如 `acpx`）。
- `OPENCLAW_SHELL=acp-client`：为 `openclaw acp client` 派生 ACP 桥接进程时设置。
- `OPENCLAW_SHELL=tui-local`：为本地 TUI `!` shell 命令设置。
- `OPENCLAW_SHELL=acp`：为 ACP 运行时后端进程启动设置（例如 `acpx`）。
- `OPENCLAW_SHELL=acp-client`：在 `openclaw acp client` 启动 ACP 桥接进程时设置。
- `OPENCLAW_SHELL=tui-local`：为本地 TUI `!` 命令行命令设置。
这些是运行时标记（不是必需的用户配置）。它们可用于 shell/profile 逻辑，
这些是运行时标记（不是必需的用户配置）。它们可用于命令行环境/配置文件逻辑
以应用特定于上下文的规则。
## UI 环境变量
- `OPENCLAW_THEME=light`：当你的终端使用浅色背景时，强制使用浅色 TUI 调色板。
- `OPENCLAW_THEME=dark`：强制使用深色 TUI 调色板。
- `COLORFGBG`：如果你的终端导出它，OpenClaw 会使用背景色提示来自动选择 TUI 调色板。
- `COLORFGBG`：如果你的终端导出它，OpenClaw 会使用背景颜色提示来自动选择 TUI 调色板。
## 配置中的环境变量替换
@ -97,34 +97,35 @@ OpenClaw 还会将上下文标记注入到派生的子进程中：
}
```
请参阅[配置：环境变量替换](/zh-CN/gateway/configuration-reference#env-var-substitution)了解详情。
了解详情，请参阅 [配置：环境变量替换](/zh-CN/gateway/configuration-reference#env-var-substitution)。
## Secret 引用与 `${ENV}` 字符串
## 密钥引用与 `${ENV}` 字符串
OpenClaw 支持两种由环境变量驱动的模式：
- 在配置值中进行 `${VAR}` 字符串替换。
- 对于支持密钥引用的字段，使用 SecretRef 对象（`{ source: "env", provider: "default", id: "VAR" }`）。
- 配置值中的 `${VAR}` 字符串替换。
- SecretRef 对象（`{ source: "env", provider: "default", id: "VAR" }`），用于支持密钥引用的字段。
两者都会在激活时从进程环境解析。SecretRef 详情记录在[密钥管理](/zh-CN/gateway/secrets)中。
两者都会在激活时从进程环境变量解析。SecretRef 的详细信息见 [密钥管理](/zh-CN/gateway/secrets)。
## 路径相关环境变量
| 变量 | 用途 |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_HOME` | 覆盖用于所有内部路径解析的主目录（`~/.openclaw/`、智能体目录、会话、凭据）。当以专用服务用户身份运行 OpenClaw 时很有用。 |
| `OPENCLAW_STATE_DIR` | 覆盖状态目录（默认 `~/.openclaw`）。 |
| `OPENCLAW_CONFIG_PATH` | 覆盖配置文件路径（默认 `~/.openclaw/openclaw.json`）。 |
| 变量 | 用途 |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OPENCLAW_HOME` | 覆盖用于所有内部路径解析的主目录（`~/.openclaw/`、智能体目录、会话、凭证）。当以专用服务用户身份运行 OpenClaw 时很有用。 |
| `OPENCLAW_STATE_DIR` | 覆盖状态目录（默认 `~/.openclaw`）。 |
| `OPENCLAW_CONFIG_PATH` | 覆盖配置文件路径（默认 `~/.openclaw/openclaw.json`）。 |
| `OPENCLAW_INCLUDE_ROOTS` | 目录的路径列表；`$include` 指令可通过这些目录解析配置目录之外的文件（默认：无 — `$include` 被限制在配置目录内）。会展开波浪号。 |
## 日志
## 日志记录
| 变量 | 用途 |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_LOG_LEVEL` | 覆盖文件和控制台的日志级别（例如 `debug`、`trace`）。优先级高于配置中的 `logging.level` 和 `logging.consoleLevel`。无效值会被忽略并显示警告。 |
| 变量 | 用途 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OPENCLAW_LOG_LEVEL` | 同时覆盖文件和控制台的日志级别（例如 `debug`、`trace`）。优先于配置中的 `logging.level` 和 `logging.consoleLevel`。无效值会被忽略并发出警告。 |
### `OPENCLAW_HOME`
设置后，`OPENCLAW_HOME` 会替代系统主目录（`$HOME` / `os.homedir()`）用于所有内部路径解析。这可为无头服务账号启用完整的文件系统隔离。
设置后，`OPENCLAW_HOME` 会在所有内部路径解析中替代系统主目录（`$HOME` / `os.homedir()`）。这可为无头服务账户实现完整的文件系统隔离。
**优先级：** `OPENCLAW_HOME` > `$HOME` > `USERPROFILE` > `os.homedir()`
@ -138,20 +139,20 @@ OpenClaw 支持两种由环境变量驱动的模式：
</dict>
```
`OPENCLAW_HOME` 也可以设置为波浪号路径（例如 `~/svc`），使用前会通过 `$HOME` 展开。
也可以将 `OPENCLAW_HOME` 设置为波浪号路径（例如 `~/svc`），使用前会通过 `$HOME` 展开。
## nvm 用户：web_fetch TLS 失败
如果 Node.js 是通过 **nvm** 安装的（而不是系统包管理器），内置的 `fetch()` 会使用
nvm 捆绑的 CA 存储，其中可能缺少现代根 CA（用于 Let's Encrypt 的 ISRG Root X1/X2、
DigiCert Global Root G2 等）。这会导致 `web_fetch` 在大多数 HTTPS 站点上因 `"fetch failed"` 而失败。
如果 Node.js 是通过 **nvm**（而不是系统包管理器）安装的，内置 `fetch()` 会使用
nvm 捆绑的 CA 存储，其中可能缺少较新的根 CA（用于 Let's Encrypt 的 ISRG Root X1/X2、
DigiCert Global Root G2 等）。这会导致 `web_fetch` 在大多数 HTTPS 站点上以 `"fetch failed"` 失败。
在 Linux 上，OpenClaw 会自动检测 nvm，并在实际启动环境中应用修复：
- `openclaw gateway install` 会将 `NODE_EXTRA_CA_CERTS` 写入 systemd 服务环境
- `openclaw` CLI 入口点会在 Node 启动前，带着已设置的 `NODE_EXTRA_CA_CERTS` 重新执行自身
- `openclaw` CLI 入口点会在 Node 启动前设置 `NODE_EXTRA_CA_CERTS` 并重新执行自身
**手动修复（适用于较旧版本或直接 `node ...` 启动）：**
**手动修复（用于旧版本或直接 `node ...` 启动）：**
在启动 OpenClaw 前导出该变量：
@ -166,17 +167,15 @@ openclaw gateway run
## 旧版环境变量
OpenClaw 只读取 `OPENCLAW_*` 环境变量。早期版本中的旧版
`CLAWDBOT_*` 和 `MOLTBOT_*` 前缀会被静默
忽略。
`CLAWDBOT_*` 和 `MOLTBOT_*` 前缀会被静默忽略。
如果 Gateway 网关进程启动时仍设置了其中任何变量，OpenClaw 会发出一条
Node 弃用警告（`OPENCLAW_LEGACY_ENV_VARS`），列出
检测到的前缀和总数。请将每个值的旧版前缀替换为
`OPENCLAW_` 来重命名（例如 `CLAWDBOT_GATEWAY_TOKEN` →
如果启动时 Gateway 网关进程上仍设置了其中任何变量，OpenClaw 会发出一条
Node 弃用警告（`OPENCLAW_LEGACY_ENV_VARS`），列出检测到的前缀和总数。请将每个值重命名，方法是用
`OPENCLAW_` 替换旧版前缀（例如 `CLAWDBOT_GATEWAY_TOKEN` →
`OPENCLAW_GATEWAY_TOKEN`）；旧名称不会生效。
## 相关内容
- [Gateway 网关配置](/zh-CN/gateway/configuration)
- [常见问题：环境变量与 .env 加载](/zh-CN/help/faq#env-vars-and-env-loading)
- [常见问题：环境变量和 .env 加载](/zh-CN/help/faq#env-vars-and-env-loading)
- [Models 概览](/zh-CN/concepts/models)