OpenClaw MacBook Docker 部署指南

三余无梦生30
11 阅读4分钟

OpenClaw MacBook Docker 部署指南

基于实际部署过程整理，适用于 macOS (Apple Silicon / Intel)

前置条件

  • macOS 系统
  • 安装 Docker Desktop for Mac（内含 Docker Compose v2）
  • 至少 4GB 可用内存，10GB 磁盘空间
  • 模型 API Key（本文以阿里云 DashScope Qwen 为例）

一、克隆仓库

git clone https://github.com/openclaw/openclaw.git
cd openclaw-main

二、运行初始化脚本

docker-setup.sh 是官方提供的初始化脚本，负责拉取镜像、生成 .env 文件、创建数据目录并启动 Gateway。必须先执行它，否则 .env 不会自动生成。

# 国内推荐使用腾讯云镜像，避免 ghcr.io 拉取超时
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./docker-setup.sh

网络问题说明：docker-setup.sh 执行过程中会进入交互式 onboarding 向导， 要求配置模型 Provider。如果向导中出现网络错误（如 OAuth 失败、verify failed）， 可以按 Ctrl+C 中断，手动完成后续配置（见第三、四步）。 .env 和目录结构已经在脚本运行初期生成，中断不影响后续流程。

脚本执行后会生成以下关键文件和目录：

~/.openclaw/              ← Gateway 配置和数据目录
~/openclaw/workspace/     ← Agent 工作区
openclaw-main/.env        ← 环境变量（含自动生成的 Token）

三、检查 .env 文件

cat .env

获取关键变量Token：

# 1. 记录 Token 备用（后续配置 openclaw.json 需要）
grep OPENCLAW_GATEWAY_TOKEN .env

四、配置 openclaw.json

配置文件路径：~/.openclaw/openclaw.json

重要：OPENCLAW_GATEWAY_TOKEN（.env）的优先级高于 openclaw.json 中的 auth.token，启动时会自动覆盖。 建议两处保持一致，避免 token mismatch 错误。

将以下内容写入配置文件（替换 Token 和 API Key 为你自己的值）：

cat > ~/.openclaw/openclaw.json << 'EOF'
{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "lan",
    "auth": {
      "mode": "token",
      "token": "YOUR_TOKEN_HERE"
    },
    "controlUi": {
      "dangerouslyAllowHostHeaderOriginFallback": true
    },
    "remote": {
      "token": "YOUR_TOKEN_HERE"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "custom-qwen": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "YOUR_DASHSCOPE_API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-32b",
            "name": "Qwen3-32B",
            "contextWindow": 131072,
            "maxTokens": 8192
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "custom-qwen/qwen3-32b"
      }
    }
  }
}
EOF

用 .env 里的真实 Token 替换两处 YOUR_TOKEN_HERE

配置字段说明

gateway 节点

字段说明
bind: "lan"绑定到局域网，浏览器可通过 127.0.0.1:18789 访问
auth.token所有客户端连接 Gateway 的鉴权 token
controlUi.dangerouslyAllow...lan 模式下必须配置，允许 Host 头作为来源校验兜底
remote.tokenCLI 容器主动连接 Gateway 时的凭证，必须与 auth.token 一致

models 节点

字段说明
mode: "merge"自定义 provider 与内置 provider 合并（replace 为完全覆盖）
api: "openai-completions"使用 OpenAI 兼容接口 /chat/completions

五、启动服务

docker compose down --remove-orphans
docker compose up -d openclaw-gateway

验证启动成功：

docker compose ps
# 期望 STATUS 列显示：Up (healthy)

docker compose logs openclaw-gateway --tail=10
# 期望看到：
# [gateway] listening on ws://0.0.0.0:18789
# [gateway] agent model: custom-qwen/qwen3-32b

六、获取 Dashboard 访问链接

docker compose run --rm openclaw-cli dashboard --no-open

输出示例：

Dashboard URL: http://127.0.0.1:18789/#token=ce9819ba...

复制完整 URL（包含 #token=...）到浏览器打开。

七、配对浏览器设备

首次打开 Dashboard 会显示 pairing required，需要审批配对请求。

# 1. 查看待配对设备
docker compose run --rm openclaw-cli devices list

输出示例：

Pending (1)
┌──────────────────────────────────────┬──────────────────┬──────────┬──────────────┐
│ Request                              │ Device           │ Role     │ IP           │
├──────────────────────────────────────┼──────────────────┼──────────┼──────────────┤
│ fd7d606e-edf5-4c56-a3ed-1e190bdd873d │ 21c243d205b1...  │ operator │ 192.168.65.1 │
└──────────────────────────────────────┴──────────────────┴──────────┴──────────────┘

Request 列的 UUID（如 fd7d606e-edf5-4c56-a3ed-1e190bdd873d）即为 REQUEST_ID，每次浏览器新设备访问都会生成一个新值，需从实时输出中复制。

# 2. 用上一步输出的 Request UUID 执行审批
docker compose run --rm openclaw-cli devices approve fd7d606e-edf5-4c56-a3ed-1e190bdd873d

审批成功后刷新浏览器即可进入 Dashboard。

八、日常管理命令

# 查看运行状态
docker compose ps

# 实时日志
docker compose logs -f openclaw-gateway

# 停止服务
docker compose down

# 更新镜像
docker pull sgccr.ccs.tencentyun.com/openclaw/openclaw:latest
OPENCLAW_IMAGE="sgccr.ccs.tencentyun.com/openclaw/openclaw:latest" \
  docker compose up -d openclaw-gateway

九、常见问题排查

错误原因解决方案
non-loopback Control UI requires...lan 模式缺少 controlUi 配置在 openclaw.json 加入 dangerouslyAllowHostHeaderOriginFallback: true
token mismatch.env Token 与 openclaw.json Token 不一致以 .env 为准，执行第四步 Token 同步脚本
pairing required浏览器首次访问需配对审批执行 devices list + devices approve
浏览器无法访问（连接重置）bind 为 loopback，Docker 端口映射无法转发改 bind 为 lan 并加入 controlUi 配置
Qwen OAuth 失败Docker 容器内无法完成浏览器授权流程改用 Custom Provider + API Key 方式接入

十、使用腾讯云镜像加速（国内推荐）

国内拉取 ghcr.io 较慢，建议使用腾讯云镜像：

export OPENCLAW_IMAGE="sgccr.ccs.tencentyun.com/openclaw/openclaw:latest"

写入 .env 永久生效：

echo "OPENCLAW_IMAGE=sgccr.ccs.tencentyun.com/openclaw/openclaw:latest" >> .env

附：关键文件路径

文件路径说明
运行时配置~/.openclaw/openclaw.json模型、鉴权、Gateway 配置
环境变量openclaw-main/.envToken、端口、镜像等启动参数
Agent 工作区~/.openclaw/workspaceAgent 可读写的文件目录
容器日志/tmp/openclaw/openclaw-YYYY-MM-DD.log容器内详细日志
avatar
文章
阅读
粉丝