安全与认证

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

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

模型提供商认证

推荐方案：API 密钥

对于长期运行的 Gateway，建议使用 API 密钥认证：

1. 在 AI 提供商控制台创建 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

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 的工具执行（文件读写、代码执行等）运行在隔离的 Docker 容器中，减少误操作的影响范围。这是可选功能，默认关闭。

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

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

agents.defaults.sandbox.mode：

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

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

agents.defaults.sandbox.scope：

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

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

agents.defaults.sandbox.workspaceAccess：

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

最小启用示例

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

自定义挂载目录

将宿主机目录挂载到沙箱容器：

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

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

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

初始化沙箱镜像

首次使用前需构建镜像：

# 基础镜像（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"],
      },
    },
  },
}