英文 Gateway Security

2026年4月5日约 19 分钟

原始链接：https://docs.openclaw.ai/gateway/security
来源章节：4. 官方文档：核心概念、模型与安全
来源小节：无
抓取方式：jina:https://r.jina.ai/http://docs.openclaw.ai/gateway/security
抓取时间：2026-04-05 13:47:10
状态：ok

中文内容

范围第一：个人助理安全模型

OpenClaw 安全指南假设个人助理部署：一个受信任的操作员边界，可能有多个代理。

支持的安全态势：每个网关一个用户/信任边界（首选每个边界一个操作系统用户/主机/VPS）。
不是受支持的安全边界：由相互不信任或敌对的用户使用的一个共享网关/代理。
如果需要敌对用户隔离，请按信任边界进行划分（单独的网关+凭据，最好是单独的操作系统用户/主机）。
如果多个不受信任的用户可以向一个支持工具的代理发送消息，请将他们视为共享该代理的相同委派工具权限。

本页解释了该模型内的强化。它并不声称在一个共享网关上进行敌对多租户隔离。

快速检查：`openclaw 安全审核`

另请参阅：形式验证（安全模型）定期运行此命令（尤其是在更改配置或公开网络表面之后）：

openclaw安全审计
openclaw安全审计--deep
openclaw 安全审计--修复
openclaw 安全审计--json

securityaudit--fix 故意保持狭窄：它将常见的开放组策略翻转到白名单，恢复 logging.redactSensitive: "tools"，收紧状态/配置/包含文件权限，并在 Windows 上运行时使用 Windows ACL 重置而不是 POSIX chmod。它标记常见的脚枪（网关身份验证暴露、浏览器控制暴露、提升的白名单、文件系统权限、许可执行批准和开放通道工具） OpenClaw 既是一个产品，也是一个实验：您将前沿模型行为连接到真实的消息传递界面和真实的工具中。 **不存在“完全安全”的设置。**目标是深思熟虑：

谁可以与你的机器人交谈
允许机器人行动的地方
机器人可以触摸什么

从仍然有效的最小访问开始，然后当您获得信心时扩大它。

部署和主机信任

OpenClaw 假设主机和配置边界是可信的：

如果有人可以修改网关主机状态/配置（~/.openclaw，包括openclaw.json），请将他们视为可信操作员。
为多个相互不信任/敌对的运营商运行一个网关不推荐设置。
对于混合信任团队，使用单独的网关（或至少单独的操作系统用户/主机）分割信任边界。
建议的默认值：每台计算机/主机（或 VPS）一个用户，该用户一个网关，以及该网关中的一个或多个代理。
在一个网关实例内，经过身份验证的操作员访问是受信任的控制平面角色，而不是每用户租户角色。
会话标识符（sessionKey、会话 ID、标签）是路由选择器，而不是授权令牌。
如果几个人可以向一个支持工具的代理发送消息，那么每个人都可以控制相同的权限集。每用户会话/内存隔离有助于保护隐私，但不会将共享代理转换为每用户主机授权。

共享 Slack 工作空间：真正的风险

如果“Slack 中的每个人都可以向机器人发送消息”，那么核心风险就是工具授权：

任何允许的发送者都可以在代理策略内引发工具调用（exec、浏览器、网络/文件工具）；
来自一个发送者的提示/内容注入可能会导致影响共享状态、设备或输出的操作；
如果一个共享代理具有敏感凭据/文件，则任何允许的发件人都可能通过工具使用来推动渗透。

使用单独的代理/网关和最少的工具来实现团队工作流程；确保个人数据代理的私密性。

公司共享代理：可接受的模式

当使用该代理的每个人都处于同一信任边界（例如一个公司团队）并且该代理严格限于业务范围时，这是可以接受的。

在专用机器/虚拟机/容器上运行； *为该运行时使用专用操作系统用户+专用浏览器/配置文件/帐户；
请勿将该运行时登录到个人 Apple/Google 帐户或个人密码管理器/浏览器配置文件中。

如果您在同一运行时混合个人和公司身份，则会破坏分离并增加个人数据暴露风险。

网关和节点信任概念

将网关和节点视为一个运营商信任域，具有不同的角色：

网关是控制平面和策略表面（gateway.auth、工具策略、路由）。
节点是与该网关配对的远程执行表面（命令、设备操作、主机本地功能）。
通过网关身份验证的调用者在网关范围内受到信任。配对后，节点操作是该节点上可信的操作员操作。
sessionKey 是路由/上下文选择，而不是每用户身份验证。
执行批准（白名单+询问）是操作员意图的护栏，而不是敌对的多租户隔离。
OpenClaw 对于可信单操作员设置的产品默认设置是允许在“gateway”/“node”上执行主机执行，无需批准提示（“security="full”、“ask="off”，除非您收紧它）。这种默认设置是故意的用户体验，而不是其本身的漏洞。
Exec 批准绑定精确的请求上下文和尽力直接的本地文件操作数；它们不会对每个运行时/解释器加载器路径进行语义建模。使用沙箱和主机隔离来实现牢固的边界。

如果您需要敌意用户隔离，请按操作系统用户/主机分割信任边界并运行单独的网关。

信任边界矩阵

在分类风险时使用此模型作为快速模型：

边界或控制	这意味着什么	常见误读
`gateway.auth`（令牌/密码/可信代理/设备身份验证）	对网关 API 的调用者进行身份验证	“需要在每一帧上对每条消息进行签名才能确保安全”
`会话密钥`	用于上下文/会话选择的路由键	“会话密钥是用户身份验证边界”
提示/内容护栏	降低模型滥用风险	“仅提示注入就证明了身份验证绕过”
`canvas.eval` / 浏览器评估	启用后的有意操作员能力	“任何 JS eval 原语都会自动成为此信任模型中的漏洞”
本地 TUI `!` shell	显式操作符触发的本地执行	“本地shell便捷命令是远程注入”
节点配对和节点命令	在配对设备上进行操作员级远程执行	“默认情况下，远程设备控制应被视为不受信任的用户访问”

并非设计缺陷

这些模式通常会被报告，并且通常会作为无操作关闭，除非显示真正的边界旁路：

仅提示注入链，无需绕过策略/身份验证/沙箱。
声称在一台共享主机/配置上进行恶意多租户操作。
将普通操作员读取路径访问（例如 sessions.list/sessions.preview/chat.history）分类为共享网关设置中的 IDOR 的声明。
仅本地主机部署结果（例如仅环回网关上的 HSTS）。
不一致此存储库中不存在的入站路径的入站 Webhook 签名结果。
当真正的执行边界仍然是网关的全局节点命令策略加上节点自己的执行批准时，将节点配对元数据视为“system.run”的隐藏的第二个每命令批准层的报告。
“缺少每用户授权”的调查结果将“sessionKey”视为身份验证令牌。

研究人员飞行前检查清单

在开设 GHSA 之前，请验证所有这些内容：

Repro 仍然适用于最新的“main”或最新版本。
报告包括确切的代码路径（“文件”、函数、行范围）和测试版本/提交。
影响跨越了记录的信任边界（不仅仅是即时注入）。
声明未在超出范围中列出。
检查现有建议是否有重复（如果适用，重复使用规范的 GHSA）。
部署假设是明确的（环回/本地与暴露、可信与不可信运营商）。

60 秒内硬化基线

首先使用此基线，然后有选择地重新启用每个受信任代理的工具：

{
  网关：{
    模式：“本地”，
    绑定：“环回”，
    auth: { 模式: "令牌", 令牌: "替换为长随机令牌" },
  },
  会话：{
    dmScope：“每个通道对等”，
  },
  工具：{
    个人资料：“消息传递”，
    拒绝：[“组：自动化”，“组：运行时”，“组：fs”，“sessions_spawn”，“sessions_send”]，
    fs: {workspaceOnly: true },
    exec: { 安全: "拒绝", 询问: "总是" },
    提升：{启用：假}，
  },
  频道：{
    Whatsapp: { dmPolicy: "配对", groups: { "*": { requireMention: true } } },
  },
}

这使得网关仅在本地，隔离 DM，并默认禁用控制平面/运行时工具。

如果不止一个人可以通过 DM 发送您的机器人：

设置 session.dmScope: "per-channel-peer" （对于多帐户通道，设置 "per-account-channel-peer"）。
保留 dmPolicy: "pairing" 或严格的白名单。
切勿将共享 DM 与广泛的工具访问权限结合起来。
这强化了合作/共享收件箱，但在用户共享主机/配置写入访问权限时并未设计为敌对共租户隔离。

上下文可见性模型

OpenClaw 区分了两个概念：

触发授权：谁可以触发代理（dmPolicy、groupPolicy、白名单、提及门）。
上下文可见性：将哪些补充上下文注入到模型输入中（回复正文、引用文本、线程历史记录、转发的元数据）。

将门触发器和命令授权列入白名单。 contextVisibility 设置控制如何过滤补充上下文（引用的回复、线程根、获取的历史记录）：

contextVisibility: "all"（默认）保留收到的补充上下文。
contextVisibility: "allowlist" 过滤活动白名单检查允许的发件人的补充上下文。
contextVisibility: "allowlist_quote" 的行为类似于 allowlist，但仍保留一个明确引用的回复。

设置每个频道或每个房间/对话的“contextVisibility”。有关设置详细信息，请参阅群聊。咨询分类指导：

仅显示“模型可以看到来自非允许列表发件人的引用或历史文本”的声明正在强化可通过“contextVisibility”解决的发现，而不是通过自身绕过身份验证或沙箱边界。
为了影响安全，报告仍然需要经过验证的信任边界旁路（身份验证、策略、沙箱、批准或其他记录的边界）。

审核检查的内容（高级别）

入站访问（DM 策略、组策略、白名单）：陌生人可以触发机器人吗？
工具爆炸半径（高架工具+开放房间）：提示注入可以变成shell/文件/网络操作吗？
Exec 批准漂移（security=full、autoAllowSkills、没有 strictInlineEval 的解释器白名单）：主机执行护栏仍在执行您认为的操作吗？
- security="full" 是一个广泛的态势警告，而不是错误的证据。这是可信个人助理设置的默认选择；仅当您的威胁模型需要批准或列入白名单时才收紧它。
网络暴露（网关绑定/身份验证、Tailscale 服务/漏斗、弱/短身份验证令牌）。
浏览器控制暴露（远程节点、中继端口、远程 CDP 端点）。
本地磁盘卫生（权限、符号链接、配置包含、“同步文件夹”路径）。
插件（没有明确允许列表的情况下存在扩展）。
策略漂移/错误配置（配置了沙箱泊坞窗设置，但沙箱模式关闭；无效的 gateway.nodes.denyCommands 模式，因为匹配仅是精确的命令名称（例如 system.run）并且不检查 shell 文本；危险的 gateway.nodes.allowCommands 条目；每个代理配置文件覆盖全局 tools.profile="minimal"；在许可工具策略下可访问扩展插件工具）。
运行时期望漂移（例如，当“tools.exec.host”现在默认为“auto”时，假设隐式执行仍然意味着“sandbox”，或者在沙箱模式关闭时显式设置“tools.exec.host =“sandbox””）。
模型卫生（当配置的模型看起来是遗留的时发出警告；不是硬块）。

如果您运行“--deep”，OpenClaw 还会尝试尽力实时网关探测。

凭证存储映射

在审核访问或决定备份内容时使用此选项：

WhatsApp：~/.openclaw/credentials/whatsapp/<accountId>/creds.json
Telegram 机器人令牌：config/env 或 channels.telegram.tokenFile （仅限常规文件；符号链接被拒绝）
Discord 机器人令牌：config/env 或 SecretRef（env/file/exec 提供程序）
Slack 令牌：config/env (channels.slack.*)
配对允许名单：
- ~/.openclaw/credentials/<channel>-allowFrom.json （默认帐户）
- ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json（非默认帐户）
模型身份验证配置文件：~/.openclaw/agents/<agentId>/agent/auth-profiles.json
文件支持的秘密负载（可选）：~/.openclaw/secrets.json
旧版 OAuth 导入：~/.openclaw/credentials/oauth.json

安全审核清单

当审计打印结果时，请将此视为优先顺序：

任何“开放”+启用的工具：首先锁定 DM/组（配对/允许列表），然后收紧工具策略/沙箱。
公共网络暴露（LAN绑定、漏斗、缺少身份验证）：立即修复。
浏览器控制远程暴露：将其视为操作员访问（仅限尾网，刻意配对节点，避免公开暴露）。
权限：确保状态/配置/凭据/身份验证不是组/世界可读的。
插件/扩展：仅加载您明确信任的内容。
模型选择：对于任何带有工具的机器人，更喜欢现代的、指令强化的模型。

安全审计术语表

您很可能在实际部署中看到高信号 checkId 值（并非详尽无遗）：

`检查 ID`	严重性	为什么这很重要	主要修复密钥/路径	自动修复
`fs.state_dir.perms_world_writable`	关键	其他用户/进程可以修改完整的 OpenClaw 状态	`~/.openclaw` 上的文件系统权限	是的
`fs.state_dir.perms_group_writable`	警告	组用户可以修改完整的 OpenClaw 状态	`~/.openclaw` 上的文件系统权限	是的
`fs.state_dir.perms_read`	警告	状态目录可供其他人读取	`~/.openclaw` 上的文件系统权限	是的
`fs.state_dir.symlink`	警告	状态目录目标成为另一个信任边界	状态 dir 文件系统布局	没有
`fs.config.perms_writable`	关键	其他人可以更改身份验证/工具策略/配置	`~/.openclaw/openclaw.json` 上的文件系统权限	是的
`fs.config.symlink`	警告	配置目标成为另一个信任边界	配置文件文件系统布局	没有
`fs.config.perms_group_read`	警告	组用户可以读取配置令牌/设置	配置文件的文件系统权限	是的
`fs.config.perms_world_read`	关键	配置可以公开令牌/设置	配置文件的文件系统权限	是的
`fs.config_include.perms_writable`	关键	配置包括

pprovals.json|没有| |tools.exec.allowlist_interpreter_without_strict_inline_eval|警告|解释器白名单允许内联评估，无需强制重新批准 |tools.exec.strictInlineEval、agents.list[].tools.exec.strictInlineEval、exec 批准白名单 |没有| | tools.exec.safe_bins_interpreter_unprofiled|警告|没有明确配置文件的“safeBins”中的解释器/运行时 bin 会扩大执行风险 |tools.exec.safeBins、tools.exec.safeBinProfiles、agents.list[].tools.exec.*|没有| |tools.exec.safe_bins_broad_behavior|警告| “safeBins”中的广泛行为工具削弱了低风险的标准输入过滤器信任模型 |tools.exec.safeBins、agents.list[].tools.exec.safeBins|没有| |tools.exec.safe_bin_trusted_dirs_risky|警告|safeBinTrustedDirs包括可变或有风险的目录 |tools.exec.safeBinTrustedDirs、agents.list[].tools.exec.safeBinTrustedDirs|没有| |skills.workspace.symlink_escape|警告|工作空间skills//SKILL.md解析外部工作空间根（符号链接链漂移）|工作区skills/文件系统状态 |没有| |plugins.extensions_no_allowlist|警告|无需明确的插件白名单即可安装扩展 |plugins.allo

通过 HTTP 控制 UI

控制 UI 需要安全上下文（HTTPS 或本地主机）来生成设备标识。 gateway.controlUi.allowInsecureAuth 是本地兼容性切换：

在本地主机上，当通过非安全 HTTP 加载页面时，它允许在没有设备身份的情况下控制 UI 身份验证。
它不会绕过配对检查。
它不会放松远程（非本地主机）设备身份要求。

首选 HTTPS（Tailscale Serve）或在“127.0.0.1”上打开 UI。仅对于破碎玻璃场景，“gateway.controlUi.dangerouslyDisableDeviceAuth”完全禁用设备身份检查。这是严重的安全降级；除非您正在积极调试并且可以快速恢复，否则请将其关闭。与那些危险标志分开，成功的gateway.auth.mode：“trusted-proxy”可以允许操作员在没有设备身份的情况下控制UI会话。这是有意的身份验证模式行为，而不是“allowInsecureAuth”快捷方式，并且它仍然不会扩展到节点角色控制 UI 会话。启用此设置时，“openclaw 安全审核”会发出警告。

不安全或危险标志摘要

当启用已知的不安全/危险调试开关时，“openclaw 安全审核”包括“config.insecure_or_dangerous_flags”。该检查当前汇总：

gateway.controlUi.allowInsecureAuth=true
gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true
gateway.controlUi.dangerouslyDisableDeviceAuth=true
hooks.gmail.allowUnsafeExternalContent=true
hooks.mappings[<index>].allowUnsafeExternalContent=true
tools.exec.applyPatch.workspaceOnly=false
plugins.entries.acpx.config.permissionMode=approve-all

完成 OpenClaw 配置模式中定义的 dangerous* / dangerously* 配置键：

gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback
gateway.controlUi.dangerouslyDisableDeviceAuth
browser.ssrfPolicy.dangerouslyAllowPrivateNetwork
channels.discord.dangerouslyAllowNameMatching
channels.discord.accounts.<accountId>.dangerouslyAllowNameMatching
channels.slack.dangerouslyAllowNameMatching
channels.slack.accounts.<accountId>.dangerouslyAllowNameMatching
channels.googlechat.dangerouslyAllowNameMatching
channels.googlechat.accounts.<accountId>.dangerouslyAllowNameMatching
channels.msteams.dangerouslyAllowNameMatching
channels.synology-chat.dangerouslyAllowNameMatching（扩展频道）
channels.synology-chat.accounts.<accountId>.dangerouslyAllowNameMatching（扩展频道）
channels.synology-chat.dangerouslyAllowInheritedWebhookPath（扩展频道）
channels.zalouuser.dangerouslyAllowNameMatching（扩展频道）
channels.zalouuser.accounts.<accountId>.dangerouslyAllowNameMatching（扩展频道）
channels.irc.dangerouslyAllowNameMatching（扩展频道）
channels.irc.accounts.<accountId>.dangerouslyAllowNameMatching（扩展频道） *`陈

els.mattermost.dangerouslyAllowNameMatching`（扩展通道）

channels.mattermost.accounts.<accountId>.dangerouslyAllowNameMatching（扩展频道）
channels.telegram.network.dangerouslyAllowPrivateNetwork
channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork
agents.defaults.sandbox.docker.dangerouslyAllowReservedContainerTargets
agents.defaults.sandbox.docker.dangerouslyAllowExternalBindSources
agents.defaults.sandbox.docker.dangerouslyAllowContainerNamespaceJoin
agents.list[<index>].sandbox.docker.dangerouslyAllowReservedContainerTargets
agents.list[<index>].sandbox.docker.dangerouslyAllowExternalBindSources
agents.list[<index>].sandbox.docker.dangerouslyAllowContainerNamespaceJoin

反向代理配置

如果您在反向代理（nginx、Caddy、Traefik 等）后面运行网关，请配置“gateway.trustedProxies”以进行正确的转发客户端 IP 处理。当网关检测到来自“trustedProxies”中不的地址的代理标头时，它不会**将连接视为本地客户端。如果禁用网关身份验证，这些连接将被拒绝。这可以防止身份验证绕过，否则代理连接看起来来自本地主机并接收自动信任。gateway.trustedProxies 还提供 gateway.auth.mode: "trusted-proxy"，但该身份验证模式更严格：

可信代理身份验证 在环回源代理上关闭失败
同主机环回反向代理仍然可以使用 gateway.trustedProxies 进行本地客户端检测和转发 IP 处理
对于同主机环回反向代理，请使用令牌/密码身份验证而不是 gateway.auth.mode: "trusted-proxy"

网关：
  可信代理：
    - "10.0.0.1" # 反向代理IP
  # 可选。默认为 false。
  # 仅当您的代理无法提供 X-Forwarded-For 时才启用。
  允许RealIpFallback：假
  授权：
    方式：密码
    密码：${OPENCLAW_GATEWAY_PASSWORD}

配置“trustedProxies”后，网关使用“X-Forwarded-For”来确定客户端 IP。默认情况下会忽略“X-Real-IP”，除非显式设置“gateway.allowRealIpFallback: true”。良好的反向代理行为（覆盖传入转发标头）：

proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-真实IP $remote_addr;

不良的反向代理行为（附加/保留不受信任的转发标头）：

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for；

HSTS 和起源注释

OpenClaw 网关优先为本地/环回。如果您在反向代理处终止 TLS，请在面向代理的 HTTPS 域上设置 HSTS

说明：该页面原文较长，已翻译前半部分；完整原文请查看原始链接。

英文 Gateway Security

中文内容

范围第一：个人助理安全模型

快速检查：openclaw 安全审核

部署和主机信任

共享 Slack 工作空间：真正的风险

公司共享代理：可接受的模式

网关和节点信任概念

信任边界矩阵

并非设计缺陷

研究人员飞行前检查清单

60 秒内硬化基线

上下文可见性模型

审核检查的内容（高级别）

凭证存储映射

安全审核清单

安全审计术语表

通过 HTTP 控制 UI

不安全或危险标志摘要

反向代理配置

HSTS 和起源注释

On this page

英文 Gateway Security

中文内容

范围第一：个人助理安全模型

快速检查：openclaw 安全审核

部署和主机信任

共享 Slack 工作空间：真正的风险

公司共享代理：可接受的模式

网关和节点信任概念

信任边界矩阵

并非设计缺陷

研究人员飞行前检查清单

60 秒内硬化基线

上下文可见性模型

审核检查的内容（高级别）

凭证存储映射

安全审核清单

安全审计术语表

通过 HTTP 控制 UI

不安全或危险标志摘要

反向代理配置

HSTS 和起源注释

On this page

快速检查：`openclaw 安全审核`

快速检查：`openclaw 安全审核`