23b - 安装与快速入门：从零到运行你的第一个 OpenClaw Agent

你需要 24/7 运行吗？
├── 否 → 一键安装（本地笔记本/台式机）
│        └── 最快上手，5 分钟搞定
└── 是 → 你的预算是？
         ├── 尽量低（$5/月）→ VPS 部署（Hetzner/DigitalOcean）
         ├── 一次性投入（~$80）→ 树莓派（低功耗、安静）
         ├── 一次性投入（$599+）→ Mac Mini（性能强、macOS 生态）
         └── 已有服务器 → Docker 部署（容器隔离、易管理）

# 一条命令完成安装（macOS / Linux / Windows WSL2）
curl -fsSL https://openclaw.ai/install.sh | bash

步骤 1：选择模式
  → Quick Start（推荐新手）

步骤 2：选择 AI 提供商
  → Anthropic（推荐，Claude Sonnet 性价比最高）
  → OpenAI
  → Google Gemini
  → OpenRouter（访问 300+ 模型）
  → 跳过（稍后配置）

步骤 3：输入 API Key
  → 粘贴你的 API Key

步骤 4：选择消息平台
  → Telegram（推荐，配置最简单）
  → Discord
  → WhatsApp
  → 跳过（稍后配置）

步骤 5：输入平台凭证
  → 粘贴 Bot Token

# 检查 OpenClaw 状态
openclaw status --all
 
# 启动 Gateway
openclaw gateway start
 
# 查看日志
openclaw gateway logs

# 1. 确保 Docker 已安装
docker --version
docker compose version
 
# 2. 克隆仓库
git clone https://github.com/openclaw/openclaw.git
cd openclaw
 
# 3. 运行 Docker 安装脚本
./docker-setup.sh

# 复制配置模板
cp .env.example .env
 
# 编辑配置（详见第 6 节 .env 配置详解）
nano .env

# ===== LLM 提供商（选一个）=====
ANTHROPIC_API_KEY=sk-ant-your-key-here
# OPENAI_API_KEY=sk-your-key-here
# GOOGLE_API_KEY=your-google-key-here
 
# ===== 消息平台（按需启用）=====
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
 
# ===== Gateway 配置 =====
OPENCLAW_GATEWAY_TOKEN=your-secure-gateway-token
AGENT_TIMEZONE=Asia/Shanghai

# 启动（后台运行）
docker compose up -d
 
# 查看日志
docker compose logs -f
 
# 设置自动重启（确保 VPS 重启后自动恢复）
docker update --restart=unless-stopped openclaw

# SSH 连接到 VPS
ssh root@your-server-ip
 
# 更新系统
apt update && apt upgrade -y
 
# 创建非 root 用户（安全最佳实践）
adduser openclaw
usermod -aG sudo openclaw
 
# 切换到新用户
su - openclaw

# 安装 Docker（官方脚本）
curl -fsSL https://get.docker.com | sh
 
# 将当前用户加入 docker 组（免 sudo）
sudo usermod -aG docker $USER
 
# 重新登录使组权限生效
exit
ssh openclaw@your-server-ip
 
# 验证
docker --version
docker compose version

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

git clone https://github.com/openclaw/openclaw.git
cd openclaw
./docker-setup.sh

# 安装 UFW
sudo apt install ufw -y
 
# 默认拒绝入站
sudo ufw default deny incoming
sudo ufw default allow outgoing
 
# 允许 SSH
sudo ufw allow ssh
 
# 启用防火墙
sudo ufw enable
 
# 验证
sudo ufw status

# 如果使用一键安装（systemd 服务）
sudo systemctl enable openclaw-gateway
 
# 如果使用 Docker
docker update --restart=unless-stopped openclaw

# 方式 A：Tailscale（推荐，零配置 VPN）
curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
 
# 方式 B：SSH 隧道
# 在本地电脑执行：
ssh -L 18789:localhost:18789 openclaw@your-server-ip
# 然后在本地浏览器访问 http://localhost:18789

# 1. 使用 Raspberry Pi Imager 烧录 Raspberry Pi OS（64-bit）到 SD 卡
#    启用 SSH、设置用户名密码、配置 Wi-Fi（如需要）
 
# 2. 启动树莓派，SSH 连接
ssh pi@raspberrypi.local
 
# 3. 更新系统
sudo apt update && sudo apt upgrade -y
 
# 4. 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
 
# 5. 按向导完成配置（同第 3 节）
 
# 6. 设置开机自启
sudo systemctl enable openclaw-gateway

# 1. 打开终端（Cmd + Space → 输入 "Terminal"）
 
# 2. 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
 
# 3. 按向导完成配置
 
# 4. 设置开机自启（macOS LaunchAgent）
# 安装脚本通常会自动配置，如需手动：
mkdir -p ~/Library/LaunchAgents

功能：
├── 菜单栏快速访问（点击图标即可对话）
├── 语音唤醒（"Hey Claw" 或自定义唤醒词）
├── 屏幕录制与截图分析
├── Canvas 集成（可视化工作区）
├── 系统通知集成
└── 快捷键支持

iOS App 功能：
├── 与 Agent 实时对话
├── 推送通知（Agent 主动汇报）
├── 语音输入
└── 快捷指令（Shortcuts）集成

Apple Watch 功能：
├── 快速查看 Agent 状态
├── 语音指令
└── 通知推送

{
  // ===== LLM 提供商配置 =====
  "models": {
    "providers": {
      "anthropic": {
        "apiKey": "${ANTHROPIC_API_KEY}",  // 环境变量引用
        "cacheRetention": "short"           // 5 分钟缓存，降低成本
      }
    }
  },
 
  // ===== Agent 默认配置 =====
  "agents": {
    "defaults": {
      "model": {
        "primary": "anthropic/claude-sonnet-4-20250514"  // 默认模型
      }
    }
  },
 
  // ===== 消息平台配置 =====
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",     // "open"=任何人可用, "pairing"=需配对码
      "allowFrom": ["*"],        // 允许的用户（"*"=所有人）
      "groupPolicy": "allowlist",
      "streamMode": "partial"    // 流式输出
    }
  },
 
  // ===== Gateway 配置 =====
  "gateway": {
    "host": "127.0.0.1",         // 仅本地访问（安全默认）
    "port": 18789
  }
}

步骤 1：打开 Telegram，搜索 @BotFather
步骤 2：发送 /newbot
步骤 3：输入 Bot 显示名称（如 "My OpenClaw Assistant"）
步骤 4：输入 Bot 用户名（必须以 "bot" 结尾，如 "my_openclaw_bot"）
步骤 5：BotFather 返回 Bot Token，格式如：
         123456789:ABCdefGHIjklMNOpqrsTUVwxyz
步骤 6：复制 Token，粘贴到 OpenClaw 配置中

可选优化：
  /setdescription  → 设置 Bot 描述
  /setabouttext    → 设置 Bot 简介
  /setuserpic      → 设置 Bot 头像
  /setcommands     → 设置命令菜单（如 /status, /help）

# SOUL.md 模板
 
## 身份
你是 [Agent 名称]，一个 [角色描述]。
 
## 行为准则
- 始终使用中文回复
- 回复简洁明了，避免冗长
- 遇到不确定的信息，明确说明而非编造
 
## 职责
1. [主要职责 1]
2. [主要职责 2]
3. [主要职责 3]
 
## 限制
- 不要执行任何删除操作
- 不要发送未经确认的邮件
- 不要访问敏感目录（如 ~/.ssh）
 
## 输出格式
- 使用 Markdown 格式
- 重要信息用 **粗体** 标注
- 列表使用有序或无序列表

□ 注册 Hetzner Cloud，创建 CX22 VPS（Ubuntu 24.04）
  → 或者直接在本地电脑操作（跳过 VPS 步骤）

□ 获取 Anthropic API Key
  → console.anthropic.com → API Keys → Create Key
  → 复制保存（只显示一次！）

□ 创建 Telegram Bot
  → Telegram 搜索 @BotFather → /newbot
  → 设置名称和用户名
  → 复制 Bot Token

# 如果是 VPS，先 SSH 连接
ssh root@your-server-ip
 
# 安装 OpenClaw（一条命令）
curl -fsSL https://openclaw.ai/install.sh | bash
 
# 向导会依次询问：
# 1. 模式 → 选择 Quick Start
# 2. AI 提供商 → 选择 Anthropic
# 3. API Key → 粘贴你的 Anthropic API Key
# 4. 消息平台 → 选择 Telegram
# 5. Bot Token → 粘贴你的 Telegram Bot Token
 
# 安装完成后，Gateway 自动启动

# 进入 Agent workspace
cd ~/.openclaw/agents/main/agent
 
# 编辑 SOUL.md（Agent 人格定义）
nano SOUL.md

# 每日摘要助手
 
## 身份
你是"晨报助手"，一个每天早上为我准备信息摘要的 AI Agent。
 
## 职责
1. 搜索并汇总今日科技新闻要点（3-5 条）
2. 查看天气预报并给出穿衣建议
3. 提醒我今天的重要日程（如果有的话）
 
## 输出格式
使用以下格式：
 
🌅 早安！今天是 [日期]
 
📰 **今日要闻**
1. [新闻1]
2. [新闻2]
3. [新闻3]
 
🌤️ **天气**
[城市] 今天 [温度]，[天气状况]。建议 [穿衣建议]。
 
📋 **今日提醒**
- [提醒事项]
 
## 行为准则
- 使用中文回复
- 简洁明了，每条新闻不超过两句话
- 如果搜索失败，诚实说明而非编造

# 重启 Gateway 使配置生效
openclaw gateway restart

在 Telegram 中：

1. 打开你创建的 Bot 对话

2. 发送 /status
   → 应该收到 Agent 状态信息（在线、模型、版本等）

3. 发送 "给我一份今天的新闻摘要"
   → Agent 应该搜索网页并返回格式化的摘要

4. 发送 "帮我查一下上海明天的天气"
   → Agent 应该返回天气信息

5. 测试工具能力：发送 "在我的 workspace 创建一个 todo.md 文件"
   → Agent 应该创建文件并确认

# 全面状态检查（最有用的诊断命令）
openclaw status --all
 
# 查看 Gateway 日志
openclaw gateway logs
 
# 检查特定通道状态
openclaw gateway status
 
# Docker 环境诊断
docker compose logs --tail=50
docker compose ps
 
# 检查 Node.js 版本
node --version
 
# 检查端口占用
sudo lsof -i :18789
 
# 树莓派温度检查
vcgencmd measure_temp
 
# 检查磁盘空间
df -h

API Key 问题排查流程：

1. 运行 openclaw status --all
   ├── 显示 "authenticated" → Key 正常，问题在别处
   └── 显示 "no key" 或 "error" → 继续排查

2. 检查 Key 格式
   ├── Anthropic: 以 "sk-ant-" 开头
   ├── OpenAI: 以 "sk-" 开头
   └── 格式不对 → 重新从提供商控制台复制

3. 检查环境变量
   ├── Docker: 检查 .env 文件
   ├── 一键安装: 检查 ~/.openclaw/openclaw.json
   └── 注意：OPENCLAW_GATEWAY_TOKEN 可能覆盖配置

4. 重新配置
   └── openclaw onboard --auth-choice anthropic-api-key

# 问题：容器无法启动
docker compose down
docker compose up -d --force-recreate
 
# 问题：配置更新后不生效
docker compose restart
 
# 问题：磁盘空间不足（Docker 镜像堆积）
docker system prune -a
 
# 问题：权限错误
# 确保数据目录权限正确
sudo chown -R 1000:1000 ./data

~/.openclaw/                    # 一键安装的数据根目录
├── openclaw.json               # 核心配置文件
├── agents/                     # Agent 数据
│   └── main/
│       └── agent/
│           ├── SOUL.md         # Agent 人格定义
│           ├── memory/         # 记忆文件
│           │   ├── long-term.md
│           │   └── *.jsonl     # 对话日志
│           ├── rules/          # 行为规则
│           └── tools/          # 自定义工具
└── auth-profiles/              # 认证信息

# 手动备份（推荐每周执行）
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/
 
# 自动备份（cron job，每天凌晨 3 点）
crontab -e
# 添加以下行：
0 3 * * * tar -czf /backup/openclaw-$(date +\%Y\%m\%d).tar.gz ~/.openclaw/
 
# 恢复备份
tar -xzf openclaw-backup-20260215.tar.gz -C ~/

# 检查服务状态
sudo systemctl status openclaw-gateway
 
# 启用开机自启
sudo systemctl enable openclaw-gateway
 
# 手动启动/停止/重启
sudo systemctl start openclaw-gateway
sudo systemctl stop openclaw-gateway
sudo systemctl restart openclaw-gateway

我想部署 OpenClaw，请帮我规划最佳方案：

我的情况：
- 技术水平：[如：熟悉 Linux 和 Docker / 完全新手]
- 预算：[如：$10/月以内 / 一次性投入 $100 以内]
- 运行需求：[如：需要 24/7 / 偶尔使用]
- 隐私要求：[如：数据不能出境 / 无特殊要求]
- 消息平台：[如：主要用 Telegram / 需要 WhatsApp + Slack]
- Agent 数量：[如：1 个 / 3-5 个]

请推荐：
1. 最适合的部署方式（本地/VPS/树莓派/Mac Mini）
2. 具体的硬件/VPS 配置
3. 预估月度成本（VPS + API）
4. 安装步骤概要

我的 OpenClaw 遇到了问题，请帮我排查：

部署方式：[一键安装 / Docker / VPS]
操作系统：[Ubuntu 24.04 / macOS / 树莓派 OS]
OpenClaw 版本：[运行 openclaw --version 获取]
Node.js 版本：[运行 node --version 获取]

问题描述：
[详细描述你遇到的问题]

已尝试的解决方案：
1. [你已经试过什么]
2. [结果如何]

错误日志（如有）：

请帮我：
1. 诊断问题根因
2. 提供解决步骤
3. 建议预防措施

请帮我为 OpenClaw Agent 生成一个 SOUL.md：

Agent 用途：[如：每天早上发送新闻摘要和天气]
目标用户：[如：我自己 / 我的小团队]
通信语言：[如：中文]
消息平台：[如：Telegram]
需要的能力：[如：网页搜索、文件读写]
安全限制：[如：不能发邮件、不能删文件、不能执行部署]
输出风格：[如：简洁专业 / 轻松幽默]

请生成完整的 SOUL.md，包含：
1. 身份定义
2. 行为准则
3. 职责列表
4. 安全限制
5. 输出格式模板

第 1 步：注册 Hetzner Cloud（2 分钟）
  → hetzner.com/cloud → 注册 → 创建项目

第 2 步：创建 VPS（3 分钟）
  → 新建服务器 → Falkenstein → Ubuntu 24.04 → CX22
  → 添加 SSH Key → 创建
  → 记录 IP：203.0.113.42

第 3 步：SSH 连接并初始化（5 分钟）
  → ssh root@203.0.113.42
  → apt update && apt upgrade -y
  → adduser openclaw && usermod -aG sudo openclaw

第 4 步：安装 OpenClaw（5 分钟）
  → su - openclaw
  → curl -fsSL https://openclaw.ai/install.sh | bash
  → 向导：Quick Start → Anthropic → 粘贴 Key → Telegram → 粘贴 Token

第 5 步：配置 SOUL.md（5 分钟）
  → nano ~/.openclaw/agents/main/agent/SOUL.md
  → 写入角色定义（参考第 8.4 节模板）

第 6 步：安全加固（5 分钟）
  → sudo apt install ufw -y
  → sudo ufw default deny incoming
  → sudo ufw allow ssh
  → sudo ufw enable
  → sudo systemctl enable openclaw-gateway

第 7 步：测试（5 分钟）
  → Telegram 发送 /status → 确认在线
  → 发送测试消息 → 确认回复正常
  → 发送 "创建一个 test.md 文件" → 确认工具执行正常

月度成本明细：
├── Hetzner CX22 VPS：€4.35/月（约 $5）
├── Anthropic API（Claude Sonnet，约 30K token/天）：约 $3/月
├── Telegram Bot：免费
├── 总计：约 $8/月
│
年度成本：约 $96/年