项目经理必看:OpenClaw 小龙虾安装教程(包含win和mac)

OpenClaw 安装教程

⚠️ 安全提示

OpenClaw 是一款本地运行的 AI 智能体，具备执行系统命令、读写文件等高权限能力。

使用前请注意：

• 仅从官方或可信渠道获取插件
• 不要授予不必要的系统权限
• 定期运行安全审计

本教程仅供学习交流，请合理合规使用。

一、Windows 部署指南

1.1 安装 Node.js

下载地址： https://nodejs.org/zh-cn/download

选择 LTS 长期支持版，下载后双击运行安装程序。

安装流程：

打开安装包 → 同意协议 → Next → Next → Install → Finish

1.2 安装 Git

下载地址： https://git-scm.com/

同样一路 Next 完成安装即可。

1.3 安装 OpenClaw

第一步： 以管理员身份打开 PowerShell

第二步： 修改执行策略

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

出现提示时输入 Y 确认。

第三步： 执行安装脚本

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

等待安装完成，看到小龙虾图标即表示成功。

1.4 初始化配置

安装后自动进入配置向导，按以下顺序操作：

步骤	选择项
安全确认	Yes
配置模式	QuickStart
AI 模型	Qwen (OAuth) ← 推荐免费
频道配置	Skip for now
技能配置	No
启动方式	Hatch in TUI

OAuth 授权： 复制终端显示的链接到浏览器完成登录。

首次对话测试：

HelloName: OpenClawMy Name: Boss

1.5 创建飞书应用

1. 访问飞书开放平台
2. 创建企业自建应用
3. 记录 App ID 和 App Secret
4. 在「应用能力 → 机器人」中启用机器人

1.6 连接飞书

openclaw configure

选择 Feishu/Lark（飞书），填入 App ID 和 App Secret。

关键配置项：

• 飞书域名：Feishu (feishu.cn)
• 群聊策略：Open
• 私聊策略：Open

完成后重启服务：

openclaw gateway restart

1.7 飞书平台配置

回到飞书开放平台完成以下设置：

事件订阅：

• 进入「事件与回调」
• 选择「使用长连接接收事件」
• 添加事件：im.message.receive_v1

权限配置：

contact:user.base:readonly    ← 用户信息im:message                    ← 消息（全部勾选）im:message:send_as_bot        ← 发消息

发布应用：

• 创建版本 → 提交审核 → 发布上线

1.8 测试验证

在飞书中搜索你的机器人，发送 Hello，收到回复即配置成功！

二、macOS 部署指南

2.1 安装 Homebrew

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2.2 安装 Git

brew install git

2.3 安装 Node.js

# 安装 NVMcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash# 重载配置source ~/.zshrc# 安装 Node 22nvm install 22

2.4 安装 OpenClaw

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

后续配置步骤与 Windows 完全相同。打开终端输入：

sudo openclaw onboard

三、实用命令手册

命令	用途
`openclaw status --all`	完整诊断报告
`openclaw doctor --fix`	自动修复配置问题
`openclaw gateway restart`	重启网关服务
`openclaw logs --follow`	实时查看日志
`openclaw update`	更新版本
`openclaw dashboard`	获取 Web 面板地址

四、故障排查大全

4.1 安装类问题

Q1: npm install failed

原因： 内存不足（建议 4GB 以上）

解决： 配置 swap 交换空间

# Linux/macOSsudo fallocate -l 2G /swapfilesudo chmod 600 /swapfilesudo mkswap /swapfilesudo swapon /swapfile

Q2: openclaw 命令找不到

原因： npm 全局路径未加入 PATH

解决：

# macOS/Linux - 添加到 ~/.zshrc 或 ~/.bashrcexport PATH="$(npm prefix -g)/bin:$PATH"# 然后执行source ~/.zshrc

Q3: Node.js 版本过低

原因： OpenClaw 需要 Node.js 22+

解决：

node -v  # 检查版本nvm install 22  # 安装正确版本nvm use 22

4.2 认证类问题

Q4: HTTP 401 Unauthorized

原因： API 密钥无效或过期

解决：

# 检查认证状态openclaw models status# 重新配置 Tokenopenclaw models auth setup-token --provider anthropic# 或使用 OAuth 重新登录# 在聊天界面输入 /logout 然后 /login

Q5: OAuth Token 刷新失败

原因： 令牌过期或权限被撤销

解决：

# 重新授权openclaw models auth <provider>

Q6: Invalid Beta Flag 错误

原因： 通过 AWS Bedrock 或 Google Vertex AI 使用 Claude 时的兼容性问题

解决方案（任选其一）：

1. 禁用 Beta 功能

// 在配置中添加"beta_features": []

2. 切换到直接 API

// 使用 anthropic 而非 bedrock/vertex"provider": "anthropic"

3. 禁用缓存

"cache": { "enabled":false }

4.3 飞书连接问题

Q7: 飞书机器人无响应

排查步骤：

# 1. 检查网关状态openclaw gateway status# 2. 查看实时日志openclaw logs --follow# 3. 测试连接openclaw channels status --probe# 4. 重启服务openclaw gateway restart

常见原因：

• 事件订阅未配置
• 权限未开通
• 应用未发布
• App ID/Secret 填写错误

Q8: 没有消息发送框

原因： 事件订阅未配置

解决： 在飞书开放平台配置 im.message.receive_v1 事件

Q9: API rate limit reached

原因： 飞书 API 调用超限

解决：

• 等待 15-30 分钟自动恢复
• 减少调用频率
• 配置备用模型

4.4 网络类问题

Q10: WebSocket 1008 错误

错误信息：disconnected (1008): unauthorized: gateway token missing

原因： Docker 或远程访问时认证失败

解决：

# 设置网关 Tokenopenclaw config set gateway.token <your-secure-token># 重启服务openclaw gateway restart

Q11: 502 Bad Gateway

原因： 上游服务商暂时不可用

解决：

• 等待几分钟后重试
• 配置备用模型
• 检查网络代理设置

Q12: 端口 18789 被占用

错误：EADDRINUSE: address already in use :::18789

解决：

# 查找占用进程lsof -i :18789  # macOS/Linuxnetstat -ano | findstr :18789  # Windows# 更换端口openclaw config set gateway.port 18790

4.5 配置类问题

Q13: Gateway won't start - configuration invalid

原因： 配置文件语法错误

解决：

# 自动修复openclaw doctor --fix# 查看具体错误openclaw doctor -v

Q14: 会话切换模型后无响应

原因： 对话历史中的工具调用 ID 格式不匹配

解决： 开启新会话（输入 /new）

Q15: 配置文件在哪里？

位置：~/.openclaw/openclaw.json

查看配置：

openclaw config get <key>

4.6 其他问题

Q16: Docker 部署后 Pairing Required

解决：

• 本地访问使用 localhost:18789
• 远程访问配置 gateway.token

Q17: 内存占用过高

解决：

// 限制历史消息数"session": {  "historyLimit": 100}

Q18: 如何查看完整诊断信息？

# 完整诊断openclaw status --all# 深度检查（测试 API 连接）openclaw status --deep# 生成可分享的诊断报告openclaw doctor --verbose

五、AI 模型选择建议

服务商	免费额度	特点
通义千问 Qwen	充足	入门首选，中文友好
KIMI	有	长文本理解强
GLM 4.7	有	性价比高
Claude	付费	代码能力顶尖
GPT-4	付费	综合能力强

六、OpenClaw 能力一览

场景	示例指令
文件管理	"把下载文件夹按类型分类"
网页处理	"总结这篇文章的要点：[URL]"
代码开发	"写个脚本批量重命名文件"
数据分析	"分析这份 Excel 数据"
自动化	"每天早上 9 点发送天气预报"
系统运维	"检查服务器磁盘空间"

遇到问题？

• 官方文档：https://docs.openclaw.ai
• GitHub Issues：https://github.com/openclaw/openclaw/issues
• 运行诊断：openclaw status --all

祝你使用愉快！