一句话结论
Docker 适合保留沙箱、一键脚本适合上手、Node 直装适合调试；首次启动只看三件事：模型、端口、面板。
适用场景
- 刚拿到 OpenClaw，不确定哪种安装方式适合自己
- 已经装过但首次启动卡在白屏
- 想为后续的网关、Bot、知识库准备好基础环境
常见现象
- 面板打不开 / 一直转圈
- 命令行报缺 Node / pnpm / Docker
- 完成安装但找不到登录入口
原因解释
- 运行环境不满足（Node 版本太低、Docker 未启动）
- .env 没填模型 BASE_URL 或 API Key
- 默认端口被其他程序占用
解决步骤
- 确认本机 Node 18+ 或 Docker 24+，然后选一种安装方式
- 把 .env 模板复制为正式 .env，填写模型 BASE_URL 与 Key
- 执行 pnpm install / docker compose up，看是否提示端口冲突
- 启动后访问 http://127.0.0.1:面板端口，确认登录页可见
- 面板里跑一条最小请求验证模型连通
可复制命令
node -v && pnpm -v && docker info | head -3
cp .env.example .env && vim .env
docker compose up -d && docker compose logs -f gateway --tail 200
仍然不行怎么办
- 面板始终打不开就先看 OpenClaw Gateway 启动失败怎么办
- 如果是中转 Key 问题，用最小 curl 验证 BASE_URL 是否能取模型列表
小白先准备什么
- 确认本机系统：macOS / Windows / Linux，以及是否已装 Docker。
- 准备一个模型 API Key 和对应的 BASE_URL（1A1API 或 OpenAI 官方均可）。
- 确认 3000、8080 等常用端口没有被其他程序占用（用 lsof -i :3000 检查）。
- 如果用 Docker，先运行 docker info 确认 Docker 已启动。
验收标准
- 浏览器打开 http://127.0.0.1:面板端口 能看到登录页
- 登录后在面板里发一条「你好」能收到模型回复
- 终端日志里没有 ERROR 或 FATAL 级别的报错
- 重启后服务能自动恢复（Docker 用 restart: unless-stopped）
可复制命令
# 检查前置环境
node -v # 需要 18+
pnpm -v # 需要 8+
docker info # 确认 Docker 运行中
lsof -i :3000 # 检查端口占用
# 一键启动（Docker 方式）
cp .env.example .env
# 编辑 .env 填入 BASE_URL 和 API_KEY
docker compose up -d
docker compose logs -f --tail 100
常见误区和不适合场景
- 误区：Node 直装和 Docker 同时跑 → 端口冲突，选一种即可
- 误区：.env 里 BASE_URL 末尾多了斜杠 → 会导致路径拼接错误
- 误区：用 sudo 运行所有命令 → 权限混乱，后续文件读写会出问题
- 不适合：只想快速试一下模型效果（直接用 curl 或 Playground 更快）
- 不适合：服务器没有公网 IP 且不会配内网穿透（先解决网络再装 OpenClaw）
还卡着？
可以把截图、日志、需求单或当前页面链接发到 zhemuy@gmail.com。