OpenClaw 保姆级教程,安装、模型接入、后台运行、避坑

最近我看到不少人又开始研究 OpenClaw。

说起来，这东西上半年火过一阵。

那时候见人就问一句，你养虾了吗？

当时各种教程、玩法满天飞，不少人都想装一个试试。

不过从下载安装到配置模型，这中间很少有人说清楚。

这次源宝我就把整个过程从头走一遍。

从安装、模型配置、网页控制台、后台运行，再到实际使用。

中间可能碰到的各种问题，都说清楚。

OpenClaw 跟 Claude Code、Codex 有点像。

都能借助大模型调用工具、执行任务。

不过，OpenClaw 更偏向个人 AI 助手。

除了写代码，还能整理文件、操作浏览器，或者定时处理一些重复工作。

它也能接入飞书、Telegram、Discord、微信、Slack 等聊天软件。

OpenClaw 的安装方式有两种。

终端命令行和官方软件。

我是觉得命令行上手难度实在是高，有软件也没必要了。

我主要用 Mac 举例。

Windows 也不用担心，后面会把对应的安装方法一起说清楚。

目前有两个下载途径。

官方网站和 GitHub 项目。

下载的安装包都是一样的，纯看个人喜好。

官网：

https://openclaw.ai/

GitHub ：

https://github.com/openclaw/openclaw

目前所有受支持平台的安装包在这都能找到。

先进入系统设置-通用-关于本机页面。

看 macOS 系统版本，以及使用的是 Apple 芯片还是 Intel 芯片。

目前 Mac 版软件要求系统在 macOS 26.2 以上。

官网没更新，所以显示的还是 mac OS15+。

如果在 macOS 26.2 以下，先去看看能不能升级。

不能升级就得用命令行。

Windows 要求 10 或 11。

打开官方 Windows Hub 的发布页面：

https://github.com/openclaw/openclaw-windows-node/releases

普通 Intel、AMD 处理器的 Windows 电脑，选：

OpenClawCompanion-Setup-x64.exe

如果是 Windows on ARM 设备，就选：

OpenClawCompanion-Setup-arm64.exe

目前支持 Windows 10 20H2 及以上版本，以及 Windows 11。

如果电脑系统比较老，还是得先去升级。

我先说命令行安装方法。

先打开 Mac 的终端。

不知道在哪找的，在 APP 搜索中输入终端。

打开后会看到一个可以输入命令的窗口。

先输入：

node -v

这是检查电脑有没有安装 Node.js。

如果输出结果和我的一样，说明电脑已经安装了 Node。

目前官方支持 Node.js 24.16 及以上的 24.x 版本。

或者 Node.js 26.1 及以上的 26.x 版本。

我更推荐 Node 26。

如果你的电脑还是 Node 22、23或更早的版本，一定要先升级。

如果提示：command not found: node

说明没安装 Node.js。

不用专门找官网下载。

官方的安装脚本可以检测 Node 环境，并在需要时准备兼容的版本。

在终端输入以下代码，按回车。

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

这就是目前官方提供的 Mac 安装命令。

它会从 OpenClaw 官方地址获取安装脚本，然后执行安装流程。

从官网或者 GitHub 下载安装包，打开。

把龙虾图标拖进文件夹。

第一次打开，可能会弹出安全提示。

我实测是没遇到。

以防万一，我把出现安全提示的方法也说一下。

在设置-隐私与安全-安全性，仍要打开。

Windows 更简单。

找到下载好的 EXE 安装程序，双击打开，按照安装向导完成安装。

如果电脑之前没有配置过 Gateway，会进入初始设置流程。

我简单解释一下 Gateway。

可以把它理解成 OpenClaw 在电脑上运行的核心服务。

聊天界面负责让你发送消息，模型负责处理问题，而 Gateway 负责让这些组件连接起来，并且协调工具调用等操作。

如果启动过程中出现错误，先不要立刻卸载。

安装窗口会显示错误的是哪个环节。

比如本地运行环境、Gateway 启动、连接认证，或者控制台加载。

后面我会专门讲这些问题怎么解决。

如果正常完成，就进入模型配置。

现在软件已经把模型连接流程整合到了初始化界面。

不需要自己打开配置文件，也不需要手动执行命令。

如果Mac 上已经使用过 Codex、Claude Code

OpenClaw 会进行检测并验证，确认能不能正常调用。

找到可用的模型，比如之前登录过 Codex。

OpenClaw 会提供现有 Codex 登录的选项。

想和原来的 Codex 使用相同登录环境，可以选择复用。

不想和原来的 Codex 共享登录及对话信息，也可以在界面里选择单独登录。

如果没用过以上任何 AI 软件也没关系。

它会提供模型连接入口。

比如用账号登录，或者用 API Key。

提醒一下：

ChatGPT、Claude 这些产品的会员，和开发者 API 不一定是同一种计费方式。

如果用账号登录，就按照它的浏览器授权流程操作。

如果用 API Key，就得去对应服务商的开发者平台申请密钥，不能直接把网站登录密码填进去。

下面我把这两种情况都讲一下。

有 ChatGPT 账号，直接选择。

界面提示使用现有登录，或者单独通过浏览器登录。

按自己的需求选。

浏览器打开后，使用对应账号完成登录授权，然后回到 OpenClaw。

它会继续检测模型连接。

只有真正调用成功，才算模型配置完成。

如果想用 API Key，也很简单。

我用 DeepSeek API 举例。

先打开开发者平台：

https://openai.com/zh-Hans-CN/api/

使用自己的账号登录，进入 API Key 管理页面。

如果没有创建过密钥，就创建一个新的。

创建以后，把密钥复制下来，保存在安全的地方。

因为只在创建时展示一次完整密钥。

如果关掉页面后无法再次查看，就只能重新生成。

用 API Key 前，记得检查账号是否有余额或者其他可用额度。

也不要刚配置完成，就直接让 Agent 执行特别复杂的任务。

因为 OpenClaw 执行一个任务时，可能会连续调用模型很多次。

最后你只看到一份结果，但后台已经产生了多次请求。

如果模型是按 Token 计费的，这些调用都可能产生费用。

准备好 API Key 以后，回到 OpenClaw。

在模型配置界面选择 DeepSeek。

输入自己的密钥。

如果失败，先看报错具体写了什么。

我整理了几个经常出现的问题。

401 Unauthorized

优先检查 API Key 是否有效、有没有复制错，或者认证方式是不是选错了。

403 Forbidden

涉及账号权限、服务商限制或者当前模型不可用。

429 Too Many Requests

可能是请求频率、用量限制或者额度问题。

Model not found

就检查自己填的模型名称，以及当前服务商是否真的提供这个模型。

如果是连接超时，就检查网络，以及接口地址是否能够正常访问。

如果出现下面这种情况。

说明密钥保存成功，但默认模型没有变更。

需要在终端执行代码。

openclaw plugins install @openclaw/deepseek-provideropenclaw gateway restart

这就配置完了。

用之前再测试一下，确保 API 以及其他问题都解决。

测试很简单，发一条简单的消息，看能不能回复。

如果回复说明没问题，如果还是不行再去排查。

再来熟悉一下整个界面。

OpenClaw 不只有聊天，还有 Agent 管理、模型、会话、渠道、插件、工具、自动化等相关功能。

不同版本的界面可能调整位置。

界面主要分成三个区域。

最左边是功能导航栏。

这里可以切换首页、智能体、仪表盘、系统、自动化和插件等功能。

比如想管理 Agent，就点智能体，想设置定时任务，就进自动化。

后面需要安装插件，也是在这里找。

下方还能看到当前的会话和在线状态。

中间是主要的聊天和工作区域。

平时给 OpenClaw 发送任务，主要就在这里操作。

底部是消息输入框，可以直接输入要求，旁边还能看到当前选择的模型。

上面则会显示 AI 的回复、任务执行过程和报错信息。

最右边是询问 OpenClaw 辅助面板。

这个区域主要用来帮你了解和配置 OpenClaw 本身。

比如不知道模型怎么接、Gateway 为什么连接失败，或者飞书、Telegram 怎么配置，都可以在这里询问。

它和中间的任务聊天区域不太一样。

这更偏向软件设置、故障排查和使用指导。

接下来试试效果。

毕竟 OpenClaw 如果只能聊天，那跟豆包一样了就。

先试试文件整理。

在桌面新建一个文件夹，名字就叫 OpenClaw-Test。

随便准备几份测试文件放进去。

最好别放重要资料，避免出现问题。

回到聊天界面，发送

我在电脑上创建了一个 OpenClaw-Test 文件夹

请先检查你能否访问这个文件夹

如果可以，列出里面的文件名称

先不要修改、移动或者删除任何文件

它会确认路径和获取必要的权限。

说实话，它读取速度还挺快。

从找我桌面上的 OpenClaw-Test 文件夹，到分析出来只用了 54S。

一共找到了 7 个文件，里面有 Markdown 文档、Word 文件、PNG 图片，还有之前留下的日志文件。

文件名也都完整列了出来。

再发送：

请读取测试文件夹中的笔记文件

把内容重新整理成一份 Markdown 文档

保留原始信息，不要自行编造内容

新文件命名为 summary.md

不要覆盖或者删除原文件

执行之前先告诉我准备写入的位置

打开对应文件夹，检查文件是不是真的生成了。

如果文件没有生成，就继续检查工具调用记录和实际写入路径。

我再说一下安装使用容易遇到的问题、原因和解决办法

1.Mac 下载好了，却打不开软件

先看系统版本。

当前官方 Mac 应用要求 macOS 26.2 或者更高版本。

如果系统版本不符合要求，就需要先解决系统兼容问题。

如果系统版本符合要求，再确认下载的是否为官方 Mac 安装包，以及芯片架构有没有选错。

如果你用的是 Apple 芯片，却下载了 Intel，那这就打不开。

2.打开以后一直停在 Getting things ready

这个提示主要表示软件正在准备运行环境。

新版 Mac 应用会使用它内置的运行组件，不需要再额外安装 Node.js。

如果一直无法完成，先看看窗口里有没有明确提示当前失败的步骤。

3.Gateway 一直显示无法连接

先从 Mac 菜单栏找到 OpenClaw，打开连接。

这里可以查看当前连接的是本机连接，还是其他设备上的远程连接。

如果出现 Install Gateway、Update Gateway 或者 Repair Gateway。

按照软件当前显示的说明处理。

4.Gateway 正常，但模型一直失败

这时候就应该先检查模型，而不是检查软件能不能打开。

进入设置，找到模型。

确认当前使用的模型提供商、认证方式，以及默认模型。

如果使用 API Key，检查密钥是否有效，账号是否拥有相应的 API 权限。

如果使用账号登录，检查授权有没有失效。

如果是自定义接口，再检查链接、模型名称和兼容格式。

5.已经配置了模型，但发消息还是没回复

先确认软件是不是已经真正完成模型验证。

如果模型没有通过验证，只是把 API Key 保存了，聊天仍然可能失败。

另外，看看是否选择了不支持当前工具调用方式的模型。

6.Mac 已经授权了，AI 还是不能操作文件

这里最容易把两种权限混在一起。

一种是 macOS 系统权限。

另一种是 OpenClaw 自己对 Agent 工具的管理。

系统已经授权，不代表 Agent 一定拥有所有工具权限。

反过来，Agent 已经配置了某个工具，也不代表 macOS 会允许它访问所有敏感信息。

7.关闭 OpenClaw 以后，定时任务不执行了

先检查自己有没有启用后台运行。

Mac 当前默认的新安装模式，会由应用托管 Gateway。

如果没有开启后台运行，退出软件可能会让 Gateway 一起停止。

8.更新以后突然用不了

如果是系统和 OpenClaw 不兼容，就用不了。

这时候得先弄清楚，到底应该更新 Mac 系统，还是更新软件。

另外，安装 Skills 和插件时，也要检查来源。

有些插件会执行代码，访问外部资源或者读取工作区文件。

如果来源不清楚，最好别装。

到这里，官方桌面应用的安装和使用就讲完了。

Mac 用户直接下载官方 DMG。

安装以后跟着软件的引导配置本地 Gateway 和模型。

Windows 用户则使用官方 Windows Hub。

首次打开时选择 Set up locally，让程序准备自己的本地运行环境。

之后就可以在软件里聊天、管理模型、配置权限，再根据需要接入飞书。

如果只是想先体验一下，不用一口气把所有功能都装齐。

先聊聊天，再试试看能不能做文档。

等真正熟练，再玩高级玩法。

相关资料我也放在这里，有不明白的地方可以直接查。

Mac 桌面应用：

https://docs.openclaw.ai/platforms/macos

Mac 官方安装引导：

https://docs.openclaw.ai/start/onboarding

模型配置：

https://docs.openclaw.ai/concepts/model-providers/control-ui-and-keys

网页控制台：

https://docs.openclaw.ai/web/control-ui

安全设置：

https://docs.openclaw.ai/gateway/security