很多人第一次接触 openclaw 的时候第一反应都是这到底是个聊天机器人还是个大模型运行框架其实它两头的活都干只是侧重点不一样。按照我自己的理解openclaw 更像一个“中间层”——把底层的大模型能力不管是本地跑的、还是云端 API和对外的对话交互接起来做成一个可以直接聊、可以配角色人设、可以挂工具调用的对话系统。也就是说你给它一个模型它给你一个能用的“人”。这项目适合谁说实在的门槛不算低但也没有想象中那么吓人。你要是接触过本地部署大模型、玩过 Ollama、或者折腾过任何一款对话框架那 openclaw 基本就是顺着这些经验往上走的。哪怕你是纯小白只要愿意跟着文档一步步敲命令一天内把基础版跑起来是没问题的。但如果你连 Python 环境、命令行是什么都还没概念我建议先花半天了解一下这些基础再动手不然报错的时候会很痛苦。这篇文章我会把我自己从零开始部署 openclaw 的完整过程写一遍覆盖安装、配置、接入大模型、对话工具的使用以及我踩过的一些坑和排查思路。内容不求面面俱到但保证每一步都是实操过的、能落地的。1. 部署形态与方案选型安装 openclaw 之前第一件事不是急着复制安装命令而是想清楚在什么环境里跑。不同系统、不同硬件条件下安装方式和后续体验差得非常多。1.1 三种主流部署方式对比我实际接触下来openclaw 的部署基本分成三条路Windows 本地直接跑、Linux 服务器/云主机部署、还有安卓 Termux 这种移动端方案。三条路各有各的脾气。首先是 Windows 本地。对绝大多数人来说这是最顺手的毕竟日常用的就是 Windows。但 openclaw 这类偏 Linux 生态的项目在 Windows 上跑多多少少会遇到一些环境变量、路径分隔符、依赖编译之类的问题。热词里有个 “openclaw windows companion”这就是官方为了解决 Windows 体验而配套的辅助组件后面会细说。其次是 Linux 服务器。如果你手头有云主机或者旧电脑装了 Ubuntu那这是最省心的方案。热词里 “ubuntu安装openclaw” 被频繁搜索说明不少人也在走这条路。Linux 下依赖冲突少、进程管理方便、可以挂后台跑我自己最后其实也是把主实例放在一台 Ubuntu 机器上的。最后是安卓 Termux。这个属于“能跑但不推荐作为主力”的水平。手机性能有限CPU 跑大模型速度感人而且 Termux 环境下编译有些 Python 包非常折磨。适合什么呢适合你有台性能还行的手机、想体验一下 openclaw 的对话功能或者纯粹想在通勤路上试试。我之前在 Termux 里装过一次单纯跑一个 1-2B 的小模型做简单对话还行再大就卡顿严重。1.2 硬件需要什么规格说到硬件很多人喜欢问“什么配置才能跑”。这个问题其实取决于你想用什么样的模型。如果你打算接云端 API比如智谱、通义、或者厂商开的兼容接口那本地完全不需要独立显卡一个能够稳定运行 Python 的普通电脑就够。openclaw 本体的内存占用大约在 1-2 GB 左右加上浏览器开个 WebUI8GB 内存的机子都能应对。如果你打算跑本地模型那就得看模型大小了。我用 Ollama 配合 openclaw 跑过 7B 级别的量化模型如 Q4_K_M 量化内存建议至少 16GB最好 32GB。显存方面如果你有 NVIDIA 显卡6GB 显存可以勉强跑 7B 模型的低量化版本12GB 显存体验就比较流畅了。AMD 显卡用 ROCm 也可以但环境配置更折腾一点不建议新手一上来就挑战。CPU 的话说实话7B 模型纯 CPU 跑也能出字但速度大概就是每秒几个 token对话体验会很着急。提示如果预算有限但想认真玩我的建议是优先保证内存容量显卡其次。很多本地模型对内存带宽和容量更敏感内存不够直接跑不起来显存小了还能用 CPU offload 顶着。1.3 版本选择与获取渠道openclaw 的版本获取就是常规做法从官方渠道克隆仓库。需要注意的一点是这类项目迭代非常快主分支有时候会带着调试代码或不稳定特性如果你想要一个相对稳定的体验建议关注带 tag 的发布版本。我自己踩过的坑是一开始图省事直接拉了默认分支结果启动的时候总有几个模块版本对不上。后来老老实实切到最新的 release tag问题少了很多。具体命令后面安装部分会写。2. 环境准备与依赖安装把环境比作做饭的厨房openclaw 是菜谱模型和工具是食材。厨房不好用菜谱再好也白搭。这一节把依赖环境说清楚照着做基本不会出错。2.1 基础运行环境openclaw 的核心是 Python所以 Python 环境是第一步。版本要注意太高太低都可能出问题。我实测比较稳的是 Python 3.10-3.12 区间。装 Python 的时候有两个细节安装时勾选 “Add Python to PATH”不然后面命令行敲python会提示找不到命令。如果你同时装了多个 Python 版本建议用虚拟环境管理项目依赖别往全局环境里塞东西。为什么建议虚拟环境因为 openclaw 依赖的第三方库非常多而且各库之间还有版本约束。比如某个库要求pydantic2另一个又要pydantic2这种冲突在全局环境里就会互相打架。虚拟环境能把这些依赖隔离起来互不干扰。我见过太多人一报错就把项目删了重装结果问题出在 Python 全局环境太乱而不是项目本身。其次是 Git最好装上并配置好用户信息。openclaw 的更新方式一般就是git pull你要是没装 Git 或者没配置后续更新会比较别扭。再就是 Node.js。openclaw 的 WebUI 前端部分和部分工具脚本依赖 Node 环境。这里注意版本用 LTS长期支持版就行别追最新有些前端依赖对过新的 Node 版本兼容性反而不好。2.2 数据库与其他服务组件热词里出现了 “mysql安装配置教程”这其实是个非常容易困惑的点——明明 OpenAI 官方的对话工具不需要数据库为什么 openclaw 要配原因在于 openclaw 需要存储会话历史、用户配置、角色卡片之类的数据。生产环境或者数据量大了之后确实可以考虑 MySQL。但如果你是自己本地玩完全没必要上 MySQLopenclaw 默认使用的 SQLite 就够用了。SQLite 是单文件数据库零配置轻量完全适合个人使用场景。那什么情况下才需要 MySQL我的体会是当你有多个 openclaw 实例共享同一份数据、或者用户量大、要多人同时访问时再用 MySQL 这种服务型数据库。单体个人部署用 SQLite 就是最优解。另外热词里还有个 “redis”这也不是必须的。openclaw 的某些异步任务队列能力会用到 Redis但个人部署用默认的内存队列就够了。别被各种教程带着走装了数据库一堆服务最后发现根本用不上。注意只装你需要的东西。多余的中间件不仅增加启动时间还会变成一个隐藏故障点排查问题时更麻烦。2.3 显卡驱动的预备检查如果你打算在本地用显卡跑模型这一步建议在装 openclaw 之前就检查好。Windows 用户命令行输入nvidia-smi能看到显卡型号和驱动版本就说明驱动正常。如果提示不是内部或外部命令说明驱动装了但没加入 PATH或者根本没装驱动。跑一次深度学习框架前先把驱动和 CUDA 环境搞定。选择什么 CUDA 版本其实现在主流的方式是通过 Ollama 这类工具来跑模型Ollama 会把 CUDA 相关的东西打包好你不需要自己手动装完整的 CUDA 工具包。只需要保证显卡驱动足够新即可。我 Windows 上用 531 或更新版本的驱动跑 Ollama 都没出过问题。3. openclaw 安装全过程这一部分直接上手。我以 Windows 部署为主线因为这是大多数人的第一站同时补充 Ubuntu 和 Termux 的差异点。3.1 克隆仓库与目录结构打开命令行Windows 用 PowerShell 或 CMD 均可进到你想要存放项目的目录然后git clone https://github.com/openclaw/openclaw.git cd openclaw这里提一下如果你 GitHub 下载速度不理想可以试试配置代理或者用镜像站但这个因人而异我这边不展开。关键是克隆完成后先看一下目录结构。通常会有core/、web/、docs/、scripts/之类的目录分别对应后端逻辑、前端界面、文档和辅助脚本。了解结构不是为了记住每个文件而是当报错时你能大概猜到问题出在哪个层面——是前端打包、还是后端依赖这个判断力会节省很多时间。3.2 Python 虚拟环境与依赖安装进入项目目录后创建并激活虚拟环境python -m venv venvWindows 激活方式venv\Scripts\activateLinux/macOS 激活方式source venv/bin/activate激活后命令行前面会出现(venv)标记说明你已经在这个隔离环境里了。然后安装依赖pip install -r requirements.txt这个步骤是安装过程中最常见的问题高发区。如果遇到某个包编译失败先别急着用pip install xxx或者去网上找零散答案。我的处理顺序是看报错信息里有没有提示缺什么系统级库比如 Windows 下缺少 Microsoft C Build Tools。如果是在安装tokenizers或grpcio之类的包失败多半是编译工具链不完整。确认 Python 版本是否在项目支持的范围内。在 Windows 上装 Microsoft C Build Tools 基本能解决 90% 的编译类报错。在 Ubuntu 上一般是缺build-essential和python3-devsudo apt update sudo apt install build-essential python3-dev前端部分单独安装依赖cd web npm install cd ..这一步需要 Node.js 环境。如果 npm 安装速度很慢可能是网络原因但这个问题我这里不展开讲。3.3 首次启动与初始化依赖装完之后先别急着配置模型直接试一下能不能启动python openclaw.py启动时应该会看到日志输出包括加载配置、初始化数据库、启动 WebUI 服务等信息。首次启动时如果提示缺少.env或配置文件程序通常会自动从模板复制一份生成比如.env.example复制成.env。启动成功的标志一般是看到类似 “Running on http://127.0.0.1:xxxx” 的日志。打开浏览器访问这个地址如果能看到界面那安装这关就过了。提示首次启动往往会比后续启动慢因为要初始化数据库和生成缓存文件。如果等了好几分钟还没动静再怀疑有问题。4. 大模型接入与对话工具配置openclaw 本身不提供模型能力它需要从某个地方获取大模型。接入方式基本就是两种本地模型工具如 Ollama和在线 API。这一节我把两条路都走一遍。4.1 本地模型Ollama 接入热词里有个 “ollama部署openclaw”可见这是最常见的组合。Ollama 的优势是安装简单、模型管理方便而且和 openclaw 配合得比较好。Ollama 安装好之后先在命令行拉取一个模型。以通义千问的 7B 版本为例ollama pull qwen2.5:7b模型体积大约在 5GB 左右等你下载完运行ollama serve这个命令会启动 Ollama 的服务默认监听在 11434 端口。然后回到 openclaw 的配置文件.env找到模型相关配置项设置MODEL_PROVIDERollama OLLAMA_BASE_URLhttp://127.0.0.1:11434 MODEL_IDqwen2.5:7b然后重启 openclaw。如果配置正确聊天界面里应该就能选择到这个本地模型并正常回复。其实还有更快的验证方式先单独测试 Ollama 是否正常。命令行里直接ollama run qwen2.5:7b如果能正常对话说明模型本身没问题。然后再排查 openclaw 与 Ollama 的连接。4.2 在线 API 方式不想在本地跑模型的话接在线 API 是最省事的选择。现在国内有不少平台提供兼容接口的大模型服务比如智谱、通义、DeepSeek 等选一家注册拿 API Key 就行。在.env里配置改为MODEL_PROVIDERopenai OPENAI_API_KEY你的密钥 OPENAI_BASE_URLhttps://你的接口地址/v1 MODEL_ID模型名称这里要注意openclaw 的 “openai” provider 并不一定就是 OpenAI 官方它兼容所有 OpenAI API 格式的服务商。很多国产模型的 HTTP 接口都实现了这个格式所以填对应的 Base URL 就能用。很多人卡在这一步是因为不知道OPENAI_BASE_URL要填什么最简单的方法就是去对应的平台文档里查 “Base URL”复制过来就行。接 API 的好处是不需要好的显卡、回复速度快、没有本地显存的压力。坏处是要花钱、有上下文长度限制、部分平台有敏感内容限制。个人玩建议先用 API 跑通功能等确认 openclaw 能满足需求、你确实需要本地离线运行的时候再上本地模型。4.3 上下文长度与模型参数调优热词里 “大模型上下文长度” 被多次搜索说明这是很多人配置时会疑惑的点。上下文长度Context Length决定了模型能“记住”多少前文内容。openclaw 作为对话工具这个参数直接影响对话体验——上下文短了聊不了几句就忘了前面说的什么上下文长了首字响应速度变慢、显存占用增加。一般配置项里有MAX_CONTEXT_LENGTH之类参数。个人使用建议本地 7B 模型4K 上下文约 4000 token是一个体验和资源消耗比较平衡的点。如果显存够大、也愿意等可以开到 8K。接在线 API 时先用平台的默认值不要盲目调大因为 token 越多费用越高。另外还有个常见的坑你配置的上下文长度超过了模型本身支持的上限就会报错或者被静默截断。本地方案下模型最大上下文是模型文件里定义死的你怎么调也是超不过去的。4.4 对话工具的使用体验openclaw 接入模型之后基础的对话已经能用了。所谓对话工具在我理解里包括三个层面WebUI 聊天界面、API 访问能力、以及角色卡片/人设管理。WebUI 是最直观的就跟你用任何聊天网站一样的界面。在里面可以新建会话、清空历史、切换模型。这里面有个小细节openclaw 的会话历史是持久化存储的重新启动之后之前的会话还在。如果你不想让之前的上下文干扰新测试记得手动开启一个新会话。角色卡片是 openclaw 比较有特点的功能。它允许你为模型预设一个“人设”然后在这个人设下对话。配置方式是在 WebUI 或者配置目录下创建角色描述里面可以写系统提示词System Prompt、对话风格、行为约束等。比如你写了一个“你是一个严谨的数学老师”那模型后续对话就会偏向这个风格。这个功能本质上就是在帮你管理不同的 System Prompt避免每次手动输入。API 访问层面openclaw 启动后本身就是个 HTTP 服务你可以用任何编程语言请求它的接口来实现程序化对话。比如写个 Python 脚本定时调用 openclaw 接口让它做某个分析任务。开个端口就能用。5. 跨平台补充Windows Companion 与 Termux正文到这里基础的安装和配置已经说完了。但搜索热词里 “openclaw windows companion” 和 “openclaw安卓部署” 出现的频率非常高说明这两块也是很多人关心的。我单独把这两个场景讲一讲。5.1 Windows Companion 是干什么的我在 Windows 上折腾 openclaw 的过程中发现某些和音频输入、桌面通知、系统托盘相关的功能在纯 Python 环境下实现得很别扭。后来明白了openclaw 在 Windows 上有一些组件是需要通过一个伴生的桌面程序来辅助的——这就是 “Windows Companion”。它的作用简单说就是把 openclaw 后端和 Windows 桌面系统的能力桥接起来。比如语音输入功能浏览器里的 Web 页面出于安全限制没法直接调麦克风但 Companion 这个本地程序可以。你把 Companion 安装好、启动后WebUI 就能通过它间接使用麦克风、通知等系统能力。安装 Companion 并不复杂从发行渠道下载对应版本解压后直接运行。关键是要注意启动顺序先把 openclaw 后端跑起来再启动 Companion这样两者才能正确建立连接。Companion 的设置界面里通常有端口号或连接地址默认应该已经指向了本地的 openclaw 服务。如果你改了 openclaw 的端口记得在 Companion 里同步修改。我的实际体会是Companion 属于“非必需但体验升级”的组件。你不需要它也能正常跑对话但如果你想要语音输入、通知提示这些桌面级体验它就很有用。5.2 Termux 安卓部署体验手机装 openclaw 这件事能跑但我先说结论只适合体验不适合长期作为主力平台。Termux 是安卓上的终端模拟器本质上就是一个可以装软件包的 Linux 环境。安装 openclaw 的思路和在 Ubuntu 上类似pkg update pkg upgrade pkg install python git nodejs pip install -r requirements.txt但问题也随之而来。手机的性能瓶颈还是其次最大的痛苦是 Python 依赖包在 Termux 环境下的编译。有些包没有为 Termux 提供预编译版本安装时只能现场编译那个时间长度真的很考验耐心。再加上大模型本身动辄几个 GB 的体积手机存储很容易就捉襟见肘。另外openclaw 启动后默认绑定的是 127.0.0.1电脑上自己访问是没问题的但如果你想在手机上用浏览器访问 openclaw 的 WebUI需要确认监听地址。有些配置里要绑定 0.0.0.0 才能从局域网访问。Termux 下一般还要处理后台保活的问题——你锁屏之后进程可能被系统回收。我的建议是如果真想体验移动端对话不如直接装一个对话客户端然后通过 API 方式连接到你电脑或服务器上的 openclaw体验要好得多也不用在手机上烧电。6. 常见问题与排查技巧实录最后这一部分我把实际部署过程中走过的弯路、踩过的问题集中整理一下。很多问题我在群里看到几乎每天都有人问这里一次说清楚。6.1 高频问题速查表现象原因解决办法启动报 “ModuleNotFoundError”Python 依赖没装全或装错了环境确认虚拟环境已激活重新执行pip install -r requirements.txt浏览器访问 WebUI 页面空白前端构建产物缺失进入web目录执行npm install npm run build重新生成后重启对话时提示 “connection refused” 或 “model not found”openclaw 连不上模型服务检查 Ollama 服务是否启动、.env中OLLAMA_BASE_URL是否正确本地模型生成速度特别慢CPU 推理或显存不足导致部分层在 CPU 跑降低模型规模、使用更小量化级别、升级硬件修改.env后没生效配置加载时机问题修改配置后必须完全重启 openclaw 进程而不是只刷新页面API 接入后报 401API Key 错误或接口地址不兼容确认 Key 有效确认OPENAI_BASE_URL以/v1结尾数据库报错或会话记录丢失数据库文件损坏或版本迁移失败备份后删除旧的数据库文件让 openclaw 重新初始化语音输入按钮灰色不可用Companion 未启动或连接失败启动 Companion确认端口与 openclaw 一致重启浏览器页面重新连接WebUI 登录后提示权限不足初始用户名密码未修改或配置未生效按文档重新设置管理员账号重启服务再登录6.2 日志排查的基本功遇到问题第一反应不应该是去群里问而是先看日志。这是所有折腾型项目的基本功。openclaw 启动的终端窗口或者日志文件里会记录每一次报错的完整堆栈。即使你看不懂堆栈的全部内容抓住关键信息还是能做到的。比如看到 “Error 111” 或者 “Connection refused”基本可以断定是网络连接问题就去查目标服务是否在监听端口看到 “SyntaxError” 或 “NameError”大概率是代码层面的错误一般等待修复或者在社区反馈看到 “Out of Memory”那就是硬件资源不够了。我常用的排查顺序是日志 → 配置文件 → 端口监听情况 → 依赖版本。按照这个顺序大部分问题都能自己解决。在 Windows 下查看端口监听命令是netstat -ano | findstr 11434Linux 下是ss -lntp | grep 11434如果端口没有进程监听那就是对应的服务没起来问题就变得清晰了。6.3 玩 openclaw 的一些习惯建议几个我自己用了觉得好使的习惯这里分享给有耐心的朋友。第一每次修改配置只改一个变量改完立刻重启验证。不要一次改十个配置项出了问题你根本不知道是哪一项引起的。这个习惯能帮你把问题定位的时间缩短一个数量级。第二定期备份配置文件和数据库文件。openclaw 的角色设定、会话历史、群聊记录都很有价值。我一般是在每次大版本更新前把项目目录里的配置文件和数据库文件复制一份加上日期后缀。一旦更新出了问题回滚就是几秒钟的事。第三认真阅读.env文件里的每一行注释。openclaw 的配置项注释一般写得很清楚很多人只看中文教程不看注释结果教程没覆盖到的功能就完全不知道。注释才是最新的文档教程会过时注释跟着代码走基本是同步的。第四如果遇到问题在社区提问一上来就把版本信息、操作系统、完整的报错日志贴出来。那种只问一句“怎么办”的提问别人想帮你也无从下手。你贴的信息越全得到的有效回答概率越高——这是真实社区里的通用规则。我个人实际体会最深的其实是配置本地模型时的那一次焦虑期总觉得自己哪里没做对反复重装环境结果后来才发现不过是.env里一个 URL 少了/v1前缀的小问题。这种经历多了之后我反而养成了先看注释、先看日志、再动手改配置的习惯——折腾这类项目最大的成本从来不是硬件而是无效的反复尝试。希望这篇文章能帮你少走一段弯路。