Skip to main content
← All posts
作者：Sagasu
AIOpenClaw启动之道

OpenClaw实战教程系列第02篇 - 5分钟安装指南：从零到第一句话

目标：一行命令装好 OpenClaw，完成初始化，和 AI 说上第一句话。

开始之前：你需要准备什么？

硬件要求

  • 一台 Mac（推荐）、Linux、或 Windows 电脑

  • 至少 2GB RAM（推荐 4GB+）

  • 稳定的网络连接

软件要求

  • Node.js 22+（后面会教你怎么装）

  • 一个 LLM API Key（现在就去申请，后面马上要用）

技能要求

  • 会用终端（Terminal）

  • 懂基本命令行操作（cd、ls 这些）

如果你都准备好了，我们开始。

第一步：获取 API Key（5 分钟）

OpenClaw 本身免费，但它需要调用 LLM API。你需要先申请一个 API Key。

推荐方案：AWS Bedrock（最稳定）

为什么推荐 Bedrock：

  • 国内访问稳定（不需要梯子）

  • 模型全（Claude 3.5/3.7 Opus/Sonnet/Haiku 都有）

  • 计费透明，可按需付费

申请步骤：

  1. 注册 AWS 账号（需要信用卡验证）

  2. 进入 AWS 控制台，搜索 “Bedrock”

  3. 在 “Model access” 页面申请 Claude 4.5 Sonnet/Opus 的访问权限（通常几分钟到几小时批准）

  4. 创建 IAM 用户，获取 Access Key ID 和 Secret Access Key

费用预期：

  • 轻度使用：$5-10/月

  • 中度使用：$10-20/月

  • 重度使用：$20-50/月

备选方案：其他 LLM 提供商

提供商优点缺点适合谁
OpenAIGPT-5 系列强国内不稳定有稳定梯子
Google AIGemini 便宜有时限流预算有限
AnthropicClaude 原版国内不稳定有稳定梯子
DeepSeek国产，便宜模型能力一般想省钱

重要提示： 不管选哪家，都要先确保能正常访问。可以在终端测试：

# 测试网络连通性（以 Bedrock 为例）
curl -I https://bedrock-runtime.us-east-1.amazonaws.com

如果能返回 HTTP 状态码，说明网络没问题。

第二步：安装 Node.js（如果还没有）

Mac 用户（推荐用 Homebrew）

# 先安装 Homebrew（如果还没有）
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装 nvm（Node 版本管理器）
brew install nvm

# 按照终端提示，把 nvm 配置添加到 ~/.zshrc 或 ~/.bash_profile
# 通常是这两行：
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 重新加载配置
source ~/.zshrc  # 或 source ~/.bash_profile

# 安装 Node.js 22+
nvm install 22
nvm use 22

# 验证
node --version  # 应该显示 v22.x.x 或更高

Linux 用户

# 使用 nvm 安装（推荐）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

# 重新加载终端或执行
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

# 安装 Node.js
nvm install 22
nvm use 22

# 验证
node --version

Windows 用户

⚠️ 重要：官方不支持原生 Windows！ 强烈推荐使用 WSL2（Windows Subsystem for Linux），原生 Windows 存在工具兼容性问题，特别是 WhatsApp/Telegram 渠道。

第一步：安装 WSL2（必须）

# 以管理员身份打开 PowerShell，执行：
wsl --install
# 安装完成后重启电脑，选择 Ubuntu 发行版

第二步：在 WSL2 内安装 Node.js（按 Linux 步骤操作）

# 进入 WSL2 终端后，按照上方 Linux 步骤安装 nvm 和 Node.js 22
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node --version

💡 如果你坚持使用原生 Windows（不推荐），可以下载 nvm-windows，但请做好遇到兼容性问题的准备：https://github.com/coreybutler/nvm-windows/releases

第三步：安装 OpenClaw（官方推荐方式）

Mac / Linux（推荐）

官方提供了一键安装脚本：

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

这个脚本会自动：

  • 下载最新版 OpenClaw

  • 安装到系统 PATH

  • 设置必要的权限

Windows（PowerShell）

iwr -useb https://openclaw.ai/install.ps1 | iex

其他安装方式（备选）

如果脚本安装失败，也可以用 npm：

npm install -g openclaw

或 Homebrew（Mac）：

brew install openclaw

验证安装

openclaw --version

如果看到版本号（比如 1.2.3），恭喜你，安装成功！

第四步：初始化配置（完整指南）

方式一：交互式向导（推荐新手）

官方推荐的初始化命令：

openclaw onboard --install-daemon

这个命令会启动交互式向导，带你完成基础配置。

向导流程详解：

? 选择你的 LLM 提供商: (Use arrow keys)
❯ AWS Bedrock        # 企业级，国内稳定
  Anthropic          # Claude原版，需梯子
  OpenAI             # GPT系列，需梯子
  Google AI          # Gemini，速度快
  Venice AI          # 隐私优先，无需KYC
  Moonshot AI        # 国产Kimi，中文好
  DeepSeek           # 国产，便宜
  ...

? 输入你的 API Key: [隐藏输入]
? 选择默认模型: (Use arrow keys)
❯ claude-3-5-sonnet-20241022   # 性价比最高
  claude-3-opus-20240229       # 最强推理
  ...

✓ 配置完成！
✓ Gateway 已安装为系统服务
✓ Gateway 已启动

方式二：手动配置（推荐进阶用户）

配置文件位于 ~/.openclaw/openclaw.json，格式为 JSON5（支持删除我这里的注释和emoji，这里是方便理解是什么，但是不能直接复制，会报错。还有就是要加上尾随逗号）。

核心配置结构：

{
  // 🔥 最核心：Agent 行为控制
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace",
      "model": {
        "primary": "anthropic/claude-3-5-sonnet-20241022",
        "fallbacks": ["google/gemini-1.5-flash"]  // 主模型失败时自动切换
      },
      "temperature": 0.2,        // 创造性vs确定性（0-2）
      "timeoutSeconds": 600,     // 单次请求超时
      "heartbeat": {
        "every": "30m"           // 30分钟无消息自动重置会话
      }
    }
  },

  // 🤖 模型提供商配置
  "models": {
    "providers": {
      // 国内用户推荐：Moonshot Kimi
      "moonshot": {
        "type": "moonshot",
        "apiKey": "YOUR_MOONSHOT_API_KEY",
        "baseUrl": "https://api.moonshot.cn/v1",  // 国内用.cn，海外用.ai
        "models": [{
          "id": "kimi-k2.5",
          "name": "Kimi K2.5",
          "contextWindow": 256000
        }]
      }
    }
  },

  // 📱 聊天渠道安全设置（必配！）
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "YOUR_BOT_TOKEN",
      "allowFrom": ["123456789"]  // 只接受指定用户的消息
    },
    "whatsapp": {
      "dmPolicy": "pairing",     // 配对模式：更安全
      "allowFrom": ["+86138xxxx"] // 只接受指定手机号
    }
  },

  // ⚙️ Gateway 基础设置
  "gateway": {
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "your-secure-token"  // Dashboard 访问令牌
    }
  },

  // 🛡️ 安全沙箱配置
  "tools": {
    "allow": ["read", "write", "edit", "exec"],
    "deny": ["browser"],         // 禁用高危工具
    "exec": {
      "timeoutSec": 1800         // 命令执行超时
    }
  }
}

配置文件关键参数说明：

参数路径类型推荐值说明
agents.defaults.model.primarystring见下方模型推荐主模型
agents.defaults.temperaturenumber0.2越低越确定，越高越创造性
agents.defaults.heartbeat.everystring"30m"空闲重置时间，省 Token
channels.*.allowFromarray[“你的 ID”]安全白名单，必配！
tools.allow/denyarray-工具权限控制

模型选择指南

官方推荐组合：

用途推荐模型成本特点
主力模型Claude 3.5 Sonnet$3/百万 token平衡能力价格
轻量任务Gemini 1.5 Flash$0.075/百万 token便宜 40 倍
复杂推理Claude 3 Opus$15/百万 token最强能力
中文场景Kimi K2.5¥0.1/千 token国产，中文好

国内用户推荐配置：

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "moonshot/kimi-k2.5",
        "fallbacks": ["deepseek/deepseek-chat"]
      }
    }
  },
  "models": {
    "providers": {
      "moonshot": {
        "type": "moonshot",
        "apiKey": "YOUR_KEY",
        "baseUrl": "https://api.moonshot.cn/v1"
      }
    }
  }
}

成本优化必配参数

节省 Token 的关键配置：

{
  "agents": {
    "defaults": {
      // 温度设为0.2，减少模型"胡思乱想"
      "temperature": 0.2,
      
      // 30分钟无消息自动重置，避免长上下文累积
      "heartbeat": {
        "every": "30m"
      },
      
      // 上下文压缩阈值，超过2万token自动压缩
      "compaction": {
        "reserveTokensFloor": 20000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  }
}

安全配置检查清单

⚠️ 生产环境必做：

  1. 限制消息来源（防止陌生人使用你的 AI）

    "channels": {
  "telegram": {
    "allowFrom": ["你的Telegram数字ID"]
  }
}

  2. 禁用高危工具（如果不是必须）

    "tools": {
  "deny": ["browser", "exec"]
}

  3. 设置消费预警（防止 API 被盗刷）

    # 在提供商后台设置预算上限
# AWS Bedrock: 设置 CloudWatch 预警
# OpenAI: 设置 Usage limit

验证配置

1. 检查配置语法：

openclaw doctor --fix

2. 查看 Gateway 状态：

openclaw gateway status

3. 测试模型连接：

openclaw agent --message "你好" --thinking low

4. 验证安全配置：

# 检查是否只接受白名单用户
openclaw config get channels.telegram.allowFrom

⚠️ 重要提醒：

  • 修改配置后大部分参数热重载，无需重启

  • 但 gateway.port、auth.token 等核心配置需要重启：openclaw gateway restart

  • 永远不要将 openclaw.json 上传到 GitHub，它包含 API 密钥

  • 建议定期备份配置：cp ~/.openclaw/openclaw.json ~/backups/

第五步：打开 Dashboard，完成第一次对话

官方推荐用 dashboard 命令打开浏览器界面：

openclaw dashboard

这会：

  1. 自动在浏览器打开 Dashboard

  2. 复制带 token 的安全链接到剪贴板

  3. 如果是无头环境（服务器），显示 SSH 隧道提示

你会看到类似输出：

🦀 OpenClaw Dashboard
━━━━━━━━━━━━━━━━━━
链接已复制到剪贴板！
浏览器正在打开...
http://127.0.0.1:18789/?token=xxxxx

💡 无头环境提示：
ssh -N -L 18789:127.0.0.1:18789 user@host

手动访问 Dashboard

如果 openclaw dashboard 没有自动打开浏览器，手动访问：

http://127.0.0.1:18789

⚠️ 首次访问需要 token：运行 openclaw dashboard 获取带 token 的完整链接，或在设置中输入 gateway.auth.token。

开始第一次对话

你会看到这样的界面：

┌─────────────────────────────────────────┐
│  🦀 OpenClaw                            │
│  ─────────────────────────────────────  │
│                                         │
│  系统: 运行中 ✓                          │
│  模型: claude-3-5-sonnet-20241022       │
│  渠道: WebUI                            │
│                                         │
│  ┌─────────────────────────────────┐   │
│  │ 你: 你好，自我介绍一下            │   │
│  │                                 │   │
│  │ AI: 你好！我是你的 OpenClaw     │   │
│  │ 助手。我可以帮你：               │   │
│  │ • 读写本地文件                  │   │
│  │ • 执行终端命令                  │   │
│  │ • 搜索网页                      │   │
│  │ • 操作浏览器                    │   │
│  │                                 │   │
│  │ 有什么我可以帮你的吗？           │   │
│  └─────────────────────────────────┘   │
│                                         │
│  [输入消息...]  [发送]                   │
└─────────────────────────────────────────┘

🎉 恭喜你！OpenClaw 已经跑起来了！

第六步（可选）：管理 Gateway

如果你之前用 openclaw onboard --install-daemon 安装，Gateway 已经设置为开机自启。

常用命令

# 查看 Gateway 状态
openclaw gateway status

# 停止 Gateway
openclaw gateway stop

# 重启 Gateway
openclaw gateway restart

# 在前台运行 Gateway（调试用）
openclaw gateway --port 18789

手动安装为系统服务（如果之前没装）

# macOS
openclaw gateway install

# Linux（systemd）
sudo tee /etc/systemd/system/openclaw.service > /dev/null <<eof [unit]="" description="OpenClaw" gateway="" after="network.target" [service]="" type="simple" user="$USER" execstart="$(which" openclaw)="" start="" restart="on-failure" [install]="" wantedby="multi-user.target" eof="" sudo="" systemctl="" daemon-reload="" enable="" openclaw="" <="" code=""></eof>

故障排除：常见问题

Q1: npm install -g 报 EACCES 权限错误

症状：

<code class="plaintext">npm ERR! Error: EACCES: permission denied
</code>

解决方案：

不要用 sudo npm install（会导致后续更多权限问题），改用下面的方法：

<code class="bash"># 1. 创建 npm 全局目录
mkdir ~/.npm-global

# 2. 配置 npm 使用这个目录
npm config set prefix '~/.npm-global'

# 3. 添加 PATH
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 4. 重新安装
npm install -g openclaw
</code>

Q2: 启动后 WebUI 打不开（端口被占用）

症状：
浏览器访问 http://127.0.0.1:18789 显示无法连接。

排查步骤：

<code class="bash"># 1. 检查端口占用
lsof -i :18789

# 2. 如果端口被占用，修改配置
cat ~/.openclaw/openclaw.json | sed 's/18789/18790/' > /tmp/config.json
mv /tmp/config.json ~/.openclaw/openclaw.json

# 3. 重启
openclaw gateway restart

# 4. 访问新端口
open http://127.0.0.1:18790
</code>

Q3: API Key 填错了，怎么修改？

<code class="bash"># 直接编辑配置文件
nano ~/.openclaw/openclaw.json

# 修改 API Key 后保存，然后重启
openclaw gateway restart
</code>

Q4: 启动成功，但 AI 不回复/报错

检查清单：

  1. API Key 是否有效？

    <code class="bash"># 测试 API Key（以 Bedrock 为例）
aws sts get-caller-identity
</code>

  2. 网络是否正常？

    <code class="bash"># 测试连通性
curl -I https://bedrock-runtime.us-east-1.amazonaws.com
</code>

  3. 查看日志

    <code class="bash"># macOS 日志位置
tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

# 或使用 openclaw 命令查看
openclaw logs
</code>

  4. 模型是否有权限？（AWS Bedrock）

    • 进入 AWS 控制台 → Bedrock → Model access

    • 确保你用的模型（如 Claude 3.5 Sonnet）状态是 “Access granted”

Q5: 支持哪些模型？

完整支持列表：

提供商支持的模型
AWS BedrockClaude 3.5/3.7 Opus/Sonnet/Haiku, Llama 3, Mistral
OpenAIGPT-4o, GPT-4-turbo, GPT-3.5-turbo
GoogleGemini 1.5 Pro/Flash
AnthropicClaude 3 系列（官方 API）
其他任何兼容 OpenAI API 格式的模型

验证清单：确保安装成功

完成以下检查，确认 OpenClaw 已正确安装：

  • Node.js 22+ 已安装 (node --version)

  • OpenClaw 已安装 (openclaw --version)

  • API Key 已配置

  • Gateway 正在运行 (openclaw gateway status)

  • Dashboard 能打开 (openclaw dashboard)

  • 能成功和 AI 对话

如果全部通过，恭喜你，安装成功！ 🎉

下一步

安装完成后，你肯定迫不及待想用手机和 AI 聊天。下一篇教你如何连接 Telegram/Discord/iMessage：

→ 第 03 篇 | 连接你的第一个聊天渠道 — 配好渠道后，用手机随时随地和 AI 对话。

💬 安装遇到问题？

在评论区留言，或加入读者微信群 saga-su（备注 OpenClaw）求助。

📚 本系列目录

  • 第 01 篇：OpenClaw 是什么？

  • 第 02 篇：5 分钟安装指南（你在这里）

  • 第 03 篇：连接你的第一个聊天渠道

  • 查看完整目录

下一篇预告：连接 Telegram/Discord/iMessage，让你的手机变成 AI 遥控器。包含每个平台的详细配置步骤，以及踩坑实录（Discord 超时、iMessage 权限等）。