乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > 「一看就会」的 OpenClaw 安装指南

「一看就会」的 OpenClaw 安装指南

当前时间： 2026-03-16 01:59:21 分类：办公文件 评论(0)
「一看就会」的 OpenClaw 安装指南

本文是一份详细的 OpenClaw 安装&上手指南，即使对于没怎么折腾过开发环境的人，顺利的话半小时也能跑起来。

  • 版本 2026.3.1，以 Release 版为准：https://github.com/openclaw/openclaw/releases
  • 官方文档 docs.openclaw.ai

macOS / Linux / WSL2 为主，Windows 原生也能装但坑多。

〇、先看这里

第一次用的话，走这条线最快：

终端从哪进：macOS 用 Spotlight（⌘+空格）搜「终端」；Windows 用 WSL2 的话，开始菜单点 Ubuntu；Linux 直接打开「终端」或 Terminal。

  1. 装好 Node.js（Node 24 或 22.16+，官方要求）
  2. 在终端里贴这一行：
    • curl -fsSL https://openclaw.ai/install.sh | bash
  3. 向导里先把模型配好，别的先默认、一路回车
  4. 跑一遍 openclaw doctor 和 openclaw dashboard，能打开网页、能对话就算成

企业微信、定时任务、Skills 这些，等本地能聊起来再搞，不然容易卡在半路。

一、OpenClaw 是什么？

OpenClaw 是自托管的 AI 助手框架。说白了就是：

  • 在你本机或服务器跑一个后台（Gateway），专门伺候 AI
  • 企业微信、WhatsApp、Discord、Signal 等都能接进来，消息从这儿进、从这儿出
  • 用「技能（Skills）」扩展能力：查股票、读 PDF、发小红书之类
  • 数据、工作区、记忆都在你自己机器上

用 OpenAI、Anthropic 这些 API 时，请求还是打到人家服务器，OpenClaw 只负责在你本机跑和编排，模型不在你机器上。

OpenClaw 能做什么？

场景
说明
个人助手
记住你的偏好、管理日程、提醒任务
信息聚合
每天自动抓取 AI 新闻、科技动态、股市行情
代码助手
代码审查、Bug 分析、需求实现
内容创作
写文章、发小红书、生成报告
数据分析
查股票行情、分析 Excel/CSV、读取 PDF
自动化定时任务
每天早上推送新闻日报、定时提醒

二、安装前的准备工作

2.0 开始前看一眼

装之前心里有数就行：能联网、能装 Node（24 或 22.16+）、手头至少有一个模型 API Key，再想好是先在本地玩还是直接上云。

想少踩坑就记住：先本机、先只配模型、先 Web 里能聊起来，再折腾别的。

2.1 确认操作系统

操作系统
支持情况
推荐度
macOS
✅ 完全支持
⭐⭐⭐⭐⭐
Linux（Ubuntu/Debian）
✅ 完全支持
⭐⭐⭐⭐⭐ 服务器首选
Linux（Fedora/CentOS）
✅ 完全支持
⭐⭐⭐⭐
Windows + WSL2
✅ 支持（推荐）
⭐⭐⭐⭐
Windows 原生
⚠️ 不推荐
⭐⭐ 坑较多
树莓派（Raspberry Pi）
✅ 支持
⭐⭐⭐ 低功耗 24h 运行
云服务器（VPS）
✅ 完全支持
⭐⭐⭐⭐⭐ 7×24 在线

2.2 Windows 用户：先装 WSL2

Windows 上跑 OpenClaw，最好用 WSL2。原生 PowerShell 那一套兼容性一般，怪问题多。

步骤就这几下：

  1. 右键开始菜单 → Windows PowerShell（管理员）
  2. 执行：
    wsl --install
  3. 装完重启
  4. 重启后打开 Ubuntu（开始菜单里有），第一次会让你设用户名和密码，设一个记住就成
  5. 之后所有操作都在这个 Ubuntu 终端里做，当 Linux 用就行

WSL2 里访问 Windows 盘符用 /mnt/c/（C 盘），文件是通的，不用纠结隔离。

2.3 安装 Node.js（24 或 22.16+）

OpenClaw 就跑在 Node 上，就这一个硬依赖。官方推荐 Node 24，或者 **22 LTS 22.16+**。

先看有没有、版本够不够：

node --version

有 v24.x 或 v22.16.x 以上就跳过这节；没有或版本老，按下面来。

macOS：用 Homebrew 最省事。没装过就先装 Homebrew，再 brew install node：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"brew install node

Ubuntu / Debian / WSL2：

# 添加 NodeSource 官方源（建议 v22.16+，或使用 setup_24.x 安装 Node 24）curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs

Fedora / CentOS / RHEL：

# 推荐优先使用 nvm；系统包安装请确保装到 Node 22.16+ 或 24curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -sudo dnf install -y nodejs

多版本切换：用 nvm 就行：

# 安装 nvm（版本以 GitHub 最新 release 为准，当前示例为 v0.40.4）curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash# 重新打开终端或执行（bash 用户）source ~/.bashrc# zsh 用户执行：source ~/.zshrc# 安装并切换到 Node 22 或 24（推荐 24）nvm install 22nvm use 22# 若需 Node 24：nvm install 24 && nvm use 24# 设置默认版本（新开终端也生效）nvm alias default 22

nvm 装完后，新开终端要用 node 得先加载 nvm（一般写进 ~/.zshrc 或 ~/.bashrc），否则会找不到命令。

验证安装成功：

node --version   # 应输出 v24.x.x 或 v22.16.x 及以上npm --version    # 应输出 10.x.x 或更高

两行都有数就对了。

三、安装 OpenClaw

3.1 一键安装（省事）

终端里贴下面这条就行：

macOS / Linux / WSL2：

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

Windows PowerShell（不推荐，请优先用 WSL2）：

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

（下载就执行，省事但看不到脚本里干啥。生产环境或特别在意安全的，先看官方文档再决定。）

脚本会检查/装 Node、npm 全局装 openclaw、再拉起引导向导。2～5 分钟，看网速。

3.2 手动装（已有 Node 24 / 22.16+）

不想跑脚本就自己装：

# npm（推荐）npm install -g openclaw@latest# 或者用 pnpm（需先安装 pnpm：npm install -g pnpm）pnpm add -g openclaw@latestpnpm approve-builds -g        # 批准构建脚本（首次需要，pnpm 10.4+）pnpm add -g openclaw@latest   # 再跑一次，执行 postinstall

装好后自己跑一遍引导：

openclaw onboard --install-daemon

3.3 从源码装（开发/贡献用）

本机要有 Node 22.16+ 或 24、pnpm。改代码或给上游提 PR 用：

# 克隆仓库git clone https://github.com/openclaw/openclaw.gitcd openclaw# 安装依赖pnpm install# 构建pnpm ui:buildpnpm build# 链接为全局命令pnpm link --global# 跑引导向导openclaw onboard --install-daemon

3.4 Docker

用 Docker 的话走容器，隔离干净、迁机器也方便。典型需要：映射端口 18789（Gateway），配置可通过环境变量 OPENCLAW_CONFIG_PATH、OPENCLAW_STATE_DIR 等挂进去或挂载卷。完整镜像与 compose 示例见官方：Install with Docker

3.5 常见报错

**openclaw: command not found** — 装上了但终端找不到命令，一般是 npm 全局 bin 没进 PATH。不想折腾：用一键安装脚本再跑一遍，通常会自动配好 PATH。要自己修的话先看：

npm prefix -g   # 查看全局路径，比如 /home/你的用户名/.npm-globalecho"$PATH"# 查看当前 PATH，看有没有包含上面那个路径

PATH 里没有的话，把全局 bin 加进去：

# 添加到 PATH（zsh 用户把 .bashrc 换成 .zshrc）echo'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc# 验证openclaw --version

**EACCES: permission denied**（Linux）— 全局装到 /usr/local 没权限，改到用户目录：

# 在用户目录下创建新的 npm 全局目录mkdir -p "$HOME/.npm-global"npm config set prefix "$HOME/.npm-global"# 加入 PATHecho'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrcsource ~/.bashrc# 重新安装npm install -g openclaw@latest

sharp 装不上（macOS + Homebrew）— 和系统自带的 libvips 打架时：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

或者先安装 Xcode 命令行工具：

xcode-select --installnpm install -g openclaw@latest

网络超时 / 很慢 — 换国内源：

npm config set registry https://registry.npmmirror.comnpm install -g openclaw@latest

四、新手引导向导

装完会自动进向导，没进就自己跑：

openclaw onboard --install-daemon

有 QuickStart 和 Advanced，新手选 QuickStart 一路回车。下面一步步来：

4.1 配模型和 API Key

就这一步决定 AI 用谁家的模型。

选项
说明
获取方式
Anthropic（Claude）
Claude 系列
Anthropic Console
OpenAI（GPT）
GPT 系列
OpenAI Platform
自定义 Provider
任意 OpenAI 兼容接口
填地址 + Token

API Key 怎么拿：打开上面对应链接 → 登录/注册 → 找到「API Keys」或「API 密钥」→ 新建一个，复制那一串（别带空格）。

API Key 只存在本机 ~/.openclaw/credentials/，不会往外传。

4.2 工作区（Workspace）

工作区就是放记忆、配置、技能的那个目录。默认 ~/.openclaw/workspace，回车就行；想放别处就自己填路径。

建好后里面会有这些文件：

文件
用途
SOUL.md
AI 的性格和行为准则
USER.md
关于你的个人信息（让 AI 认识你）
MEMORY.md
AI 的长期记忆
AGENTS.md
AI 的工作规范
HEARTBEAT.md
定时心跳任务配置

都可以改，用来调 AI 的脾气。Bootstrap 跑完可能还会多出 IDENTITY.md 之类，存 AI 的自我设定。

4.3 Gateway

Gateway 是核心进程，消息都从这儿过。

配置项
默认值
说明
端口
18789
Web 界面访问端口
绑定地址
127.0.0.1
只有本机可访问
认证方式
Token
自动生成随机 Token
Tailscale
关
用于跨设备访问，可选开启

本地用就全默认、一路回车。要局域网或外网访问，把绑定改成 0.0.0.0 或配 bind: "lan"，并保证 Token 开着。

4.4 消息渠道

渠道就是 企业微信、Discord 这些入口，向导会一个个问你要不要配：

渠道
需要什么
难度
Discord
创建 Discord Bot
⭐⭐⭐ 中等
企业微信
企业微信 Bot 配置
⭐⭐⭐ 中等
Signal
Signal CLI 注册
⭐⭐⭐⭐ 较复杂
iMessage
仅 macOS
⭐⭐ 简单

新手先把渠道都跳过，浏览器里能聊起来再回来配也不迟。

4.5 装成系统服务（Daemon）

选「是」的话，Gateway 会变成后台服务，开机自启，关终端也不会停。macOS 用 LaunchAgent，Linux/WSL2 用 systemd 用户服务。

装好后想看状态和日志：

  • systemctl --user status openclaw
  • journalctl --user -u openclaw -f

只是临时玩一下可以跳过，以后要用了再 openclaw gateway start。

五、验证一下

5.1 Gateway 状态

openclaw gateway status

正常的话大概长这样（端口、延迟可能不同）：

Gateway: running · ws://127.0.0.1:18789 · reachable 12ms · auth token

5.2 自检

openclaw doctor

会查 Node 版本、配置、Gateway、权限等，有毛病会提示你怎么修。

5.3 整体状态

openclaw status

比 gateway status 信息多：版本、模型、渠道、Agent 数、内存等。

5.4 Web 控制台

openclaw dashboard

会打开浏览器到 http://127.0.0.1:18789/，就是 Web 控制台（Control UI）。发条消息能有回复，就说明通了。

算装成了：gateway status 是 running、doctor 没报拦你的错、dashboard 能开、网页里能聊。

六、第一次对话（Bootstrap）

新装完第一次开，工作区里会有 BOOTSTRAP.md，AI 会问你几件事：它叫啥、怎么叫你、时区偏好等。答完写进 USER.md 和 IDENTITY.md，后面就靠这些认你。填细一点后面更好用。

Bootstrap 只跑一次，跑完 BOOTSTRAP.md 就没了，以后再开直接进对话。

七、Skills（技能）

Skills 就是插件，一个技能一种能力。市场在 clawhub.com，下面下载量会变，看个大概就行。

跟 AI 说「帮我安装 xxx 技能」它就会自己去搜、装、配好。例如：

帮我安装天气查询技能帮我安装股票数据技能

openclaw skills list 看已装、openclaw skills check 看有没有坏的。

下载量靠前的几个（数字会变）：

技能名
功能
下载量
stock-data
股票实时行情、K线、资金流
13,524
pdf
PDF 文件读取、提取、总结
9,493
skill-creator
创建自定义技能
7,685
xlsx
Excel 文件处理分析
5,725
diagrams-generator
生成流程图、架构图
3,638
code-review
代码审查和问题分析
2,935
weather
天气查询和预报
~800
arxiv-paper-search
搜索学术论文
~500
ai-news-everyday
每日 AI 资讯日报
~400

八、配置消息渠道

不确定怎么改配置时：直接用 openclaw configure --section channels 交互配，比手改 JSON 稳。下面给的 JSON 是片段，要和现有配置合并，别整文件替换。企业微信、Signal 等看官方 Channels。

8.1 WhatsApp

用个人号扫码就行，不用商业 API。跑 openclaw configure --section channels 选 WhatsApp，会出二维码；手机 WhatsApp → 设置 → 已连接的设备 → 扫一下。完事 openclaw gateway restart，给自己发条消息试。

注意：这是基于手机 Web 会话的，手机长时间断网可能掉线，要重新扫码。

8.2 Discord

到 discord.com/developers/applications 新建应用，左侧 Bot → Add Bot，复制 Token。Bot 页面把 Message Content Intent 打开（必选），要认成员就开 Server Members Intent，Presence 随便。

OAuth2 → URL Generator，勾 bot 和 applications.commands，权限选发消息、读历史，拿链接在浏览器打开把 Bot 拉进服务器。

OpenClaw 里编辑 ~/.openclaw/openclaw.json，加上：

{"channels": {"discord": {"token": "你的BotToken"    }  }}

同样是片段，和现有配置合并。保存后 openclaw gateway restart，到服务器里 @Bot 发一句试试。

九、定时任务（Cron）

定时让 AI 干活，比如每天早上推新闻、每周五提醒写周报。

对话里直接说，比如：

每天早上 8:30 给我发一份 AI 新闻日报每周五下午 5 点提醒我写周报

它会帮你建好任务。

openclaw cron list 看任务和 id，cron run <id> 立刻跑一次，cron rm <id> 删掉。写法举例：

任务
Cron 表达式
说明
每天早 8:30 推送新闻
30 8 * * *
每天执行一次
每天下午 3 点技术更新
0 15 * * *
下午刷新资讯
每周一早 9 点周计划
0 9 * * 1
周一工作规划
工作日每小时股市监控
0 * * * 1-5
周一到周五整点执行

十、常用命令

openclaw status / gateway status / doctor   # 看状态、诊断openclaw gateway start|stop|restart        # 启停openclaw dashboard                          # 开 Web 控制台openclaw configure                          # 全量向导openclaw configure --section channels|model|gateway  # 只改某一块openclaw skills list|check                 # 技能openclaw update                             # 更新

configure --section 后面能填啥，版本不同可能不一样，openclaw configure --help 或向导里能看到。

十一、更新

如果要更新，就再跑一遍安装脚本、或 npm install -g openclaw@latest、或 openclaw update（加 --yes 跳过确认）。

更完跑一遍 openclaw doctor。

十二、丢上云（7×24 在线）

本机一关 AI 就没了，想一直在线就扔服务器上。

12.1 机器

配置
最低
顺手一点
CPU
1核
2核
内存
512MB
1～2GB
存储
5GB
20GB
系统
Ubuntu 20.04+
Ubuntu 22.04 LTS
带宽
1Mbps
5Mbps+

腾讯云、阿里云、Hetzner、DigitalOcean 都行。

12.2 怎么部署

尽量别用 root，先建个普通用户给 sudo。下面都假设你是这个普通用户。

# 1. SSH 登录服务器ssh <你的用户名>@你的服务器IP# 2. 更新系统sudo apt-get update && sudo apt-get upgrade -y# 3. 一键安装 OpenClawcurl -fsSL https://openclaw.ai/install.sh | bash# 4. 配置外网访问（让 Gateway 监听所有网卡，否则外网无法访问）# 方式一：临时生效，重启后失效#   openclaw gateway --bind lan# 方式二：永久生效 — 运行 openclaw configure，在向导里选 Gateway，将 bind 设为 lan# 方式三：永久生效 — 直接编辑 ~/.openclaw/openclaw.json，在 gateway 下加 "bind": "lan"openclaw configure# 5. 安装 systemd 服务（开机自启）openclaw onboard --install-daemon# 6. 验证（服务名以实际为准，可用 systemctl --user list-units | grep -i openclaw 查）openclaw gateway status# 或：systemctl --user status openclaw

bind: "lan" 就是监听 0.0.0.0，外网能访问。本地用别乱开。自己多设备用的话，优先 Tailscale 这类；真要暴露公网，前面挂个反向代理 + HTTPS，别裸奔。

12.3 安全

公网暴露的话：Token 别关、防火墙收一收、前面挂 Nginx/Caddy 反代 + HTTPS、别用 root 跑、系统和 OpenClaw 记得更。

防火墙（Ubuntu 示例）：

sudo ufw allow 22        # SSHsudo ufw allow 18789     # OpenClaw（若用反代，可只放行 80/443）sudo ufw enable

反向代理示例（Nginx 把 80/443 转到 Gateway 18789，便于上 HTTPS）：

# Nginx: 例如 /etc/nginx/sites-available/openclawserver {    listen 80;    server_name your-domain.com;    location / {        proxy_pass http://127.0.0.1:18789;        proxy_http_version 1.1;        proxy_set_header Upgrade $http_upgrade;        proxy_set_header Connection "upgrade";        proxy_set_header Host $host;    }}

Caddy 更简单：your-domain.com { reverse_proxy 127.0.0.1:18789 }。证书与完整配置见 Nginx/Caddy 文档。

十三、常见问题

AI 不记得上次聊的？

分两种：当前对话的上下文 vs 长期记忆（MEMORY.md、USER.md）。

想跨会话记住东西，就让 AI 把关键信息写进工作区文件，或直接说「记住这件事」。

要是同一会话里突然失忆，看看是不是换了 Agent、工作区或渠道。

配置文件在哪？

~/.openclaw/openclaw.json，手改或 openclaw configure 都行。

里头和 ~/.openclaw/credentials/ 可能有机密，别往公开仓库丢。

自定义路径看官方 Environment vars。

多台设备共用一个 AI？

一台服务器跑 OpenClaw，别的机器只装 CLI，向导里选 Remote 填地址和 Token（服务器上 openclaw status 能看见 Token）。

技能装不上？

先 openclaw skills check，多半缺依赖或要配 API Key，照着提示做。

回复很慢？

主要是模型和网络的事，和 OpenClaw 关系不大，换模型或查网络。

完全卸载？

openclaw uninstall 卸服务，npm uninstall -g openclaw 删 CLI，要清数据就 rm -rf ~/.openclaw（先备份的话 cp -r ~/.openclaw ~/.openclaw.backup）。最后一步不可逆，配置、记忆、技能全没。

多 Agent？

每个 Agent 独立工作区，openclaw agents add myagent 加一个。

渠道配了没反应？

openclaw channels list 看状态、openclaw doctor 跑一遍。

要看日志就 openclaw gateway stop 然后直接 openclaw gateway 前台跑。

多半是 Token 填错、没重启 Gateway、或者防火墙拦了。

当前用的哪个模型？

openclaw status 里有。要换就 openclaw configure --section model。

总结

从零到能聊：装好 Node → 运行一键安装脚本 → 在向导里配好模型（其余默认）→ openclaw doctor 和 openclaw dashboard，网页里能对话就算成。

之后想扩展：技能直接在对话里说「帮我安装 xxx 技能」；消息渠道用 openclaw configure --section channels 按提示配。

遇到问题：先跑 openclaw doctor，按提示排查；仍不行再看上文「常见报错」和「常见问题」。

参考文献

[1] OpenClaw. Getting started (Quick start) [EB/OL]. https://docs.openclaw.ai/start/quickstart

[2] OpenClaw. Install [EB/OL]. https://docs.openclaw.ai/install

[3] OpenClaw. Onboarding wizard [EB/OL]. https://docs.openclaw.ai/start/wizard

[4] OpenClaw. Channels [EB/OL]. https://docs.openclaw.ai/channels

[5] OpenClaw. Environment variables [EB/OL]. https://docs.openclaw.ai/help/environment

[6] OpenClaw. openclaw/openclaw [EB/OL]. https://github.com/openclaw/openclaw

[7] Node.js. NodeSource distributions [EB/OL]. https://github.com/nodesource/distributions

[8] nvm-sh. nvm: Node Version Manager [EB/OL]. https://github.com/nvm-sh/nvm

[9] pnpm. approve-builds [EB/OL]. https://pnpm.io/cli/approve-builds