mwaeckerlin/openclaw

Simple Secure OpenClaw in SSH Sandbox

将OpenClaw的安全性与易用性相结合！开箱即可运行基于Docker的安全沙箱化OpenClaw，支持本地或云环境部署。

运行安全的沙箱化预配置OpenClaw从未如此简单：

1. 获取OpenAI令牌（或使用LiteLLM）
2. 在.env中写入配置变量
3. 运行npm start
4. 打开：http://localhost:18789/

目标受众：具备基本Docker知识的安全意识开发者。其他用户：请勿使用OpenClaw！

安全模型

主要安全机制是严格隔离：AI运行在专用沙箱容器中，仅包含其工具和工作区——无主机秘密、无生产数据、无无关资源。

容器隔离

• 隔离的独立容器——网关控制访问和秘密。代理无法直接访问网关（无令牌、无秘密）。代理无法访问网关中定义的文件、变量或秘密。切勿向沙箱暴露任何秘密！
• 通过MCP访问——当SSH沙箱代理无法从网关获取访问权限时，我们添加MCP服务器，在独立容器中保存令牌。
• 容器强化——no-new-privileges、pids_limit: 256防止权限提升和fork炸弹

网络隔离

• 网络隔离——容器在独立内部网络上通信。每两个容器拥有自己的网络。
• 网络加密（生产环境）——生产环境中，加密网络（例如Docker Swarm中的加密覆盖网络：为所有网络设置networks.<network>.driver_opts.encrypted: "true"，或添加服务网格）
• 无端口过度暴露——仅端口***（UI/API）用于本地测试；内部端口保持内部。如果连接聊天工具（如***），甚至可以关闭该端口，通过访问OpenClaw。不要在没有进一步保护的情况下将暴露到互联网。如需通过互联网访问，可在OpenClaw前添加Traefik服务和Authentik proxy-provider outpost。

注意：如果网络既未隔离也未加密，代理可能在共享或未加密网络上嗅探秘密。因此网络隔离至关重要，生产环境强烈建议加密。

秘密管理

• 秘密（生产环境）——在Docker Swarm中使用Docker Secrets而非环境变量（或在Kubernetes等环境中使用Hashicorps等Vault）。秘密可挂载到/var/secrets/secret-name，然后作为环境变量SECRET_NAME导出到OpenClaw。

其他工具和隔离

• Docker-in-Docker隔离——如允许代理运行docker命令，可附加专用Docker容器（docker:dind），代理可在隔离环境中运行docker，与主机Docker隔离。注意代理可获取该隔离容器的root权限，但仅在隔离容器内。发生突破时重启容器即可恢复，无数据风险。
• OpenClaw-MCP-Gateway——项目https://github.com/mwaeckerlin/openclaw-mcp-gateway%E8%BF%90%E8%A1%8CMCP%E6%9C%8D%E5%8A%A1%E5%99%A8%EF%BC%8C%E5%85%81%E8%AE%B8%E6%B2%99%E7%AE%B1%E6%9C%89%E9%99%90%E8%AE%BF%E9%97%AE%E7%BD%91%E5%85%B3%E4%BB%A5%E6%89%A7%E8%A1%8C%E5%AE%89%E5%85%A8%E7%9A%84%60openclaw%60 CLI命令。有助于自我分析和设置定时任务。仅MCP服务器持有网关令牌，沙箱无访问权限。
• MCP-Github——项目https://github.com/mwaeckerlin/mcp-github%E5%85%81%E8%AE%B8%E6%B2%99%E7%AE%B1%E8%AE%BF%E9%97%AEGitHub API。仅MCP服务器持有GitHub令牌，沙箱无访问权限。

强化的OpenClaw设置

• 工作区限制（tools.fs.workspaceOnly: true）——文件工具限制在沙箱工作区。
  注意：workspaceOnly设置限制OpenClaw的文件工具到工作区。但exec/shell命令仍可读取容器系统文件（如/etc/passwd、/proc）。这是可接受的，因为沙箱是隔离容器——其中无主机秘密。
• 循环检测（loopDetection）——防止工具/代理循环的断路器。主要用于防止令牌过度消耗。

strictHostKeyChecking: false

在Docker管理DNS的受控内部Docker网络中可接受。生产环境强化可考虑固定主机密钥。

完整架构

plantuml

@startuml architecture
actor User as user

cloud docker {

  node "mwaeckerlin/openclaw:gateway" as gw {
    [Gateway] as ctrl
    storage "openclaw-config" as cfg
    ctrl - cfg
  }

  node "mwaeckerlin/openclaw-mcp-gateway" {
    [MCP OpenClaw Server] as mcp
  }

  node "mwaeckerlin/openclaw:sandbox" as sb {
    [Sandbox] as sshd
    storage "openclaw-workspace" as ws
    sshd -right- ws
  }

  node "openclaw-dind" as dind {
    [Docker] as dd
    storage "openclaw-docker" as dv
    dd -left- dv
  }

  node "mwaeckerlin/mcp-github" {
    [Github-Gateway] as gh
  }

  component "allow-write-access" as aw
}

user --> ctrl : "HTTP"
ctrl --> sshd : "SSH"
sshd --up--> mcp : openclaw\ncommands
mcp --up--> ctrl : forward\ncommands
sshd -left-> dd : docker
aw .up.> cfg : chown
sshd --> gh
gh ----> [GitHib]
@enduml

本地开发设置

使用docker compose和.env文件进行本地测试。

1. 生成SSH密钥对和.env文件

最简单的用法是使用OpenAI令牌并存储在OPENAI_API_KEY中。其他秘密可随机生成：

bash
ssh-keygen -t ed25519 -f openclaw-key -N "" -C "openclaw-sandbox"
cat > .env <<EOF
OPENCLAW_GATEWAY_TOKEN=$(pwgen 40 1)
OPENCLAW_SANDBOX_SSH_PUBLIC_KEY=$(cat openclaw-key.pub)
OPENCLAW_SANDBOX_SSH_PRIVATE_KEY=$(sed -z 's/\n/\\n/g' openclaw-key)
OPENAI_API_KEY=sk-...[在此处放置令牌]
EOF
rm openclaw-key openclaw-key.pub

2. 生成MCP网关设备配对

如果使用MCP网关（默认启用），生成设备密钥对以实现安全的网关到MCP通信：

bash
node generate-device-pairing.mjs

这会将OPENCLAW_DEVICE_IDENTITY和OPENCLAW_DEVICE_PAIRING追加到.env。MCP网关使用私钥进行身份验证，OpenClaw网关预注册公钥，使设备在首次连接时受信任。

使用--stdout可打印值而非写入.env。

3. 启动服务

前台运行（实时查看日志）：

bash
npm start

后台运行（守护进程模式）：

bash
npm run start:daemon

控制UI：http://localhost:18789/

仅用于本地/可信网络。网关令牌未加密传输。不要在没有TLS反向代理的情况下将端口***暴露到互联网。

完整配置指南

自动秘密映射

网关入口点遍历/run/secrets/中的所有文件，并将每个文件导出为环境变量。文件名转换为大写，破折号替换为下划线，例如：

沙箱直接从/run/secrets/openai_api_key或备选的/run/secrets/openai-api-key读取公钥（当OPENAI_API_KEY未设置时，-和_可互换）。

这意味着任何Docker Secret自动作为环境变量可用——无需显式映射。秘密优先级高于环境变量。

核心配置

特性配置

LiteLLM配置

当设置LITELLM_MASTER_KEY时，LiteLLM启用为模型提供程序，默认模型切换为litellm/openrouter/anthropic/claude-sonnet-4。未设置时，直接使用OpenAI，默认模型为openai/gpt-4o。

配置后，模型列表从提供程序动态发现：

• LiteLLM：LITELLM_URL/v1/models → models.providers.litellm.models
• OpenAI：${OPENCLAW_OPENAI_BASE_URL:-https://api.openai.com/v1}/models → models.providers.openai.models（除非显式设置OPENCLAW_OPENAI_MODELS_JSON）

代理与模型配置

插件配置与安装

示例：

bash
OPENCLAW_PLUGIN_ENTRIES_JSON='{"matrix":{"enabled":true,"config":{"homeserver":"[***]","accessToken":"${OPENCLAW_MATRIX_ACCESS_TOKEN}"}}}'
PLUG