type
Post
status
Published
date
Mar 12, 2026
slug
openclaw-install-guide
summary
本文介绍如何在 Windows、macOS 或 Linux 上安装 OpenClaw，完成模型配置、启动服务，并通过首轮对话验证系统是否正常可用。
tags
工具
开发
category
技术分享
icon
password
这篇文章主要介绍如何从零安装 OpenClaw，并完成最小化配置、启动服务和首轮验证。整篇内容尽量按最短路径来写，目标不是把所有功能都讲完，而是先让你把 OpenClaw 真正跑起来。
OpenClaw 是一个开源、自托管的 AI Agent 平台，可以把大模型、技能系统和多种消息渠道接到一起。官方文档本身已经能把流程讲清楚，但第一次装的人通常还是会卡在三个地方：Node.js 版本、配置文件格式、模型连通性。本文就只解决这三个最容易卡住的点。
📝 1. 安装前准备
在开始安装之前，先确认两件事：
- 你的机器已经安装 Node.js 20 或更高版本
- 你已经准备好了一个可用的大模型提供商配置，例如 OpenAI，或者本地的 Ollama
先执行下面的命令确认 Node.js 版本：
截图位 1：
node -v 和 npm -v 的检查结果如果版本过低，建议先升级。官方文档里最常见的安装方式如下。
1.1 Windows 安装 Node.js
1.2 macOS 安装 Node.js
1.3 Ubuntu / Debian 安装 Node.js
注意：官方安装页明确要求 Node.js 20+。如果版本不对，后面的安装、构建和启动步骤都可能直接失败。
📝 2. 安装 OpenClaw
OpenClaw 官方提供了两种路线：快速安装和手动安装。
如果你只是想先把服务跑起来，推荐直接用快速安装。它的好处不是“更高级”，而是更少踩坑。尤其是第一次安装时，省掉一堆路径和构建细节，成功率会高很多。
2.1 快速安装（推荐）
Linux / macOS
Windows PowerShell
如果 PowerShell 提示权限问题，可以先用管理员身份打开 PowerShell，再执行：
然后重新运行安装命令。
截图位 2： OpenClaw 安装脚本执行过程或安装完成后的终端界面
快速安装脚本默认会完成下面几件事：
- 检查 Node.js 和 npm 是否可用
- 下载 OpenClaw 到本地目录
- 安装依赖
- 完成构建
- 生成默认配置文件
2.2 手动安装
如果你希望自己掌控每一步，或者后面准备基于源码做定制，可以走手动安装流程：
如果你想锁定某个版本，也可以先切换版本标签：
2.3 验证安装是否成功
安装完成后，先检查 CLI 是否可用：
然后再跑一遍健康检查：
如果终端提示
openclaw: command not found，通常是 PATH 没配好。可以先执行：如果你想永久生效，再把它写进
~/.bashrc、~/.zshrc 或 ~/.profile。📝 3. 配置 OpenClaw
OpenClaw 的主配置文件通常在这里：
你可以用任何文本编辑器打开它：
或者：
3.1 一个最小可用的 OpenAI 配置示例
截图位 3：
config.yaml 编辑完成后的关键配置片段这里有几个点建议优先注意：
admin.password一定要改，不要继续用默认密码
llm.provider、api_key和model必须对应上，不然服务能启动，但不会正常回复
agent.language和timezone可以按你自己的使用习惯调整
3.2 如果你想接本地 Ollama
如果你不想把请求发到云端，也可以直接把
llm 段改成 Ollama：这种方式不需要 API Key，但前提是 Ollama 已经在本机正常运行。
3.3 配置校验
配置文件改完以后，不要急着启动，先校验一遍：
如果配置没有问题，你会看到类似
Configuration is valid. 这样的结果。截图位 4：
openclaw config validate 校验通过的终端结果这一步非常重要。YAML 只要缩进错了，或者字段名写错了，后面你看到的通常不是“哪里配错了”，而是“服务起不来”或者“模型不可达”。
📝 4. 启动 OpenClaw
配置完成后，就可以真正把服务拉起来了。
4.1 前台启动
正常情况下，你会看到类似下面的信息：
截图位 5：
openclaw start 成功启动后的终端界面4.2 后台启动
如果你不想一直占着当前终端，也可以后台运行：
停止后台服务：
查看日志：
查看状态：
4.3 打开 Web 界面
浏览器访问：
如果你把 OpenClaw 部署在远程服务器上，把
localhost 换成服务器 IP 即可，例如：登录时使用你在
config.yaml 里设置的管理员账号密码。登录完成后，你就会进入聊天界面。4.4 发第一条消息
你可以先发一句最简单的话测试：
如果配置没有问题，OpenClaw 会正常返回内容。这个时候，安装才算真正闭环，不是“服务能启动”，而是“系统能正常工作”。
截图位 6： OpenClaw Web 界面登录后首页，或首轮对话成功返回的界面
📝 5. 常见问题
5.1 openclaw 命令找不到
优先检查 PATH 是否包含
~/.openclaw/bin。这是最常见的问题之一。5.2 3000 端口被占用
如果本机已经有别的服务占用了 3000，可以直接改
config.yaml：改完记得重新执行：
5.3 服务能启动，但模型不可达
这类问题大概率集中在下面几项：
- API Key 写错了
- 模型名写错了
- 网络无法正常访问外部模型服务
- 你配置的是 Ollama，但 Ollama 服务本身没有启动
所以排查顺序也很简单：先看配置，再看网络，最后看模型服务本身。
5.4 构建阶段内存不足
如果你碰到 out-of-memory，可以先加大 Node.js 堆内存，再重新构建：
🤗 总结
- OpenClaw 官方安装要求 Node.js 20+
- 最省事的方式是直接跑官方安装脚本
- 安装完成后，重点是把
config.yaml配正确，尤其是管理员密码和 LLM 提供商
- 启动前最好先跑一次
openclaw config validate
- 启动成功后，用 Web UI 登录并发第一条消息，才算真正完成安装
- 如果你后面还要接 Slack、Telegram、Discord 或者继续装技能，可以在这个基础上继续扩展
📎 参考文章
- GitHub 仓库：https://github.com/clawdbot/clawdbot
有关 OpenClaw 安装或者使用上的问题，欢迎你在评论区留言，一起交流。
- 作者:Springli
- 链接:https://blog.5280717.xyz/article/openclaw-install-guide
- 声明:本文采用 CC BY-NC-SA 4.0 许可协议，转载请注明出处。
