OpenClaw 入门指南：从零到一的完整安装配置教程

📚 AI 工具使用教程
⏱️ 阅读时间：约 20 分钟

💡

想拥有一个 24 小时待命的个人 AI 助手吗？OpenClaw 让你能够在 WhatsApp、Telegram、Discord 等常用聊天工具中随时随地与 AI 对话。本文将从零开始，带你完成 OpenClaw 的完整安装和配置，让你在最短时间内拥有属于自己的 AI 助手。

📑 目录导航

📌 一、什么是 OpenClaw？为什么你需要它？
📌 二、安装前的准备工作
📌 三、完整安装步骤
📌 四、模型认证配置
📌 五、通道配置详解
📌 六、配置文件详解
📌 七、常见问题与解决方案
📌 八、最佳实践建议
📌 九、下一步学习路径
📌 十、总结

# OpenClaw 入门指南：从零到一的完整安装配置教程

一、什么是 OpenClaw？为什么你需要它？

1.1 OpenClaw 的核心价值

OpenClaw 不是一个简单的”ChatGPT 包装器”，而是一个本地优先的控制平面，让你能够在自己的硬件上运行一个功能强大的 AI 助手，并通过你日常使用的聊天应用（WhatsApp、Telegram、Discord、iMessage 等）随时随地访问它。

核心价值主张：

特性	传统 AI 服务	OpenClaw
数据隐私

数据存储在第三方服务器

数据完全本地控制	可用性	依赖网络连接和服务状态	24/7 本地运行，不受外部影响	定制化	有限的自定义选项	完全可配置，支持多代理、多模型	集成成本

需要单独访问每个平台	统一接口，多通道支持	成本	按使用量计费	一次性硬件投入，长期使用

1.2 适用场景

OpenClaw 适合以下场景：

个人助手：日常问答、任务管理、信息整理

开发辅助：代码审查、文档查询、自动化脚本

团队协作：在团队聊天工具中集成 AI 能力

智能家居：与家庭自动化系统集成

学习研究：知识库管理、文献整理

1.3 系统要求

最低配置：

CPU：1 核心

内存：1GB RAM

存储：500MB 磁盘空间

Node.js：版本 22 或更高

推荐配置：

CPU：2 核心或更高

内存：2GB RAM 或更高

存储：2GB+（用于日志、媒体文件）

操作系统：Ubuntu LTS、macOS、Windows（WSL2）

二、安装前的准备工作

2.1 检查系统环境

在开始安装之前，我们需要确认系统满足基本要求。

检查 Node.js 版本：

node --version

如果版本低于 22，需要升级：

macOS (使用 Homebrew)
brew install node@22

Ubuntu/Debian
curl -fsSL https://deb.nodesource.com/setup_22.xsudo -E bash -
sudo apt-get install -y nodejs

Windows (下载官方安装包)
# https://nodejs.org/

检查 pnpm（推荐）：

pnpm --version

如果没有安装 pnpm：

npm install -g pnpm

2.2 选择安装方式

OpenClaw 提供两种安装方式：

安装方式	适用场景	优点	缺点	npm 安装

普通用户，快速上手

简单快捷，自动更新	无法修改源代码	Git 安装	开发者，需要定制	可修改源码，参与贡献	需要手动更新

推荐：新手用户选择 npm 安装，开发者选择 Git 安装。

三、完整安装步骤

3.1 方法一：npm 安装（推荐新手）

步骤 1：安装 OpenClaw

npm install -g openclaw@latest

步骤 2：运行引导向导

openclaw onboard --install-daemon

这个命令会：

引导你完成模型认证设置

配置 Gateway 基本参数

选择要启用的通道（WhatsApp、Telegram 等）

安装系统服务（开机自启）

步骤 3：检查 Gateway 状态

openclaw gateway status

如果看到 Runtime: running，说明安装成功。

步骤 4：打开控制面板

openclaw dashboard

这会在浏览器中打开 OpenClaw 的 Web 控制面板，你可以在这里：

查看会话历史

配置系统参数

管理连接的通道

监控系统状态

3.2 方法二：Git 安装（开发者）

步骤 1：克隆仓库

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

步骤 2：安装依赖

pnpm install
pnpm build

步骤 3：运行引导向导

pnpm openclaw onboard --install-daemon

步骤 4：开发模式运行（可选）

pnpm openclaw gateway --port 18789

四、模型认证配置

OpenClaw 支持多种 AI 模型提供商，以下是主流配置方法。

4.1 Anthropic（Claude）配置

方式一：使用 Setup Token（订阅用户）

如果你使用 Claude Pro/Max 订阅：

claude setup-token

复制生成的 token，然后在 OpenClaw 中配置：

openclaw models auth paste-token --provider anthropic

方式二：使用 API Key（推荐生产环境）

1. 登录 [Anthropic Console](https://console.anthropic.com/)
2. 创建 API Key
3. 配置到 OpenClaw：

openclaw models auth paste-token --provider anthropic
粘贴 API Key

4.2 OpenAI（Codex/GPT）配置

使用 OAuth（订阅用户）：

openclaw models auth login --provider openai-codex --set-default

这会打开浏览器完成 OAuth 认证流程。

使用 API Key：

openclaw models auth paste-token --provider openai
粘贴 API Key

4.3 本地模型配置（完全离线）

如果你希望数据完全本地化，可以使用本地模型：

使用 LM Studio：

1. 下载并安装 [LM Studio](https://lmstudio.ai/)
2. 下载合适的模型（推荐 7B+ 参数）
3. 启动本地服务器
4. 配置 OpenClaw：

{
  models: {
    providers: {
      "local": {
        baseUrl: "http://localhost:1234/v1",
        api: "openai-completions"
      }
    },
    defaults: {
      primary: "local/your-model-name"
    }
  }
}

4.4 模型选择建议

使用场景	推荐模型	理由	日常对话

Claude Sonnet / GPT-4o | 响应快，成本低 |

五、通道配置详解

5.1 WhatsApp 配置

步骤 1：启用 WhatsApp

在引导向导中选择 WhatsApp，或手动配置：

openclaw channels login whatsapp

步骤 2：扫描二维码

系统会显示一个二维码，用 WhatsApp 手机应用扫描。

步骤 3：配置访问控制

编辑配置文件 ~/.openclaw/openclaw.json：

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",  // pairing | allowlist | open | disabled
      allowFrom: ["+8613800138000"],  // 允许的用户号码
      groups: {
        "": { requireMention: true }  // 群组中需要@提及才响应
      }
    }
  }
}

步骤 4：重启 Gateway

openclaw gateway restart

5.2 Telegram 配置

步骤 1：创建 Bot

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot

创建新机器人

3. 复制 Bot Token

步骤 2：配置 OpenClaw

{
  channels: {
    telegram: {
      botToken: "YOUR_BOT_TOKEN",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],  // 用户 ID 或 @username
      groups: {
        "": { requireMention: true }
      }
    }
  }
}

步骤 3：获取用户 ID

方法一：查看日志

openclaw logs --follow
发送消息给 bot，查看 from.id

方法二：使用官方 API

curl "https://api.telegram.org/botYOUR_BOT_TOKEN/getUpdates"

5.3 Discord 配置

步骤 1：创建 Discord 应用

1. 访问 [Discord Developer Portal](https://discord.com/developers/applications)
2. 创建新应用
3. 进入 “Bot” 页面，创建机器人
4. 复制 Bot Token

步骤 2：邀请机器人到服务器

生成邀请链接：

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=0&scope=bot

步骤 3：配置 OpenClaw

{
  channels: {
    discord: {
      token: "YOUR_BOT_TOKEN",
      guilds: {
        "YOUR_GUILD_ID": {
          requireMention: false,
          channels: {
            "general": { allow: true }
          }
        }
      }
    }
  }
}

六、配置文件详解

6.1 配置文件位置

~/.openclaw/openclaw.json

6.2 最小可用配置

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace"
    }
  },
  channels: {
    whatsapp: {
      allowFrom: ["+8613800138000"]
    }
  }
}

6.3 常用配置项

代理配置：

{
  agents: {
    list: [
      {
        id: "main",
        workspace: "~/.openclaw/workspace",
        model: "anthropic/claude-sonnet-4-5-20260514"
      },
      {
        id: "coding",
        workspace: "~/.openclaw/workspace-coding",
        model: "anthropic/claude-opus-4-5-20260514"
      }
    ]
  }
}

消息配置：

{
  messages: {
    responsePrefix: "🦞",  // 回复前缀
    ackReaction: "👀",     // 确认表情
    queue: {
      mode: "collect",     // 消息队列模式
      debounceMs: 1000     // 防抖时间
    }
  }
}

安全配置：

{
  gateway: {
    bind: "127.0.0.1",  // 绑定地址
    port: 18789,        // 端口
    auth: {
      token: "YOUR_GATEWAY_TOKEN"
    }
  },
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",  // 只允许白名单用户
      allowFrom: ["+8613800138000"]
    }
  }
}

七、常见问题与解决方案

7.1 安装问题

问题 1：Node.js 版本过低

使用 nvm 管理 Node 版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

问题 2：权限错误

npm 全局安装权限问题
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

7.2 Gateway 启动问题

问题：Gateway 无法启动

查看详细日志
openclaw logs --follow

检查配置
openclaw doctor

重置配置
openclaw doctor --fix

问题：端口被占用

查找占用端口的进程
lsof -i :18789

修改配置使用其他端口
# 编辑 ~/.openclaw/openclaw.json
{
  gateway: { port: 18790 }
}

7.3 通道连接问题

WhatsApp 无法连接：

1. 检查网络连通性
2. 重新扫描二维码
3. 清除认证缓存：

<code class="language-bash"  rm -rf ~/.openclaw/credentials/whatsapp/*
   openclaw channels login whatsapp

Telegram 收不到消息：

1. 检查 Bot Token 是否正确
2. 确认用户已启动与 bot 的对话
3. 检查 allowFrom

配置

八、最佳实践建议

8.1 安全建议

1. 使用白名单：始终配置 allowFrom

限制访问用户

2. 启用配对码：对未知用户启用配对码验证
3. 定期更新：保持 OpenClaw 为最新版本
4. 备份配置：定期备份 ~/.openclaw/

8.2 性能优化

1. 使用 SSD：提高文件读写速度
2. 限制历史消息：配置 historyLimit

减少上下文大小

3. 选择合适的模型：根据任务选择性价比最高的模型
4. 启用缓存：配置模型缓存减少重复请求

8.3 运维建议

1. 监控系统状态：定期检查 openclaw gateway status
2. 日志轮转：配置日志文件大小限制
3. 自动重启：使用 systemd 或 LaunchAgent 实现开机自启
4. 备份策略：

<code class="language-bash"  # 创建备份脚本
   tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

九、下一步学习路径

完成基础安装后，你可以继续学习：

1. 多通道集成：配置 WhatsApp、Telegram、Discord 等多个通道
2. 多代理系统：创建不同用途的 AI 代理（工作、个人、开发）
3. 技能开发：编写自定义技能扩展 AI 能力
4. 远程部署：在 VPS 上部署，实现随时随地访问
5. 自动化任务：配置定时任务和自动化工作流

十、总结

OpenClaw 为你提供了一个强大而灵活的个人 AI 助手平台。通过本文的完整教程，你应该已经：

✅ 完成了 OpenClaw 的安装和配置
✅ 理解了核心概念和架构
✅ 配置了至少一个聊天通道
✅ 掌握了基本的故障排除方法

关键要点回顾：

OpenClaw 是本地优先的 AI 网关，数据完全可控

支持多种 AI 模型和聊天平台

配置灵活，可根据需求定制

社区活跃，文档完善

现在，你的 AI 助手已经准备就绪！开始探索更多可能性吧。

参考资料：

[OpenClaw 官方文档](https://docs.openclaw.ai)

[GitHub 仓库](https://github.com/openclaw/openclaw)

[社区 Discord](https://discord.com/invite/clawd)

[技能市场](https://clawhub.com)

下一篇预告：《OpenClaw 多通道集成实战：WhatsApp/Telegram/Discord 全攻略》

/* 基础样式 */
.article-container {
max-width: 100%;
margin: 0 auto;
padding: 15px;
font-family: -apple-system, BlinkMacSystemFont, “Segoe UI”, “PingFang SC”, “Hiragino Sans GB”, “Microsoft YaHei”, sans-serif;
line-height: 1.8;
color: #333;
background: #fff;
}

/* 文章头部 */
.article-header {
border-bottom: 3px solid #4a90e2;
padding-bottom: 20px;
margin-bottom: 25px;
}

.main-title {
font-size: 1.8em;
color: #1a1a1a;
margin-bottom: 12px;
font-weight: 700;
line-height: 1.3;
}

.article-meta {
display: flex;
gap: 12px;
flex-wrap: wrap;
align-items: center;
}

.category-badge {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: #fff;
padding: 4px 12px;
border-radius: 16px;
font-size: 0.85em;
font-weight: 500;
}

.read-time {
color: #666;
font-size: 0.85em;
}

/* 导读框 */
.intro-box {
background: linear-gradient(135deg, #f0f4ff 0%, #e8f0fe 100%);
border-left: 4px solid #4a90e2;
padding: 18px;
margin: 20px 0;
border-radius: 0 8px 8px 0;
display: flex;
gap: 12px;
align-items: flex-start;
}

.intro-icon {
font-size: 1.8em;
flex-shrink: 0;
}

.intro-text {
margin: 0;
color: #444;
font-size: 1em;
line-height: 1.6;
}

/* 目录 */
.toc-container {
background: #f8f9fa;
border: 1px solid #e9ecef;
border-radius: 8px;
padding: 15px;
margin: 25px 0;
}

.toc-title {
font-size: 1.2em;
color: #333;
margin-bottom: 12px;
font-weight: 600;
}

.toc-list {
list-style: none;
padding: 0;
margin: 0;
}

.toc-list li {
margin: 6px 0;
}

.toc-list a {
color: #4a90e2;
text-decoration: none;
display: block;
padding: 6px 10px;
border-radius: 4px;
font-size: 0.95em;
transition: all 0.2s;
}

.toc-list a:hover {
background: #4a90e2;
color: #fff;
}

/* 文章内容 */
.article-content {
font-size: 1em;
}

.article-title {
font-size: 1.6em;
color: #1a1a1a;
margin: 35px 0 18px;
padding-bottom: 8px;
border-bottom: 2px solid #4a90e2;
}

.section-title {
font-size: 1.4em;
color: #2c3e50;
margin: 30px 0 12px;
padding-left: 12px;
border-left: 4px solid #4a90e2;
}

.subsection-title {
font-size: 1.2em;
color: #34495e;
margin: 22px 0 10px;
}

.subsubsection-title {
font-size: 1.05em;
color: #666;
margin: 18px 0 8px;
}

/* 代码块 – 支持横向滚动 */
.code-wrapper {
margin: 18px 0;
border-radius: 6px;
overflow: hidden;
}

.code-block {
background: #1e1e1e;
padding: 15px;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
margin: 0;
border-radius: 6px;
}

.code-block code {
color: #d4d4d4;
font-family: “Fira Code”, “Consolas”, “Monaco”, monospace;
font-size: 0.85em;
line-height: 1.6;
white-space: pre;
}

.inline-code {
background: #f5f5f5;
color: #e83e8c;
padding: 2px 6px;
border-radius: 3px;
font-family: “Fira Code”, “Consolas”, monospace;
font-size: 0.9em;
}

/* 表格 – 响应式滚动 */
.table-wrapper {
margin: 20px 0;
overflow-x: auto;
-webkit-overflow-scrolling: touch;
border-radius: 8px;
box-shadow: 0 2px 8px rgba(0,0,0,0.08);
}

.styled-table {
width: 100%;
border-collapse: collapse;
min-width: 600px;
font-size: 0.9em;
}

.styled-table thead {
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
color: #fff;
}

.styled-table th {
padding: 12px 15px;
text-align: left;
font-weight: 600;
white-space: nowrap;
}

.styled-table td {
padding: 12px 15px;
border-bottom: 1px solid #e1e4e8;
vertical-align: top;
}

.styled-table tbody tr {
transition: background 0.2s;
}

.styled-table tbody tr:hover {
background: #f8f9fa;
}

.styled-table tbody tr:nth-child(even) {
background: #fafbfc;
}

.styled-table tbody tr:nth-child(odd) {
background: #fff;
}

/* 列表 */
.styled-list {
list-style: none;
padding: 0;
margin: 15px 0;
}

.list-item {
padding: 6px 0 6px 22px;
position: relative;
color: #333;
}

.list-item::before {
content: “•”;
position: absolute;
left: 0;
color: #4a90e2;
font-weight: bold;
font-size: 1.2em;
}

.checkbox-item {
padding: 6px 0 6px 32px;
position: relative;
color: #333;
}

.checkbox-item.checked {
color: #28a745;
}

/* 信息框 */
.info-box {
background: #e8f4fd;
border-left: 4px solid #4a90e2;
padding: 15px;
margin: 18px 0;
border-radius: 0 6px 6px 0;
color: #2c3e50;
}

/* 分隔线 */
.section-divider {
border: none;
height: 2px;
background: linear-gradient(to right, transparent, #4a90e2, transparent);
margin: 35px 0;
}

/* 文章尾部 */
.article-footer {
margin-top: 40px;
padding-top: 25px;
border-top: 2px solid #e9ecef;
}

.tags-section {
margin-bottom: 20px;
}

.tag-label {
font-weight: 600;
color: #666;
margin-right: 8px;
}

.tag {
display: inline-block;
background: #f0f4ff;
color: #4a90e2;
padding: 4px 10px;
border-radius: 12px;
margin: 3px;
font-size: 0.85em;
text-decoration: none;
transition: all 0.2s;
}

.tag:hover {
background: #4a90e2;
color: #fff;
}

.back-to-top {
text-align: center;
padding: 15px;
background: #f8f9fa;
border-radius: 6px;
}

.back-to-top a {
color: #4a90e2;
text-decoration: none;
font-weight: 500;
}

/* 移动端优化 */
@media (max-width: 768px) {
.article-container {
padding: 12px;
}

.main-title {
font-size: 1.4em;
}

.article-title {
font-size: 1.3em;
}

.section-title {
font-size: 1.2em;
}

.code-block {
padding: 12px;
font-size: 0.8em;
}

.styled-table {
font-size: 0.85em;
min-width: 500px;
}

.styled-table th,
.styled-table td {
padding: 10px 12px;
}

.intro-box {
padding: 15px;
}

.intro-icon {
font-size: 1.5em;
}
}

@media (max-width: 480px) {
.main-title {
font-size: 1.3em;
}

.article-meta {
flex-direction: column;
gap: 8px;
}

.category-badge,
.read-time {
font-size: 0.8em;
}

.code-block {
font-size: 0.75em;
padding: 10px;
}

.styled-table {
min-width: 450px;
font-size: 0.8em;
}

.styled-table th,
.styled-table td {
padding: 8px 10px;
}
}

// 移动端表格提示
document.addEventListener(‘DOMContentLoaded’, function() {
var tables = document.querySelectorAll(‘.table-wrapper’);
tables.forEach(function(table) {
if (!table.querySelector(‘.scroll-hint’)) {
var hint = document.createElement(‘div’);
hint.className = ‘scroll-hint’;
hint.innerHTML = ‘👈 左右滑动查看更多’;
hint.style.cssText = ‘text-align:center;padding:8px;background:#f8f9fa;color:#666;font-size:12px;border-radius:0 0 8px 8px;’;
table.parentNode.insertBefore(hint, table.nextSibling);
}
});
});

OpenClaw 入门指南：从零到一的完整安装配置教程

一、什么是 OpenClaw？为什么你需要它？

1.1 OpenClaw 的核心价值

1.2 适用场景

1.3 系统要求

二、安装前的准备工作

2.1 检查系统环境

macOS (使用 Homebrew)

Ubuntu/Debian

Windows (下载官方安装包)

2.2 选择安装方式

三、完整安装步骤

3.1 方法一：npm 安装（推荐新手）

3.2 方法二：Git 安装（开发者）

四、模型认证配置

4.1 Anthropic（Claude）配置

粘贴 API Key

4.2 OpenAI（Codex/GPT）配置

粘贴 API Key

4.3 本地模型配置（完全离线）

4.4 模型选择建议

五、通道配置详解

5.1 WhatsApp 配置

5.2 Telegram 配置

发送消息给 bot，查看 from.id

5.3 Discord 配置

六、配置文件详解

6.1 配置文件位置

6.2 最小可用配置

6.3 常用配置项

七、常见问题与解决方案

7.1 安装问题

使用 nvm 管理 Node 版本

npm 全局安装权限问题

7.2 Gateway 启动问题

查看详细日志

检查配置

重置配置

查找占用端口的进程

修改配置使用其他端口

7.3 通道连接问题

八、最佳实践建议

8.1 安全建议

8.2 性能优化

8.3 运维建议

九、下一步学习路径

十、总结

相关推荐

OpenClaw 安全与访问控制：保护你的 AI 助手

Midjourney 绘画教程_AI 绘画入门

OpenClaw 远程部署指南：VPS/云服务器完整教程

AI 视频生成工具实战：Runway、Pika、Sora 技术解析与应用场景

OpenClaw 高级配置与最佳实践：从入门到精通

OpenClaw 多通道集成实战：WhatsApp/Telegram/Discord 全攻略