乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > 项目经理必看:OpenClaw 小龙虾安装教程(包含win和mac)

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

当前时间： 2026-03-11 19:47:01 分类：办公文件 评论(0)
项目经理必看: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. 1. 访问 飞书开放平台
  2. 2. 创建企业自建应用
  3. 3. 记录 App ID 和 App Secret
  4. 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. 1. 禁用 Beta 功能
// 在配置中添加"beta_features": []
  1. 2. 切换到直接 API
// 使用 anthropic 而非 bedrock/vertex"provider": "anthropic"
  1. 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

祝你使用愉快！