OpenClaw 新手入门指南（虾老大亲手编制）

概念	说明	类比理解
Gateway（网关）	后台核心服务，连接消息平台与 AI 模型	像手机的"操作系统"，必须保持运行
Channel（渠道）	接入的聊天平台（飞书、Telegram 等）	像微信、短信等不同的沟通方式
Skill（技能）	AI 可执行的自动化任务能力	像手机 App，每个技能解决一类问题
Agent（智能体）	配置了技能和渠道的 AI 助手	像你雇佣的专属助理，有特定职责
Onboarding（初始化）	首次安装后的配置引导流程	像新手机的初始设置向导

环境准备

1. 系统要求

操作系统：macOS / Linux / WSL2 / Windows（PowerShell）
Node.js：版本必须 ≥ v22.0.0（低于此版本会安装失败）

检查 Node.js 版本：

node -v

升级 Node.js（推荐用 nvm 管理）：

nvm install 22 nvm use 22

2. 准备 API Key

需要 AI 模型密钥才能使用：

国内推荐：阿里云百炼（稳定、速度快）
海外可选：Anthropic Claude、OpenAI GPT

3. 网络环境（国内用户）

建议配置代理或使用国内镜像源，避免依赖下载失败：

export https_proxy=http://127.0.0.1:你的代理端口

安装步骤

方式一：一键脚本（推荐 ⭐）

自动检测环境、安装 CLI 并启动初始化向导。

macOS / Linux / WSL2：

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

Windows（PowerShell）：

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

方式二：手动安装（可选）

npm install -g openclaw

初始化配置

1. 运行初始化向导

openclaw onboard --install-daemon

这会：

🔧 安装后台服务
🔑 自动运行 OAuth 流程并写入凭证
🎯 启动配置引导流程

2. 验证 Gateway 状态

openclaw gateway status

看到正常运行提示即成功。

3. 打开控制界面（最快验证方式）

openclaw dashboard

然后在浏览器访问：http://localhost:18789 或 http://127.0.0.1:18789

💡 提示：这是最快的验证路径，无需配置消息渠道即可直接在网页端聊天测试。

快速体验

完整流程：

安装 →
运行 openclaw onboard 完成初始化 →
启动 openclaw dashboard →
在浏览器访问控制界面 →
发送消息（如"你好"）→
收到 AI 回复即成功 ✅

预期结果：

你：你好 AI：你好！我是你的个人助手，有什么可以帮你的吗？🦞

技能扩展

什么是技能？

技能是 OpenClaw 的能力扩展包，可以让 AI 执行特定任务，如：

📊 数据分析
📝 文档处理
🔍 信息检索
🤖 自动化工作流

安装技能

通过 ClawHub（OpenClaw 公共技能注册表）安装：

浏览技能库： https://clawhub.com

常用命令：

# 安装技能 clawhub install <skill-slug> # 搜索技能 clawhub search "关键词" # 更新所有技能 clawhub update --all

创建自定义技能

步骤：

创建技能目录
编写 SKILL.md
重启 Gateway
测试技能在对话中输入触发指令即可。

详细教程： https://docs.openclaw.ai/zh-CN/tools/creating-skills

常见问题 FAQ

❌ 安装后打不开/崩溃

排查步骤：

查看日志：
重新配置：
重新安装：
查阅发布说明，确认是否有破坏性变更
问题持续？带日志到 GitHub Issues 反馈

❌ 网关启动失败

可能原因及解决：

1. 端口被占用

lsof -i:18789 # 查看占用进程 # 终止占用进程后重试

2. 配置无效

openclaw doctor # 检测配置错误 openclaw doctor --fix # 自动修复 openclaw config --validate # 验证配置文件

❌ 授权失败（Error 401）

检查清单：

✅ API Key 是否正确
✅ 模型服务商账户余额是否充足
✅ 模型兼容性（部分模型可能存在兼容问题，可切换至 DeepSeek-V3.2 等）

❌ 命令不存在（command not found）

解决：

检查 Node.js 环境变量配置
重新安装 OpenClaw

❌ 国内访问慢/超时

方案：

配置全局代理：export HTTP_PROXY=http://proxy:8080
使用国内镜像源
检查 API 连接：ping api.example.com

❌ 云服务器无法访问

开放端口：需在防火墙/安全组中开放 18789 端口（TCP 协议）

Windows： Windows Defender 防火墙 → 新建入站规则macOS：系统偏好设置 → 安全性与隐私 → 防火墙

🔧 通用排查工具

# 实时查看日志 openclaw logs --follow # 查看错误日志 openclaw logs --level error # 健康检查 openclaw health # 检测并修复配置 openclaw doctor openclaw doctor --fix # 版本更新 openclaw upgrade