本教程基于官方最新文档、社区博客实战指南优化编写，覆盖从架构理解、环境准备、安装配置、渠道接入到日常使用、安全加固、故障排查的全流程，重点补充国内用户适配方案、新手避坑指南，新手跟着步骤走，20 分钟即可跑通最小可用闭环。
前置快速通关路径（20 分钟极速体验）
如果你只想最快跑通核心流程，直接按以下 4 步操作：
- 一键安装：macOS/Linux/WSL2 终端执行
curl -fsSL https://openclaw.ai/install.sh | bash；Windows 管理员 PowerShell 执行iwr -useb https://openclaw.ai/install.ps1 | iex - 初始化配置：执行
openclaw onboard --install-daemon，跟着向导选「本地模式」、配置 AI 模型 API Key、选择 Telegram 渠道、安装后台守护进程 - 安全配对：给 Telegram 机器人发第一条消息，终端执行
openclaw pairing list telegram查看配对码，执行openclaw pairing approve telegram <配对码>完成授权 - 测试验证：给机器人发送「你是谁，用 3 句话介绍自己」，收到回复即跑通闭环
第一章 先搞懂 OpenClaw：核心定位 & 架构原理
1.1 核心定位
OpenClaw 是一款开源自托管的 AI 个人智能体，核心能力是「发一句话，就帮你在本机/服务器上真实执行任务」。
- 入口：微信、Telegram、WhatsApp、Discord 等聊天软件
- 大脑：支持 Claude、GPT、Kimi、智谱 GLM 等云端 API，也支持 Ollama 本地大模型
- 双手：可执行终端命令、读写文件、控制浏览器、管理邮件日历、运行脚本等
- 记忆：跨会话保存上下文与配置，越用越贴合你的使用习惯
1.2 核心架构全景
一次完整的指令执行链路：
聊天App（Telegram/WhatsApp等）→ Gateway网关（唯一总机，管理所有连接、认证、消息路由）→ Agent智能体运行时（理解指令、调用模型、执行工具）→ 内置工具/技能插件 → AI大模型提供商
关键名词：Gateway 相当于总机；Agent 相当于接线员+执行者；Channels 是消息入口渠道；Session 是会话上下文容器；Workspace 是 Agent 工作目录；Pairing 是安全配对机制；Skills 是技能插件。
1.3 新手心态
- 先跑通最小闭环，不要追求全自动化
- 当成「会犯错的实习生」，先给最小权限
- 先只接入一个能力，跑稳了再扩展
第二章 安装前的环境准备
2.1 系统要求
- macOS 推荐 14+，内存 ≥4GB，磁盘 ≥5GB
- Windows 强烈推荐 WSL2（Ubuntu 22.04+）
- Linux 推荐 Ubuntu/Debian/Fedora/Arch
2.2 必备依赖
核心必装：Node.js ≥22.0（否则必报错）。推荐 nvm 安装。Windows 原生系统直接下载 22.x LTS 版本。可选依赖：Git、pnpm、Chrome/Chromium。
2.3 AI 模型 API Key 准备
OpenClaw 本身不提供大模型能力，需提前准备好 API Key。海外推荐 Anthropic Claude、OpenAI GPT；国内可选 Moonshot Kimi、MiniMax、智谱 GLM；本地需提前安装 Ollama。
2.4 国内网络环境
使用海外模型需配置系统代理，否则无法调用 API。可通过终端临时配置或 OpenClaw 配置中设置代理。
第三章 OpenClaw 全方式安装教程
方式 1：一键脚本安装（新手首选）
macOS/Linux/WSL2：curl -fsSL https://openclaw.ai/install.sh | bash
Windows 管理员：iwr -useb https://openclaw.ai/install.ps1 | iex
方式 2：NPM/PNPM 手动安装
npm install -g openclaw@latest
方式 3：源码安装（开发者）
克隆官方仓库，安装依赖，构建 UI 和项目，执行初始化配置。
新手避坑指南
- 禁止使用 Bun 运行 WhatsApp/Telegram 渠道
- 不要使用低于 22.0 的 Node.js
- Windows 用户优先使用 WSL2
- 不要在代理未配置好时安装/启动
第四章 交互式初始化配置
执行 openclaw onboard --install-daemon，全程交互式引导。核心步骤：
- 选择配置模式 → 新手选 QuickStart
- 选择 Gateway 运行模式 → 新手选 Local
- 配置 AI 模型 API Key（最核心步骤）
- Workspace 工作目录 → 新手选默认
- Gateway 端口 → 默认 18789
- 聊天渠道 → 新手优先 Telegram
- 后台守护进程 → 必选 Yes
- 技能插件 → 新手选跳过
后续修改配置：openclaw configure
第五章 国内大模型接入教程
Kimi（Moonshot）接入
- 访问 Moonshot 开放平台获取 API Key
- 通过 onboard 向导或手动配置
- 执行
openclaw status、openclaw health验证
可用模型：kimi-k2.5、kimi-k2-turbo-preview、kimi-k2-thinking 等。通过 /model 临时切换或 openclaw models set 永久切换。
本地 Ollama 接入
提前安装 Ollama，编辑配置文件添加提供商配置，重启网关验证。
第六章 Gateway 网关 & Web 控制界面
网关启动：openclaw gateway start（前台运行用 run）
启动后验证三连：openclaw gateway status、openclaw status、openclaw health
Web 控制界面：http://127.0.0.1:18789/ 或 openclaw dashboard
警告：禁止绑定 0.0.0.0，会将网关暴露到公网！
第七章 聊天渠道接入 & 安全配对
Telegram Bot 接入
- 通过 @BotFather 创建 Bot 获取 Token
- 配置 Token 到 OpenClaw
- 安全配对（最关键）：发消息后执行
openclaw pairing list telegram查看配对码，openclaw pairing approve telegram <配对码>批准
WhatsApp 接入
openclaw channels login → 手机扫码 → 完成配对
Discord 接入
在 Discord 开发者平台创建应用和 Bot，获取 Token，邀请到服务器。
第八章 跑通最小闭环
基础对话测试：发送「你是谁？用 3 句话介绍你自己」
低风险执行测试：告诉系统时间 → 列出文件 → 创建 test.txt → 读取文件
官方自检三连（必跑）：openclaw status、openclaw health、openclaw doctor --fix
第九章 日常使用 & 核心能力
- 触发规则：私聊直接发送，群聊必须 @机器人
- 媒体文件：直接发送图片/音频/文档，再补充需求指令
- 内置工具：exec 终端、browser 浏览器、file 文件管理
- 技能插件：推荐 gmail、calendar、web-search、github、home-assistant
第十章 进阶玩法
- 多智能体路由：配置多个独立 Agent，按发送者/渠道自动路由
- 定时任务：支持 Cron 定时任务，无人值守自动化
- 远程访问：推荐 Tailscale 或 SSH 隧道，禁止直接暴露公网
- 移动节点：支持 iOS/Android 移动节点配对
第十一章 安全加固
- 最小权限：Sandbox 沙箱 + Tool Policy 工具策略 + Elevated 权限三层控制
- 网络安全：禁止绑定公网地址、防火墙配置、启用 Token 认证
- 凭证管理：使用环境变量存放、定期轮换 API Key、配置文件加密
- 二次审批：可配置 rm -rf 等危险命令执行前必须手动批准
第十二章 日常维护
- 状态检查：每日/每周/每月检查清单
- 日志管理：
openclaw logs实时查看、过滤错误 - 配置备份：手动/自动备份，支持恢复
- 版本更新：停止网关 → 备份 → 更新 → 诊断 → 重启
第十三章 常见问题排查
- COMMAND NOT FOUND：npm 全局目录不在 PATH 中
- 网关启动失败：端口占用/JSON错误/Node版本过低/代理问题
- Bot 没反应：确认网关运行 → 渠道连接 → 配对批准 → 白名单 → 网络 → API
- 执行报错：确认工具权限/沙箱权限/系统权限/浏览器安装
- API 调用失败：401未授权/403禁止/超时/额度不足
- 国内网络：优先国内模型；海外模型必须配代理
第十四章 常用命令速查
基础：openclaw –version/status/health/doctor/dashboard/update
网关：openclaw gateway start/stop/restart/status/run
配置：openclaw configure/config get/set/unset
模型：openclaw models list/status/scan/set/probe
渠道：openclaw channels login/logout/list/status
配对：openclaw pairing list/approve/deny
官方资源
- 官方网站：openclaw.ai
- 官方中文文档：docs.openclaw.ai
- GitHub：github.com/openclaw/openclaw
- Discord 社区：discord.com/invite/clawd
- 中文社区：moltcn.com
本文收集自网络，本文观点不代表发现AI立场，如若转载，请联系原作者；如有侵权，请联系编辑删除。
