𝐗𝐀𝐈 𝐑𝐨𝐮𝐭𝐞𝐫

手把手在 macOS 安装并使用 OpenClaw

Posted February 5, 2026 by XAI 技术团队 ‐ 4 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) 准备环境变量与配置文件

先设置两个环境变量：

export XAI_API_KEY="sk-..."
export OPENCLAW_GATEWAY_TOKEN="$(openssl rand -hex 32)"

OpenClaw 默认读取：

~/.openclaw/openclaw.json

下面这份是当前推荐的 gpt-5.4 + openai-responses 接法：

{
  "models": {
    "mode": "replace",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com/v1",
        "apiKey": "${XAI_API_KEY}",
        "api": "openai-responses",
        "models": [
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": { "primary": "xairouter/gpt-5.4" },
      "models": {
        "xairouter/gpt-5.4": {
          "alias": "Codex",
          "params": { "transport": "sse" }
        }
      }
    }
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "http": {
      "endpoints": {
        "responses": { "enabled": true }
      }
    }
  }
}

要点：

  • api: "openai-responses" + https://api.xairouter.com/v1 是 OpenClaw 官方支持的自定义 provider 结构。
  • 不需要额外添加 headers.originator；保持 provider 配置最小即可。
  • params.transport: "sse" 会优先走 HTTP /v1/responses；如果你想 WebSocket-first，可改成 "auto"。
  • 这里把 models.mode 设为 "replace"，避免局部 models.json 或内置目录合并造成的覆盖歧义。
  • OpenClaw 内置 openai-codex OAuth 是直连 OpenAI 的路线，不会经过 XAI Router。
  • apiKey 与 gateway.auth.token 都建议通过环境变量注入。

3) 启动 Gateway（前台）

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

先做一次最小验证：

curl -sS http://127.0.0.1:18789/v1/responses \
  -H "Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-openclaw-agent-id: main" \
  -d '{"model":"openclaw","input":"ping"}'

启动后访问控制台：

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：让它后台常驻、开机自启