𝐗𝐀𝐈 𝐑𝐨𝐮𝐭𝐞𝐫

手把手在 macOS 安装并使用 OpenClaw

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

OpenClaw

OpenClaw + macOS

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

  • 安装 OpenClaw CLI
  • 复制配置文件（路线 A，2 选 1）
  • 打开 Memory Search（可选推荐）
  • 接入 OpenAI Codex 官方 OAuth（可选进阶）
  • 启动 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) 准备配置文件（路线 A：2 选 1）

大多数用户先做路线 A 就够了。你不需要一开始就理解环境变量、provider 切换、OAuth 路由这些概念；先选下面 2 个完整配置里的 1 个，复制过去跑起来，这是最省事的做法。

先创建配置目录并打开默认配置文件：

mkdir -p ~/.openclaw
nano ~/.openclaw/openclaw.json

如果你用的是 nano，保存方式如下：

  • 粘贴完整内容
  • 按 Ctrl + O 保存
  • 回车确认文件名
  • 按 Ctrl + X 退出

开始前先记住 5 点：

  • 下面两个配置是 2 选 1，不要同时粘贴两个。
  • 不管你选的是下面哪一种接法，最终保存路径都应该是 ~/.openclaw/openclaw.json。
  • 务必把所有示例里的 "apiKey": "sk..." 替换成你自己的 xairouter.com API Key。 这个占位值不能直接用。
  • 如果你对环境变量没有概念，最简单的做法就是把示例里的 sk... 直接替换成你自己的 API Key，其他内容先不要动。
  • 示例里的 gateway.auth.token 也可以直接先用；后面 curl 验证和网页控制台登录都要用到它。如果你之后想改成自己的随机字符串，再改也可以。

路线 A / 方案 1：（openai-responses）

如果你想先走 openai-responses 这条接法，就把下面完整内容复制到 ~/.openclaw/openclaw.json：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
	"baseUrl": "https://api.xairouter.com",
	// 务必替换成你自己的 xairouter.com API Key
	"apiKey": "sk...",
	"api": "openai-responses",
	"models": [
	  {
	    "id": "gpt-5.4",
	    "name": "GPT",
	  }
	]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
	"primary": "xairouter/gpt-5.4"
      },
      "models": {
	"xairouter/gpt-5.4": {
	  "alias": "GPT"
	}
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "db86e9b5a527ddf76339d61153eb59915ab58d14ed1cfdfc75b2c35dc0f98c01"
    },
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "plugins": {
    "entries": {
      "telegram": {
	"enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.1.30",
    "lastTouchedAt": "2026-02-02T08:31:26.394Z"
  }
}

路线 A / 方案 2：（openai-completions）

如果你更想走 openai-completions 这条接法，就把下面完整内容复制到 ~/.openclaw/openclaw.json：

{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
	"baseUrl": "https://api.xairouter.com",
	// 务必替换成你自己的 xairouter.com API Key
	"apiKey": "sk...",
	"api": "openai-completions",
	"models": [{ "id": "MiniMax-M2.5", "name": "MiniMax-M2.5" }]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
	"primary": "xairouter/MiniMax-M2.5"
      },
      "models": {
	"xairouter/MiniMax-M2.5": {
	  "alias": "MiniMax"
	}
      },
      "maxConcurrent": 4,
      "subagents": {
	"maxConcurrent": 8
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "db86e9b5a527ddf76339d61153eb59915ab58d14ed1cfdfc75b2c35dc0f98c01"
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "plugins": {
    "entries": {
      "telegram": {
	"enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.1.30",
    "lastTouchedAt": "2026-02-02T08:31:26.394Z"
  }
}

如果你现在的目标只是先把 OpenClaw 跑起来，这一节可以先跳过。 如果你希望 OpenClaw 后面能检索 MEMORY.md、memory/*.md 里的笔记，再回来把下面这段补上即可。

一眼先看懂怎么选：

你想要什么推荐模型适合谁
先开起来，成本更稳text-embedding-3-small大多数用户
更强召回，预算更宽text-embedding-3-large笔记较多、希望语义匹配更强

开始前只记 4 点：

  • memorySearch.provider 这里写的是 "openai"，因为这里走的是 OpenAI-compatible embeddings 接口。
  • memorySearch.remote.baseUrl 这里要写 https://api.xairouter.com/v1，不是上面聊天模型配置里的 https://api.xairouter.com。
  • 为了避免和上面自定义的 xairouter 聊天 provider 混淆，最省事的办法就是直接把 key 写在 memorySearch.remote.apiKey。
  • 这里的 memorySearch.remote.apiKey 也必须替换成你自己的 xairouter.com API Key。 sk... 只是占位示例。

把下面这段加到你现有配置的 agents.defaults 里面：

如果你是把这段直接粘到 agents.defaults 的最后面，记得给前一个字段补上一个逗号。

"memorySearch": {
  "enabled": true,
  "provider": "openai",
  "model": "text-embedding-3-small",
  "fallback": "none",
  "remote": {
    "baseUrl": "https://api.xairouter.com/v1",
    // 务必替换成你自己的 xairouter.com API Key
    "apiKey": "sk..."
  },
  "query": {
    "maxResults": 8,
    "minScore": 0.25
  }
}

如果你想走效果优先版，只需要把 model 改成：

"model": "text-embedding-3-large"

启动 Gateway 后，直接做这 3 个检查：

openclaw memory status --deep
openclaw memory index --force
openclaw memory search --query "deployment notes"

如果你还没有 memory 文件，可以先准备一份最小示例：

mkdir -p ~/.openclaw/workspace/memory
printf '# Team Notes\n\n- Deploy with blue-green rollout.\n' > ~/.openclaw/workspace/memory/team-notes.md

不想自己拼？下面是两份“已内置 Memory Search”的整段可复制版

  • 下面两份完整配置已经把 Memory Search 配好了，默认使用 text-embedding-3-small。
  • 如果你更想用 text-embedding-3-large，只需要把下面配置里的 "model": "text-embedding-3-small" 改成 "model": "text-embedding-3-large"。
  • 这两份仍然是 2 选 1，不要同时粘贴。
  • 这两份整段配置里出现的所有 apiKey，都要替换成你自己的 xairouter.com API Key。
{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com",
        // 务必替换成你自己的 xairouter.com API Key
        "apiKey": "sk...",
        "api": "openai-responses",
        "models": [
          {
            "id": "gpt-5.4",
            "name": "GPT"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "xairouter/gpt-5.4"
      },
      "models": {
        "xairouter/gpt-5.4": {
          "alias": "GPT"
        }
      },
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "text-embedding-3-small",
        "fallback": "none",
        "remote": {
          "baseUrl": "https://api.xairouter.com/v1",
          // 务必替换成你自己的 xairouter.com API Key
          "apiKey": "sk..."
        },
        "query": {
          "maxResults": 8,
          "minScore": 0.25
        }
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "db86e9b5a527ddf76339d61153eb59915ab58d14ed1cfdfc75b2c35dc0f98c01"
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.1.30",
    "lastTouchedAt": "2026-02-02T08:31:26.394Z"
  }
}
{
  "models": {
    "mode": "merge",
    "providers": {
      "xairouter": {
        "baseUrl": "https://api.xairouter.com",
        // 务必替换成你自己的 xairouter.com API Key
        "apiKey": "sk...",
        "api": "openai-completions",
        "models": [
          {
            "id": "MiniMax-M2.5",
            "name": "MiniMax-M2.5"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "xairouter/MiniMax-M2.5"
      },
      "models": {
        "xairouter/MiniMax-M2.5": {
          "alias": "MiniMax"
        }
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      },
      "memorySearch": {
        "enabled": true,
        "provider": "openai",
        "model": "text-embedding-3-small",
        "fallback": "none",
        "remote": {
          "baseUrl": "https://api.xairouter.com/v1",
          // 务必替换成你自己的 xairouter.com API Key
          "apiKey": "sk..."
        },
        "query": {
          "maxResults": 8,
          "minScore": 0.25
        }
      }
    }
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto"
  },
  "gateway": {
    "mode": "local",
    "auth": {
      "mode": "token",
      "token": "db86e9b5a527ddf76339d61153eb59915ab58d14ed1cfdfc75b2c35dc0f98c01"
    }
  },
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  },
  "meta": {
    "lastTouchedVersion": "2026.1.30",
    "lastTouchedAt": "2026-02-02T08:31:26.394Z"
  }
}

路线 B（可选进阶）：接入 OpenAI Codex 官方 OAuth

如果你现在的目标只是先把 OpenClaw 跑起来，可以先跳过这一步。只有在你想直接使用 ChatGPT / OpenAI 官方 Codex 登录时，再执行：

openclaw models auth login --provider openai-codex

如果你确认要把默认模型切到官方 Codex 路线，再加 --set-default：

openclaw models auth login --provider openai-codex --set-default

这个流程会：

  • 拉起浏览器完成 ChatGPT 登录
  • 使用 http://127.0.0.1:1455/auth/callback 作为本地回调地址
  • 在自动回跳失败时，提示你把回调 URL / code 粘回终端
  • 把 OAuth 凭据写入 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 不会覆盖你刚才保存的路线 A 配置

如果 OAuth 在打开浏览器前就报 TLS 证书校验错误，可先修一下 Homebrew Node / OpenSSL 的证书链：

brew postinstall ca-certificates
brew postinstall openssl@3

3) 启动 Gateway（前台）

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

启动后，按你刚才选择的配置做一次最小验证。

如果你选的是 openai-responses

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

如果你选的是 openai-completions

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H "Authorization: Bearer db86e9b5a527ddf76339d61153eb59915ab58d14ed1cfdfc75b2c35dc0f98c01" \
  -H "Content-Type: application/json" \
  -H "x-openclaw-agent-id: main" \
  -d '{"model":"openclaw","messages":[{"role":"user","content":"ping"}]}'

如果你自己改过 gateway.auth.token，把上面命令里的 token 换成你现在配置文件里的值即可。

这里请求里的 model: "openclaw" 是 Gateway 的统一模型名，你不需要改成 xairouter/gpt-5.4 或 xairouter/MiniMax-M2.5。

启动后访问控制台：

http://127.0.0.1:18789/

如果控制台要求输入 token，就填配置文件里 gateway.auth.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

总结

  • 路线 A：多数用户先走这里，2 个完整配置选 1 个，保存为 ~/.openclaw/openclaw.json
  • 方案 1：openai-responses 接法
  • 方案 2：openai-completions 接法
  • Memory Search：可选推荐；走 xairouter OpenAI-compatible embeddings 时，provider 写 openai，baseUrl 写 https://api.xairouter.com/v1，文中也附了两份已内置 Memory Search 的整段可复制版配置
  • 路线 B：官方 openai-codex OAuth，属于可选进阶项
  • OpenClaw.app：赋予系统能力 + 更完整的 macOS 控制
  • Gateway install：让它后台常驻、开机自启

提醒：如果你照着本文使用 方案 1（openai-responses / gpt-5.4），充值时请选择 Codex（Codex/Claude/OpenClaw） 对应套餐；如果你使用 方案 2（openai-completions / MiniMax-M2.5），请选择 MiniMax-M2.5（OpenClaw/Claude） 对应套餐。套餐购买地址：m.xairouter.com。具体套餐名称以充值页实际显示为准。