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

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

只需 install 一条（已实测）：gateway install 本身就会把服务跑起来，紧接着再执行 gateway start 会报 another OpenClaw process owns state-lifecycle。

第六步：配置模型（MiMo）

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

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

openclaw config

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

openclaw gateway install

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

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

# 创建配置目录（如果不存在）
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 错误。

模型版本说明：mimo-v2.5 / mimo-v2.5-pro 官方已公告 2026 年 10 月 21 日下线。到期后把上面两处模型名（id 和 name）换成 mimo-v2.6-pro 即可，其余字段不变。

保存配置。如果网关还没安装，直接安装（install 本身就会把服务跑起来）：

openclaw gateway install

只需 install 一条（已实测）：gateway install 本身就会把服务跑起来，紧接着再执行 gateway start 会报 another OpenClaw process owns state-lifecycle。
网关已经装过的话才用 openclaw gateway restart 让新配置生效。

等待 2～4 分钟后验证网关状态（低配机器更久，已实测）：

openclaw gateway status

启动要 1～3 分钟（已实测，低配机器更久）：它会先做 SQLite 快照、状态迁移和 agent 预热。
gateway start / gateway restart 自带的就绪预算只有 45～60 秒，所以常常报
Gateway start timed out after 45s —— 这不代表失败，服务还在起。
用这条自己等，别反复重启：

# 轮询等待端口就绪（最多 12 分钟）
for i in $(seq 1 48); do
  sleep 15
  ss -lnt | grep -q 18789 && echo "就绪（${i}×15 秒）" && break
done

需要停掉网关时，openclaw gateway stop 会被拒绝，必须加 --force：
openclaw gateway stop --force。

正确的输出应包含：

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"
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

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

关键：plugins.entries.feishu.enabled 这行别漏。飞书插件是从外部安装的，OpenClaw 要求显式"信任"才会运行；只配 channels.feishu 的话，通道会一直显示 stopped, health:not-running（不报错，只有 warning，很容易卡住）。

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

openclaw gateway restart

验证飞书连接

openclaw channels status

正确的输出：

- Feishu default: enabled, configured, running, connected

如果显示 not configured 或 disabled，检查：
1. 飞书插件是否已安装：openclaw plugins install @openclaw/feishu
2. 配置文件中 channels.feishu 是否正确
3. 配置里有没有 plugins.entries.feishu.enabled=true（外部插件需要显式信任才会运行）
4. 重启网关：openclaw gateway restart

如果显示 stopped, health:not-running：配置没问题，是插件没被信任——按上面第 3 条补上 plugins.entries.feishu.enabled=true 再重启网关。

第八步：测试

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 秒，再在飞书发消息测试。

低配服务器上重启后要等 1～3 分钟网关才真正就绪（openclaw gateway status 显示 Connectivity probe: ok 才算），急着发消息会没有响应。

Q: 飞书通道显示 `stopped, health:not-running`？

配置没错，是外部插件没被"信任"。在 ~/.openclaw/openclaw.json 里补上（与 channels 同级）：

"plugins": {
  "entries": {
    "feishu": { "enabled": true }
  }
}

保存后 openclaw gateway restart，再 openclaw channels status 应显示 enabled, configured, running, connected。

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

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

只需 install 一条（已实测）：gateway install 本身就会把服务跑起来，紧接着再执行 gateway start 会报 another OpenClaw process owns state-lifecycle。

第五步：配置模型（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"
    }
  },
  "plugins": {
    "entries": {
      "feishu": {
        "enabled": true
      }
    }
  }
}

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

关键：plugins.entries.feishu.enabled 这行别漏。飞书插件是从外部安装的，OpenClaw 要求显式"信任"才会运行；只配 channels.feishu 的话，通道会一直显示 stopped, health:not-running（不报错，只有 warning，很容易卡住）。

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

openclaw gateway restart

验证飞书连接

openclaw channels status

正确的输出：

- Feishu default: enabled, configured, running, connected

如果显示 not configured 或 disabled，检查：
1. 飞书插件是否已安装：openclaw plugins install @openclaw/feishu
2. 配置文件中 channels.feishu 是否正确
3. 配置里有没有 plugins.entries.feishu.enabled=true（外部插件需要显式信任才会运行）
4. 重启网关：openclaw gateway restart

如果显示 stopped, health:not-running：配置没问题，是插件没被信任——按上面第 3 条补上 plugins.entries.feishu.enabled=true 再重启网关。

第七步：测试

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 安装教程。

WSL2 也要开 linger：WSL 终端全部关掉后，systemd 用户服务同样会退出。在 Ubuntu 里跑一条 sudo loginctl enable-linger <你的用户名>，网关才能在后台常驻。

常见问题

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

常用管理命令速查