最近后台一直有人在问同一类问题openclaw 到底怎么装Windows 能不能跑安卓手机有没有办法折腾不想写代码行不行。说实话openclaw 这类框架的官方文档写得并不差但零基础的读者真正缺的不是某个参数而是从零到一怎么把整条链路捋顺。我前后踩了几十个坑把安装、配置、跑通任务、拆解常见问题这整套流程重新整理了一遍这篇东西就是给“零基础”这三个字准备的实操记录。这篇文章既是一份部署手册也是一份避坑笔记。它解决的核心问题是让你在最短时间内把一个能用的 openclaw 环境搭起来并跑通一个实际任务。不管你是想在 Windows 笔记本上做自动化脚本想在 Ubuntu 服务器上挂一个常驻智能体还是想用 Termux 在手机上折腾下面的内容都会覆盖到。如果你已经在 GitHub 上刷到过这个项目但一直没动手或者动手到一半被依赖错误劝退这篇文章就是给你写的。1. openclaw 到底解决什么问题部署前先想清楚1.1 一句话讲清楚它是什么openclaw 在我的理解里是一个偏“实操型”的 AI 智能体框架核心目标是把大语言模型的能力对接到真实环境里让模型调用你的本地工具、读写文件、执行脚本、操作浏览器、调度外部接口而不是只停留在对话框里聊天。你可以把它理解成一个“给大模型装上手脚”的中间层模型负责理解和决策openclaw 负责把决策变成真实的系统操作。这和单纯部署一个大模型完全是两码事。网上很多人一搜“openclaw 部署”以为跟 ollama 部署一样装个模型然后调 API 就结束了。实际上 openclaw 更像一个工作台模型只是它的“大脑”它还需要一堆“器官”——文件访问权限、命令执行环境、API 密钥、工具链——才能真的干起活来。这也是为什么部署它比部署一个纯模型要繁琐一些因为你要配置的维度更多。零基础部署最容易栽跟头的地方恰恰不是模型本身而是环境匹配、依赖冲突和权限设计这三件事。如果开篇就能把这三件事的优先级看清后面会顺利很多。1.2 适合谁用不适合谁用先泼一盆冷水openclaw 不是拿来“即装即用”的傻瓜软件。它适合下面这些人群有一定命令行基础至少知道cd、pip install、git clone这些命令是干嘛的。想用大模型来自动化日常重复工作的人比如定时抓取网页信息、批量处理文件、管理本地知识库。需要把大模型接到自己业务系统里的开发者比如电商场景的价格监控、客服话术生成、订单归类。玩机器人仿真、希望用自然语言控制 Gazebo 里虚拟机器人的 ROS2 玩家。不适合谁呢完全没碰过终端、遇到报错就慌、不愿意读英文文档的人建议先补一补基础再回来。否则就算你把部署过程硬啃下来后面写 skill、调参数的时候大概率还是会被卡住。我的建议是第一次部署时把目标缩小到“启动成功 跑通一个 5 分钟能完成的简单任务”就算胜利。不要一上来就想把电商助手、ROS2 控制、手机端、云端全打通那是进阶玩法不是新手该干的事。1.3 生态观察那些“类 openclaw”项目到底什么关系搜索热词里有一类提问很典型workbuddy 这种是不是参考了 openclaw 才搞出来的时间对得上吗这个问题我专门留意过。从开源时间线看openclaw 公开之后确实出现了一批形态相近的智能体框架比如 headline 提到过的 workbuddy、clawdbot、agno 等它们都走“模型 工具调用 自动化执行”这个思路。我的判断是同一赛道的项目往往互相启发说 workbuddy 这类“参考了 openclaw”不算冤枉但也不能把所有相似项目都算成 openclaw 的复制品。很多团队本来就在做 Agent 框架openclaw 的火爆更多是让市场确认了“模型操作真实环境”这条路是通的属于一种方向性的推动。如果你只是用 openclaw 的用户而不是国产框架开发者这个问题的现实意义不大搞明白怎么部署和扩展才是重点。2. 部署前的硬性准备和方案选型别急着敲命令2.1 三种部署环境怎么选Windows / Linux / 安卓 Termux很多人一上来就问“openclaw 怎么安装”但没想清楚自己要在什么环境里跑。部署环境直接决定了后续的依赖包、系统服务和权限配置方式这个选择做错了后面全是坑。Windows最适合新手入门。图形界面操作直观Windows Companion 这类配套组件能帮你把桌面操作能力暴露给框架而且很多人在 Windows 上装过 Python、Git心理门槛低。缺点是路径问题多比如中文用户名、带空格的目录名都可能让程序找不到配置。LinuxUbuntu / CentOS适合长期稳定运行。没有桌面环境占用资源systemd 可以做成开机自启配合 screen 或 tmux 可以挂后台。缺点是命令行的要求高一点出了问题排查起来没那么直观。安卓 Termux适合折腾党。手机上装一个 Termux 就能跑但受限于 ARM 性能和内存对大模型推理极不友好一般只用来做客户端连接远程 API 或局域网内的本地模型服务。我的建议很明确第一台机器选 Windows 或 Ubuntu不要拿手机做第一次试验。手机端放在整个流程全部跑通之后再去搞不然你会同时面对“openclaw 没搞懂”和“Termux 环境怪异”两个难题心态很容易崩。2.2 算力选型只能用 API 方式用算力吗热词里有人问openclaw 是不是只能用接入 API 的方式使用算力答案是不一定但 API 方式确实最省事。接入 API 意味着你把模型推理交给第三方模型服务处理openclaw 本地只负责工具调度。这种方式有三大好处不需要强显卡、不需要下载动辄十几 GB 的权重文件、响应速度取决于网络而不是本地硬件。缺点是每次调用按量计费而且数据要经过外部服务对隐私敏感的场景不太友好。如果不想依赖外部 API也可以走本地模型路线。主流方案是两个用 ollama 在本地拉取开源模型暴露一个 OpenAI 兼容接口openclaw 通过这个接口调用本地模型。用 GPUStack 这类集群管理工具把多台 GPU 节点统一管理起来对外提供一个稳定的模型服务地址再让 openclaw 接入。我个人的经验是零基础用户先用 API 跑通流程等确实有隐私或成本诉求了再切换到本地模型。因为本地模型涉及的显存估算、量化选择、推理速度调优每一项都是新坑别挤在第一天上。2.3 16GB 显存到底能本地跑什么模型很多人的机器是 16GB 显存想知道不接外部 API 能玩多大模型。我直接给一个基于实际部署经验的速查表注意这是估算值实际占用会因上下文长度、量化方式和推理引擎有浮动。模型规模推荐量化方式显存占用约16GB 显存是否可行7B 级别Q4_K_M5-6 GB非常轻松8B 级别Q4_K_M6-7 GB可行余量不错14B 级别Q4_K_M10-12 GB可行但并发别开太高32B 级别Q4_K_M约 20 GB单卡跑不动需 CPU 卸载或多卡70B 级别Q4 量化40 GB 以上基本不可能所以如果只有 16GB 显存老老实实选 7B 到 14B 之间的量化模型。我实测下来7B 模型跑 openclaw 的工具调用任务速度和稳定性都够用14B 理解能力更强但响应时间会明显增加。上下文长度设置也很关键默认 4096 是一个安全的起点拉到 8192 以上显存占用会显著增加。2.4 Windows Companion 是干什么的到底怎么配Windows 用户搜“openclaw windows companion 怎么配置”的频率特别高这里单独说一下。Companion 是 Windows 下的配套程序它的核心作用是让 openclaw 拥有访问桌面系统的“触手”截屏、键盘输入、鼠标操作、读取窗口信息这些能力都通过 Companion 暴露出来。如果你只是想让 openclaw 处理纯文本任务Companion 可以不装但如果你想让它帮你操作真实软件那它就是必不可少的桥梁。配置的要点有三个安装时要确认启动服务的端口没有被防火墙拦截否则 openclaw 这边连不上。第一次启动时会要求授权基于安全考量建议只给当前用户权限不要给管理员权限减少风险。如果同时开了多套 Python 环境Companion 和 openclaw 要用同一个环境否则版本不匹配会静默失败。我见过太多人在这一步卡住现象是 openclaw 已经起来了但调用工具时报连接超时折腾半天才发现是 Companion 根本没启动。所以装完后第一时间确认任务管理器里有没有相关进程比什么都重要。3. 零基础部署全流程实操从命令行到跑通第一个任务3.1 第一步把基础工具装齐一个都不能少在拿到 openclaw 源码之前先把地基打好。我推荐的最小工具集是Git用来拉取源码和更新版本Python 3.10 及以上版本推荐 3.11 或 3.12兼容性更好一个终端工具Windows 用 PowerShell 或 Windows TerminalLinux 直接用系统终端检查 Python 装没装好在终端里执行python --version git --version这两个命令能正常输出版本号才算过了第一关。如果提示python 不是内部或外部命令大概率是你安装 Python 时没勾选“Add Python to PATH”重新安装一次并勾选即可。这个坑从我看到的情况来说十个零基础用户里至少有两个会踩。Linux 用户如果是从裸机开始需要先把编译工具链装上因为部分依赖需要本地编译sudo apt update sudo apt install -y git python3 python3-venv python3-pip build-essentialWindows 用户如果缺编译环境通常默认会有但遇到个别依赖报错时需要安装 Visual Studio 的 C 生成工具这个后面在问题排查章节细说。3.2 第二步克隆仓库并创建隔离环境openclaw 的源码托管在 GitHub 上你直接在搜索框搜项目名就能找到官方仓库。这里要认准仓库的所属组织或作者避免下到别人二次封装的旧版本。拿到仓库地址后在终端里执行git clone 官方仓库地址 cd openclaw然后立刻创建一个 Python 虚拟环境。为什么一定要用虚拟环境因为 openclaw 的依赖和我见过的多数 AI 项目一样版本锁定非常敏感你机器上其他项目如果用了不同版本的 pydantic 或 fastapi很容易互相打架。虚拟环境就是给项目单独隔一个房间互不干扰。python -m venv .venvWindows 上激活虚拟环境.venv\Scripts\activateLinux/macOS 上激活source .venv/bin/activate激活成功后终端提示符前面会出现(.venv)字样。看到这个说明你已经进入隔离环境了后面所有安装操作都要在这个状态下进行。3.3 第三步安装依赖并配置第一个模型连接依赖安装是另一个事故高发区。openclaw 的仓库里通常有两个选择一个是核心依赖 requirements.txt一个是包含文档、测试等功能的完整依赖 requirements-dev.txt。新手装核心依赖就够了pip install -r requirements.txt如果网络慢导致安装超时国内建议直接用镜像源比如清华 PyPI 镜像命令加上-i参数即可。这里特别提醒一下千万不要因为某个依赖一直装不上就“绕过”虚拟环境直接全局安装这样短期省事后期版本冲突会加倍奉还。装完依赖后需要配置模型连接。openclaw 的配置文件大多数是 JSON 或 YAML 格式默认会有一个样例文件复制一份改成自己的配置。配置内容核心是下面几个字段以 OpenAI 兼容接口为例{ model_provider: openai_compatible, base_url: http://127.0.0.1:11434/v1, api_key: ollama, model: qwen2.5:7b-instruct-q4_K_M }这段配置的意思是让 openclaw 连到本地 11434 端口上的 ollama 服务用 qwen2.5 7B 量化模型。如果你用的是第三方模型服务的 API就把base_url换成服务商给的地址api_key换成自己的密钥model换成实际可用的模型名。注意具体配置文件的字段名和位置可能因为版本不同而有差异但思路是一致的你只需要让 openclaw 知道“模型服务在哪里、用什么凭证访问、调用哪个模型”这三件事。3.4 第四步首次启动验证确认链路是通的模型连接配置好之后先不要急着写任何自动化任务先跑一个最简单的启动命令验证链路。openclaw 通常会提供命令行入口或者一个启动脚本具体命令以仓库 README 为准常见的形态是python -m openclaw.cli check这个命令的作用类似“体检”它会检查模型 Endpoint 是否可达、依赖是否完整、配置是否合法。如果输出有OK或SUCCESS之类的字样恭喜你的部署已经完成了八成。如果检查报错也别慌。最可能的情况无非三种模型服务没启动、base_url 写错、API key 无效。先确认你本地装 ollama 的话ollama serve有没有在跑第三方 API 的话试着 curl 一下 base_url 地址看有没有响应。拿一张纸把链路写出来——openclaw 连接模型模型返回结果——这条链路上每一环单独验证问题很快能定位。第一次启动的另一个任务是确认日志输出。openclaw 一般会有一个日志文件位置通常在用户目录下的.openclaw或者项目目录下的logs里。养成看日志的习惯比遇到问题乱猜有效一百倍。日志级别可以调成 DEBUG虽然信息量大但排错时非常有用。3.5 第五步写第一个 skill 并完成一个真实任务部署成功的标志不该只是“程序能跑”而是“能干活”。openclaw 的技能体系叫 skill你可以把它理解为给模型写的一份“岗位说明书”告诉它你能做什么、需要什么输入、调用哪个脚本。我先演示一个最简单的 skill功能是“检查本地某个目录下的文件数量”。在项目里创建如下结构skills/ count_files/ SKILL.md run.pySKILL.md 里写明这个 skill 的用途和参数参考结构如下# 统计文件数量 统计指定目录下的文件数量。输入参数directory_path字符串类型绝对路径。run.py 里是实际执行逻辑比如import sys import os directory_path sys.argv[1] count 0 for root, dirs, files in os.walk(directory_path): count len(files) print(f文件总数: {count})然后确保配置文件里把 skill 目录加载进来重新检查并启动。这样你再让 openclaw “帮我数一下某个文件夹里有多少文件”它就能通过大模型的意图识别把路径参数填进去执行 run.py 并返回结果。这一步的意义非常关键它证明了你部署的环境已经形成了一个完整闭环——模型理解指令、框架解析指令、代码执行指令、结果回传给模型。后面不管接电商自动化、接 ROS2、还是接本地知识库本质都是在这个闭环上换不同的 skill 而已。先把闭环跑通复杂度就降下来了大半。4. 进阶部署手机端、云端服务器和常驻后台4.1 Termux 手机版安装步骤在手机上用 Termux 安装 openclaw属于“能跑但要想清楚用来干嘛”的玩法。先说结论手机本地跑大模型几乎不现实所以手机端的定位应该是“轻客户端”也就是通过 API 连远程模型服务而不是本地推理。Termux 安装流程如下。首先千万别用 Google Play 商店里的版本那个版本长期停滞、权限受限推荐从 F-Droid 或 Termux 官网直接下载最新版。装好后打开终端先更新基础环境pkg update -y pkg install -y git python build-essential后面克隆仓库、创建虚拟环境、安装依赖的流程跟桌面端一样只是要注意 Termux 的文件系统路径跟普通 Linux 不同你的家目录实际在/data/data/com.termux/files/home下。这个路径容易让人困惑但其实只需使用cd ~就能回到用户目录。手机端还有一个头疼问题Termux 进程容易被系统在息屏后杀死。解决方法是termux-wake-lock这个命令申请持续唤醒锁保证 openclaw 在后台不被杀掉。另外如果要访问手机存储里的文件需要额外授权termux-setup-storage运行后手机会弹出文件访问权限请求允许后才能在 Termux 里访问/sdcard下的文件。4.2 无头服务器与 Railway 云端部署有些人想用 Railway 这类 PaaS 平台部署 openclaw理由是“开箱即用、免运维”。思路合理但有个前提必须想清楚openclaw 这类框架的设计目标通常是操作真实系统而云端容器默认没有桌面环境无法截屏、无法操作 GUI 程序只能跑 headless 模式。如果只是跑纯后台任务比如定时抓数据、调 API、处理文本云端容器完全够用。但如果你想让它操作浏览器那就得给容器额外装 Chromium 之类的无头浏览器用 Playwright 或 Selenium 这类工具去模拟操作再把结果回传给 openclaw。这一套不是说不能做而是复杂度比本地部署高一个量级对零基础用户相当劝退。另外云端部署的核心问题是存储。很多 PaaS 平台的免费容器是临时文件系统每次重启都会丢数据而 openclaw 的配置、日志、skill 文件都落在文件系统里。因此必须挂载持久化存储卷把配置目录和日志目录映射出来。部署前先把“数据保存在哪里”这个问题想透再谈别的。4.3 内网服务器部署与本地知识库联动如果你是想部署到公司或家里的内网服务器最核心的诉求通常是隐私和数据安全。这类场景我建议把模型推理也彻底本地化用 ollama 或 GPUStack 在内网搭建模型服务openclaw 通过内网 API 地址连接整个链路不经过公网。本地知识库的联动是另一个实用方向。做法不难理解把一堆文档比如产品手册、行业报告、个人笔记向量化存进本地向量数据库然后给 openclaw 写一个专门做 RAG检索增强生成的 skill。用户向 openclaw 提问时它先检索知识库里的相关片段再让模型基于这些片段生成回答。这样你得到的答案都有本地资料做支撑不会完全依赖模型自身的记忆。部署层面需要额外注意两点一是给向量数据库分配固定的磁盘位置定期做索引备份二是 openclaw 的请求超时时间要调大一点因为本地检索加上模型推理的整体延迟比单纯调用 API 要高不少。4.4 让 openclaw 持续运行screen、tmux、systemd 怎么选部署完了openclaw 能不能 7x24 小时在后台跑是另一个高频需求。在 Linux 服务器上最常见的是三种方案。临时挂后台用nohup适合测试nohup python -m openclaw.cli serve openclaw.log 21 这行命令的意思是把 openclaw 放到后台运行所有输出写入openclaw.log即使关掉终端也不会被杀掉。缺点是管理不方便想停就得先找进程号再 kill。实战里我推荐 tmux 或 screen因为它们能让你随时重新“贴”回会话界面里看实时日志tmux new -s openclaw # 在 tmux 里启动 openclaw # 按 CtrlB 再按 D 分离会话关闭终端也不影响运行 # 想回来就看一眼tmux attach -t openclaw如果希望开机自启并且服务崩溃后自动重启那就得用 systemd。在/etc/systemd/system/openclaw.service里写一个服务文件参考结构如下[Unit] Descriptionopenclaw service Afternetwork.target [Service] User你的用户名 WorkingDirectory/你的路径/openclaw ExecStart/你的路径/openclaw/.venv/bin/python -m openclaw.cli serve Restartalways RestartSec5 [Install] WantedBymulti-user.target写完后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw以后它就会开机自启崩了自动拉起日志用journalctl -u openclaw -f就能实时查看。这是所有部署方式里最“一劳永逸”的建议服务器用户直接学这个。5. 常见问题与排查技巧实录每一个都是实测踩过的5.1 安装和依赖问题先列几个我装过几十遍之后总结的高频问题现象原因解决方案pip install 超时或卡住网络源较慢使用国内 PyPI 镜像源例如清华源安装某个依赖报编译错误本地缺少 C/C 编译工具Windows 装 VS Build ToolsLinux 装 build-essential依赖版本冲突与全局 Python 环境互相污染删除虚拟环境重建严格用.venv环境安装Python 版本过低openclaw 需要 3.10 的新语法特性安装新的 Python 版本并配置到 PATH我的习惯是遇到莫名其妙的依赖错误先用最笨的办法——重新建一个虚拟环境干净安装。很多问题不是你操作错了而是包管理器里残留的旧版本在作怪。删掉.venv目录重建通常能解决 80% 的玄学问题。5.2 模型连接和权限问题配置没问题但启动失败九成出在模型连接这一环。常见错误如下模型连接超时。先确认远程模型服务真的在跑用curl -X POST 模型地址/v1/chat/completions试一发能返回 JSON 就说明服务活着问题出在 openclaw 配置如果 curl 都超时那是网络或服务本身的问题。认证失败。很多本地模型服务比如 ollama对 key 不敏感随便填一个字符串就行但如果你用的是第三方云端 APIkey 就必须严格复制不能多一个空格。检查配置里有没有看不见的制表符或空格这个低级错误我踩过不止一次。还有一个容易被忽略的是防火墙。openclaw 和模型服务如果不在同一台机器上要确保服务端口对外开放。测试时先关防火墙排除干扰确认能通了再精细化放行。Windows 上尤其注意第一遍弹出的防火墙授权窗口别直接拒绝拒绝之后默认规则就不放行了后面很麻烦。5.3 GPU 显存不足和性能问题本地推理最常见的报错是CUDA out of memory。解决办法按优先级排列降低并发数把 openclaw 同时处理的请求数调到 1。缩短上下文长度从 8192 降到 4096显存占用立刻降一截。换更小的量化模型从 14B 换到 7B。关闭 CPU offload强制全程 GPU 推理避免内存显存来回倒腾。如果跑起来之后响应很慢先看模型是不是在 CPU 上跑。很多机器装完驱动但 Python 的 CUDA 版本没对上模型会静默落到 CPU 推理。解决办法是检查nvidia-smi和python -c import torch; print(torch.cuda.is_available())输出 True 说明 GPU 可用False 就重新装匹配的 torch 版本。5.4 卸载和清理指南装了想卸载是很正常的我也卸载过重新来。清理的关键不是“删掉文件”这么简单而是把配置、服务、进程都处理干净。最标准的卸载流程是这样先停掉正在运行的进程或 systemd 服务然后删除虚拟环境和源码目录再去用户目录下找.openclaw、.config/openclaw这类隐藏配置目录一并删除。Windows 用户如果装过 Companion需要在服务管理里停掉并删除对应服务Termux 用户直接删除项目目录再执行pkg uninstall清理包。如果你是通过 Docker 安装的则要docker rm -f openclaw_container docker rmi openclaw_image删完之后可以全局搜索一下项目名看还有没有残留文件夹。这世界上没有“卸载不干净”的软件只有没找对地方的人。5.5 模型训练和个性化扩展的进阶方向部署走上正轨之后很多人会问“能不能训练自己的配置”。先说清楚这里的“训练”通常指两件事一是给 openclaw 添加新的 skill教它学会新工具二是针对模型本身做微调让它更适应你的特定任务风格。前者是基本操作后者才是真正的模型训练对硬件和训练数据都有要求。我的建议是绝大多数人不需要做模型微调。你只要把 skill 写清楚、把工具链配好模型在通用能力基础上已经能完成很不错的任务。如果确实要对模型微调请先准备至少几百条高质量的任务样例用 LoRA 这类参数高效微调方法在单卡上跑16GB 显存训练 7B 模型是可行的但训练周期和调参成本要提前做好心理准备。6. 一些个人体会和最后的小技巧折腾 openclaw 大半年之后我最深的体会是这个项目的复杂度不在安装而在任务设计。安装只是把零件拼起来真正决定它好不好用的是你让它干什么、怎么干、给什么权限。很多人装完就跑上来问“我接下来能做什么”本质上是对自己的场景没有做拆解。不要指望框架替你思考业务它只能帮你执行。最后分享一个小技巧第一次部署时先别追求自动化。你可以手动调用每个 skill 的底层脚本确认单个工具都是好的再让模型在 openclaw 里自动串联。很多看起来莫名其妙的全链路失败拆成单点测试之后三分钟就定位到了问题。这个习惯能帮你省下大把排错时间。另外养成固定时间看上游更新的习惯。openclaw 这类项目迭代非常快配置文件格式和命令入口都可能变动如果你用老教程对照新版代码对不上是正常的别怀疑自己装错了先看看更新日志再说。保持“跟着项目本身走”而不是“跟着一篇教程走”才是长期用下去最稳定的策略。