夜雨聆风
OpenClaw 简介
OpenClaw 是一个开源的个人 AI 助手平台，它允许你在自己的设备上运行一个强大的 AI 助手，并通过日常使用的通讯工具与之交互。这个项目最初名为 ClawdBot，后改名为 Moltbot，现在统一使用 OpenClaw 这个名称。截至 2026 年初，该项目在 GitHub 上已经获得超过 19 万个星标，是 Node.js 生态中最活跃的个人 AI 助手项目之一。
与传统的云端 AI 服务不同，OpenClaw 完全运行在你自己的计算机上，这意味着你可以完全掌控自己的数据和工作流程。它支持连接多种主流大语言模型，包括 Anthropic Claude、OpenAI GPT、Google Gemini，以及本地运行的 Ollama 模型。通过 WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Microsoft Teams 和 Google Chat 等通讯平台，你可以随时随地与你的 AI 助手对话，让它帮你处理邮件、管理日历、编写代码，甚至控制智能家居设备。
OpenClaw 采用 MIT 开源协议，拥有活跃的社区支持。它的模块化设计允许开发者通过技能系统扩展功能，社区中已经涌现出大量创造性的应用场景，从自动化公司运营到个人生活管理，展现了个人 AI 助手的巨大潜力。
官方网站：https://openclaw.ai/
系统要求与准备工作
在开始安装 OpenClaw 之前，你需要确保系统满足基本的运行要求。OpenClaw 对硬件的要求并不高，但对软件环境有明确的版本要求。
首先是 Node.js 环境。OpenClaw 要求 Node.js 版本必须在 22.0 或更高版本。这是一个硬性要求，低于此版本将无法正常运行。如果你的系统中已经安装了较低版本的 Node.js，建议使用 nvm（Node Version Manager）来管理多个 Node.js 版本，这样可以避免版本冲突问题。
在操作系统方面，OpenClaw 支持主流的桌面和服务器操作系统。macOS 用户可以直接在 macOS 10.15 或更高版本上运行。Linux 用户需要确保使用较新的发行版，推荐 Ubuntu 20.04 及以上版本、Debian 11 及以上版本，或者 CentOS 8 及以上版本。Windows 用户则需要通过 WSL2（Windows Subsystem for Linux 2）来运行 OpenClaw，因为它依赖一些 Unix 环境的特性。
除了基本的系统环境，你还需要准备一个大语言模型服务的 API Key。OpenClaw 本身不提供 AI 能力，它需要连接到外部的 LLM 服务。你可以选择 Anthropic Claude、OpenAI GPT、Google Gemini 等商业服务，也可以使用本地运行的 Ollama 模型。如果选择商业服务，你需要提前注册账号并获取 API Key。
对于需要连接通讯平台的用户，还需要准备相应平台的访问凭证。例如，如果要使用 WhatsApp 功能，需要准备一个可用的 WhatsApp 账号；使用 Telegram 则需要创建一个 Telegram Bot 并获取 Bot Token。这些配置可以在安装完成后进行，初始阶段并非必需。
安装方式选择与对比
OpenClaw 提供了多种安装方式，每种方式都有其适用场景和特点。选择合适的安装方式可以大大简化部署过程，提高使用体验。
官方提供的安装脚本是最推荐的方式，特别适合初次接触 OpenClaw 的用户。这个脚本会自动检测系统环境，安装必要的依赖，并完成 OpenClaw 的配置。使用脚本安装的好处是省心省力，脚本会处理大部分环境配置工作，你只需要按照提示进行选择即可。这种方式特别适合在 Linux 服务器或 macOS 系统上快速部署。
通过 npm 安装是另一种常见方式。如果你已经有了完整的 Node.js 环境，并且熟悉 npm 包管理器，这种方式会很直接。只需要一条命令就可以将 OpenClaw 安装为全局命令行工具。这种方式的优点是简单快速，缺点是需要自己确保 Node.js 版本符合要求，并且在某些系统上可能需要解决权限问题。
pnpm 是 npm 的替代品，它在处理依赖时更加高效，占用的磁盘空间更少。如果你的项目中已经在使用 pnpm，或者对包管理性能有较高要求，可以选择这种方式。pnpm 的安装方式与 npm 类似，但它使用符号链接来避免重复安装相同的依赖包，这在管理多个 Node.js 项目时特别有用。
Docker 安装方式适合那些希望将 OpenClaw 与系统环境完全隔离的用户。通过 Docker 容器运行 OpenClaw，你不需要担心系统依赖问题，也不会影响到宿主机的环境。这种方式特别适合在服务器上长期运行，或者需要同时运行多个 OpenClaw 实例的场景。Docker 方式的缺点是需要额外学习 Docker 的使用方法，并且在某些功能上可能受到容器环境的限制。
从源码安装是最灵活的方式，适合开发者或需要自定义修改的用户。你可以直接从 GitHub 克隆源代码仓库，然后本地编译运行。这种方式可以让你深入了解 OpenClaw 的内部结构，方便进行调试和功能扩展。但相应地，它也是最复杂的安装方式，需要处理各种编译依赖和构建工具。
对于大多数用户来说，官方安装脚本是最佳选择。它在易用性和功能完整性之间取得了很好的平衡。如果你在使用过程中需要更灵活的控制，可以随时切换到其他安装方式。
使用官方脚本安装
官方安装脚本是最简便的安装方式，它会自动处理大部分配置工作。整个安装过程通常只需要几分钟时间。
首先确保你的系统已经安装了 Node.js 22 或更高版本。打开终端，运行以下命令检查 Node.js 版本：
官方网站：https://nodejs.org/
node --version
如果版本低于 22.0，你需要先升级 Node.js。推荐使用 nvm 来管理 Node.js 版本。安装 nvm 后，运行以下命令安装并切换到最新的 Node.js 版本：
nvm install 22
nvm use 22
确认 Node.js 版本符合要求后，运行官方提供的安装脚本。在终端中执行：
npm install -g openclaw
这条命令会从 npm 仓库下载并安装 OpenClaw 的最新版本。安装过程中，脚本会自动检测系统环境，下载必要的依赖包。整个过程可能需要几分钟时间，具体取决于你的网络速度和系统配置。
安装完成后，你可以运行以下命令验证安装是否成功：
which openclaw
openclaw --version
如果命令能够正常执行并显示版本号，说明安装已经成功。此时 OpenClaw 已经作为全局命令行工具安装在你的系统中，你可以在任何目录下使用 openclaw 命令。
在 macOS 系统上，如果遇到权限问题，可能需要在安装命令前加上 sudo。但更推荐的做法是配置 npm 的全局安装路径，避免使用 sudo，这样可以减少潜在的安全风险。
初始化配置向导
安装完成后，第一次启动 OpenClaw 需要进行初始化配置。OpenClaw 提供了友好的配置向导，会引导你完成所有必要的设置。
运行以下命令启动配置向导：
openclaw onboard
配置向导会以交互式问答的形式进行。首先它会询问你希望如何使用 OpenClaw。你可以选择在终端中使用（TUI 模式），或者通过 Web 界面使用。对于初次使用的用户，建议选择 TUI 模式，这样可以更直观地了解 OpenClaw 的工作方式。后续你随时可以开启 Web 界面。
接下来向导会要求你配置 AI 模型。OpenClaw 支持多种 LLM 服务，包括 Anthropic Claude、OpenAI GPT、Google Gemini 等。新版本的配置向导会自动识别你系统中可用的模型配置。如果你已经有了 API Key，可以直接输入；如果还没有，可以先跳过这一步，后续再进行配置。
以配置 Google Gemini 为例，选择 Google 选项后，向导会提示你登录 Google 账号并授权。完成授权后，你可以从可用的模型列表中选择一个模型。Gemini 提供了多个版本的模型，包括 Gemini Pro、Gemini Ultra 等，你可以根据需求和配额选择合适的版本。
如果你选择使用 Anthropic Claude，需要提供 Claude API Key。登录 Anthropic 官网，在 API Keys 页面创建一个新的 API Key，然后将它粘贴到配置向导中。OpenAI GPT 的配置过程类似，需要从 OpenAI Platform 获取 API Key。
配置完 AI 模型后，向导会询问你是否要安装技能插件。OpenClaw 的技能系统允许你扩展功能，社区提供了许多实用的技能，比如邮件管理、日历同步、文件操作等。你可以使用空格键选择要安装的技能，支持多选。对于首次安装，建议先安装一些常用的基础技能，后续可以根据需要再添加更多。
在技能选择环节结束后，向导会显示一个 “Install missing skill dependencies” 的界面，这里会列出所选技能需要的依赖包。确认后，向导会自动安装这些依赖。
最后，向导会询问一些可选配置，比如是否要设置启动时自动加载的 markdown 文本（boot-md 功能），是否要启用命令日志记录（command-logger 功能）等。这些功能可以根据个人需求选择，对于初学者来说，可以先跳过这些高级选项。
完成所有配置后，向导会提示你重启服务。选择确认后，OpenClaw 就完成了初始化，可以开始使用了。
网关管理与服务控制
OpenClaw 使用网关（Gateway）来管理与外部服务的连接。网关是 OpenClaw 架构中的核心组件，它负责接收来自通讯平台的消息，将消息转发给 AI 模型处理，然后将结果返回给用户。理解和掌握网关管理命令是高效使用 OpenClaw 的基础。
最基本的启动命令是在前台运行网关。执行以下命令：
openclaw gateway run
这个命令会在当前终端窗口中启动网关，你可以实时看到所有的日志输出。这种方式适合用于调试和开发，因为你可以直接观察到每一次交互的详细过程。但缺点是一旦关闭终端窗口，网关就会停止运行。
对于日常使用，更推荐使用后台守护进程模式。运行以下命令：
openclaw gateway start
这个命令会将网关作为后台服务启动，即使关闭终端窗口，网关也会继续运行。你可以随时通过 SSH 连接到服务器，无需担心网关被意外终止。
要停止正在运行的网关，使用：
openclaw gateway stop
如果需要重启网关（比如修改了配置文件后），可以使用：
openclaw gateway restart
这个命令会先停止当前运行的网关，然后立即重新启动。它等效于先执行 stop 再执行 start，但更加便捷。
要查看网关的当前状态，使用：
openclaw gateway status
这个命令会显示网关是否正在运行，以及运行了多长时间。如果网关没有运行，命令会明确提示。
OpenClaw 还提供了将网关安装为系统服务的功能。执行以下命令：
openclaw gateway install
这个命令会将 OpenClaw 网关注册为系统服务，实现开机自动启动。在 Linux 系统上，它会创建一个 systemd 服务单元；在 macOS 上，它会创建一个 launchd 配置文件。这样即使系统重启，OpenClaw 也会自动恢复运行。
如果你使用 Docker 部署，网关管理命令会略有不同。对于 Docker 容器，你可以使用标准的 Docker 命令来管理：
docker restart openclaw
docker stop openclaw
docker start openclaw
OpenClaw 还提供了一个简化的守护进程管理命令集。如果你觉得 gateway 子命令太长，可以使用 daemon 别名：
openclaw daemon start
openclaw daemon stop
openclaw daemon restart
openclaw daemon status
这些命令与 gateway 命令功能完全相同，只是提供了一个更简短的写法。
常用命令汇总
OpenClaw 提供了丰富的命令行工具来管理和使用系统。熟练掌握这些命令可以大大提高使用效率。
启动 OpenClaw 最简单的方式是直接运行：
openclaw
不带任何参数的 openclaw 命令会启动默认的交互模式。如果你已经配置了 Web 界面，可以使用：
openclaw dashboard
这个命令会在浏览器中打开 OpenClaw 的 Web 控制台。Web 控制台提供了图形化的界面来管理配置、查看日志和执行操作。
要查看或修改配置，使用：
openclaw config
这个命令会打开配置文件编辑器，你可以直接修改各种设置，比如更换 API Key、调整模型参数等。OpenClaw 的配置文件使用 JSON 格式，结构清晰易懂。
技能管理是 OpenClaw 的重要功能。要查看已安装的技能列表，使用：
openclaw skills
这个命令会显示所有已安装的技能及其状态。你可以从这里看到每个技能的版本、描述和启用状态。
要更新 OpenClaw 到最新版本，运行：
openclaw update
这个命令会检查是否有新版本可用，如果有，会自动下载并安装。OpenClaw 会保留你的配置和数据，所以更新过程是安全的。
当遇到问题时，OpenClaw 提供了一个诊断工具：
openclaw doctor
这个命令会自动检测系统配置，查找可能的问题并尝试修复。它会检查 Node.js 版本、依赖包完整性、配置文件有效性等，并给出具体的修复建议。
要查看 OpenClaw 的日志，使用：
openclaw logs
默认情况下，这个命令会显示最近的日志记录。如果你想实时跟踪日志，可以添加 --follow 参数：
openclaw logs --follow
这样日志会持续输出，类似于 tail -f 的效果。你可以实时看到每一次操作和交互的详细过程。
如果需要查看所有可用的命令和选项，使用：
openclaw --help
这个命令会显示完整的命令列表和使用说明。每个子命令也有自己的帮助信息，比如 openclaw gateway --help 会显示网关相关的所有命令。
通讯平台集成
OpenClaw 的核心价值在于它能够与各种通讯平台无缝集成，让你通过日常使用的聊天工具与 AI 助手交互。配置通讯平台连接需要一些额外的步骤，但一旦完成，就可以享受到极大的便利。
WhatsApp 集成是最受欢迎的功能之一。要连接 WhatsApp，你需要在 OpenClaw 配置中启用 WhatsApp 技能。首次连接时，OpenClaw 会生成一个二维码，你需要使用 WhatsApp 扫描这个二维码来完成配对。配对成功后，你就可以直接通过 WhatsApp 向你的 AI 助手发送消息了。OpenClaw 会在后台保持与 WhatsApp 的连接，实时接收和回复消息。
Telegram 的集成相对简单。首先你需要创建一个 Telegram Bot，通过 @BotFather 机器人可以快速完成这个过程。创建 Bot 后，你会获得一个 Bot Token，将这个 Token 配置到 OpenClaw 中即可。与 WhatsApp 不同，Telegram Bot 不需要保持持续连接，它使用 Webhook 或轮询方式接收消息，这意味着即使 OpenClaw 暂时离线，消息也不会丢失。
Discord 集成适合团队协作场景。你需要在 Discord 开发者门户创建一个应用程序，然后创建一个 Bot 用户。将 Bot 的 Token 配置到 OpenClaw 中，并将 Bot 邀请到你的 Discord 服务器。配置完成后，服务器中的用户都可以通过 @提及 Bot 的方式与 AI 助手交互。
Slack 集成与 Discord 类似，需要创建一个 Slack App 并获取必要的凭证。Slack 提供了更丰富的集成功能，比如斜杠命令、交互式按钮等，OpenClaw 可以充分利用这些特性提供更好的交互体验。
对于企业用户，OpenClaw 还支持飞书、钉钉等国内常用的企业通讯工具。这些平台的集成流程大同小异，都需要创建企业应用并获取相应的凭证。OpenClaw 的文档中提供了详细的配置指南，针对每个平台都有具体的步骤说明。
需要注意的是，不同的通讯平台有不同的消息格式和功能限制。OpenClaw 会尽可能适配各个平台的特性，但某些高级功能可能在特定平台上无法使用。在选择通讯平台时，建议根据实际需求和使用习惯来决定。
Docker 部署方案
对于需要在服务器上长期运行 OpenClaw 的用户，Docker 是一个理想的部署方案。使用 Docker 可以确保环境的一致性，简化维护工作，也便于在不同服务器之间迁移。
首先确保你的系统已经安装了 Docker 和 Docker Compose。在 Linux 系统上，可以通过包管理器安装：
sudo apt-get update
sudo apt-get install docker.io docker-compose
OpenClaw 官方提供了预构建的 Docker 镜像，你可以直接拉取使用。创建一个目录用于存放配置文件：
mkdir -p ~/openclaw
cd ~/openclaw
创建一个 docker-compose.yml 文件，内容如下：
version:'3.8'
services:
openclaw:
image:openclaw/openclaw:latest
container_name:openclaw
restart:unless-stopped
volumes:
-./data:/app/data
-./config:/app/config
environment:
-NODE_ENV=production
ports:
-"3000:3000"
这个配置文件定义了一个 OpenClaw 服务，使用最新版本的镜像，并将数据和配置目录挂载到宿主机上。这样即使容器被删除，你的数据和配置也不会丢失。
启动容器：
docker-compose up -d
参数 -d 表示在后台运行。首次启动时，Docker 会自动下载镜像，这个过程可能需要几分钟。
查看容器运行状态：
docker-compose ps
查看容器日志：
docker-compose logs -f openclaw
进入容器内部执行配置：
docker-compose exec openclaw bash
在容器内部，你可以运行 openclaw onboard 来完成初始化配置，或者直接编辑配置文件。
如果需要更新 OpenClaw 版本，执行：
docker-compose pull
docker-compose up -d
这会拉取最新的镜像并重新创建容器。你的数据和配置不会受到影响。
对于有特殊需求的用户，可以自己构建 Docker 镜像。从 GitHub 克隆 OpenClaw 源代码，然后使用项目中提供的 Dockerfile 进行构建：
git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker build -t openclaw:custom .
自定义构建允许你修改源代码或添加额外的依赖，满足特定的业务需求。
配置文件详解
OpenClaw 的行为可以通过配置文件进行精细调整。配置文件位于 OpenClaw 数据目录中，通常是 ~/.openclaw/config.json。理解配置文件的结构可以帮助你更好地定制 OpenClaw。
配置文件使用 JSON 格式，主要包含以下几个部分：
首先是 AI 模型配置。在 models 部分，你可以配置一个或多个 LLM 服务。每个模型配置包含服务提供商、API Key、模型名称等信息。例如：
{
"models":{
"default":{
"provider":"anthropic",
"apiKey":"sk-ant-xxxxx",
"model":"claude-3-opus-20240229",
"maxTokens":4096
}
}
}
你可以配置多个模型，然后在使用时指定使用哪一个。OpenClaw 会使用标记为 default 的模型作为默认选择。
通讯平台配置在 platforms 部分。每个平台都有自己特定的配置项。以 Telegram 为例：
{
"platforms":{
"telegram":{
"enabled":true,
"botToken":"1234567890:ABCdefGHIjklMNOpqrsTUVwxyz",
"allowedUsers":["username1","username2"]
}
}
}
allowedUsers 字段用于限制可以使用 Bot 的用户，这是一个重要的安全设置。如果不设置这个字段，任何人都可以向你的 Bot 发送消息。
技能配置在 skills 部分。每个技能可以有自己的配置选项：
{
"skills":{
"email":{
"enabled":true,
"accounts":[
{
"email":"user@example.com",
"password":"app-specific-password"
}
]
}
}
}
在 general 部分，你可以配置一些全局选项，比如日志级别、数据存储路径、Web 界面端口等：
{
"general":{
"logLevel":"info",
"dataDir":"~/.openclaw/data",
"webPort":3000,
"language":"zh-CN"
}
}
修改配置文件后，需要重启 OpenClaw 网关才能生效。为了避免手动编辑配置文件时出错，建议使用 openclaw config 命令，它会提供语法检查和自动补全功能。
OpenClaw 还支持通过环境变量来覆盖配置文件中的设置。这在 Docker 部署或 CI/CD 流程中特别有用。例如，你可以通过 OPENCLAW_MODEL_API_KEY 环境变量来设置 API Key，而不是将它写在配置文件中。
安装完成后进行访问
http://127.0.0.1:18789
常见问题与故障排查
在使用 OpenClaw 的过程中，你可能会遇到各种问题。这里总结了一些常见问题和解决方法，可以帮助你快速定位和解决问题。
首先是 Node.js 版本问题。OpenClaw 要求 Node.js 版本必须在 22.0 或以上，如果版本不符合要求，启动时会报错。错误信息通常会明确指出版本不匹配。解决方法是升级 Node.js 到最新版本。使用 nvm 的用户可以运行 nvm install 22 和 nvm use 22 来快速切换版本。
网关启动失败是另一个常见问题。如果运行 openclaw gateway start 后网关无法启动，首先检查端口是否被占用。OpenClaw 默认使用 3000 端口，如果这个端口已经被其他程序使用，网关就无法启动。你可以通过修改配置文件中的 webPort 选项来更换端口。
API Key 配置错误会导致无法与 LLM 服务通信。如果你的 AI 助手没有响应，或者报错说无法访问模型，首先检查 API Key 是否正确。注意有些服务（如 OpenAI）的 API Key 格式有特定要求，复制粘贴时要确保没有多余的空格或换行符。
通讯平台连接问题也比较常见。以 WhatsApp 为例，如果无法生成二维码或扫码后无法连接，可能是网络问题导致无法访问 WhatsApp 服务器。检查防火墙设置，确保允许 OpenClaw 访问外部网络。如果使用代理，需要在配置中正确设置代理参数。
技能安装失败通常是因为依赖包问题。某些技能需要额外的系统依赖，比如图像处理技能可能需要 ImageMagick，邮件技能可能需要特定的 Python 包。查看错误日志，根据提示安装缺失的依赖。
如果 OpenClaw 运行缓慢或占用大量资源，可能是因为配置了过高的并发设置或启用了过多的技能。检查配置文件，适当降低 maxTokens 参数，禁用不常用的技能。
Docker 部署特有的问题包括挂载目录权限错误。如果容器无法写入配置或数据目录，检查宿主机目录的权限设置。通常需要确保运行 Docker 的用户有读写权限。
当遇到复杂问题时，OpenClaw 提供了详细的日志系统。使用 openclaw logs --follow 查看实时日志，通常可以从中找到问题的线索。日志会显示每个步骤的详细信息，包括网络请求、API 调用、错误堆栈等。
如果自己无法解决问题，OpenClaw 社区是一个很好的求助渠道。GitHub Issues 中有大量讨论，很多问题已经有了详细的解决方案。你也可以在社区论坛或 Discord 频道中提问，通常会得到及时的帮助。
使用技巧与最佳实践
掌握了基本的安装和配置后，一些实用技巧可以让你更高效地使用 OpenClaw，发挥出它的最大价值。
首先是模型选择策略。不同的 LLM 模型有不同的特点，Claude 擅长长文本分析和创作，GPT-4 在代码生成方面表现出色，Gemini 则在多模态任务上有优势。根据不同的任务选择合适的模型，可以获得更好的效果和更低的成本。OpenClaw 支持配置多个模型，你可以在对话中随时切换。
合理使用技能系统可以大幅提升效率。OpenClaw 的技能不仅仅是简单的功能扩展，很多技能之间可以协同工作。例如，结合邮件技能和日历技能，可以实现自动从邮件中提取会议信息并添加到日历；结合文件技能和代码技能，可以实现自动代码审查和文档生成。
Boot-md 功能是一个强大但容易被忽视的特性。通过在启动时加载一段 markdown 文本，你可以设定 AI 助手的行为规则和背景知识。比如，你可以在 boot-md 中说明你的工作领域、常用的术语、偏好的回复风格等，这样 AI 助手就能更好地理解你的需求。
定期备份配置和数据是一个好习惯。虽然 OpenClaw 很稳定，但意外情况总是可能发生。定期将 ~/.openclaw 目录备份到安全的地方，可以避免因系统故障或误操作导致的数据丢失。如果使用 Docker 部署，确保挂载的数据目录也包含在备份计划中。
对于长期运行的服务器部署，建议配置日志轮转。OpenClaw 的日志文件会随着时间增长，如果不加以管理，可能会占用大量磁盘空间。使用 logrotate 或类似工具，定期清理旧日志，保留最近一段时间的记录即可。
安全性是不容忽视的方面。OpenClaw 运行在你的设备上，有权访问你的各种账号和数据。确保配置文件中的敏感信息（如 API Key、密码）得到妥善保护。如果在服务器上运行，配置防火墙规则，只允许必要的入站连接。对于 Web 界面，如果要通过公网访问，务必配置强密码或启用 HTTPS。
监控 OpenClaw 的运行状态可以及时发现问题。设置简单的健康检查脚本，定期检查网关是否正常运行，API 配额是否即将耗尽。很多云服务商提供了免费的监控服务，可以在出现异常时及时发送通知。
积极参与社区可以让你了解到更多使用技巧。OpenClaw 的用户社区非常活跃，经常有人分享有趣的配置方案和自定义技能。关注官方博客和社区动态，可以第一时间了解到新功能和最佳实践。
最后，保持 OpenClaw 的版本更新。开发团队会持续改进功能、修复 bug、优化性能。定期运行 openclaw update 检查更新，不仅可以获得新功能，还能确保系统的安全性和稳定性。
通过合理运用这些技巧，你可以将 OpenClaw 打造成一个真正高效的个人 AI 助手，让它成为你日常工作和生活中不可或缺的得力助手。
