安全与认证

本页涵盖两个核心安全主题：

1. 模型认证：如何为 AI 提供商配置凭据
2. 沙箱（Sandboxing）：隔离 Agent 的工具执行环境

模型提供商认证

推荐方案：API 密钥

对于长期运行的 Gateway，建议使用 API 密钥认证。以 Anthropic 为例：

1. 在提供商控制台创建 API 密钥
2. 将密钥设置在运行 Gateway 的机器上：

export ANTHROPIC_API_KEY="sk-ant-..."
openclaw models status

3. 如果 Gateway 以 systemd/launchd 守护进程运行，将密钥写入 ~/.openclaw/.env：

cat >> ~/.openclaw/.env <<'EOF'
ANTHROPIC_API_KEY=...
EOF

重启守护进程后验证：

openclaw models status
openclaw doctor

Anthropic 订阅 Token（setup-token）

如果你使用 Claude 订阅账户，可在运行 Gateway 的机器上执行：

claude setup-token

然后粘贴到 OpenClaw：

openclaw models auth setup-token --provider anthropic

如果 token 是在另一台机器上生成的：

openclaw models auth paste-token --provider anthropic

警告：Anthropic setup-token 仅在技术层面与 OpenClaw 兼容。Anthropic 曾在部分情况下限制 Claude Code 以外的订阅使用。请自行核查 Anthropic 当前条款，风险自担。

如果遇到如下错误：

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

请改用 Anthropic API 密钥。

检查认证状态

openclaw models status
openclaw doctor

自动化检查（认证过期时退出码 1，即将过期时退出码 2）：

openclaw models status --check

API 密钥轮换（多 Key 自动切换）

部分提供商支持配置多个 API 密钥，触发速率限制时自动切换。优先级顺序：

1. OPENCLAW_LIVE_<PROVIDER>_KEY（临时覆盖）
2. <PROVIDER>_API_KEYS
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_*

只有速率限制错误（429、rate_limit、quota、resource exhausted）才触发切换，其他错误不重试。

控制使用哪个凭据

会话级别（通过聊天命令）：

使用 /model <别名或ID>@<profileId> 固定当前会话使用的提供商凭据。 示例 profileId：anthropic:default、anthropic:work

Agent 级别（CLI 设置）：

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

加 --agent <id> 指定特定 Agent，不加则使用默认 Agent。

沙箱隔离（Sandboxing）

沙箱功能让 Agent 的工具执行（文件读写、代码执行等）运行在隔离环境中，减少误操作的影响范围。这是可选功能，默认关闭。

注意：沙箱不是完美的安全边界，但能有效限制文件系统和进程访问。

什么会被沙箱隔离

会被沙箱隔离的操作：

• 工具执行（exec、read、write、edit、apply_patch 等）
• 可选的沙箱浏览器

不会被沙箱隔离的操作：

• Gateway 进程本身
• 通过 tools.elevated 显式允许在宿主机运行的工具

沙箱模式（什么时候启用沙箱）

agents.defaults.sandbox.mode 控制何时使用沙箱：

• "off"：不使用沙箱
• "non-main"：只对非主会话（群聊等）使用沙箱，个人 DM 不沙箱
• "all"：所有会话都使用沙箱

沙箱范围（创建几个容器）

agents.defaults.sandbox.scope 控制创建多少个隔离容器：

• "session"（默认）：每个会话一个容器
• "agent"：每个 Agent 一个容器
• "shared"：所有沙箱会话共用一个容器

沙箱后端（运行在哪里）

agents.defaults.sandbox.backend 控制沙箱运行环境：

• "docker"（默认）：本地 Docker 容器
• "ssh"：通过 SSH 在远程主机运行
• "openshell"：通过 OpenShell 托管沙箱运行

特性	Docker	SSH	OpenShell
运行位置	本地容器	任意 SSH 可达主机	OpenShell 托管沙箱
初始化	scripts/sandbox-setup.sh	SSH 密钥 + 目标主机	启用 OpenShell 插件
浏览器沙箱	✅ 支持	❌ 不支持	❌ 暂不支持
适用场景	本地开发、完全隔离	卸载到远程主机	托管远程沙箱

SSH 后端

在配置了 SSH 密钥的远程主机上运行沙箱：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        backend: "ssh",
        scope: "session",
        workspaceAccess: "rw",
        ssh: {
          target: "user@gateway-host:22",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          identityFile: "~/.ssh/id_ed25519",
          knownHostsFile: "~/.ssh/known_hosts",
        },
      },
    },
  },
}

SSH 后端采用「远程规范」模式：初次使用时从本地工作区同步到远程，之后以远程工作区为准，不自动同步回本地。

工作区访问（沙箱能看到什么）

agents.defaults.sandbox.workspaceAccess 控制沙箱对 Agent 工作区的访问权限：

• "none"（默认）：沙箱使用 ~/.openclaw/sandboxes 下的独立隔离空间
• "ro"：将 Agent 工作区只读挂载到 /agent（禁用写入/编辑工具）
• "rw"：将 Agent 工作区读写挂载到 /workspace

最小启用示例

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}

自定义挂载目录

将宿主机目录挂载到沙箱容器（仅 Docker 后端）：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
  },
}

格式：宿主机路径:容器路径:模式（模式为 ro 只读 或 rw 读写）

安全注意：挂载目录绕过了沙箱文件系统隔离。OpenClaw 会阻止危险的挂载源（docker.sock、/etc、/proc、/sys、/dev 等）。

初始化沙箱镜像

首次使用前需构建 Docker 镜像（默认镜像不含 Node.js，如有需要请用增强版）：

# 基础镜像（bookworm-slim，无 Node）
scripts/sandbox-setup.sh

# 功能增强镜像（含 curl、jq、nodejs、python3、git）
scripts/sandbox-common-setup.sh

# 沙箱浏览器镜像
scripts/sandbox-browser-setup.sh

默认镜像：openclaw-sandbox:bookworm-slim 增强镜像：设置 agents.defaults.sandbox.docker.image 为 openclaw-sandbox-common:bookworm-slim

沙箱容器默认无网络访问，可通过 agents.defaults.sandbox.docker.network 覆盖。

一次性容器初始化命令

setupCommand 在沙箱容器创建后执行一次（不是每次运行都执行）：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          setupCommand: "apt-get update && apt-get install -y ffmpeg",
        },
      },
    },
  },
}

常见踩坑：

• 默认无网络（docker.network: "none"），安装包会失败
• readOnlyRoot: true 阻止写入，安装包需设 readOnlyRoot: false 或改用自定义镜像
• 执行 root 权限操作需省略 user 字段或设为 user: "0:0"

逃生舱（Elevated 模式）

tools.elevated 是一个显式逃生舱，让特定来源的 exec 工具在宿主机上运行（绕过沙箱）：

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
      },
    },
  },
}

如需完全禁用 exec，使用 tool policy deny 而非依赖沙箱。

诊断沙箱问题

openclaw sandbox explain

输出有效的沙箱模式、工具策略和修复建议。

完整配置示例

{
  gateway: {
    bind: "loopback",
    auth: {
      mode: "token",
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          readOnlyRoot: true,
          network: "none",
          user: "1000:1000",
        },
      },
    },
  },
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
      },
    },
  },
}