乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > OpenClaw 安装部署完全指南:从零开始打造你的私人 AI 助理

OpenClaw 安装部署完全指南:从零开始打造你的私人 AI 助理

当前时间： 1970-01-01 08:00:00 分类：办公文件 评论(0)
OpenClaw 安装部署完全指南:从零开始打造你的私人 AI 助理

一篇搞定 OpenClaw 的安装、启动、配置与目录结构详解

一、OpenClaw 是什么？

OpenClaw 是一个自托管的 AI 网关服务，它能够将你常用的聊天应用（WhatsApp、Telegram、Discord、飞书、iMessage 等）连接到 AI 编程智能体。简单来说，你只需要在自己的设备上运行一个 Gateway 进程，就可以通过手机上的聊天软件随时随地调用 AI 助手。

核心特点：

  • • 自托管：数据完全由你自己掌控，不依赖第三方云服务
  • • 多渠道支持：一个 Gateway 同时服务 WhatsApp、Telegram、Discord、飞书等多个平台
  • • 智能体原生：专为编程智能体设计，支持工具调用、会话管理、记忆系统
  • • 开源免费：MIT 许可证，社区驱动开发

二、系统要求

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

       
                                           
项目要求
操作系统macOS / Linux / Windows (推荐 WSL2)
Node.js版本 22 或更高
包管理器npm / pnpm / bun（任选其一）
       
     

检查 Node 版本：

node --version
# 输出应显示 v22.x.x 或更高

三、安装方式详解

OpenClaw 提供多种安装方式，推荐使用安装脚本一键完成。

3.1 方式一：安装脚本（推荐）

这是最简单的安装方式，脚本会自动检测并安装 Node.js，然后完成 OpenClaw 的安装。

macOS / Linux / WSL2：

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

Windows PowerShell：

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

安装完成后，脚本会自动启动配置向导。

安装流程图

3.2 方式二：npm 全局安装

如果你已经安装了 Node.js 22+，可以直接使用 npm 安装：

npm install -g openclaw@latest

如果遇到 sharp 构建错误，可以使用以下命令：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3.3 方式三：pnpm 安装

pnpm 用户需要额外的构建脚本审批步骤：

pnpm add -g openclaw@latest
pnpm approve-builds -g  # 审批 openclaw、sharp 等包的构建脚本

3.4 方式四：从源码构建

开发者或贡献者可以选择从源码构建：

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

# 安装依赖并构建
pnpm install
pnpm ui:build
pnpm build

# 全局链接 CLI
pnpm link --global

四、启动命令详解

安装完成后，你需要运行初始化配置和启动服务。

4.1 运行配置向导

openclaw onboard --install-daemon

这个命令会：

  1. 1. 启动交互式配置向导
  2. 2. 引导你设置 API 认证
  3. 3. 配置 Gateway 参数
  4. 4. 安装系统服务（launchd/systemd）

4.2 启动 Gateway 服务

方式一：后台服务模式

openclaw gateway start

方式二：前台运行模式

openclaw gateway --port 18789

前台模式适合调试和故障排查，日志会直接输出到终端。

4.3 查看服务状态

openclaw gateway status

输出示例：

Gateway Service: running (pid: 12345)
WebSocket: ws://127.0.0.1:18789
Config: ~/.openclaw/openclaw.json

4.4 打开控制面板

openclaw dashboard

这会在浏览器中打开 Web 控制界面（默认地址：http://127.0.0.1:18789/）。

五、常用命令速查表

以下是 OpenClaw 最常用的命令汇总：

       
                                           
命令功能说明
openclaw onboard启动配置向导
openclaw gateway start启动 Gateway 服务
openclaw gateway stop停止 Gateway 服务
openclaw gateway restart重启 Gateway 服务
openclaw gateway status查看服务状态
openclaw gateway --port 18789前台运行 Gateway
openclaw dashboard打开 Web 控制界面
openclaw doctor诊断配置问题
openclaw status查看会话和连接状态
openclaw config get <path>获取配置值
openclaw config set <path> <value>设置配置值
openclaw channels list列出已配置的渠道
openclaw channels login登录渠道账号（如 WhatsApp）
openclaw logs --follow实时查看日志
openclaw models status查看模型配置状态
       
     

六、目录结构详解

OpenClaw 的核心数据存储在 ~/.openclaw/ 目录下，了解每个文件的作用有助于更好地管理和调试。

~/.openclaw/
├── openclaw.json          # 主配置文件（JSON5 格式）
├── openclaw.json.bak      # 配置文件备份
├── workspace/             # 智能体工作空间
│   ├── AGENTS.md          # 工作空间说明文档
│   ├── SOUL.md            # 智能体人格定义
│   ├── USER.md            # 用户信息
│   ├── MEMORY.md          # 长期记忆文件
│   ├── HEARTBEAT.md       # 心跳检查配置
│   ├── TOOLS.md           # 工具配置说明
│   ├── IDENTITY.md        # 身份标识
│   └── memory/            # 每日记忆日志
│       └── YYYY-MM-DD.md  # 按日期存储的记忆文件
├── agents/                # 多智能体配置目录
├── channels/              # 渠道会话数据
├── devices/               # 设备配对信息
├── logs/                  # 日志文件目录
├── media/                 # 媒体文件缓存
├── cron/                  # 定时任务配置
├── delivery-queue/        # 消息投递队列
├── identity/              # 身份凭证
├── subagents/             # 子智能体数据
└── extensions/            # 扩展插件

6.1 核心文件说明

openclaw.json - 主配置文件

这是 OpenClaw 的核心配置文件，采用 JSON5 格式（支持注释和尾逗号）。基本结构：

{
  // Gateway 网关配置
  gateway: {
    port: 18789,           // WebSocket 端口
    mode: "local",         // 运行模式：local | remote
    auth: {
      mode: "token",       // 认证方式：token | password
      token: "your-token"  // 认证令牌
    }
  },

  // 智能体默认配置
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: {
        primary: "anthropic/claude-sonnet-4-5"
      }
    }
  },

  // 渠道配置
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",  // DM 访问策略
      allowFrom: ["+15555550123"]
    },
    telegram: {
      enabled: true,
      botToken: "123:abc"
    }
  }
}

workspace/ - 智能体工作空间

这是 AI 智能体的"大脑"所在，包含：

  • • SOUL.md：定义智能体的人格、语气和行为准则
  • • USER.md：存储用户的基本信息和偏好
  • • MEMORY.md：长期记忆，保存重要决策和上下文
  • • memory/ 目录：每日记忆日志，记录当天发生的事件

AGENTS.md - 工作空间指南

这个文件告诉智能体如何使用工作空间：

  • • 每次会话开始时，智能体会自动读取 SOUL.md、USER.md 和当天的记忆文件
  • • 记忆文件帮助智能体保持上下文连续性

七、配置示例

7.1 最小配置

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

7.2 多渠道配置

{
  channels: {
    whatsapp: {
      enabled: true,
      dmPolicy: "pairing",
      groups: {
        "*": { requireMention: true }
      }
    },
    telegram: {
      enabled: true,
      botToken: "123456:ABC-DEF",
      dmPolicy: "allowlist",
      allowFrom: ["tg:12345678"]
    },
    discord: {
      enabled: true,
      botToken: "MTk4NjI...",
      dmPolicy: "open"
    }
  }
}

7.3 模型配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-4o"]
      }
    }
  }
}

八、故障排查

8.1 常见问题诊断

# 运行诊断工具
openclaw doctor

# 查看详细日志
openclaw logs --follow

# 检查配置有效性
openclaw config validate

8.2 openclaw 命令找不到

如果安装后运行 openclaw 提示命令不存在：

# 检查 npm 全局路径
npm prefix -g

# 添加到 PATH（添加到 ~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"

8.3 Gateway 无法启动

检查端口是否被占用：

# macOS/Linux
lsof -i :18789

# 终止占用进程或使用其他端口
openclaw gateway --port 18790

九、进阶功能

9.1 心跳检查

设置定期检查任务：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",      // 每 30 分钟
        target: "last"     // 发送到上次对话的渠道
      }
    }
  }
}

9.2 定时任务（Cron）

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2
  }
}

9.3 沙箱模式

在隔离的 Docker 容器中运行智能体：

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent"     // session | agent | shared
      }
    }
  }
}

十、更新与卸载

10.1 更新 OpenClaw

openclaw update
# 或
npm update -g openclaw

10.2 卸载

# 卸载服务
openclaw uninstall --service --state

# 卸载 CLI
npm uninstall -g openclaw

# 完全清理
openclaw uninstall --all --yes

结语

OpenClaw 为开发者和高级用户提供了一个强大的自托管 AI 助理解决方案。通过本文的详细指南，你应该已经掌握了从安装到配置的完整流程。接下来，你可以：

  1. 1. 连接你常用的聊天渠道
  2. 2. 自定义智能体的人格和记忆
  3. 3. 探索更多高级功能（多智能体、沙箱、自动化等）

开始打造属于你自己的私人 AI 助理吧！ 🦞