OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI 命令

安全性

openclaw security

安全工具：审计及可选的安全修复。相关内容：安全。

bash
openclaw security auditopenclaw security audit --deepopenclaw security audit --deep --password <password>openclaw security audit --deep --token <token>openclaw security audit --auth password --password <password>openclaw security audit --fixopenclaw security audit --json

审计模式

普通的 security audit 仅使用冷配置、文件系统和只读路径：它不会发现插件运行时安全收集器，因此常规审计不会加载每个已安装插件的运行时。--deep 会添加尽力而为的实时 Gateway 网关探测和插件自有的安全审计收集器（明确的内部调用方在已有适当运行时作用域时，也可以选择启用这些收集器）。

如果 Gateway 网关密码身份验证仅在启动时提供，请通过 --auth password --password <password> 传入相同的值，以便审计将其与 hooks.token 进行比对。

检查内容

私信/信任模型

  • 当多个私信发送者共享主会话时发出警告，并建议对共享收件箱使用安全私信模式：session.dmScope="per-channel-peer"（多账户渠道则使用 per-account-channel-peer）。这是针对协作式共享收件箱的安全强化措施，并不能为互不信任的操作员提供隔离；对于这种情况，应使用不同的 Gateway 网关（或不同的操作系统用户/主机）划分信任边界。
  • 当配置表明可能存在多用户共享入口时（例如开放的私信/群组策略、已配置的群组目标或通配符发送者规则），生成 security.trust_model.multi_user_heuristic——OpenClaw 的默认信任模型是个人助理（单个操作员），而不是可抵御恶意行为的多租户隔离。对于有意设置的多用户共享环境：对所有会话启用沙箱隔离，将文件系统访问限制在工作区作用域内，并且不要在该运行时中存放个人/私有身份或凭据。
  • 当使用小型模型（参数量 <=300B）、未启用沙箱隔离且启用了 Web/浏览器工具时发出警告。

Webhook/Hooks

启动日志会记录非致命的安全警告；如果 hooks.token 重用了当前有效的 Gateway 网关共享密钥身份验证值（gateway.auth.token / OPENCLAW_GATEWAY_TOKEN、gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD），审计也会将其标记。此外，以下情况也会触发警告：

  • hooks.token 过短
  • hooks.path="/"
  • 未设置 hooks.defaultSessionKey
  • hooks.allowedAgentIds 不受限制
  • 已启用请求 sessionKey 覆盖
  • 已启用覆盖，但未设置 hooks.allowedSessionKeyPrefixes

运行 openclaw doctor --fix 轮换持久化存储且被重复使用的 hooks.token，然后更新外部 Hook 发送方以使用新令牌。

沙箱/工具

  • 配置了沙箱 Docker 设置，但沙箱模式处于关闭状态时发出警告。
  • 当 gateway.nodes.denyCommands 使用无效的类似模式或未知条目时发出警告（仅对节点命令名称进行精确匹配，不过滤 Shell 文本）。
  • 当 gateway.nodes.allowCommands 明确启用危险的节点命令时发出警告。
  • 当全局 tools.profile="minimal" 被智能体工具配置文件覆盖时发出警告。
  • 当写入/编辑工具已禁用，但 exec 仍然可用，且没有限制性的沙箱文件系统边界时发出警告。
  • 当开放的私信或群组在没有沙箱/工作区保护措施的情况下暴露运行时/文件系统工具时发出警告。
  • 当已安装插件的工具可能在宽松的工具策略下可访问时发出警告。

沙箱浏览器

  • 当沙箱浏览器使用 Docker bridge 网络，但未设置 sandbox.browser.cdpSourceRange 时发出警告。
  • 标记危险的沙箱 Docker 网络模式，包括 host 和 container:* 命名空间联接。
  • 当现有沙箱浏览器 Docker 容器缺少哈希标签或标签已过期时（例如迁移前的容器缺少 openclaw.browserConfigEpoch）发出警告，并建议运行 openclaw sandbox recreate --browser --all。

网络/设备发现

  • 标记 gateway.allowRealIpFallback=true（代理配置错误时存在请求头欺骗风险）。
  • 标记 discovery.mdns.mode="full"（通过 mDNS TXT 记录泄露元数据）。
  • 当 gateway.auth.mode="none" 导致无需共享密钥即可访问 Gateway 网关 HTTP API（/tools/invoke 以及任何已启用的 /v1/* 端点）时发出警告。

插件/渠道

  • 当基于 npm 的插件/hook 安装记录未锁定版本、缺少完整性元数据，或与当前安装的软件包版本不一致时发出警告。
  • 当渠道允许列表依赖可变的名称/电子邮件/标签，而不是稳定 ID 时发出警告（适用于 Discord、Slack、Google Chat、Microsoft Teams、Mattermost、IRC 的相关权限范围）。

以 dangerous/dangerously 为前缀的设置是供操作员在紧急情况下显式启用的越权覆盖；启用其中一项本身并不构成安全漏洞报告。有关危险参数的完整清单，请参阅安全中的“Insecure or dangerous flags summary”。

SecretRef 行为

security audit 会以只读模式解析其目标路径中受支持的 SecretRef。如果当前命令路径中无法使用某个 SecretRef，审计将继续进行并报告 secretDiagnostics，而不会崩溃。--token 和 --password 仅覆盖该次命令调用的深度探测身份验证；它们不会重写配置或 SecretRef 映射。

抑制项

使用 security.audit.suppressions 接受有意保留的常驻发现。每个抑制项均匹配一个确切的 checkId，并可使用不区分大小写的 titleIncludes 和/或 detailIncludes 子字符串进一步缩小匹配范围：

json
{  "security": {    "audit": {      "suppressions": [        {          "checkId": "plugins.tools_reachable_permissive_policy",          "detailIncludes": "已启用的扩展插件：gbrain",          "reason": "受信任的本地操作员插件"        }      ]    }  }}

被抑制的发现会从活动的 summary 和 findings 列表中移除。为便于审计，JSON 输出会将其保留在 suppressedFindings 下。配置抑制项后，活动输出还会保留一个不可抑制的 security.audit.suppressions.active 信息级发现，以便读者判断审计结果已被筛选。危险配置标志会按每个发现一个标志的方式输出，因此，接受一个危险标志不会隐藏共享同一 config.insecure_or_dangerous_flags checkId 的其他已启用标志。

由于抑制项可能隐藏常驻风险，除非 Exec 已针对受信任的本地自动化以 security="full" 和 ask="off" 运行，否则通过智能体运行的 shell 命令添加或移除抑制项需要 Exec 审批。

JSON 输出

bash
openclaw security audit --json | jq '.summary'openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'

使用 --fix --json 时，输出同时包含修复操作和最终报告：

bash
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'

--fix 会更改的内容

应用安全且确定性的修复：

  • 将常见的 groupPolicy="open" 改为 groupPolicy="allowlist"（包括受支持渠道中的账户变体）
  • 当 WhatsApp 群组策略改为 allowlist 时，如果已存储的 allowFrom 文件中存在列表，且配置尚未定义 allowFrom，则使用该列表初始化 groupAllowFrom
  • 将 logging.redactSensitive 从 "off" 设置为 "tools"
  • 收紧状态/配置文件以及常见敏感文件（credentials/*.json、auth-profiles.json、openclaw-agent.sqlite 和旧版会话工件）的权限
  • 同时收紧 openclaw.json 所引用的配置包含文件的权限
  • 在 POSIX 主机上使用 chmod，在 Windows 上使用 icacls 重置权限

--fix 不会：

  • 轮换令牌/密码/API 密钥
  • 禁用工具（gateway、cron、exec 等）
  • 更改 Gateway 网关的绑定/身份验证/网络暴露选项
  • 移除或重写插件/Skills

相关内容

Was this useful?
On this page

On this page