AI 实战文档

Appearance

安装与 Onboarding 深入指南 ​

目标 ​

把"能跑起来"升级为"可稳定运维"的安装方案，并明确不同环境下推荐路径。

官方优先顺序 ​

  1. 安装脚本（推荐）
  2. openclaw onboard --install-daemon
  3. openclaw gateway status 验证服务状态
  4. openclaw dashboard 验证控制面可用

参考：

前置条件 ​

系统要求 ​

项目最低要求推荐配置
Node.js20.x22.x LTS
内存2GB4GB+
磁盘1GB5GB+
操作系统macOS / Linux / WSL2macOS / Linux

网络要求 ​

yaml
network:
  outbound:
    - api.openai.com # OpenAI API
    - api.anthropic.com # Anthropic API
    - discord.com # Discord
    - api.telegram.org # Telegram
    - slack.com # Slack

  optional:
    - tailscale.com # Tailscale VPN
    - github.com # GitHub (更新)

安装路径选择 ​

路径 A：标准安装（团队默认） ​

bash
# macOS / Linux
curl -fsSL https://openclaw.ai/install.sh | bash

# 验证安装
openclaw --version

# 运行 Onboarding
openclaw onboard

# 安装为系统服务
openclaw onboard --install-daemon

# 验证状态
openclaw gateway status

适用场景：

  • 新团队落地
  • 希望快速统一安装方式
  • 无需自定义安装路径

路径 B：npm / pnpm 安装 ​

bash
# npm 安装
npm install -g openclaw@latest

# pnpm 安装（更快）
pnpm add -g openclaw

# 验证安装
openclaw --version

# 运行 Onboarding
openclaw onboard --install-daemon

适用场景：

  • 已有统一 Node 环境
  • 想把安装流程并入现有脚本体系
  • 需要版本管理

路径 C：源码安装 ​

bash
# 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 安装依赖
pnpm install

# 构建
pnpm build

# 本地运行
pnpm dev

# 或安装到全局
pnpm link --global

适用场景：

  • 需要阅读源码或二次开发
  • 需要实验性功能验证
  • 贡献代码

路径 D：Docker 安装 ​

bash
# 拉取镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

# 查看日志
docker logs -f openclaw

适用场景：

  • 容器化部署
  • 多环境一致性
  • CI/CD 集成

Onboarding 流程详解 ​

步骤 1：初始化配置 ​

bash
openclaw onboard

这一步会：

  1. 检测系统环境
  2. 创建配置目录 ~/.openclaw/
  3. 生成默认配置文件
  4. 引导配置 Provider

步骤 2：配置 Provider ​

bash
# 交互式配置
openclaw configure provider

# 或手动配置
openclaw config set providers.openai.api_key sk-xxx
openclaw config set providers.anthropic.api_key sk-ant-xxx

步骤 3：配置渠道 ​

bash
# 配置 Telegram
openclaw configure channel telegram

# 配置 Discord
openclaw configure channel discord

# 配置 Slack
openclaw configure channel slack

步骤 4：安装系统服务 ​

bash
# 安装为系统服务
openclaw onboard --install-daemon

# 验证服务状态
openclaw gateway status

# 启动/停止服务
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

步骤 5：验证安装 ​

bash
# 完整验证
openclaw doctor

# 检查各项状态
openclaw status
openclaw gateway status --deep
openclaw channels status --probe
openclaw providers test

# 打开 Dashboard
openclaw dashboard

Onboarding 输出检查 ​

完成 openclaw onboard 后，至少确认：

markdown
- [ ] 网关已安装为服务并可启动
- [ ] 默认配置可通过 `openclaw config` 读取
- [ ] 模型 Provider 已可用
- [ ] Dashboard 可访问
- [ ] 至少一个渠道配置完成
- [ ] 发送测试消息能收到回复

验证检查表 ​

bash
#!/bin/bash
# verify-onboarding.sh

echo "=== OpenClaw Onboarding Verification ==="

# 1. 检查服务
echo "1. Gateway Service:"
openclaw gateway status --json | jq '.status'

# 2. 检查配置
echo "2. Configuration:"
test -f ~/.openclaw/config.yaml && echo "✓ Config exists" || echo "✗ Config missing"

# 3. 检查 Provider
echo "3. Provider Status:"
openclaw providers test --json | jq '.[] | {name: .name, status: .status}'

# 4. 检查渠道
echo "4. Channels:"
openclaw channels list --json | jq '.[] | {name: .name, enabled: .enabled}'

# 5. 检查 Dashboard
echo "5. Dashboard:"
curl -s http://localhost:18789/health && echo "✓ Dashboard accessible" || echo "✗ Dashboard not accessible"

echo "=== Verification Complete ==="

安装后配置 ​

安全加固 ​

bash
# 启用认证
openclaw config set gateway.auth.enabled true
openclaw config set gateway.auth.type token

# 生成安全 Token
TOKEN=$(openssl rand -hex 32)
openclaw config set gateway.auth.token $TOKEN

# 限制访问
openclaw config set gateway.host 127.0.0.1

# 安全审计
openclaw security audit --fix

性能调优 ​

bash
# 连接数
openclaw config set gateway.performance.max_connections 1000

# 超时设置
openclaw config set gateway.performance.request_timeout 30000
openclaw config set gateway.performance.idle_timeout 60000

# 日志级别
openclaw config set gateway.logging.level info

备份配置 ​

bash
# 导出配置
openclaw config export --output config-backup-$(date +%Y%m%d).yaml

# 备份密钥
openclaw secrets export --output secrets-backup-$(date +%Y%m%d).yaml

给开发者的建议 ​

  • 首次上线只接入一个渠道，先验证消息闭环
  • 先用最小 tool profile，别直接 full
  • 使用版本控制管理配置文件
  • 定期备份配置和密钥

给产品经理的建议 ​

  • 把 Onboarding 当成上线里程碑的一部分，形成验收清单
  • 明确"哪些能力首发上线，哪些能力后续灰度"
  • 制定培训计划，确保团队成员熟悉使用

常见问题排查 ​

问题 1：安装失败 ​

bash
# 检查 Node 版本
node --version  # 需要 20+

# 检查权限
ls -la ~/.openclaw

# 清理重装
rm -rf ~/.openclaw
rm -rf node_modules
npm install -g openclaw@latest

问题 2：服务启动失败 ​

bash
# 检查端口占用
lsof -i :18789

# 检查日志
openclaw logs --tail 50

# 前台运行调试
openclaw gateway --verbose

问题 3：Provider 连接失败 ​

bash
# 检查 API 密钥
openclaw secrets validate

# 测试连接
openclaw providers test

# 检查网络
curl -I https://api.openai.com