1. OpenClaw 能做什么先说清楚它在解决什么问题OpenClaw 最近在本地 AI 工具圈里热度不低它不是一个只能聊天的网页前端而是一个开源的本地 AI Agent 运行框架。把它装在 Windows、Linux 或 mac 上之后你可以把某家大模型平台的 API Key 填进配置文件然后用自然语言向它下达任务它会自动拆解成一系列可执行操作在终端里跑命令、读取指定目录下的文件、批量重命名、检查端口状态、定时执行脚本甚至按预设流程操作浏览器完成页面交互。任务实际发生在你自己的机器上所以数据处理更可控调试链路更短也更适合用来做自动化实验。我见过不少人在 Windows 上装这类工具时卡住卡住的原因大多数不是项目本身有问题而是安装流程里的细节没对上。比如依赖版本不对、服务端口被占用、浏览器打开面板时提示“无法访问此页面”、没有可用的 AI Token这几类问题几乎占了安装报错的八成。这篇内容会把 OpenClaw 的安装路径完整走一遍覆盖 Windows 的典型坑、Linux 和 mac 的差异、申请免费 AI Token 的流程以及如何排查“无法访问此页面”这类报错。整条链路都按国内网络环境下能落地的方式来讲确保你能自己跑通第一台可用的本地 Agent。我推荐下面这几类人重点关注一是想做 AI Agent 实验但不想每个功能都付费的开发者二是需要让 AI 自动操作本机命令和文件的运维同学三是产品原型验证阶段需要快速把“对话 工具调用”打通的人。OpenClaw 的优势在于安装形态灵活既可以源码跑也可以容器跑不绑定特定硬件中低配置的电脑也能完成基础功能验证。如果你之前用过其他类似 Agent 工具会发现它们的能力上限往往取决于两个东西模型接口的质量以及你能不能在本地把工具链安装顺。OpenClaw 本身只是框架真正给框架注入智能的是你申请的 Token 和模型能力。所以这篇内容不只看安装也会把 Token 申请和配置这块讲透让整个链路从“装起来”到“用起来”完整闭环。2. 装之前先想清楚三件事安装方式、依赖和目录规划2.1 源码安装和容器安装怎么选OpenClaw 的部署方式本质上只有两条路线源码安装和容器安装。很多人一上来就执行安装脚本结果装到一半发现缺依赖又回头补环境浪费时间。我建议你先根据机器的系统状态选择一种方式再动手。对比项源码安装容器安装上手门槛需要熟悉命令行需要了解 Docker 基础命令环境隔离依赖本机已有运行时依赖镜像环境相对独立升级更新手动拉取新版本再装拉取新镜像即可占用资源相对更轻镜像和容器有一定额外开销适合场景Windows 本机快速体验Linux 服务器、需要稳定隔离的环境如果你只是想先在 Windows 上跑通流程源码安装更适合如果你是在 Linux 服务器上部署希望尽量不污染系统环境或者经常要换版本就更适合容器安装。两种方式不冲突同一台机器也可以并存只是端口和时间要注意区分。2.2 依赖版本怎么核对无论哪种方式你都需要确认几个基础依赖。OpenClaw 这类项目通常依赖 Node.js 或 Python 运行时具体看下载版本的说明。一般建议 Node.js 选 18 以上的 LTS 版本Python 选 3.10 以上的稳定版版本太老会出现语法不兼容版本太新则可能连带升级其他底层依赖反而引入新问题。在 Windows 上安装 Node.js 时建议勾选“添加到 PATH”和“启用原生模块编译工具”两个选项后面安装依赖时能少很多折腾。Python 则要注意安装时勾选“Add python.exe to PATH”否则终端里执行 python 命令会报“不是内部或外部命令”。这类问题虽然基础但出现频率非常高。Linux 和 mac 环境也要提前准备编译链。Linux 上一般需要 build-essential、openssl、pkg-config 这些基础包mac 上需要 Xcode Command Line Tools。没有编译链时很多 Python 包或 Node 原生模块无法从源码编译安装过程会卡在“building wheel”这一步报错也不够直观很多人因此误以为是网络问题。2.3 目录和端口规划安装目录尽量不要放在带中文、空格或特殊字符的路径下比如“C:\Users\我的文档\OpenClaw 项目”这种路径容易引起命令解析问题。建议统一放在纯英文路径下比如“C:\Tools\OpenClaw”解压后所有文件权限也更好处理。端口方面默认服务端口通常是一个固定值如果被占用服务会启动失败或起在别的端口接着就会出现“无法访问此页面”的情况。你可以在配置文件中提前改成不常用的高位端口比如 8787、18080 等。改端口的同时也要把访问地址改到对应端口避免启动成功但浏览器还是访问旧地址。3. Windows 安装通关流程从下载到启动一步步来3.1 准备目录和下载安装包我建议按下面顺序操作每一步都验证后再进入下一步。第一步在磁盘上建好目录“C:\Tools\OpenClaw”。把这个目录当作软件的主目录后续所有源码、配置、日志都放在这里排查时会更方便。第二步从项目官方渠道获取安装包。如果你是源码方式推荐用 git clone 拉取代码而不是直接下载压缩包。git clone 的好处是以后更新版本方便出问题时也能快速切回旧版本。克隆完成后进入项目目录先看 README 或其他说明文件里标记的版本要求确认之前提到的依赖版本匹配。如果你没有安装 git也可以直接下载源码压缩包但解压后要额外注意目录嵌套问题。很多压缩包解压后会出现外层多套一层同名目录命令行里容易找错路径。建议解压后手动查一眼目录结构确保项目根目录下的文件层级正确。3.2 把依赖装稳这一步是 Windows 用户最容易卡住的地方。打开终端进入项目目录后先执行依赖安装命令。常见的方式有两种如果项目基于 Node就执行npm install如果项目基于 Python就执行pip install -r requirements.txt。如果你下载的是二进制发行版通常不需要执行依赖安装直接进入下一步启动命令即可。在国内网络环境下依赖安装最常见的报错是下载超时、连接被重置、找不到源站这类。解决办法不是反复重试同一个命令而是先把包管理器源切换到国内可用镜像。npm 和 pip 都支持设置镜像源设置之后下载速度会明显提升。切换完镜像源再执行依赖安装成功率会高很多。依赖安装过程如果输出大量 warning不一定要立即处理大多数 warning 不影响运行。但如果出现“error”或“failed”字样就要停下来看。最常见的错误是某个原生依赖需要编译而本机缺少编译工具。这时回到上一章提到的依赖版本核对把 Node.js 附带的编译工具或 Python 的编译链安装好再重装一次。我习惯在依赖安装结束后做一个小验证查看关键依赖的版本号是否与项目要求一致。比如项目要求 Node.js 18 以上你执行node -v确认要求 Python 3.10 以上执行python --version确认。版本不对就不要往下走否则启动阶段会出现各种诡异报错。3.3 启动服务和访问面板依赖装好后先把必要的配置复制备份。很多项目都会提供一个示例配置模板比如.env.example或config.example.json需要你复制一份并改成实际使用的配置名然后在里面填入 Token 等信息。启动命令要以项目文档为准但大体上是三类执行npm run start、执行python main.py、执行项目的可执行文件。启动成功后终端会输出一串日志里面通常包含服务监听的地址和端口比如 “http://127.0.0.1:8787”。把那个地址复制到浏览器打开就能看到 Web 面板或对话入口。如果终端没有任何报错但浏览器一直转圈或提示“无法访问此页面”先别着急改配置。确认三件事第一服务进程是否还在第二终端显示的端口是多少第三浏览器访问的地址是否和终端一致。最常见的问题是服务明明已经监听在 127.0.0.1:8787浏览器却打开了 8080 或 localhost:3000自然访问不到。3.4 登录态和防火墙的提前规避Windows 安装还有一个隐性问题就是防火墙和安全软件会把本机服务端口拦截掉。当你启动 OpenClaw 后系统可能弹出一个“是否允许应用通过防火墙”的窗口如果你点了取消服务本身已经在运行但外部访问会被挡住浏览器也会表现成“无法访问此页面”。处理方法是启动服务之前先把软件目录加入信任列表或者在第一次启动弹窗时选择允许。如果你已经错过弹窗可以在系统防火墙的放行列表里手动添加 OpenClaw 对应的端口再把服务重启一遍。这一步在 Linux 服务器上也类似需要开放对应端口但 Windows 上更容易被忽略。4. Linux 和 macOS 安装差别没那么大但这几个坑必须单独说4.1 Linux 端依赖与权限Linux 上安装 OpenClaw 的流程与 Windows 大同小异但有两点要特别注意。第一是权限不要用 root 用户运行服务和安装依赖因为很多项目启动时会检测进程权限一旦遇到权限限制就直接退出。建议创建一个普通用户来部署目录权限也要调整好。第二是系统依赖包。Ubuntu 和 Debian 系的系统安装前先执行系统包更新然后安装基本编译工具。CentOS 和 OpenEuler 这类则要注意包管理器的差异依赖名可能不一样缺少时会出现“找不到头文件”或“undefined reference”一类的编译报错。遇到这种情况别硬着头皮看日志直接去安装对应的开发包。Linux 上我更喜欢用容器安装原因是不需要自己折腾编译链只要 Docker 能正常工作拉取镜像后直接启动环境问题会少很多。如果你选择容器方式建议在项目目录下准备好 compose 文件再执行启动命令。启动过程中如果卡在拉取镜像大概率是网络波动或磁盘剩余空间不够先查磁盘再考虑加国内镜像加速器不要反复硬试。4.2 macOS 端签名与路径问题macOS 安装和 Linux 比较像但有几个特有动作。首先安装 Xcode Command Line Tools你可以在终端输入xcode-select --install系统会弹出安装界面。没有这个基础工具很多 Python 和 Node 原生模块都编不过去。其次是软件签名问题。如果你下载的是编译好的二进制包首次运行时 macOS 可能提示“无法打开因为来自身份不明的开发者”。解决方法是右键点击应用选择“打开”然后在弹出窗口里确认或者在终端执行解除隔离属性再重新启动。这里不建议直接关闭系统保护风险太高。macOS 上还要留意环境变量。用zsh作为默认 shell 的环境下编辑配置文件时容易被忽略Token 填进配置文件后却没有 source 生效启动后一直提示鉴权失败。配置完成后记得重新打开终端或执行环境刷新命令让配置真正加载。4.3 三种系统安装后的验证三连不管你用哪种系统启动完成之后都建议做三个快速验证避免表面启动、实际不可用。第一确认端口正在被监听。Windows 上执行netstat -ano | findstr 8787Linux 和 mac 上执行ss -lntp | grep 8787能看到监听记录才能说明服务真正起来了。第二访问对应的本地地址。浏览器打开终端里提示的地址看到页面或返回 JSON 就算通过。第三用一个最小化提示词测试 Agent 是否真正连通。比如让它执行一个最简单的命令比如打印当前目录或生成一句话。这一步会触发 Token 调用如果 Token 有问题在这一步就会暴露出来而不是等到复杂任务无人响应。5. 申请免费 AI Token 的完整链路5.1 找对申请入口很多人把安装问题解决后卡在了“没有可用 Token”这一步。目前主流的大模型开放平台大多提供免费额度但入口藏在开发者后台里不在普通用户界面。你需要在平台注册一个账号完成手机或邮箱验证然后进入开发者或控制台页面找到“API Keys”或“访问令牌”这类入口。如果你不注册或者没有完成实名认证通常看不到创建 Key 的页面。部分平台还支持直接通过主页的开发者文档进入申请页所以我一般会建议先去找到官方文档再顺着文档里的“接入流程”或“快速开始”去创建密钥。文档里定义的创建方式往往就是平台推荐的方式。5.2 创建 Key 并回填配置创建 Key 的过程不复杂但有一个关键细节Key 只会在创建时完整显示一次之后你再回控制台只能看到掩码无法复制完整内容。所以创建成功后要立即复制并保存到本地临时文档再回 OpenClaw 配置文件去填。配置文件里通常有一行类似API_KEY的设置把复制的 Key 原样粘贴进去不要加多余空格也不要用粘贴时隐式带入的换行。很多鉴权失败的错误最终查下来就是 Key 多了一个空格或者少一位字符。配置完成后重启服务。如果项目支持配置热加载可能不用重启但为了稳妥我每次都会重启一次重启后再测试问题。启动日志里如果出现“invalid key”“unauthorized”“401”之类的字样基本就是 Key 复制不完整、权限范围不对或免费额度已用完。5.3 免费 Token 有哪些“隐藏门槛”申请到免费 Token 只是第一步实际使用时还有几个门槛。第一限速。免费档通常有每分钟请求数和每日总调用量限制对于 OpenClaw 这种本地 Agent一个任务可能连续触发多次模型调用很容易触发限速。表现就是第一次回答正常第二次开始等待很久然后报超时。第二模型选择限制。免费额度可能只开放部分模型复杂的推理任务或长上下文任务会被拒。建议先用轻量模型把整体链路跑通再在配置里切换更强大的模型。第三数据边界。免费 Token 产生的请求会在对应平台处理如果你要做的是敏感数据实验不要把真实文件内容喂给在线模型。这也是我支持本地 Agent 的原因框架可以在本机运行但模型调用上游会产生数据流转这个边界要自己清楚。第四有效期。很多免费 Key 不是长期有效的到期后服务会突然不可用。遇到“突然不能用了”的情况先去看 Key 状态不要反复重启服务或重装系统。6. 安装报错排查实录把高概率问题一次性列清楚6.1 页面提示“无法访问此页面”的第一时间检查顺序“无法访问此页面”这个提示在安装 OpenClaw 的场景里九成是服务没起来或地址不对。打开浏览器看到这句提示时不要急着重新安装按下面顺序排查。先看终端窗口。如果终端里有报错解决报错如果终端没有报错再往回滚动日志找到实际监听的端口。终端如果是关闭状态或卡死了服务就已经停了需要重新启动。再检查端口监听。Windows 上执行netstat -ano | findstr 8787把 8787 换成你配置的端口。有输出说明服务在监听没输出说明服务没起来。Linux 和 mac 用ss -lntp | grep 8787代替。然后确认浏览器访问的地址。如果你用localhost:8787访问失败可以试试127.0.0.1:8787两者大部分时候等同但某些系统对 localhost 的解析会走 IPv6导致连接失败。如果你在配置里把服务绑定到了0.0.0.0地址访问方式也要对应调整。最后再看防火墙和安全软件。Windows 上最容易拦截本机服务端口macOS 也会弹出网络访问授权Linux 则依赖防火墙策略。如果前面几步都没问题把端口放行后重启服务一般就能解决。6.2 启动和配置阶段的高频问题清单问题现象常见原因处理思路依赖安装时下载超时包管理器源访问慢切换国内镜像源后重试启动时报端口被占用默认端口已被其他程序使用检查监听进程换一个高位端口页面能打开但对话无响应Token 未配置或配置错误检查 Key 是否完整确认服务重启执行任务时提示鉴权失败Key 过期或权限不足去平台后台查看 Key 状态容器运行时一直拉取镜像失败网络波动或磁盘空间不足先释放磁盘空间再配置镜像加速mac 上提示无法打开二进制签名未信任右键打开或执行解除隔离属性启动后马上退出无提示依赖版本不兼容核对运行时版本查看完整日志这个清单基本覆盖了我实际安装中遇到过的问题。你也可以把这当做一个快速速查表遇到问题时先对照现象再定位原因。很多时候不是项目不行而是细节没对齐。6.3 容易被忽略的几个细节再分享几个容易被忽略但很影响体验的细节。第一浏览器要尽量用无痕模式访问本地面板避免浏览器插件或本地缓存干扰。我之前遇到过面板打不开换一个无痕窗口立刻正常排查了很久才发现是扩展程序把本地请求拦截了。第二配置文件里的注释符号要认真看。很多配置文件使用#开头表示注释如果你在 Key 前面误加了#等于把整行注释掉服务会静默跳过这个配置表现得就像没有设置 Token 一样。第三长期不用之后再次启动要重新确认 Key 是否还有效。免费 Token 的时效通常不会写在配置里只有看过期时间才知道。我习惯把申请时间和过期时间记录到本地备忘避免下次用的时候一脸懵。第四如果你在本机跑过多个类似项目要留意环境变量和配置文件可能互相干扰。两个项目使用同一个环境变量名后启动的会覆盖前面的设置导致行为不可预期。建议每个项目单独用一个终端窗口或者用容器隔离减少这类问题的发生。安装这类工具最忌讳的就是一上来就闷头重装系统或反复拉取新版。多数问题都能通过日志和端口状态判断出来找到根因往往只需要几分钟。按照上面的步骤走下来OpenClaw 在你机器上跑起来就是一个水到渠成的事情。