OpenInfoHub
Go back

OpenClaw 完全指南（二）：快速安装与配置

在上一篇文章中，我们了解了 OpenClaw 的核心概念和架构。现在让我们动手实践，从零开始安装和配置你自己的 OpenClaw 实例。

目录

前置准备

在开始安装之前，确保你的系统满足以下要求：

系统要求

操作系统：

运行时环境：

硬件配置：

AI 模型准备

你需要至少一个 AI 模型的访问权限：

推荐选项（按优先级）：

  1. Anthropic Claude（强烈推荐）

    • Claude Opus 4.6 提供最佳的长上下文处理
    • 更好的提示注入抵抗能力
    • 需要 Anthropic API 密钥或 Pro/Max 订阅

  2. OpenAI

    • GPT-4、GPT-5.2 或 Codex 模型
    • 需要 OpenAI API 密钥

  3. 自定义提供商

    • 任何 OpenAI 兼容或 Anthropic 兼容的 API
    • 本地模型（通过 Ollama 等）

可选：消息平台账号

根据你想使用的频道准备：

快速安装（推荐）

OpenClaw 提供了最简单的一键安装方式。

方法一：全局安装（推荐）

使用 npm 全局安装 OpenClaw：

npm install -g openclaw@latest

或使用 pnpm：

pnpm add -g openclaw@latest

或使用 bun：

bun add -g openclaw@latest

方法二：一键安装脚本

在 macOS 或 Linux 上，可以使用官方安装脚本：

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

这个脚本会自动：

验证安装

安装完成后，验证 OpenClaw 是否正确安装：

openclaw --version

你应该看到类似 vYYYY.M.D 的版本号。

使用配置向导

OpenClaw 提供了一个交互式配置向导，这是设置 OpenClaw 的推荐方式。

启动向导

运行以下命令启动配置向导并安装守护进程：

openclaw onboard --install-daemon

向导流程

向导会引导你完成以下步骤：

1. 选择配置模式

向导首先会询问你选择配置模式：

QuickStart 默认设置：

建议：首次使用选择 QuickStart，熟悉后可以手动调整配置。

2. 配置模型和认证

向导会询问你要使用的 AI 模型提供商：

选择 Anthropic（推荐）：

? 选择 AI 提供商: Anthropic
? 输入 Anthropic API 密钥: sk-ant-xxxxx
? 选择默认模型: claude-opus-4-6

选择 OpenAI：

? 选择 AI 提供商: OpenAI
? 输入 OpenAI API 密钥: sk-xxxxx
? 选择默认模型: gpt-4

选择自定义提供商：

? 选择 AI 提供商: Custom Provider
? 选择兼容性: OpenAI-compatible / Anthropic-compatible / Unknown
? 输入 Base URL: https://api.example.com/v1
? 输入 API 密钥: xxxxx
? 输入模型 ID: custom-model-name
? 输入模型别名（可选）: my-model
? 输入端点 ID: custom-endpoint

密钥存储模式：

向导支持两种密钥存储方式：

引用模式示例：

# 设置环境变量
export ANTHROPIC_API_KEY="sk-ant-xxxxx"

# 使用引用模式运行向导
openclaw onboard --secret-input-mode ref

3. 配置工作区

工作区是 Agent 存储文件、记忆和技能的地方。

? 工作区位置: ~/.openclaw/workspace (默认)

向导会自动创建工作区并生成引导文件：

4. 配置 Gateway

Gateway 是 OpenClaw 的核心控制平面。

? Gateway 端口: 18789 (默认)
? 绑定地址: 127.0.0.1 (默认，仅本地访问)
? 认证模式: token (推荐)
? Tailscale 暴露: off (默认)

Tailscale 选项（可选）：

如果你想远程访问 Gateway：

5. 配置频道

向导会询问你想连接哪些消息平台。

配置 Telegram：

? 配置 Telegram? Yes
? Telegram Bot Token: 123456:ABCDEF...
? 允许的用户（逗号分隔）: @your_username

配置 WhatsApp：

? 配置 WhatsApp? Yes
? 允许的号码（逗号分隔）: +1234567890

WhatsApp 会显示一个二维码，使用你的 WhatsApp 扫描配对。

配置 Discord：

? 配置 Discord? Yes
? Discord Bot Token: xxxxx
? 允许的用户 ID（逗号分隔）: 123456789

其他频道：

向导还支持配置：

6. 安装守护进程

向导会询问是否安装系统守护进程，让 Gateway 在后台持续运行。

? 安装守护进程? Yes

macOS：创建 LaunchAgent Linux/WSL2：创建 systemd 用户单元

7. 健康检查

向导会启动 Gateway 并验证其运行状态：

✓ Gateway 已启动
✓ WebSocket 连接正常
✓ 认证配置正确
✓ 频道连接成功

8. 安装技能

最后，向导会询问是否安装推荐的技能：

? 安装推荐技能? Yes

推荐技能可能包括：

完成配置

配置完成后，向导会：

  1. 打开 Control UI 仪表板
  2. 显示访问链接（不含 token）
  3. 提供下一步建议
✓ OpenClaw 配置完成！

Dashboard: http://localhost:18789
Token: xxxxx (保存在 ~/.openclaw/openclaw.json)

下一步：
- 在 Telegram/WhatsApp 中发送消息测试
- 访问 Dashboard 查看状态
- 运行 'openclaw status' 检查系统状态

手动配置（高级）

如果你想完全控制配置，可以手动编辑配置文件。

配置文件位置

OpenClaw 的配置文件位于：

~/.openclaw/openclaw.json

最小配置示例

{
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "workspace": "~/.openclaw/workspace"
  },
  "gateway": {
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    }
  },
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF",
      "allowFrom": ["@your_username"]
    }
  }
}

完整配置示例

{
  "logging": {
    "level": "info"
  },
  "agent": {
    "model": "anthropic/claude-opus-4-6",
    "workspace": "~/.openclaw/workspace",
    "thinkingDefault": "high",
    "timeoutSeconds": 1800,
    "heartbeat": {
      "every": "30m"
    }
  },
  "gateway": {
    "port": 18789,
    "bind": "127.0.0.1",
    "auth": {
      "mode": "token",
      "token": "your-secure-token-here"
    },
    "tailscale": {
      "mode": "off"
    }
  },
  "channels": {
    "telegram": {
      "botToken": "123456:ABCDEF",
      "allowFrom": ["@your_username"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    },
    "whatsapp": {
      "allowFrom": ["+1234567890"],
      "groups": {
        "*": {
          "requireMention": true
        }
      }
    }
  },
  "routing": {
    "groupChat": {
      "mentionPatterns": ["@openclaw", "openclaw"]
    }
  },
  "session": {
    "scope": "per-sender",
    "resetTriggers": ["/new", "/reset"],
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080
    }
  },
  "browser": {
    "enabled": true,
    "color": "#FF4500"
  }
}

环境变量

OpenClaw 支持通过环境变量覆盖配置：

# 自定义主目录
export OPENCLAW_HOME=/custom/path

# 自定义状态目录
export OPENCLAW_STATE_DIR=/custom/state

# 自定义配置文件路径
export OPENCLAW_CONFIG_PATH=/custom/config.json

# Telegram Bot Token
export TELEGRAM_BOT_TOKEN=123456:ABCDEF

# Discord Bot Token
export DISCORD_BOT_TOKEN=xxxxx

# Slack Tokens
export SLACK_BOT_TOKEN=xoxb-xxxxx
export SLACK_APP_TOKEN=xapp-xxxxx

从源码安装（开发者）

如果你想参与开发或需要最新的功能，可以从源码安装。

克隆仓库

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

安装依赖

推荐使用 pnpm：

pnpm install

构建 UI

pnpm ui:build

这会自动安装 UI 依赖并构建前端。

构建项目

pnpm build

运行配置向导

pnpm openclaw onboard --install-daemon

开发模式

在开发模式下运行，支持自动重载：

pnpm gateway:watch

启动 Gateway

配置完成后，有多种方式启动 Gateway。

方式一：使用守护进程（推荐）

如果你在配置向导中安装了守护进程，Gateway 会自动启动。

macOS：

# 启动
launchctl start ai.openclaw.gateway

# 停止
launchctl stop ai.openclaw.gateway

# 查看状态
launchctl list | grep openclaw

Linux/WSL2：

# 启动
systemctl --user start openclaw-gateway

# 停止
systemctl --user stop openclaw-gateway

# 查看状态
systemctl --user status openclaw-gateway

# 开机自启
systemctl --user enable openclaw-gateway

方式二：手动启动

直接运行 Gateway：

openclaw gateway --port 18789 --verbose

参数说明：

方式三：后台运行

使用 nohup 在后台运行：

nohup openclaw gateway --port 18789 > /tmp/openclaw.log 2>&1 &

验证安装

检查 Gateway 状态

openclaw status

输出示例：

✓ Gateway 运行中 (PID: 12345)
✓ WebSocket: ws://127.0.0.1:18789
✓ 已连接频道: telegram, whatsapp
✓ 活跃会话: 2
✓ 工作区: ~/.openclaw/workspace

完整诊断

运行完整的系统诊断：

openclaw status --all

这会检查：

深度检查

包括 Gateway 健康探测：

openclaw status --deep

健康检查（JSON 格式）

openclaw health --json

访问 Control UI

OpenClaw 提供了一个 Web 界面用于管理和监控。

打开 Dashboard

openclaw dashboard

这会自动在浏览器中打开 Dashboard。

手动访问

在浏览器中访问：

http://localhost:18789

如果启用了 Token 认证，需要输入 Token（在配置文件中的 gateway.auth.token）。

Dashboard 功能

常见问题排查

问题 1：Node.js 版本过低

错误：

Error: OpenClaw requires Node.js 22 or higher

解决：

使用 nvm 安装最新版本：

# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

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

或使用 Homebrew（macOS）：

brew install node@22

问题 2：端口被占用

错误：

Error: Port 18789 is already in use

解决：

查找占用端口的进程：

# macOS/Linux
lsof -i :18789

# 或使用不同端口
openclaw gateway --port 18790

问题 3：WhatsApp 配对失败

错误：

Error: Failed to pair WhatsApp

解决：

  1. 确保使用专用的 WhatsApp 号码（不是你的主号码）
  2. 清除旧的凭证： 
    rm -rf ~/.openclaw/credentials/whatsapp
  3. 重新运行配对： 
    openclaw channels login

问题 4：API 密钥无效

错误：

Error: Invalid API key

解决：

  1. 验证 API 密钥是否正确
  2. 检查 API 密钥是否有足够的权限
  3. 更新配置文件中的密钥
  4. 重启 Gateway

问题 5：权限问题（macOS）

错误：

Error: Permission denied

解决：

macOS 可能需要授予某些权限：

  1. 系统偏好设置 > 安全性与隐私
  2. 隐私选项卡
  3. 授予以下权限：
    • 完全磁盘访问（如果需要）
    • 辅助功能（用于浏览器控制）
    • 屏幕录制（用于截图功能）

查看日志

日志文件位于：

/tmp/openclaw/openclaw-YYYY-MM-DD.log

实时查看日志：

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

下一步

恭喜！你已经成功安装和配置了 OpenClaw。现在你可以：

  1. 连接更多频道：在下一篇文章中，我们将详细介绍如何配置各种消息平台
  2. 开始对话：向你的 Agent 发送第一条消息
  3. 自定义工作区：编辑 AGENTS.md 和 SOUL.md 来定制 Agent 的行为
  4. 安装技能：添加更多功能和集成

在下一篇文章中，我们将深入探讨：

参考资源

内容基于 OpenClaw 官方文档改编，遵循内容许可限制

Share this post on:
Share this post on X Share this post via Telegram Share this post on Pinterest Share this post via email
Previous Post
OpenClaw 完全指南（三）：频道配置与日常使用
Next Post
OpenClaw 完全指南（一）：重新定义个人 AI 助手