OpenClaw 入门指南

一、OpenClaw 是什么？

OpenClaw 的核心是一个 AI 智能体 Gateway（网关）。你可以把它想象成一个智能中枢，它负责：

连接：通过单个网关进程，统一连接和管理你日常使用的各种聊天应用（渠道）。
路由：将来自不同渠道的消息，智能地路由到后端的 AI 智能体进行处理。
响应：将智能体的处理结果（文本、图片、文档等）再发送回对应的聊天应用。

它的设计目标是让你能在 任何操作系统 上，通过你已经习惯的聊天软件，随时随地与 AI 智能体交互。

核心功能亮点

多渠道支持：原生支持 WhatsApp、Telegram、Discord、iMessage（通过 BlueBubbles）。通过插件可扩展支持飞书、LINE、Matrix、Mattermost、Microsoft Teams、Slack、Twitch 等数十种渠道。
多智能体路由：可以按智能体、工作区或消息发送者来隔离会话，实现不同场景使用不同 AI 助手。
完整的媒体支持：支持在聊天中发送和接收图片、音频和文档。
Web 控制界面：提供基于浏览器的仪表盘，用于管理聊天、配置、会话和节点，操作直观。
移动端支持：提供 iOS 和 Android 节点应用，支持 Canvas 画布功能。
强大的工具集成：为智能体提供了浏览器操作、文件系统读写、代码执行、定时任务、节点管理等一流工具，能力远超简单聊天。
灵活的模型支持：支持 Anthropic Claude、OpenAI GPT、Google Gemini、Venice AI 等多种主流和开源 LLM 提供商，并可轻松切换和设置故障转移。

架构核心：Pi 智能体集成

OpenClaw 并非简单地调用 API，而是深度集成了 pi-coding-agent SDK。它采用嵌入式运行模式，直接实例化 Pi 的 AgentSession，从而获得对会话生命周期、工具注入、系统提示词定制和会话持久化的完全控制。这意味着 OpenClaw 能够充分利用 Pi 智能体的代码理解和执行能力。

二、如何安装 OpenClaw？

安装过程非常简单，官方强烈推荐使用安装脚本。

系统要求

Node.js >= 22
操作系统：macOS、Linux 或 Windows（通过 WSL2）
（仅从源码构建时需要）pnpm

其他安装方式

全局安装（手动）：如果你已具备 Node 环境，可以直接通过 npm 安装。
```
npm install -g openclaw@latest
```

从源代码安装（适合开发者）：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
openclaw onboard --install-daemon

安装后验证

安装完成后，可以通过以下命令快速检查：

openclaw doctor          # 进行健康检查
openclaw status          # 查看网关状态
openclaw health          # 检查网关健康接口
openclaw dashboard       # 打开 Web 控制界面

三、如何使用 OpenClaw？

OpenClaw 的使用主要围绕 CLI 命令、Gateway 网关服务 和 Web 控制台 展开。

1. 核心概念与配置

Gateway（网关）：常驻进程，是所有聊天连接和控制平面的核心。使用 openclaw gateway命令管理。
渠道（Channels）：指具体的聊天应用，如 WhatsApp、Telegram。需要先登录配对。
智能体（Agents）：后端的 AI 处理单元，默认使用 Pi。可以配置多个智能体并指定路由规则。
配置文件：主配置文件位于 ~/.openclaw/openclaw.json，可以在此配置模型、渠道、工具策略等。

2. 基本使用流程

a. 启动与运行网关

启动网关服务（默认端口 18789）：

openclaw gateway --port 18789

更常见的做法是将其安装为系统服务，实现开机自启：

openclaw gateway install   # 安装服务
openclaw gateway start     # 启动服务

b. 添加并登录聊天渠道

以登录 WhatsApp 为例：

# 列出渠道状态
openclaw channels list
# 启动 WhatsApp 登录流程（会显示二维码）
openclaw channels login --channel whatsapp

按照提示用手机 WhatsApp 扫描二维码即可完成配对。Telegram 等其他渠道的配置类似，通常需要提供 Bot Token。

c. 进行首次对话

网关运行且渠道登录成功后，你就可以直接在配对的 WhatsApp 或 Telegram 中向你的账号或群组发送消息。OpenClaw 会自动接收消息，交由智能体处理并回复。

d. 常用 CLI 命令速查

配置管理：

openclaw config get agents.defaults.model.primary  # 查看当前主模型
openclaw config set agents.defaults.model.primary "anthropic/claude-opus-4-5" # 设置模型
openclaw configure                                 # 交互式配置向导

智能体会话：

openclaw agents list                               # 列出所有智能体
openclaw message send --to +1234567890 --message "Hello" # 主动发送消息

系统状态与维护：

openclaw logs --follow                            # 实时查看网关日志
openclaw sessions                                 # 查看所有会话
openclaw update                                   # 更新 OpenClaw

3. 高级配置与特性

模型提供商与设置：在 onboard引导或配置文件中，你可以设置默认的 AI 模型。OpenClaw 支持轮换多个认证配置文件，并在主模型不可用时自动故障转移。
工具控制：你可以精细控制智能体能使用哪些工具。例如，可以全局禁用 browser工具，或为某个智能体单独设置只允许使用消息相关工具。
```
{
  "tools": {
    "profile": "coding",
    "deny": ["browser"]
  }
}
```
多网关与隔离：支持在同一台机器上运行多个隔离的网关实例（例如用于开发测试或运行独立的“救援机器人”），只需使用不同的配置文件和端口即可。
定时任务（Cron）：可以通过 CLI 或智能体工具创建定时任务，让 OpenClaw 在指定时间自动执行操作或发送消息。

4. 获取帮助

官方文档是首要资源：https://docs.openclaw.ai
使用 openclaw --help查看所有命令。
遇到问题时，先运行 openclaw doctor进行诊断和自动修复。
查看详细日志：openclaw logs或前往 Web 控制台的日志页面。

总结

OpenClaw 是一个将聊天应用生态与强大编码智能体（Pi）无缝桥接的开源平台。它通过网关架构解决了多平台统一接入的问题，并通过深度集成提供了可靠、可扩展的 AI 助手服务。无论是想通过 WhatsApp 让 AI 帮你写代码，还是在 Discord 服务器中部署一个自动化助手，OpenClaw 都提供了一个企业级、可自托管的解决方案。其丰富的工具集、灵活的配置和活跃的插件生态，使其成为构建个人或团队 AI 工作流的有力工具。