OpenClaw 安装与配置完全指南：多平台安装到模型配置

macOS 安装教程

系统要求

操作系统：macOS 12.0 或更高版本

处理器：Apple Silicon (M1/M2/M3/M4) 或 Intel

内存：至少 4GB RAM

运行环境：Node.js 24（推荐）或 Node.js 22.19+

网络：需要互联网连接

OpenClaw 是一款开源的个人 AI 助手框架，支持多模型接入、工具调用和持久记忆。本教程基于服务器实测，涵盖从安装到配置的完整流程。

第一步：安装 Homebrew（包管理器）

打开 终端（Spotlight 搜索 Terminal），执行：

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

安装完成后，按照终端最后两行提示将 Homebrew 加入 PATH（复制那两行 echo 命令执行即可）。

验证：

brew --version  # 应该显示 Homebrew 4.x

第二步：安装 Node.js

brew install node@24

Homebrew 暂未提供 Node 24 时，用 Node 22：brew install node@22

验证：

node -v   # 应该显示 v24.x 或 v22.x
npm -v    # 应该显示 10.x 或更高

第三步：安装 OpenClaw

npm i -g openclaw
openclaw onboard

国内网络慢的话，用镜像加速：

npm config set registry https://registry.npmmirror.com
npm i -g openclaw
openclaw onboard

第四步：验证安装

openclaw --version      # 确认 CLI 可用
openclaw doctor         # 检查配置问题
openclaw gateway status # 确认 Gateway 运行状态

第五步：安装 Gateway 守护进程（后台常驻）

openclaw gateway install
openclaw gateway start

macOS 会自动创建 LaunchAgent，开机自启。

第六步：配置模型（MiMo）

💡 推荐使用小米 MiMo：注册 MiMo 平台（邀请码 L2HBDP 注册送 ¥10 体验金）

方式一：通过配置向导（推荐新手）

openclaw config

在配置向导中按顺序操作：
1. 选择 Local (this machine) → 回车
2. 选择 Model → Continue → 回车
3. 选择模型提供商（如 Xiaomi MiMo）→ 回车
4. 输入你的 API Key（格式：sk-xxxxxxxx）→ 回车
5. 选择模型版本（推荐 mimo-v2.5）→ 回车
6. 完成后重启网关：

openclaw gateway restart

方式二：手动编辑配置文件（推荐，更可靠）

如果向导方式遇到问题，直接编辑配置文件：

# 创建配置目录（如果不存在）
mkdir -p ~/.openclaw

# 找到配置文件，如果不存在会自动创建
nano ~/.openclaw/openclaw.json

找到 models 部分，确保内容如下（替换 你的API_KEY）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xiaomi": {
        "baseUrl": "https://api.xiaomimimo.com/v1",
        "apiKey": "你的API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "mimo-v2.5",
            "name": "MiMo v2.5",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local"
  }
}

⚠️ 关键：api 字段必须是 "openai-completions"，不能是 "openai-responses"！
MiMo 不支持 OpenAI Responses API，用错了会报 404 错误。

保存后重启网关：

openclaw gateway restart

然后安装 Gateway 守护进程（后台常驻）：

openclaw gateway install
openclaw gateway start

等待几秒后验证网关状态：

openclaw gateway status

正确的输出应包含：

Runtime: running (pid xxxxx, state active, sub running)
Connectivity probe: ok

验证模型连接

openclaw doctor

确认没有 model_not_found 或 404 错误。

第七步：配置飞书

💡 需要先安装飞书插件，然后选择扫码方式或手动配置。

7.1 安装飞书插件

openclaw plugins install @openclaw/feishu

看到 Installed plugin: feishu 表示安装成功。

7.2 方式一：扫码方式（推荐新手）

openclaw channels login --channel feishu

交互式操作步骤：

1. 出现菜单 安装 Feishu 插件？
2. 默认已选 从 npm 下载（@openclaw/feishu）

3. 如果已通过 7.1 安装，直接按 回车 跳过

4. 出现菜单 你想如何连接 Feishu？

5. 按 ↓ 下箭头 选择 扫描二维码自动创建 bot

6. 按 回车 确认

7. 出现菜单 选择 Feishu 域名？

8. 默认已选 Feishu (feishu.cn) - 中国

9. 直接按 回车 确认

10. 终端显示二维码

11. 用手机飞书扫描二维码

12. 手机上确认授权

13. 扫码完成后出现 群聊策略 菜单

14. 推荐选 允许列表 - 只在指定群中响应（默认已选）

15. 按 回车 确认

16. 看到 Bot 已配置。 表示成功

7.3 方式二：手动配置（推荐，更可靠）

如果你有飞书应用的 App ID 和 App Secret，可以直接编辑配置文件：

nano ~/.openclaw/openclaw.json

在文件中添加 channels 部分（与 models 同级）：

{
  "models": {
    ...
  },
  "gateway": {
    "mode": "local"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "你的App_ID",
      "appSecret": "你的App_Secret"
    }
  }
}

替换 你的App_ID 和 你的App_Secret 为你的飞书应用凭证。

⚠️ 重要：配置完成后，必须重启网关才能生效！

openclaw gateway restart

验证飞书连接

openclaw channels status

正确的输出：

- Feishu default: enabled, configured, running

如果显示 not configured 或 disabled，检查：
1. 飞书插件是否已安装：openclaw plugins install @openclaw/feishu
2. 配置文件中 channels.feishu 是否正确
3. 重启网关：openclaw gateway restart

第八步：测试

8.1 首次使用需要批准配对

当用户第一次在飞书中给机器人发消息时，服务器会收到配对请求。需要在服务器端批准：

# 查看待批准的配对请求
openclaw pairing list --channel feishu

# 批准配对（替换为实际的配对码）
openclaw pairing approve feishu <配对码>

💡 配对码可以在 openclaw pairing list 的输出中看到，格式如 M4RCTKAL。

批准后，机器人会自动设置 command owner，之后用户就可以正常对话了。

8.2 测试对话

1. 在飞书私聊机器人，发送 你好
2. 等待几秒钟，机器人应该正常回复
3. 如果回复 Something went wrong 错误，参见常见问题中的 "飞书机器人报 404 错误" 部分

❓ 常见问题

Q: `npm i -g openclaw` 安装超时怎么办？

国内网络访问 npm 官方源可能很慢或超时，解决方案：

# 配置国内镜像（npmmirror）
npm config set registry https://registry.npmmirror.com

# 重新安装
npm i -g openclaw

Q: `openclaw doctor` 显示 Memory search 警告？

这是正常的，不影响使用。Memory search 需要 OpenAI API key，如果不需要语义记忆功能可以忽略。

Q: `openclaw doctor` 显示 "command owner not configured"？

这是正常的，不影响基本功能。只有需要使用 owner-only 命令时才需要配置。

Q: 飞书扫码后没有反应？

1. 确保手机飞书已登录且有管理员权限
2. 扫码后如果终端没有反应，重新运行 openclaw channels login --channel feishu
3. 选择手动输入 App ID 和 App Secret 方式作为备选

Q: 飞书扫码完成但机器人不回复？

最常见原因是网关未重启：

openclaw gateway restart

重启后等待 5 秒，再在飞书发消息测试。

Q: 飞书机器人回复 "Something went wrong" / 404 错误？

这是 MiMo API 类型配置错误导致的。MiMo 只支持 Chat Completions API（/v1/chat/completions），不支持 OpenAI Responses API（/v1/responses）。

解决方法：

# 编辑配置文件
nano ~/.openclaw/openclaw.json

# 找到 models.providers.xiaomi 部分
# 将 api 字段从 "openai-responses" 改为 "openai-completions"
# 同样修改 models 数组中每个模型的 api 字段

# 保存后重启网关
openclaw gateway restart

验证：

openclaw channels status

应该显示 Feishu default: enabled, configured, running

Q: 飞书通道状态显示 "not configured"？

检查配置文件：

cat ~/.openclaw/openclaw.json | grep -A 5 feishu

如果只有 "enabled": true 没有 appId/appSecret，说明配置没有保存成功，需要重新扫码或手动配置。

Q: 命令找不到（command not found）？

添加 PATH 环境变量：

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Q: `openclaw` 命令找不到？

# 检查 Node 是否安装
node -v

# 检查全局包路径
npm prefix -g

# 确认路径在 PATH 中
echo "$PATH"

# 如果不在，添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc）
export PATH="$(npm prefix -g)/bin:$PATH"

然后打开新终端窗口。

Q: 启动失败怎么办？

# 查看实时日志
openclaw logs --follow

Q: 如何查看已配置的模型？

openclaw models list

Q: 如何重新配置？

openclaw config

Q: 如何更新到最新版？

openclaw update

📚 常用管理命令速查

Windows 安装教程

系统要求

操作系统：Windows 10/11

处理器：x64 架构 CPU

内存：至少 4GB RAM

运行环境：Node.js 24（推荐）或 Node.js 22.19+

网络：需要互联网连接

💡 本教程提供两种安装方式：原生 Windows（推荐）和 WSL2（Linux 子系统）。选择适合你的方式。

方式一：原生 Windows 安装

第一步：安装 Node.js

1. 访问 https://nodejs.org 下载 Node.js 24 LTS 安装包
2. 双击安装包，按默认选项一路 Next 完成安装
3. 重新打开 PowerShell（重要！否则环境变量不生效）

验证：

node -v   # 应该显示 v24.x
npm -v    # 应该显示 10.x 或更高

第二步：安装 OpenClaw

npm i -g openclaw
openclaw onboard

国内网络慢的话，用镜像加速：

npm config set registry https://registry.npmmirror.com
npm i -g openclaw
openclaw onboard

第三步：验证安装

openclaw --version      # 确认 CLI 可用
openclaw doctor         # 检查配置问题
openclaw gateway status # 确认 Gateway 运行状态

第四步：安装 Gateway 守护进程

openclaw gateway install
openclaw gateway start

Windows 会创建定时任务实现开机自启。

第五步：配置模型（MiMo）

💡 推荐使用小米 MiMo：注册 MiMo 平台（邀请码 L2HBDP 注册送 ¥10 体验金）

方式一：通过配置向导（推荐新手）

openclaw config

在配置向导中按顺序操作：
1. 选择 Local (this machine) → 回车
2. 选择 Model → Continue → 回车
3. 选择模型提供商（如 Xiaomi MiMo）→ 回车
4. 输入你的 API Key（格式：sk-xxxxxxxx）→ 回车
5. 选择模型版本（推荐 mimo-v2.5）→ 回车
6. 完成后重启网关：

openclaw gateway restart

方式二：手动编辑配置文件（推荐，更可靠）

如果向导方式遇到问题，直接编辑配置文件：

# 打开配置文件（用记事本）
notepad %USERPROFILE%\.openclaw\openclaw.json

找到 models 部分，确保内容如下（替换 你的API_KEY）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xiaomi": {
        "baseUrl": "https://api.xiaomimimo.com/v1",
        "apiKey": "你的API_KEY",
        "api": "openai-completions",
        "models": [
          {
            "id": "mimo-v2.5",
            "name": "MiMo v2.5",
            "api": "openai-completions",
            "reasoning": true,
            "input": ["text"],
            "contextWindow": 128000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "gateway": {
    "mode": "local"
  }
}

⚠️ 关键：api 字段必须是 "openai-completions"，不能是 "openai-responses"！
MiMo 不支持 OpenAI Responses API，用错了会报 404 错误。

保存后重启网关：

openclaw gateway restart

验证模型连接

openclaw doctor

确认没有 model_not_found 或 404 错误。

第六步：配置飞书

💡 需要先安装飞书插件，然后选择扫码方式或手动配置。

6.1 安装飞书插件

openclaw plugins install @openclaw/feishu

看到 Installed plugin: feishu 表示安装成功。

6.2 方式一：扫码方式（推荐新手）

openclaw channels login --channel feishu

交互式操作步骤：

1. 出现菜单 安装 Feishu 插件？
2. 默认已选 从 npm 下载（@openclaw/feishu）

3. 如果已通过 6.1 安装，直接按 回车 跳过

4. 出现菜单 你想如何连接 Feishu？

5. 按 ↓ 下箭头 选择 扫描二维码自动创建 bot

6. 按 回车 确认

7. 出现菜单 选择 Feishu 域名？

8. 默认已选 Feishu (feishu.cn) - 中国

9. 直接按 回车 确认

10. 终端显示二维码

11. 用手机飞书扫描二维码

12. 手机上确认授权

13. 扫码完成后出现 群聊策略 菜单

14. 推荐选 允许列表 - 只在指定群中响应（默认已选）

15. 按 回车 确认

16. 看到 Bot 已配置。 表示成功

6.3 方式二：手动配置（推荐，更可靠）

如果你有飞书应用的 App ID 和 App Secret，可以直接编辑配置文件：

nano ~/.openclaw/openclaw.json

在文件中添加 channels 部分（与 models 同级）：

{
  "models": {
    ...
  },
  "gateway": {
    "mode": "local"
  },
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "你的App_ID",
      "appSecret": "你的App_Secret"
    }
  }
}

替换 你的App_ID 和 你的App_Secret 为你的飞书应用凭证。

⚠️ 重要：配置完成后，必须重启网关才能生效！

openclaw gateway restart

验证飞书连接

openclaw channels status

正确的输出：

- Feishu default: enabled, configured, running

如果显示 not configured 或 disabled，检查：
1. 飞书插件是否已安装：openclaw plugins install @openclaw/feishu
2. 配置文件中 channels.feishu 是否正确
3. 重启网关：openclaw gateway restart

第七步：测试

6.1 首次使用需要批准配对

当用户第一次在飞书中给机器人发消息时，服务器会收到配对请求。需要在服务器端批准：

# 查看待批准的配对请求
openclaw pairing list --channel feishu

# 批准配对（替换为实际的配对码）
openclaw pairing approve feishu <配对码>

💡 配对码可以在 openclaw pairing list 的输出中看到，格式如 M4RCTKAL。

批准后，机器人会自动设置 command owner，之后用户就可以正常对话了。

6.2 测试对话

1. 在飞书私聊机器人，发送 你好
2. 等待几秒钟，机器人应该正常回复
3. 如果回复 Something went wrong 错误，参见常见问题中的 "飞书机器人报 404 错误" 部分

方式二：WSL2 安装（Linux 子系统）

💡 如果你更习惯 Linux 环境，或者原生方式遇到问题，可以用 WSL2。

第一步：安装 WSL2

打开 PowerShell（以管理员身份运行），执行：

wsl --install

重启电脑后，从开始菜单打开 Ubuntu，设置用户名和密码。

第二步：一键安装

在 Ubuntu 终端中执行：

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

国内网络慢的话，用镜像加速：

curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/openclaw/openclaw/main/install.sh | bash

第三步：验证与配置

openclaw --version
openclaw doctor
openclaw dashboard

WSL2 方式和 Linux 安装完全一致，后续步骤（配置模型、配置飞书）请参考 OpenClaw Linux 安装教程。

❓ 常见问题

Q: `npm i -g openclaw` 安装超时怎么办？

国内网络访问 npm 官方源可能很慢或超时，解决方案：

# 配置国内镜像（npmmirror）
npm config set registry https://registry.npmmirror.com

# 重新安装
npm i -g openclaw

Q: `openclaw doctor` 显示 Memory search 警告？

这是正常的，不影响使用。Memory search 需要 OpenAI API key，如果不需要语义记忆功能可以忽略。

Q: `openclaw doctor` 显示 "command owner not configured"？

这是正常的，不影响基本功能。只有需要使用 owner-only 命令时才需要配置。

Q: 飞书扫码后没有反应？

1. 确保手机飞书已登录且有管理员权限
2. 扫码后如果终端没有反应，重新运行 openclaw channels login --channel feishu
3. 选择手动输入 App ID 和 App Secret 方式作为备选

Q: 飞书扫码完成但机器人不回复？

最常见原因是网关未重启：

openclaw gateway restart

重启后等待 5 秒，再在飞书发消息测试。

Q: 飞书机器人回复 "Something went wrong" / 404 错误？

这是 MiMo API 类型配置错误导致的。MiMo 只支持 Chat Completions API（/v1/chat/completions），不支持 OpenAI Responses API（/v1/responses）。

解决方法：

# 编辑配置文件
notepad %USERPROFILE%\.openclaw\openclaw.json

# 找到 models.providers.xiaomi 部分
# 将 api 字段从 "openai-responses" 改为 "openai-completions"
# 同样修改 models 数组中每个模型的 api 字段

# 保存后重启网关
openclaw gateway restart

验证：

openclaw channels status

应该显示 Feishu default: enabled, configured, running

Q: 命令找不到（command not found）？

npm 全局包路径通常在：

C:\Users\你的用户名\AppData\Roaming\npm

确保这个路径在系统 PATH 中：

1. 右键 此电脑 → 属性 → 高级系统设置 → 环境变量
2. 在 用户变量 中找到 Path，编辑
3. 添加 npm 全局包路径
4. 重新打开 PowerShell

Q: `openclaw` 命令找不到？

# 检查 Node 是否安装
node -v

# 检查全局包路径
npm prefix -g

# 确认路径在 PATH 中
echo $env:PATH

Q: 启动失败怎么办？

# 查看实时日志
openclaw logs --follow

Q: 如何查看已配置的模型？

openclaw models list

Q: 如何重新配置？

openclaw config

Q: 如何更新到最新版？

openclaw update

📚 常用管理命令速查