更正说明
更正说明:本文原稿曾将 OpenClaw 写成基于 Django/Python 的企业自动化平台,并给出一个并不存在的源码仓库地址,内容与官方资料不符。现已按 OpenClaw 官方仓库(github.com/openclaw/openclaw)与官方文档全面重写。文中的安装命令、目录与配置方式以官方文档为准;官方迭代较快,如个别命令有出入,请以官方文档的最新说明为准。
OpenClaw是什么
OpenClaw 是一个开源的个人 AI 助手项目,用 TypeScript 编写、运行在 Node.js 环境中。它与常见的“网页聊天机器人”最大的不同在于:它住在你自己的设备上,并接入你日常使用的聊天软件。你在 WhatsApp、Telegram、Discord、Slack、Signal、飞书等聊天渠道里给它发消息,它就能帮你处理日程与提醒、整理信息、查资料、写摘要、处理文件乃至运行脚本。
它的核心是一个叫 Gateway(网关)的本地长驻进程:Gateway 负责连接各个聊天渠道和 AI 模型、维护会话与工作区,并提供一个本机打开的控制面板(Control UI)。你不需要自己搭一套复杂的服务端架构,一台常开的个人电脑、迷你主机或 VPS 就能跑。打算部署到服务器的读者,可以先看看本站的VPS搭建教程,把服务器环境准备好。

它还支持可扩展的技能(Skills)、定时任务(Cron)与心跳(Heartbeat)等机制:技能可以从官方技能社区 ClawHub 安装,也可以自己编写;定时任务让它按计划主动工作,比如每天早上推送一份日程与待办简报;工作区里的记忆文件则让它在多次会话之间记住你的偏好与上下文。下面我们从概念、安装、配置、渠道接入到日常使用,一步步把它跑起来。
核心功能与概念
先把几个核心概念理清,后面的安装和配置就顺理成章了:
- Gateway 网关——本地运行的控制中枢,默认端口 18789、只监听本机,负责渠道连接、会话、工具调用与控制面板。
- 聊天渠道接入——支持 WhatsApp、Telegram、Discord、Slack、Signal、iMessage、飞书、Microsoft Teams、Matrix 等多种渠道(完整列表以官方文档为准),通过扫码登录或机器人 Token 等方式接入。
- 工作区与记忆——默认工作区在 ~/.openclaw/workspace,其中的说明与记忆文件决定助手的人设、用户信息与长期记忆,可直接用文本编辑器维护。
- 技能与插件——通过技能扩展能力,可从 ClawHub 查找、安装社区技能,也可把自己的脚本封装成技能。
- 定时与主动任务——Cron 定时任务与 Heartbeat 心跳检查,让助手能定点提醒、定期巡检并汇总信息。
- 多智能体与路由——可按渠道、账号或联系人把消息路由到不同的智能体与工作区,属于进阶用法,具体以官方文档为准。
安装教程
官方提供了一键安装脚本与向导式初始化(Onboarding),会引导你选择模型、安装 Gateway 守护进程并接入第一个聊天渠道。开始前请确认系统为 macOS、Windows 或 Linux(WSL2 亦可),并装有较新版本的 Node.js(具体版本要求以官方文档为准)。整个过程大约十几分钟,视网络情况而定。
# 方式一:官方安装脚本(macOS / Linux)
curl -fsSL https://openclaw.ai/install.sh | bash
# Windows(PowerShell)请使用官方的 install.ps1 安装脚本,命令见官方文档
# 方式二:用 npm 全局安装
npm install -g openclaw@latest
# 方式三:只想先试用(免安装,单次运行)
npx -y openclaw@latest
安装完成后,运行初始化向导,并确认网关状态:
# 启动向导:选择模型、安装 Gateway 守护进程、接入渠道
openclaw onboard --install-daemon
# 查看网关状态
openclaw gateway status
# 在浏览器打开控制面板(Control UI)
openclaw dashboard
向导完成后,Gateway 会作为系统服务常驻(macOS 为 LaunchAgent、Linux 为 systemd 用户服务、Windows 为计划任务,以官方文档为准)。控制面板默认地址为 http://127.0.0.1:18789/ ,只建议在本机访问;如果装在 VPS 上,请配合 SSH 隧道等安全方式访问,不要把网关端口直接暴露到公网。
配置说明
OpenClaw 的主状态目录默认是 ~/.openclaw,主配置文件为 ~/.openclaw/openclaw.json(JSON5 格式)。官方更推荐用向导和命令来改配置,而不是手动编辑文件:
# 打开配置向导(模型、渠道、工作区等)
openclaw configure
# 查看 / 修改单个配置项(示例)
openclaw config get gateway.port
openclaw config set gateway.port 18789
| 配置项 | 说明 | 备注 |
|---|---|---|
| 状态目录 ~/.openclaw | 配置、会话、渠道凭据、工作区都存放在这里 | 可用环境变量 OPENCLAW_STATE_DIR 自定义位置 |
| 主配置 openclaw.json | JSON5 格式的主配置文件 | 推荐用 openclaw configure / config 命令修改;改出问题可用 openclaw doctor 排查 |
| Gateway 端口(默认 18789) | 网关与控制面板共用的本机端口 | 仅本机监听;远程访问请用 SSH 隧道等安全方式 |
| 模型与 API Key | 在向导中选择模型服务并填入密钥 | 密钥是敏感信息,不要提交到公开仓库 |
| 渠道配对 | 新联系人私聊默认需要配对批准 | 避免陌生人直接调用你的助手 |
配置安全提示:网关掌握着你的聊天渠道与文件访问能力,务必只在本机或可信内网使用,开启配对与白名单,并保管好 API Key 与整个状态目录。
接入聊天渠道
渠道接入是 OpenClaw 的日常入口。官方文档列出了全部受支持渠道与各自的接入方式,这里以最常见的两个为例:
- Telegram(上手最快)——在 Telegram 里找 @BotFather 创建一个机器人、拿到 Token,在向导或渠道设置中填入 Token,网关重启后给机器人发消息,按提示完成配对即可。
- WhatsApp——使用 openclaw channels login 扫码登录(类似 WhatsApp Web 的绑定方式),登录状态保存在状态目录中。
# 渠道登录(按终端提示选择渠道并扫码 / 授权)
openclaw channels login
# 查看网关与渠道的健康状态
openclaw health
其他渠道(Discord、Slack、Signal、飞书等)的接入方式类似:创建机器人或应用、填入凭据、在 OpenClaw 中启用渠道并完成配对。各渠道的具体字段与步骤,以官方文档的渠道指南为准。
日常使用与实际案例
接入完成后,你就可以在聊天软件里直接使唤它了。下面是几类常见用法,实际效果取决于你接入的模型与已安装的技能:
- 日程与提醒——让它汇总今天的日程、设置定时提醒,或用 Cron 每天固定时间推送一份简报。
- 收件箱与消息整理——把长对话、通知消息汇总成摘要,提炼出待办事项与关键时间点。
- 文件与资料处理——在工作区中整理文件、摘录文档要点、生成清单或草稿。
- 信息巡检——用 Heartbeat 定期检查你关心的事项(如新邮件、服务状态),有变化再通知你。
- 编程与运维辅助——在沙盒或指定目录中运行命令、查看日志、执行脚本。涉及命令执行时请留意官方的沙盒与授权设置,先小范围试用。
版本升级方法
OpenClaw 更新较频繁,官方推荐用自带命令升级。升级前请先备份状态目录——其中包含配置、会话、渠道登录状态与工作区文件:
# 1. 备份状态目录(升级前务必做;路径以你的实际安装为准)
cp -a ~/.openclaw ~/.openclaw-backup-$(date +%Y%m%d)
# 2. 使用官方推荐的升级命令(检查、更新、重启网关并做健康检查)
openclaw update
# 3. 升级后做一次诊断与健康检查
openclaw doctor
openclaw gateway restart
openclaw health
如果 openclaw update 遇到问题,可按官方文档的手动方式处理:用安装脚本或包安装的用户,重新运行安装脚本或用包管理器更新到 latest;源码安装的用户,在仓库目录拉取最新代码后按文档重新构建并安装守护进程。升级完成后,建议逐一确认各渠道还能正常收发消息。
常见问题
- 网关起不来或端口被占用——先跑 openclaw doctor 与 openclaw gateway status 看诊断信息;确认 18789 端口未被其他程序占用,必要时用 openclaw config set gateway.port 改一个端口后重启。
- 机器人不回复消息——检查渠道是否完成配对批准、网关是否在运行(openclaw health),并看网关日志里是否有模型密钥失效等报错。
- 聊天里发的命令不执行——多半是权限与沙盒设置问题。命令执行、文件访问等能力受官方安全策略控制,请按官方文档的工具与沙盒说明逐步放开,不要一上来就给全部权限。
- 想换模型或换电脑——模型在配置向导中重新选择即可;换电脑时把整个 ~/.openclaw 状态目录迁移过去(内含渠道登录状态与密钥,注意保密),在新机器上安装后运行 openclaw doctor 检查。
总结
OpenClaw 的定位是“住在你自己设备上的个人 AI 助手”:Gateway 在本地常驻,聊天软件就是它的操作界面,技能与定时任务让它从被动答题走向主动干活。它的上手门槛主要在渠道接入与权限配置,建议从 Telegram 这类简单的渠道开始,跑通之后再逐步接入更多渠道与技能。想横向了解同类工具,可继续阅读本站的《2026年AI自动化三大机器人深度对比:Codex vs Hermes vs OpenClaw》;该文侧重横向比较,涉及 OpenClaw 的具体功能与命令时,请以官方文档为准。
关注智搭云,获取更多自建应用与数字化工具教程!

