装完OpenClaw之后，我差点把它删了

一个macOS新手的完整避坑指南（不需要问任何人的那种）

我装了删，删了装，整了两遍。

不是OpenClaw不好用——是我太菜了，不想问人，又不敢乱点。

整个过程没问过一个群、一个大神、一个客服。

全靠反复试、反复踩坑、反复搜。

所以如果你现在也卡在某一步，不知道下一步点哪里——这篇文章就是写给你的。

你照着做，30分钟装好，直接跑起来。

先搞清楚 OpenClaw 是什么（1分钟）

OpenClaw是一个AI个人助手框架，说人话就是：

给你配了一支AI团队，你说话它们干活，你休息它们帮你盯着。

不是ChatGPT那种"你问我答"，而是：

• 你说"帮我盯着A股，有异动叫我" → 它真的在后台跑着，股票跌了10%发消息告诉你
• 你说"帮我写篇公众号文章" → 它真的帮你写好、生成封面图、传到草稿箱

你教它越多，它帮你做得越多。

安装篇：一行命令装好

OpenClaw是终端命令行工具，没有App Store，没有安装包，全程只需要一行命令。

第一步：打开终端

按 Command + Space 调出苹果搜索，输入"终端"，回车。

黑色的窗口就是终端——全程只需要这一个工具。

第二步：确认你的Mac已经装了Homebrew和Node

官方安装脚本会自动检测并安装它们，但如果你的网络有问题或者Homebrew之前装过但不完整，这个步骤可能会卡住。

建议先自己装好：

确认安装成功：

第三步：粘贴安装命令，回车

在终端里粘贴这行命令，回车：

安装脚本会自动完成：

• 检测/安装 Homebrew（如果没有）
• 检测/安装 Node（推荐 Node 24，最低 Node 22.16）
• 全局安装 OpenClaw
• 启动初始化向导

整个过程1-3分钟。

⚠️ 坑1：Homebrew安装卡住超过5分钟

按 Ctrl+C 停掉，自己先按上面第二步的方法装好Homebrew，再跑安装命令。

⚠️ 坑2：命令粘贴后回车没反应

确保你粘贴的是完整一行命令，不要有换行。关掉终端重新打开再试。

第四步：验证安装成功

看到 OpenClaw is ready! 提示后，验证三连：

如果都正常，说明装好了。

⚠️ 坑3：提示 command not found: openclaw

关掉终端重新打开，再试。如果还是不行：

```bash

echo 'export PATH="$(npm prefix -g)/bin:$PATH"' >> ~/.zshrc

```

然后关掉终端重新打开。

配置篇：这一节最重要，也最容易踩坑

装好之后，OpenClaw还不能用——你需要配置两件事：AI模型 和 消息渠道。

不配置它就是聋子瞎子，只能在终端里自言自语。

这一节我卸载重装了两遍才搞明白，下面每个细节都是血泪经验。

第五步：运行初始化向导

终端执行：

这会启动一个交互式向导，帮你完成基础配置。向导会逐步问你：

2. 选择模式
   ：新手选 QuickStart（默认）就好
4. 选择模型
    → 填API Key
6. 工作区位置
   ：默认 ~/.openclaw/workspace，直接回车确认
8. 配置Gateway
   ：默认本地，端口18789
10. 添加消息渠道
    ：选飞书（或暂时跳过）
12. 安装技能
    ：推荐直接装

⚠️ 坑4：执行 openclaw onboard 报错

如果提示权限问题：

```bash

sudo chown -R $(whoami) ~/.openclaw

```

再重试。

5.1 配置AI模型（踩坑重灾区）

这是整个安装过程中最容易出问题的地方，也是我卸载重装两遍的原因。

openclaw onboard 会问你用哪个模型，你需要先有 API Key。

第一步：申请 MiniMax API Key（推荐新手从这里开始）

为什么推荐 MiniMax：

• 国内直连，不需要特殊网络
• 有免费额度（每天50张图 + 一定量对话）
• 我们整个内容团队现在就在用它

申请步骤：

2. 打开 https://platform.minimaxi.com
4. 点右上角「注册/登录」，用手机号注册
6. 登录后进入「开发」→「API Key管理」
8. 点「创建API Key」，随便起个名字，点创建
10. 复制这个Key，保存好
    ——只显示一次，刷新页面就没了

⚠️ 坑5：打开 minimaxi.com 显示"此地区不支持"

确认浏览器语言是中文，或者换个节点重试。

第二步：在 onboard 里填入 API Key

回到终端，openclaw onboard 会：

2. 让你选择模型提供方 → 选 MiniMax
4. 让你粘贴 API Key → 把刚才复制的 Key 粘贴进去
6. 等待连接测试完成

⚠️ 坑6：粘贴 Key 后显示"认证失败"或"无效 Key"

最常见三个原因：

- Key 前后有多余空格（终端粘贴经常带空格）——删掉前后空格重新粘贴

- Key 被刷新过了（只显示一次）——去 minimaxi.com 重新创建一个

- 网络连不上 MiniMax ——等30秒重试

可选模型介绍

| 模型 | 官网 | 特点 | 适合人群 |

|-----|------|------|---------|

| MiniMax | minimaxi.com | 国内直连，有免费额度 | 新手首选 |

| DeepSeek | platform.deepseek.com | 国产大模型，性价比高 | 深度用户 |

| Kimi | moonshot.cn | 国产，支持超长上下文 | 有长文本需求 |

⚠️ 国外模型（Claude、GPT-4、Gemini）需要翻墙才能完成认证，国内用户建议直接用上面三个。

如果你选了 Claude 或 GPT-4，认证那一步需要翻墙。

第三步：单独重新配置模型

如果 onboard 过程中跳过了，或者之后想换一个模型，执行：

或者打开网页控制台（浏览器访问）：

在「设置」→「模型」里填入 API Key，界面操作更直观。

⚠️ 坑7：网页控制台打不开

确认 Gateway 在运行：

```bash

openclaw gateway status

```

如果显示 stopped，执行 openclaw gateway restart 再试。

5.2 添加消息渠道（让AI能收到你的消息）

不配置它，你就只能在终端里跟它说话。

OpenClaw 支持：飞书、微信、Telegram、Discord 等。

推荐选飞书，国内访问稳定、免费、支持多账号绑定不同 Agent。

在 onboard 里用方向键选中「飞书」，回车确认。

⚠️ 坑8：方向键在 onboard 里没反应

确保输入法是英文状态，不要在中文输入法下操作方向键和回车。

飞书配置的详细步骤我单独写了一篇（下一篇），这里先配到能让机器人回复你的程度即可。

第六步：验证配置成功

以上都配置完之后，先试最简单的方式——不需要配置飞书，直接用浏览器聊天：

这会在浏览器里打开控制台，直接就能跟 AI 对话，不需要任何渠道配置。

如果能看到聊天界面并回复了，说明整个安装配置全部成功。

或者在终端里测试：

⚠️ 坑9：发消息后一直显示"思考中"然后没反应

三个排查步骤：

1. 先等1分钟（大模型第一次响应本来就慢）

2. 还是没反应？openclaw gateway restart 重启后台

3. 执行 openclaw doctor 看输出，根据提示修复

问题排查篇：其他常见问题

状态栏显示"未连接"或红色

原因：OpenClaw 后台服务没在跑。

Agent回复乱说话或行为奇怪

原因：系统提示词被误改了。

解决方法：按 Command + Shift + G，输入 ~/.openclaw/，找到对应 Agent 的工作区目录，打开 memory/ 文件夹，删掉里面的会话历史文件（不要删文件夹本身），然后重启 Agent。

重新运行 onboard 会丢失配置吗？

不会。

openclaw onboard 默认不会清除任何现有配置，除非你主动选择 Reset。

如果想重新配置但不想丢失东西，用：

装完之后：第一件事该做什么

OpenClaw 真正强大的不是问答——你教它你的情况，它帮你做事。

所以装完第一步，告诉它你是谁。

在你工作区目录里有个 USER.md 文件，用文本编辑器打开，写入：

Agent 每次启动都会读这个文件。你写得越详细，它越懂你。

然后从一个小任务开始：

"帮我查一下今天上海天气"

如果它正常回复了——你的 OpenClaw 已经完全跑起来了。

写在最后

装 OpenClaw 这件事本身真不难。

难的只有两件事：

2. 知道每一步敲什么命令
    —— 这篇指南已经帮你解决了
4. 配置模型那一步
    —— 第一次配确实容易踩坑，按坑1到坑9逐个排查就好

你描述得越清楚，它做得越准确。

所以——先从一个小任务开始跑。

跑通的那一刻，你会回来谢我的。

📌 下期预告：飞书机器人的完整配置教程——从创建应用到让机器人真正收到消息，每一步都有。

艾伦，普通人，用 OpenClaw 做跨境电商、内容创作。用 AI 打工人，AI 时代的手艺人。