9、MAC客户端安装教程

📋 目录

  1. 系统要求

  2. 快速安装（推荐）

  3. 新手引导

  4. 常用插件配置

  5. 浏览器扩展安装

  6. Control UI 使用

  7. 常用命令速查

  8. 故障排除

系统要求

  • 操作系统: macOS 12.0 (Monterey) 或更高版本

  • Node.js: 版本 22 或更高

  • 内存: 建议 8GB 以上

  • 存储: 至少 2GB 可用空间

  • 网络: 需要访问互联网（用于安装和模型 API）

大部分安装和配置的过程都需要在Mac的终端完成，可以在启动台搜索“终端打开”

image-pau7.png

快速安装（推荐）

方法一：一键安装脚本

打开终端（Terminal），复制并输入以下命令实现一键安装：

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

安装脚本会自动：

  • 检测并安装 Homebrew（如果缺失）

  • 安装 Node.js 22+

  • 安装 Git

  • 全局安装 OpenClaw

  • 运行新手引导

方法二：手动安装（已有 Node.js）

如果你已经安装了 Node.js 22+（你可以在终端输入 npm -v ，查看是否正确输出版本号来验证）

v2-f6420f20a258102298cebbfa4f6bec69_1440w.webp

如果返回了版本号，你可以使用npm进行安装，逐条运行以下命令（#开头的部分属于注释，无需运行）：

# 使用 npm
npm install -g openclaw@latest

# 或使用 pnpm（需要批准构建脚本）
pnpm add -g openclaw@latest
pnpm approve-builds -g
pnpm add -g openclaw@latest

方法三：从源代码安装（开发者）

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build
pnpm build

# 通过 pnpm 运行
pnpm openclaw --version


新手引导

安装完成后，运行新手引导：

openclaw onboard --install-daemon

新手引导会帮你配置：

  • Gateway 令牌（用于浏览器 Control UI）

  • 模型提供商和 API 密钥

  • 默认频道设置

  • Daemon 服务安装

image-ftqo.png

验证安装

# 查看版本
openclaw --version

# 检查健康状态
openclaw doctor

# 查看 Gateway 状态
openclaw gateway status

# 查看可用工具
openclaw tools list

# ******  启动（重启）openclaw  ****** #
openclaw gateway restart

自定义模型源（初次试用可跳过）

额外说下，模型提供商和 API 密钥的配置很重要，默认的模型比如Qwen，Kimi等。新手不建议立即自行配置，可以先试用新手引导中设置的基础模型。

模型每日会有API调用限额，超出限额后你无法再和openclaw聊天互动（页面会有提示）。这时候你可以切换商业化的模型源，比如阿里百炼，以百炼平台为例，阿里云百炼的模型 API 调用支持 OpenAI-compatible 接口，你只需要登录 阿里云百炼大模型服务平台 准备好：

阿里云百炼 API key：

https://bailian.console.aliyun.com/cn-beijing/?source_channel=zhihedoc&tab=globalset#/efm/api_key

模型调用地址 base_url： https://dashscope.aliyuncs.com/compatible-mode/v1

模型名称 model code：如 qwen-plus, qwen3-max 等

随后，找到你mac电脑中的 ~/.openclaw/openclaw.json 文件

提示： /.openclaw 为隐藏文件夹，你需要定位到你自己电脑的用户根目录 /Users/XXXX 下，同时按下 shift(⇧)+command（⌘）+. (>)，即可显示隐藏文件。

若你是电脑小白，你也可以直接同时按住command（⌘）+空格，在搜索框中搜索~/.openclaw/

image-nxnh.png

从而找到该文件夹，打开并编辑openclaw.json 文件（可用文本编辑器打开），主要分为两步：1.添加模型提供商，2. 配置首选模型提供商。

1 . 加模型提供商:

找到 "models": { "providers": { ... 那部分花括号对中，添加 // >>>> 到 // <<<<中的内容（// <<<<和// <<<<可以去掉）。原先的模型提供商那部分可以加在后面，当做备用。

修改"apiKey": "xxx", 中的xxx 为你在阿里云百炼申请的 API key。

若你申请的不是qwen3.5-plus这个模型，需要修改 "id": "qwen3.5-plus"中的qwen3.5-plus为你实际申请的模型名称（id）。

 ...  
 "models": {
    "providers": {
       // >>>>
       "bailian": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "xxx",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3.5-plus",   // 这里修改为你申请的模型id
            "name": "qwen3.5-plus",
            "reasoning": false,
            "input": [
              "text", "image"
            ],
            "cost": {
              "input": 0.0025,
              "output": 0.01,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 1048576,
            "maxTokens": 65536
          }
        ]
      },
     // <<<<
     ... // 原先的那部分可以加在后面

  }
}
...

2. 设置首选模型提供商。找到 "agents": { "defaults": { "model": {"primary": 这部分，将"primary"修改为"bailian/qwen3.5-plus"。 其中bailian对应着上边providers中配置的提供商bailian。“qwen3.5-plus” 对应着上面你申请的模型名称（id）。

... 
"agents": {
    "defaults": {
      "model": {
        "primary": "bailian/qwen3.5-plus"  // 此处设置首选模型
      },
      "models": {
        "bailian/qwen3.5-plus": {
          "alias": "qwen3.5-plus"  // 这里只是设置一个别名。
        },
    ....
...

修改完配置文件openclaw.json 后，需要重启或者应用配置：

应用配置
openclaw config apply
重启gateway
openclaw gateway restart

若你实在不会修改openclaw.json 配置文件，可以尝试在终端运行：

百炼平台：替换 $DASHSCOPE_API_KEY 为你申请的API_KEY
openclaw onboard --non-interactive --auth-choice dashscope-api-key --dashscope-api-key "$DASHSCOPE_API_KEY"

KIMI：替换 $KIMI_API_KEY 为你申请的API_KEY
openclaw onboard --non-interactive --auth-choice kimi-api-key --kimi-api-key "$KIMI_API_KEY"

浏览器扩展安装

OpenClaw Chrome 扩展允许你控制现有的 Chrome 标签页（而不是打开独立的浏览器窗口）。

步骤 1：安装扩展

openclaw browser extension install

步骤 2：获取扩展路径

openclaw browser extension path

步骤 3：加载到 Chrome

  1. 打开 Chrome，访问 chrome://extensions

  2. 开启右上角的 “开发者模式”

  3. 点击 “加载已解压的扩展程序”

  4. 选择上一步获取的扩展路径

步骤 4：固定扩展

在 Chrome 工具栏上点击扩展图标右侧的图钉，固定扩展。

步骤 5：配置扩展

  1. 点击扩展图标 → 选项（Options）

  2. 设置：

  • Port: 18792（默认）

  • Gateway Token: 与 openclaw onboard 时设置的令牌一致

步骤 6：使用扩展

  1. 打开你想让 OpenClaw 控制的标签页

  2. 点击扩展图标

  3. 徽章显示 ON 表示已连接

  4. 再次点击可断开连接

命令行使用：

# 查看标签页
openclaw browser --browser-profile chrome tabs

# 或使用 browser 工具（在聊天中）
# 设置 profile="chrome"

Control UI 使用

Control UI 是 OpenClaw 的网页管理界面，可以：

  • 聊天对话

  • 配置频道

  • 管理 Cron 任务

  • 查看日志

  • 编辑配置

访问方式

本地访问：

# 确保 Gateway 已启动
openclaw gateway

# 浏览器打开
http://127.0.0.1:18789

远程访问（Tailscale 推荐）：

在配置文件中启用 Tailscale Serve：

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" }
  }
}

然后通过 Tailscale 的 MagicDNS 访问：

https://<你的设备名>.tailnet-name.ts.net

设备配对

首次从新设备访问 Control UI 时，需要配对：

# 查看待审批的设备
openclaw devices list

# 批准设备
openclaw devices approve <requestId>


部分插件配置

1. Webchat（网页聊天）

Webchat 是内置的网页聊天界面，无需额外配置即可使用。

访问方式：

# 启动 Gateway 后，在浏览器打开
http://127.0.0.1:18789

2. Telegram

Telegram 是最易用的消息渠道之一。

配置步骤：

  1. 在 Telegram 中搜索 @BotFather

  2. 发送 /newbot 创建机器人

  3. 获取 Bot Token

  4. 在 OpenClaw 配置中添加：

openclaw channels telegram enable
# 按提示输入 Bot Token

启动：

openclaw channels telegram start

3. Discord

Discord 适合团队和技术社区使用。

配置步骤：

  1. 访问 Discord Developer Portal

  2. 创建新应用 → Bot → 复制 Bot Token

  3. 启用以下 Privileged Gateway Intents：

  • MESSAGE CONTENT INTENT

  • SERVER MEMBERS INTENT

  1. 邀请机器人到你的服务器

  2. 在 OpenClaw 中配置：

openclaw channels discord enable
# 输入 Bot Token 和需要的频道 ID

4. 微信（WeChat）

⚠️ 注意：微信非官方支持，使用第三方库（如 WeChaty），存在封号风险。

配置方式（使用 Wechaty）：

# 安装 Wechaty 相关依赖
npm install -g wechaty wechaty-puppet-wechat

# 在 OpenClaw 配置中启用
openclaw channels wechat enable

替代方案：使用企业微信（更安全稳定）

5. 钉钉（DingTalk）

配置步骤：

  1. 访问钉钉开放平台

    https://open.dingtalk.com

创建企业内部应用（机器人），获取appKey和appSecret。这部分略过，可以网上搜索钉钉机器人。但需要注意将消息接收模式改为“Stream模式”。

9670d391-74d4-45b0-a985-d7e4ad86f9c0.png

OpenClaw 配置：

安装钉钉插件：
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

完成上方步骤后，需要在~/.openclaw/openclaw.json 文件中修改channels/dingtalk-connector、gateway/auth 和 gateway/http/endpoints3 个配置项。

...
{
  "channels": {
    "dingtalk-connector": {  // 在channels下 添加dingtalk-connector
      "clientId": "钉应用app_key（钉应用、机器人）",// 必填
      "clientSecret": "钉应用app_secret", // 必填
      "gatewayToken": "Gateway 认证 token",// 必填，同配置文件中：gateway—>auth->token 这一项
      "gatewayPassword": "",              // 可选：Gateway 认证 password（与 token 二选一）
      "sessionTimeout": 1800000  // 超时时间 30min
    },
   ...
  },
  "gateway": { // gateway通常是已有的节点，配置时注意把http部分追加到已有节点下
    "auth": {
      "mode": "token",
      "token": "Gateway 认证 token" // 必填，之前会自动生成。
    },
    "http": {  // 在gateway项下添加这部分，注意逗号隔开
      "endpoints": {
        "chatCompletions": {
          "enabled": true // 必选
        }
      }
    },
   ...
  }
}
...

常用命令速查

Gateway 管理

openclaw gateway start    # 启动 Gateway
openclaw gateway stop     # 停止 Gateway
openclaw gateway restart  # 重启 Gateway
openclaw gateway status   # 查看状态

频道管理

openclaw channels status              # 查看所有频道状态
openclaw channels <name> enable       # 启用频道
openclaw channels <name> disable      # 禁用频道
openclaw channels <name> start        # 启动频道
openclaw channels <name> stop         # 停止频道

配置管理

openclaw config get        # 查看配置
openclaw config edit       # 编辑配置
openclaw config apply      # 应用配置更改

技能（Skills）

openclaw skills list       # 列出所有技能
openclaw skills enable <name>   # 启用技能
openclaw skills disable <name>  # 禁用技能

调试和诊断

openclaw doctor      # 健康检查
openclaw status      # 系统状态
openclaw health      # Gateway 健康
openclaw logs tail   # 实时日志

会话管理

openclaw sessions list          # 列出会话
openclaw sessions history <key> # 查看历史

故障排除

1. openclaw 命令找不到

原因：npm 全局路径不在 PATH 中

解决：

# 查看 npm 全局路径
npm prefix -g

# 添加到 ~/.zshrc
export PATH="$(npm prefix -g)/bin:$PATH"

# 重新加载
source ~/.zshrc

2. sharp 安装失败

原因：系统安装了 libvips 导致冲突

解决：

SHARP_IGNORE_GLOBAL_LIBVIPS=1 npm install -g openclaw@latest

3. Gateway 启动失败

检查：

# 查看端口占用
lsof -i :18789

# 查看日志
openclaw logs tail

# 检查配置
openclaw config get

4. 浏览器扩展显示 ! 错误

原因：

  • 本地中继服务器未运行

  • Gateway Token 不匹配

解决：

  1. 确保 Gateway 正在运行

  2. 检查扩展 Options 中的 Gateway Token 是否正确

  3. 重启扩展

5. 频道连接失败

检查清单：

  • [ ] API Token/密钥是否正确

  • [ ] 网络是否可达

  • [ ] 是否需要特殊权限（如 Discord 的 Message Content Intent）

  • [ ] 查看频道日志：openclaw channels <name> logs

6. 模型调用失败

检查：

# 查看模型配置
openclaw models list

# 测试连接
openclaw models test

附录：配置文件位置

~/.openclaw/
├── openclaw.json      # 主配置文件
├── workspace/         # 工作空间（AGENTS.md、MEMORY.md 等）
├── memory/            # 记忆文件
└── gateway/           # Gateway 相关数据

ZiKX ᓚᘏᗢ 🎲
ZiKX ᓚᘏᗢ 🎲
更新于 2026-03-13
上一篇 8、Linux 客户端部署及对接飞书
下一篇 没有了
评论交流

文档目录

Open Claw教程