1. OpenClaw 为什么要做成一键部署1.1 OpenClaw 到底是什么OpenClaw 这个东西说白了就是一个开源的 AI 智能体编排工具也是我最近折腾得最多的一键部署工具。圈子里常把它调侃叫“龙虾”——Claw 在英文里就是螯爪的意思社区头像也经常是只举着钳子的小龙虾。它能干的事不少通过自然语言指令调度本地工具、操作文件、跑命令、接各种模型本质上是把“AI 助手”从聊天框里解放出来让它能真正动手干活而不是只动嘴。2.0 版本之后它的定位更清晰了就是一个以命令行和工作区为核心的 agent 运行时CLI、IM、桌面端都能作为入口去指挥它干活。很多人拿它和 Codex 这类工具对比就我实际体验来说Codex 更偏向 IDE 内的编码补全和代码任务而 OpenClaw 的长处在于“工具编排”——它可以跨文件、跨命令、跨应用去执行任务而且给了用户很多控制权比如哪些命令要审批、哪些模型跑什么任务、接哪个 IM 平台都可以自己配。换句话说Codex 是一个很会写代码的助手OpenClaw 更像一个能调度各种工具帮你办事的管家。1.2 手动部署的痛点在哪但 OpenClaw 的问题也很典型依赖链条长。装它不只是装一个二进制就完事涉及运行时环境、CLI 工具、模型服务商配置、工作区初始化、审批策略文件……每一步都有可能出幺蛾子。我在 Windows 11 和 Ubuntu 22.04 上都装过也帮朋友远程排查过十几台机器发现 90% 的安装失败都不是 OpenClaw 本身的问题而是前置环境不一致导致的。有人 PowerShell 版本太老有人 PATH 没配有人把模型 API 地址填错了位置还有人根本不知道装完还要初始化 workspace。一键部署工具解决的正是这个痛点把环境探测、依赖安装、目录初始化、路径配置这些脏活累活打包成一个脚本你只要执行一条命令剩下的交给脚本去判断。这篇文章我就以自己实际跑通的流程为主线把 Windows 和 Linux 两套环境的部署、初始化、常见报错全部串一遍内容适合第一次接触 OpenClaw 的新手也适合已经装上但被配置折磨过的老手。接着说一下我对“一键式部署”这个说法的理解真正好用的部署脚本不是帮你把命令敲完就结束而是要做到三点——可重复执行、可指定目录、可回滚卸载。后面我会针对这三点逐个展开。尤其是“可重复执行”这一点很多人没意识到脚本如果中途失败一次就留下半截环境第二次跑必定出问题所以判断一个部署工具好不好用先看它的幂等性。2. 部署之前先把这些环境问题想清楚2.1 Windows 11 的前置依赖先看 Windows 11。很多人一上来就开个 PowerShell 窗口执行安装命令结果报一堆错原因多半是前置条件没满足。以我排障的经验Windows 上至少需要确认三件事第一PowerShell 版本。OpenClaw 的官方安装脚本对 PowerShell 5.1 和 7.x 都兼容但 5.1 在 Windows 11 上是自带的老版本有些语法和网络请求行为跟 7.x 不一样。如果你要装的是最新版建议直接用 PowerShell 7省心得多。检查版本用$PSVersionTable.PSVersion如果显示 5.1可以去装个 7.x或者继续用 5.1 跑脚本通常也能跑只是部分输出格式不一样遇到奇怪的格式化问题别太惊讶。第二执行策略。Windows 默认的 PowerShell 执行策略是 Restricted会阻止脚本运行。安装 OpenClaw 之前要么用管理员身份打开 PowerShell 执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser要么在运行安装命令时用-ExecutionPolicy Bypass的方式临时绕过。我个人的建议是修改 CurrentUser 级别的策略而不是改整个机器的 LocalMachine避免影响其他脚本的安全策略。这个操作本质上就是给 PowerShell 发一张“许可证”范围越小越安全。第三管理员权限。OpenClaw 默认装在用户目录下~/.openclaw理论上不需要管理员权限。但如果你在安装时指定了全局目录或者系统某些目录有写入限制就需要注意权限问题了。我遇到过有人用管理员 PowerShell 装完后普通 PowerShell 里找不到命令原因就是安装脚本写入的 PATH 是管理员级别的普通用户环境看不到。这个问题非常隐蔽因为它不会报错只是找不到命令。2.2 Ubuntu 22.04 与 CUDA 的搭配Linux 环境下我测试最多的是 Ubuntu 22.04。纯粹跑 OpenClaw 本身不需要 CUDA但如果你打算接 NVIDIA NIM 这类本地推理服务或者用 GPU 跑本地模型那 CUDA 环境的检查就跑不掉了。这里有个很常见的误区以为装了显卡驱动就等于有 CUDA 工具链。实际上驱动只是底层的NVIDIA NIM 或很多本地模型推理框架还需要 CUDA Toolkit 或者容器运行时NVIDIA Container Toolkit。如果你是用 Docker 方式跑 NIM记得先装好nvidia-container-toolkit并在启动容器时加--gpus all。如果你是直接在宿主机上跑 Python 推理服务那就要确认nvidia-smi输出的 CUDA Version 和你要装的推理框架要求的版本对得上。我在 Ubuntu 22.04 上踩过的一个坑是系统自带驱动是开源版 nouveau装完nvidia-smi根本不存在OpenClaw 能跑但一接 NIM 就报错。解决方案就是先禁掉 nouveau再装官方驱动重启后确认nvidia-smi正常再往下走。这个步骤很机械但是不做后面全是坑。如果你只是用云端模型完全不用管 CUDA别被网上的教程吓到。2.3 关于安装目录的一个建议很多人会问安装时能不能指定目录。答案是可以而且我强烈建议你指定。特别是 Windows 下如果你用系统默认的 PowerShell 安装方式脚本往往会装到用户目录的.openclaw下这个目录之后会存放 workspace、配置文件、日志日积月累体积不小。如果你 C 盘空间紧张一定要在一开始就指定安装位置。我平时习惯在 D 盘建一个D:\Tools\OpenClaw作为安装目录工作区单独指定到D:\Workspaces\OpenClaw这样系统重装时数据和程序分离备份还原都很方便。具体怎么指定不同版本的安装脚本参数不一样有的用-DestinationPath有的用--dir装之前先跑一下脚本的帮助信息别想当然。总而言之先规划好目录再执行安装这是我一再强调的顺序。3. 一键部署脚本的完整执行过程3.1 Windows 下的 PowerShell 安装Windows 上安装 OpenClaw官方推荐的是 PowerShell 方式社区里最常用的一条命令和很多其他工具一样是“下载远程脚本并直接执行”的模式irm https://get.openclaw.cloud/install.ps1 | iexirm是Invoke-RestMethod的别名iex是Invoke-Expression的别名整条命令的意思就是把远程脚本下载下来直接在当前会话里执行。这种方式对用户最友好但也有安全隐患——你等于把机器的执行权交给了一段远程脚本。所以我建议执行前先手动把脚本下载到本地看一下关键步骤确认没问题再跑Invoke-WebRequest -Uri https://get.openclaw.cloud/install.ps1 -OutFile install-openclaw.ps1 # 检查脚本内容确认安装路径、写入的注册表项、环境变量没有可疑操作 .\install-openclaw.ps1安装脚本跑起来之后通常会自动完成几件事下载对应平台的二进制、解压到目标目录、把可执行文件路径写入用户 PATH、创建~/.openclaw目录骨架。整个过程中你只需要注意输出的提示信息看有没有出现WARNING或ERROR级别的内容。如果中途断了重跑一次脚本一般是安全的这类脚本大多做了幂等处理重复执行不会重复写入 PATH。如果你想指定安装目录以社区版脚本为例一般支持这样的写法.\install-openclaw.ps1 -DestinationPath D:\Tools\OpenClaw装完之后新开的 PowerShell 窗口里输入openclaw --version如果能输出版本号说明安装成功。这里注意必须在新开的窗口里执行因为 PATH 环境变量的更改不会自动传递到已经打开的会话。这个坑我已经提醒过无数次了但每次还是会有人踩。3.2 Linux 下的安装方式Linux 下的安装思路和 Windows 一致只是换成了 shell 脚本。Ubuntu 22.04 上常见的方式是curl -fsSL https://get.openclaw.cloud/install.sh | bash-fsSL四个参数分别代表失败时不输出内容-f、跟随重定向-L、静默模式-s、显示错误-S组合起来就是“出错要报、重定向要跟、正常别刷屏”。如果你在内网环境或者下载不稳定curl管道执行可能会失败我建议先手动下载脚本curl -fsSL -o install-openclaw.sh https://get.openclaw.cloud/install.sh bash install-openclaw.sh --dir /opt/openclaw把安装目录指定到/opt/openclaw这种系统级目录时记得用sudo否则没有写权限。装完之后OpenClaw 的可执行文件可能会被放到/usr/local/bin或者需要你自己加入 PATH。验证命令同样是openclaw --version。这里补充一点Linux 下的 PATH 写入位置因 shell 而异bash 用户看~/.bashrczsh 用户看~/.zshrc如果脚本自动写入失败手动检查这两个文件。3.3 安装完成后的三分钟验证很多人装完输入openclaw --version看到版本号就以为万事大吉其实这时候只是“装上了”离“能用”还差得远。我建议你按下面三步做一次快速验证第一步检查目录结构。执行openclaw doctor或者手动查看~/.openclaw下是否有workspace、config、logs等子目录。如果缺目录后续启动多半会报错。这步就是给房子检查地基地基歪了后面装修全是白搭。第二步检查配置文件是否能正常生成。运行一次openclaw configure看它能否正确创建默认配置而不只是打印一堆帮助信息。如果这一步能走通说明 CLI 到配置文件的链路没问题。第三步跑一条最简单的指令。比如openclaw run 列出当前目录下的文件看它是否能正常调起模型并返回结果。如果这一步通了说明从 CLI 到模型服务的整条链路都是通的后面再折腾 Skill、飞书接入才是有意义的。很多人跳过验证直接配 Skill结果模型都还没接通Skill 自然跑不起来到时候又要回头查浪费的时间比省下的多得多。4. 首次启动后的初始化配置4.1 workspace 目录与 exec-approvals 审批机制OpenClaw 的设计理念是AI 可以执行命令但关键操作需要经过你的审批。这套机制落地就是exec-approvals.json文件。你第一次运行 OpenClaw 时它会在配置目录下生成这个文件里面按命令模式列出了哪些命令需要审批、哪些可以放行。在 Linux 下路径是/root/.openclaw/exec-approvals.jsonroot 用户或~/.openclaw/exec-approvals.jsonWindows 下则是C:\Users\用户名\.openclaw\exec-approvals.json。注意 Windows 下路径里的用户名如果你是从别的机器迁移过来的配置很可能因为用户名不一致导致 OpenClaw 找不到原来的配置。理解这个文件的核心在于“审批粒度”。默认情况下像ls、cat这类只读命令可能被列为自动放行而rm、curl上传、git push这类有副作用的命令会要求确认。这个设计相当于家长给零花钱——小额随便花大额要报备。我自己一般会把高频且安全的命令比如git status、pip list加入免审批列表把rm -rf、dd这类高危命令保持强制审批。审批规则不是越多越好太严会频繁打断 AI 的干活节奏太松又容易出事需要自己在使用中不断调优。4.2 模型接入OpenAI 兼容接口、Ollama、NVIDIA NIMOpenClaw 本身不带模型它是个“调度大脑”真正的推理能力来自你接入的模型服务。配置模型是初始化中最核心的一步常见的三种接法我都试过第一种接 OpenAI 兼容接口。OpenClaw 支持base_urlapi_keymodel三段式配置。如果你用官方接口base_url 填官方地址api_key 填你自己的密钥。如果你用的是第三方兼容服务base_url 要换成对方提供的地址。这里有个很多新手会犯的错base_url填到最后一级路由还是二级路由搞不清楚导致 404。一般来说OpenAI 兼容服务要求的 base_url 是到/v1这一级模型名称则要填服务商实际支持的模型 ID这两个字段一个填错请求就出问题。第二种接本地 Ollama。如果你不想把数据发到云端Ollama 是个很好的选择。先在本地把模型拉下来比如ollama pull qwen2.5:7b然后在 OpenClaw 的模型配置里选择 Ollama Provider填http://localhost:11434作为接口地址模型名填你拉的模型标签。要注意的是本地小模型的推理能力和云端大模型差距不小复杂任务容易“翻车”所以我通常建议本地模型干点轻活比如文件整理、命令执行重型推理还是交给云端。第三种接 NVIDIA NIM。NIM 是 NVIDIA 的推理微服务方案适合跑 Llama 3 这类模型对 GPU 要求高。配置方式和 OpenAI 兼容接口类似填 NIM 提供的 endpoint 和对应的模型名比如meta/llama3-8b-instruct这类。NIM 的坑主要在环境GPU 要支持、驱动要新版、端口要通这些我在 2.2 小节已经讲过这里不再重复。一句话总结先确认环境再配模型顺序不能反。4.3 自定义 API 网关该怎么填热搜词里有“OpenClaw 自定义中转站”很多人以为这是什么特殊功能其实就是在模型配置里指向一个自定义的 API 网关地址。很多团队会自建 API 网关来统一管理多家模型服务的密钥、限流和日志OpenClaw 接入这种网关的方式特别简单model: provider: openai base_url: https://your-gateway.example.com/v1 api_key: sk-your-gateway-key model: gpt-4o-mini只要你的网关兼容 OpenAI 的/v1/chat/completions协议OpenClaw 就能直接对接。需要注意的只有两点一是确认网关的协议兼容性有些网关虽然宣传支持 OpenAI 格式但返回结构有细微差别导致 OpenClaw 解析失败二是确认网关的鉴权方式有些网关用的是自定义 HeaderOpenClaw 不一定原生支持可能需要通过配置文件里的headers字段手动加。配好后先用一条最简单的对话指令测通再跑复杂任务可以节省大量排障时间。5. 高频报错与排查实录5.1 “无法将 openclaw 项识别为 cmdlet”的根源这是 Windows 新手最常遇见的报错英文原文大概是“openclaw : 无法将‘openclaw’项识别为 cmdlet、函数、脚本文件或可运行程序的名称”。说白了就是系统在 PATH 环境变量里找不到 openclaw 这个可执行文件。排查链路我建议按三步走第一步确认安装是否真的成功。去你指定的安装目录里找 openclaw.exe找不到就直接重装。第二步查看 PATH 是否包含安装目录。执行echo $env:PATH看输出里有没有对应路径。第三步如果 PATH 没有说明安装脚本写入环境变量那步失败了手动把路径加进去即可。打开“系统属性 - 环境变量”在用户变量里找到 Path新建一条填入 openclaw 可执行文件所在目录然后保存。之后重新打开PowerShell 再试。这步操作虽然基础但我碰到的十个人里有八个人是栽在“改完环境变量没重开终端”上。改完环境变量不重开终端就像换了锁但还用旧钥匙开门它当然打不开。5.2 legacy exec approvals 提示的处理装完新版本第一次启动有时会遇到类似提示legacy exec approvals exist at /root/.openclaw/exec-approvals.json. run ope... (后续命令被截断)这个提示的意思是检测到你配置目录下有一个旧版本的 exec-approvals.json格式跟新版本不兼容需要你手动运行某条迁移命令。我当时遇到时也愣了一下因为提示信息被终端宽度截断了看不到完整命令。解决方法是打开终端手动执行迁移命令不同版本命令不同一般是openclaw migrate或openclaw approvals migrate。跑完后它会自动把旧文件备份成exec-approvals.json.bak再生成新格式的文件。如果你不想迁移也可以手动删除旧文件重新生成但那样你之前配置的免审批规则就全没了我建议还是走迁移流程。这里也提醒一句遇到被截断的提示先把终端窗口拉宽或者把输出重定向到文件里别急着猜命令猜错一次就是多一条报错。5.3 高频报错速查表把我在部署过程中见过的问题整理成一张表方便你对症下药现象大概率原因快速处理openclaw 不是内部或外部命令PATH 未生效或安装不完整检查安装目录、手动添加 PATH、重开终端安装脚本下载超时网络不稳定或源站响应慢手动下载脚本后本地执行启动报 exec-approvals 相关错误旧配置格式与新版不兼容执行迁移命令不要直接删文件接 NIM 时提示 GPU 不可用驱动或容器工具链缺失先跑 nvidia-smi确认驱动和 toolkitbase_url 请求 404地址层级填错确认到 /v1 一级检查服务商文档飞书事件订阅收不到回调公网回调地址不可达改用长连接模式或让运维协助配置可达的回调地址5.4 卸载、关闭与重装的完整路径热词里有“关闭 openclaw”这个搜索我顺手一起说了。如果你指的是停止正在运行的后台服务或守护进程一般执行openclaw stop或openclaw service stop就行如果只是退出当前交互会话CtrlC直接中断即可不需要额外操作。至于彻底卸载Windows 下建议这样做# 如果有自带的卸载命令优先执行 openclaw uninstall # 手动清理目录 Remove-Item -Recurse -Force $env:USERPROFILE\.openclaw Remove-Item -Recurse -Force D:\Tools\OpenClaw # 清理 PATH 环境变量务必手动编辑删掉相关路径Linux 下同理用rm -rf ~/.openclaw /opt/openclaw之类的命令清理目录再检查/etc/profile、~/.bashrc或~/.zshrc里有没有写入 PATH。这里要提醒一句卸载前记得备份~/.openclaw下的配置和 workspace我见过有人卸载重装后才发现自己之前的工作流配置全没了的那感觉跟硬盘格式化差不多。卸载不是删文件是把你搭好的厨房拆了拆之前至少把菜谱抄下来。6. 从能用到好用Skill、飞书与 Cau Computer6.1 ClawHub 与 OpenClaw 的关系以及如何装 Skill很多人分不清 ClawHub 和 OpenClaw 的关系。我的理解是OpenClaw 是运行框架本身ClawHub 是它的插件/技能市场类似 VS Code 和扩展市场的关系。Skill 可以理解为给 OpenClaw 预装的一套“操作手册”比如你装一个“PDF 处理”Skill它就学会了调用相关工具来解析、合并、拆分 PDF。安装 Skill 的命令一般长这样openclaw skills install pdf-toolkit安装完后Skill 通常会在配置目录的skills/下生成一个子目录里面有描述文件、脚本和清单。你可以手动编辑描述文件来调整 Skill 的行为改完不需要重新安装重启 OpenClaw 就能生效。所以 Skill 这东西本质是一组“教 AI 怎么干活”的本地资源和模型放在哪个平台上没有直接关系。6.2 本地 Ollama 环境下 Skill 的适配思路热词里有人问“OpenClaw 使用本地 Ollama 如何安装 Skill”这个问题其实分两层。第一层是 Skill 本身跟模型无关装就能用因为 Skill 的核心是工具调用逻辑和提示词模板第二层是 Skill 描述里如果引用了特定模型能力比如图像识别、代码推理本地 Ollama 模型未必扛得住。所以我的适配思路是先装 Skill再逐个试。每个 Skill 装完后用一条典型指令测一下比如装了“代码审查”Skill就真的丢一段有 bug 的代码让它跑一遍。如果发现 Skill 的反应明显变笨要么换更大的本地模型要么考虑把该 Skill 对应的任务切到云端模型上。没必要为了“全本地”而牺牲实际效果工具是拿来用的不是拿来凑理念的。6.3 飞书接入与“呼叫口令”把 OpenClaw 接到飞书上等于给 AI 助手开了个 IM 入口你可以在飞书群里直接给它发消息指挥它干活。“呼叫口令”这个词听着玄乎其实就是你在配置里设定的一个触发词比如“小蟹小蟹”或者“龙虾龙虾”群里发这句口令再加指令OpenClaw 才会响应避免它把群里所有人的闲聊都当任务来处理。这个设计的价值只有你真的在多人群里用它干活时才能体会——不然光是区分“这句话是给 AI 的”还是“大家随便聊的”就够你头疼了。飞书接入的大致流程是先去飞书开放平台创建一个应用拿到 App ID 和 App Secret然后在 OpenClaw 的配置里填上这些凭据再配置事件订阅的地址或长连接。飞书这边的事件订阅回调对公网可达性有要求如果你没有公网 IP可以试试长连接模式让 OpenClaw 主动连飞书而不是等飞书回调进来。这一步是很多人在内网环境下卡住的地方我在 5.3 的速查表里也提到了。6.4 Cau Computer 的设置要点Cau Computer 这个功能说白了就是让 OpenClaw 能操控你的电脑界面——移动鼠标、点击按钮、输入文字像人一样操作 GUI 应用。它的底层依赖屏幕截图、坐标映射和动作执行三个环节。设置时的要点有三个第一权限要给足。Windows 下需要允许脚本模拟键鼠操作否则动作会被系统拦截。第二屏幕分辨率变化会直接影响坐标映射如果你经常外接显示器建议在操作前固定分辨率否则分辨率一变AI 点到的位置就全偏了。第三敏感区域的保护。我建议把涉及密码、支付、隐私信息的区域加入黑名单防止 AI 误操作。这个功能很强大但也属于“能力越大责任越大”的类型配置时保守一点没坏处。7. 关于部署这件事最后再唠叨几句7.1 部署阶段最容易忽略的三件事第一能用官方脚本就用官方脚本不要自己手动去下载二进制、复制目录、配路径。手动安装虽然看起来“可控”但 OpenClaw 的目录结构、权限要求、环境变量设置有一套自己的约定手动操作漏掉任何一环后面排查的成本都远超省下来的那几分钟。我自己早期就犯过这个毛病总觉得脚本干的事自己都能干直到有一次漏配了环境变量排查了一个下午。第二日志是你最好的排障工具。OpenClaw 在~/.openclaw/logs下会维护运行日志任何诡异问题先打开日志找对应的报错堆栈比在群里问人更高效。我遇到过好几个“装不上”的问题最后都是靠自己翻日志定位到的——比如某次其实是一个依赖包版本冲突日志里写得很清楚只是我不愿意看而已。先看日志再提问这是排障的基本修养。第三配置要版本化。~/.openclaw下的配置文件我用 Git 管起来了改之前先提交一版改坏了随时回滚。这个习惯让我在折腾 Skill 和模型参数时非常从容反正改错了可以回退。这就像写文章之前先存个草稿后面大改不心疼。7.2 认准官方信息源别被过时教程带偏网上有人搜“腾讯 openclaw 官网”我查了一下OpenClaw 本质是个社区开源项目部署和使用都以官方仓库和文档为准。搜索引擎里叫“OpenClaw”的东西不少有些是第三方教程站点内容参差不齐甚至拿旧版本的命令来教人照着做很容易翻车。判断教程是否过时的一个小技巧看它给的命令是openclaw开头还是claw开头旧教程里后者居多新版本统一用前者。另外建议多关注 2.0 之后的更新日志OpenClaw 迭代速度很快每个版本都可能调整配置文件格式或命令参数官方文档的更新速度通常是最快的。你在网上搜索“openclaw 安装教程”时可以拿搜索结果当参考但最终以官方 README 和文档为准。7.3 我给新手的部署路线图如果你今天刚决定要装 OpenClaw我的建议是这样一条路线先在 Windows 或 Ubuntu 上任选一个熟悉的平台用官方一键脚本装好跑通 3.3 的三分钟验证然后把模型接上优先用 OpenAI 兼容接口或者 Ollama先别碰 NIM因为 GPU 环境本来就是个分水岭最后再考虑 Skill 和飞书接入这些都是锦上添花的东西没必要在第一步就全部铺开。这个顺序是我自己在多台机器上验证过的虽然不是最快但每一步都有明确的验证节点不会让你在黑暗中乱撞。OpenClaw 这套工具部署只是第一步真正玩起来之后Skill 组合、模型路由、审批策略调整才是真正费心思的地方。这篇就先写到这后面如果有时间我再单独写一篇关于如何编排 Skill 和自定义审批规则的文章。
