𝐗𝐀𝐈 𝐑𝐨𝐮𝐭𝐞𝐫

手把手在 macOS 安装并使用 OpenClaw

Posted February 5, 2026 by XAI 技术团队 ‐ 5 min read

OpenClaw

OpenClaw + macOS

本文是一份从零开始的 macOS 本地安装指南，包含：

  • 安装 OpenClaw CLI
  • 编写配置文件
  • 启动 Gateway（前台 / 后台）
  • 访问控制台
  • 接入 Telegram（可选）
  • 授权 macOS 系统能力（可选）

0) 先决条件

  • Node.js 22+（仅 CLI + Gateway 即可）
  • macOS 终端（Terminal）
  • 如果需要 macOS 系统能力（系统命令/屏幕/相机/通知），需安装 OpenClaw.app（菜单栏应用）

Node.js 官方下载：https://nodejs.org/（建议 LTS 版本）

1) 安装 OpenClaw CLI

sudo npm install -g openclaw@latest

如果你已经把 npm 的全局目录改成了用户可写路径，可去掉 sudo：

npm install -g openclaw@latest

验证安装：

openclaw --version

提示：不要用 sudo 启动 OpenClaw。否则配置会写到 /var/root，并且无法正常使用 macOS 权限。

2) 准备配置文件

OpenClaw 默认读取：

~/.openclaw/openclaw.json

下面是一个OpenAI Responses 兼容的示例（含图片输入、maxTokens=32000）：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.2",
            "name": "GPT",
            "reasoning": false,
            "input": ["text", "image"],
            "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
            "contextWindow": 200000,
            "maxTokens": 32000
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.2" },
      "models": { "xairouter/gpt-5.2": { "alias": "GPT" } }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": { "mode": "token", "token": "REPLACE_WITH_TOKEN" }
  }
}

要点：

  • 如果你不需要图片输入，可把 input 改成 "text"。
  • apiKey 建议通过环境变量注入，避免把密钥写死。
  • 如果你不想自定义路径，直接把配置保存为 ~/.openclaw/openclaw.json。

3) 启动 Gateway（前台）

openclaw gateway --bind loopback --port 18789 --verbose

启动后访问控制台：

http://127.0.0.1:18789/

如果配置了 gateway.auth.token，控制台会要求输入 token。

4) 安装为后台服务（launchd）

如果你希望开机后自动运行：

openclaw gateway install

常用维护命令：

openclaw gateway status
openclaw gateway restart
openclaw gateway stop

日志位置：

~/.openclaw/logs/gateway.log
~/.openclaw/logs/gateway.err.log

如果你安装了 OpenClaw.app 并使用 Local 模式，Gateway 由 App 管理，不建议再手动 install。

5) 接入 Telegram（可选）

最简方式（CLI 写配置）：

openclaw channels add --channel telegram --token <BOT_TOKEN>

或者直接写到配置文件：

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "BOT_TOKEN",
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist"
    }
  }
}

首次私聊会生成配对码，需要批准：

openclaw pairing list telegram
openclaw pairing approve telegram <code>

6) 让 OpenClaw 使用 macOS 系统能力（可选）

要使用 system.run、屏幕录制、相机、通知等能力，需要安装 OpenClaw.app 并完成授权：

  1. 安装并启动 OpenClaw.app（菜单栏）
  2. 按提示授予权限（通知、辅助功能、屏幕录制、麦克风、语音识别、自动化/AppleScript）
  3. 在 App 中配置 Exec approvals

Exec approvals 文件位置：

~/.openclaw/exec-approvals.json

推荐使用 allowlist（只放开必要命令）：

{
  "version": 1,
  "defaults": { "security": "allowlist", "ask": "on-miss" },
  "agents": {
    "main": {
      "security": "allowlist",
      "ask": "on-miss",
      "allowlist": [
        { "pattern": "/opt/homebrew/bin/rg" },
        { "pattern": "/usr/bin/osascript" }
      ]
    }
  }
}

如果你明确知道风险并希望完全放开，可将 security 设为 full，ask 设为 off。

完全放开示例（高风险）：

{
  "version": 1,
  "defaults": { "security": "full", "ask": "off" },
  "agents": {
    "main": {
      "security": "full",
      "ask": "off"
    }
  }
}

7) 常用检查命令

openclaw health
openclaw status
openclaw models status
openclaw channels status

总结

  • CLI + Gateway：即可在本机跑通 OpenClaw
  • OpenClaw.app：赋予系统能力 + 更完整的 macOS 控制
  • Gateway install：让它后台常驻、开机自启