轻松掌握！macOS 上 OpenClaw 安装与首次配置全攻略

很多人觉得 OpenClaw 安装起来挺麻烦，其实没那么复杂。真正容易出问题的就两个地方：一个是环境配置不对，另一个是第一次运行时选项不懂。OpenClaw 官方推荐的安装方法是用安装脚本，它能自动识别你的系统，如果需要的话还会帮你安装 Node，并开启引导过程；推荐的运行环境是 Node 24，22.14 及以上的版本也可以使用。如果你打算从源码构建，才需要 pnpm。

一、这篇教程适合哪些人

如果你正好符合以下几种情况，这篇教程就很适合你：

你想在 macOS 上本地安装 OpenClaw；你准备接入 Telegram、WhatsApp 等渠道；你不打算用官方方式直接连接模型，而是想用第三方的 OpenAI 兼容接口；你希望它能在后台常驻，而不想每次都手动启动。在 OpenClaw 的官方文档中也明确提到，把“Getting Started”作为首次配置的入口，并把 openclaw onboard –install-daemon 作为标准的首次运行方式。

二、先安装环境，别急着动手

虽然官方安装脚本能在缺少 Node 的时候自动处理，但我还是建议你先把 macOS 的基础环境设置好，这样后面出错时能更容易找到问题。官方文档上写得很清楚，Node 24 是推荐版本，22.14 及以上的版本也可以用。

1. 安装 Homebrew

如果你的 Mac 上还没装 Homebrew，先打开终端执行：

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

安装完成后，确认一下：

brew --version

如果能正常显示版本号，说明 Homebrew 安装成功了。

2. Apple Silicon 机器把 brew 加入 PATH

如果你用的是 M 系列芯片，Homebrew 一般会在 /opt/homebrew。有时候你明明安装了，但终端输入 brew 却提示找不到，这通常是因为 PATH 没有设置。可以执行：

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofileeval "$(/opt/homebrew/bin/brew shellenv)"

然后再试一次：

brew --version

3. 安装 Node.js

我建议直接使用 Homebrew 安装 Node，这样最稳妥：

brew install node

安装完成后确认版本：

node --versionnpm --version

如果 node –version 显示 24.x 那就最好了；如果是 22.14 及以上，也在官方支持的范围内。OpenClaw 的安装文档和 Getting Started 都说明了这个版本要求。

4. 安装 Xcode Command Line Tools

虽然这不是 OpenClaw 官方“必备”的单独条目，但在 macOS 上进行命令行安装时非常常见，很多后续依赖都默认你已经安装了。直接执行：

xcode-select --install

如果系统提示已经安装过，那就不用管了。

5. 不建议用 root 安装

OpenClaw 的官方安装器明确说明，它的 CLI 安装是放在 ~/.openclaw 这样的用户目录下，自身就不需要 root 权限。GitHub 上也有人提到用 root 安装可能会引发问题。最稳妥的做法是：用你平常登录的普通 macOS 用户进行安装，千万别用 sudo，也不要用 root。

三、正式安装 OpenClaw

官方推荐的安装命令就是这一条：

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

官方文档说明，这个脚本会自动检测你的系统，必要时安装 Node 和 OpenClaw，并启动引导过程。如果你想跳过引导，只安装而不进入引导，可以加 –no-onboard，但我不建议第一次安装时这么做。

如果你之前已经安装过，或者想先只安装 CLI，而不立即启动向导，也可以使用：

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

四、安装完毕后，先确认 CLI 是否可用

安装完成后，别急着配置模型，先确认命令行是否正常：

openclaw --help

如果能看到帮助信息，说明 CLI 已经安装成功。

你还可以执行一次初始化：

openclaw setup

OpenClaw 的官方 CLI 文档说明，openclaw setup 会初始化 ~/.openclaw/openclaw.json 和工作区；如果想从 setup 直接进入向导，也可以用 openclaw setup –wizard。

五、第一次运行：一定要用 onboarding

第一次正式配置时，执行：

openclaw onboard --install-daemon

官方的 Getting Started 里就是这么写的。这个命令的作用不仅是“引导你完成配置”，还会顺便帮你把后台服务安装好。在 macOS 上对应的是 LaunchAgent；官方文档也提到，macOS 的后台服务是通过 openclaw onboard –install-daemon 或 openclaw gateway install 来实现的。

接下来是最重要的部分：第一次究竟该怎么选择。

六、首次运行时，每一步该怎么选择

虽然不同版本的 onboarding 界面可能有一些文字差异，但整体逻辑是一样的。你可以按照下面的思路来操作。

第一步：确认风险提示

这一步通常会告诉你，OpenClaw 具备控制系统的能力，属于高权限工具。在这里你要选择“确认”或者“Yes”。如果你在这一步选择了保守模式，后面它可能会变成“只会告诉你怎么做”的聊天机器人，而不是执行型的代理。OpenClaw 的官方首页也把它定位为“the AI that actually does things”，不是普通的问答工具。

第二步：连接模式优先选择 Local

如果向导让你选择本地还是远程，第一次安装建议选 Local。OpenClaw 的本地网关默认是指向本机 127.0.0.1，官方文档也一直把本地 Gateway 作为标准起步模式，常见的默认端口是 18789。

第三步：工作目录用默认设置

如果它询问你工作区放在哪里，直接用默认设置就行，也就是：

~/.openclaw/workspace

官方文档说明，默认工作区就是这里，而且首次 setup 或首次代理运行时会自动创建一些基础文件，比如 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md 等。你的长期定制最好都放在这里，而不要去改动程序本体。

第四步：模型提供方选择 Custom

这一点非常重要，很多教程会建议你选择“Anthropic”或“OpenAI”，但如果你打算接入第三方转发、自己的网关，或者任何 OpenAI 兼容的平台，这里就该选择 Custom。

原因是什么呢？因为你需要自己填写 Base URL、API Key 和模型名。这个时候，OpenClaw 不再为你预设官方线路，而是把模型访问配置的权力交给你。虽然官方文档没有逐一列出第三方平台，但从 CLI 和 Gateway 的设计来看，它是允许你自行维护 auth profile、provider state 和 workspace 配置的。相关状态和凭证的位置，官方 Setup 文档也有详细说明。

七、自定义模型应该怎么填写

这一部分是最容易出错的地方。

通常你会遇到以下几个字段。

1）Base URL

这里不要填完整的接口路径，更不要填到 /chat/completions 或 /responses 这个层级。一般只填到 /v1：

https://你的域名/v1

举个例子，如果你的第三方平台文档是 OpenAI 兼容的，那么通常要求的就是这样的 base URL。很多人第一次遇到 404 Not Found，实际上不是 key 错，而是 URL 写得过深了。

2）API Key

这一项就是你从平台获得的 key，直接粘贴进去。一般格式像这样：

sk-xxxxxxxx

轻松上手OpenClaw：安装与配置全攻略

在这里，你得填写真实的模型名称，可别自己瞎编哦！比如，如果你用的是 qwen3-coder-plus，就老老实实写这个；如果是 gpt-4o-mini，那就填这个。填错了，最常见的结果可不是401错误，而是“没有响应”或者“模型不存在”的提示。

4）API 类型选择

当向导让你选择协议类型时，优先考虑 OpenAI-compatible。因为大部分第三方接口都是基于这个协议设计的，兼容性更好。

八、首次设置其他选项的处理方式

如果向导问你关于技能、挂钩或者额外插件的事儿，建议第一次先跳过。为什么呢？因为你的首要目标是“让它先运行起来”，而不是“配置得最强”。

OpenClaw 的官方文档也提到，首次流程是：先安装、进行入门设置、让 Gateway 跑起来，最后拿到一个能工作的聊天会话。后续的技能和高级定制可以留到后面再说。

九、为什么一定要安装 daemon

当你第一次运行时，记得用：

openclaw onboard --install-daemon

这个 –install-daemon 是个重要的步骤。在 macOS 上，它会把网关以后台服务的形式常驻运行。官方的安装文档和 GitHub 上都强调了，macOS 的后台服务就是走这个路径。

这样有什么好处呢？很简单，以后你就不用每次都手动打开一个终端来运行 OpenClaw。特别是如果你后续要接入 Telegram 或其他渠道，它必须保持在线状态。要是你关了终端，整个链路就断了。

十、首次运行后，检查这些文件和目录

配置完成后，别急着聊天，先看看本地的状态有没有生成。

重点关注以下位置：

配置文件：

~/.openclaw/openclaw.json

工作区：

~/.openclaw/workspace

凭证和渠道状态：

~/.openclaw/credentials/

会话和 agent 状态：

~/.openclaw/agents/

日志：

/tmp/openclaw/

这些路径都是官方安装文档里提到的。今后排查问题时，你基本上离不开这些地方。

十一、启动并检查 Gateway

尽管 daemon 通常会帮助你启动，但还是建议你手动确认一下。

先检查状态：

openclaw gateway status

如果你想手动运行前台模式，也可以试试：

openclaw gateway --port 18789

OpenClaw 官方的个人助手设置也是用这个例子： openclaw gateway –port 18789。

接下来做个健康检查：

openclaw health

官方安装文档里把 openclaw health 作为一个简单的检查。

十二、打开控制台，确认不是“假成功”

你可以执行：

openclaw dashboard

官方文档提到，完成入门设置后会自动打开仪表板，以后需要重启时也可以手动执行 openclaw dashboard。

如果仪表板能正常打开，说明前面的设置已经成功了。

十三、最关键的验证：它真的能“干活”吗？

很多人在这一步看似都成功了，但其实可能只是“会聊天”。

最简单的测试方式就是让它执行一个无害的命令，比如：

帮我执行 pwd

或者：

帮我列出当前目录文件

如果它能直接返回结果，那就说明你的执行链路正常。如果它还是一脸认真地告诉你“请在终端里输入 pwd”，那就说明执行工具没连接好，或者权限设置太严格了。

这也是我之前一直强调的：OpenClaw 不仅仅是个聊天工具，它的真正价值在于“能执行任务”。前提是它得有可用的 Gateway、本地模式、工作区和执行能力。官方首页和入门指南对此都有明确说明。

十四、如果后续打算接入 Telegram 或其他渠道

第一次安装时先别急着接入。先确保本地链路正常。等确认了 gateway、仪表板、模型和基础命令都能正常工作后，再去做：

openclaw channels login

官方的安装文档建议，把渠道登录放在 Gateway 设置之后，先完成本地的健康检查，再去连接外部渠道。这个顺序是非常重要的。

十五、常见问题提前说清楚

第一个问题是 Node 版本过低。官方明确要求，推荐使用 Node 24，最低也得是 22.14+。如果版本太旧，很多奇怪的报错其实和 OpenClaw 本身无关。

第二个问题是 Base URL 填错。很多人填成了完整接口路径，结果导致404错误。自定义模型时，最稳妥的做法是只填到 /v1，不要随便加更深的路径。

第三个问题是用 root 账户安装。之前提到过，最好不要这么做。用户目录安装是最稳妥的，官方安装器也是朝这个方向设计的。

第四个问题是以为“能聊天就算成功”。这可不对！OpenClaw 真正成功的标志不是它能回复你，而是能否执行一个简单的任务。

第五个问题是工作区和配置文件改错地方。官方建议的定制位置是 ~/.openclaw/openclaw.json 和 ~/.openclaw/workspace，切勿随意修改程序内部文件。

十六、总结

很多人在第一次安装 OpenClaw 时，得到的结果只是一个“会说话的 AI”；而那些成功安装的人，收获的是一个“能长期为你工作的系统”。这其中的区别，不在于模型的聪明程度，而在于你是否把环境、网关、首次配置和执行链路都理顺。官方文档将安装、入门设置、工作区、网关和健康检查分得很清楚，按照这个顺序走，成功率会大大提高。