OpenClaw 本地 AI 助手安装配置指南

适合需要自定义开发、修改源码的用户，macOS/Linux/Windows（WSL2）均可使用：

git clone https://github.com/openclaw/openclaw.git
cd openclaw && pnpm install && pnpm run build
pnpm run openclaw onboard

三、初始化配置（核心步骤）

安装完成后，执行初始化命令进入交互式配置向导，配置 AI 模型和基础参数：

# 通用初始化命令
openclaw onboard
# Windows 新手推荐快速配置
openclaw onboard --flow quickstart

1. 风险确认

首次配置会出现风险提示：I understand this is powerful and inherently risky. Continue?，选择 Yes 继续。

2. 选择 AI 模型并配置 API Key

1. 按方向键选择常用 AI 模型（推荐 Claude/GPT-4/阿里云百炼，国内用户优先选阿里云百炼/Kimi，访问更稳定）；
2. 粘贴提前获取的 API Key（格式为 sk-xxxxxxxx），回车确认；
3. 部分模型需浏览器打开链接完成账号授权，按提示操作即可。

3. 基础功能配置

• 技能包（Skill）：新手直接选 No 跳过，后续按需安装；
• 记忆功能（Hooks）：选中 session-memory（启用多轮对话记忆，避免重复说明需求），其他默认；
• 配置完成后，系统会自动启动 Gateway 网关服务，默认端口 18789。

4. 打开管理控制台

配置完成后，浏览器会自动打开本地控制台，手动访问地址：

http://127.0.0.1:18789

首次进入需输入初始化生成的配置 Token（妥善保存，丢失需重新初始化）。

四、对接聊天软件（以飞书为例，国内常用）

OpenClaw 支持 WhatsApp、Telegram、飞书、钉钉、微信等平台，飞书配置难度低、稳定性高，以下为详细对接步骤，其他平台操作逻辑类似。

1. 安装飞书插件

在终端/PowerShell 执行插件安装命令：

openclaw plugins install @m1heng-clawd/feishu
# 进入插件目录完成依赖安装
cd /root/.openclaw/extensions/feishu/ && npm install --verbose

2. 飞书开放平台创建应用

1. 访问飞书开放平台：https://open.feishu.cn/app/，登录后点击**创建企业自建应用**；
2. 填写应用名称（如「大龙虾 AI 助手」），选择图标，点击创建；
3. 进入应用管理页，点击添加应用能力 → 选择机器人 → 点击添加。

3. 配置飞书应用权限与事件

（1）批量导入权限

1. 进入应用管理页权限管理 → 点击批量导入权限；

粘贴以下 JSON 代码，点击导入（核心权限，确保机器人能收发消息）：

{"scopes":{"tenant":["contact:user.base:readonly","im:chat","im:message","im:message:send_as_bot","im:resource"],"user":[]}}

（2）事件订阅配置

1. 进入事件与回调 → 事件配置选择长连接，点击保存；
2. 点击添加事件 → 选择消息与群组 → 勾选im.message.receive_v1（接收消息事件，必选）；
3. 订阅方式选择使用长连接，无需填写回调地址，自动生效。

（3）发布应用

1. 进入版本管理与发布 → 点击新建版本，填写版本号和描述；
2. 点击保存并发布，飞书应用配置完成（未发布则配置不生效）。

4. OpenClaw 绑定飞书应用

1. 按提示输入飞书应用的 App ID 和 App Secret（在飞书开放平台「凭证基础信息」中复制）；

验证状态：

openclaw status

显示 Gateway running 即绑定成功。

重启网关服务，使配置生效：

openclaw gateway restart

在终端执行命令，添加飞书通信渠道：

openclaw channels add

5. 飞书端测试使用

1. 打开飞书 APP，进入工作台 → 找到创建的「大龙虾 AI 助手」，点击进入私聊窗口；
2. 发送任意消息（如「你好」「整理我的今日日程」），收到机器人回复即对接完成。

五、基础使用与常用命令

1. 核心使用方式

在绑定的聊天软件中直接发送自然语言指令，机器人即可执行操作，例如：

• 邮件处理：「帮我整理上周的未读邮件，提取会议纪要」；
• 文件管理：「将桌面 PDF 文件按日期归档到文档文件夹」；
• 系统操作：「执行 shell 命令查看电脑 CPU 使用率」；
• 定时任务：「每天早上 9 点给我发送今日待办事项」。

2. 常用终端命令汇总

六、常见问题与避坑指南

1. 安装时卡在 node-gyp rebuild

原因：缺少 Python 和 C++ 编译工具； 解决：

• Windows：安装 Visual Studio Build Tools 和 CMake；
• macOS：执行 xcode-select --install 安装 Xcode 命令行工具；
• Linux：执行 sudo apt install build-essential python3。

2. Windows 提示「系统找不到指定的路径」

原因：系统组件被精简、WSL 未启用或 Git 环境未配置； 解决：

1. 安装 Git（官网：https://git-scm.com/download/win），安装后**重启电脑**；
2. 启用 WSL2：在 PowerShell 执行 wsl --install；

清理 npm 缓存并重装：

npm cache clean --force
npm install -g openclaw@latest

3. 飞书配置提示「未建立长连接」

解决：

1. 检查 App ID 和 App Secret 是否输入正确；
2. 等待 1-2 分钟再重新保存长连接配置（网络延迟导致）；
3. 执行 openclaw gateway restart 重启网关，再重新配置。

4. 聊天软件发送消息无回复

排查步骤：

1. 执行 openclaw status 确认网关服务正常运行；
2. 检查聊天软件应用的事件订阅是否添加 im.message.receive_v1；
3. 确认应用已在飞书开放平台发布（未发布无法收发消息）；
4. 查看网关日志：openclaw gateway --verbose，定位错误原因。

5. 国内网络下载依赖卡顿/失败

解决：

1. 配置国内 npm 镜像：npm config set registry https://registry.npmmirror.com；
2. 使用代理工具，或手动下载离线安装包进行安装。

七、进阶优化（可选）

1. 本地模型部署：修改 .env 文件中的 MODEL_PROVIDER 和 API_KEY，支持本地运行 Llama、Qwen 等模型，完全脱离外网。
2. 权限限制：在 config.json 中设置 allowed_commands 和 denied_commands，禁止机器人执行危险 shell 命令，提升安全性。

Docker 部署：适合需要 7×24 小时运行的用户，容器化部署更稳定：

git clone https://github.com/openclaw/openclaw.git
cd openclaw
docker compose up -d openclaw-gateway

汉化适配：国内用户建议安装社区汉化版，优化微信/企业微信支持：

npm install -g openclaw-cn@latest

八、注意事项

1. 隐私安全：OpenClaw 默认本地部署，数据不上传，但建议不要在装有重要商业/隐私数据的电脑上运行，可使用闲置设备或云端虚拟机（VPS）；
2. 版本兼容：避免使用最新版（官方频繁更新易出问题），新手建议安装稳定版：npm install -g [email protected]（替换为实际稳定版本号）；
3. 服务保活：本地部署时，关闭终端/PowerShell 会导致网关服务停止，可使用 pm2 等工具实现后台保活。