第一次部署OpenClaw的时候我卡在启动流程上接近一个下午后来才发现是Python版本太老导致依赖装不干净日志又没认真看白折腾了半天。前阵子群里又有人问这个项目怎么落地我干脆把自己机器重新完整跑了一遍把环境准备、模型接入、channel配置和几个高频报错一次性整理出来希望能让后来的人少走点弯路。OpenClaw是一个本地优先的AI Agent运行框架核心价值是把agent本体、会话记录和技能定义全部留在本机模型层既可以接本地Ollama这类服务也可以接云端兼容API。它自带Session管理、工具调用和多渠道接入能力你可以把它跑到飞书、Teams、Telegram这些IM里跟自己部署的大模型对话。适合不想把数据交给外部服务、想自己控制agent行为的个人用户或小团队也适合正在折腾本地大模型、想找个顺手框架把模型用起来的朋友。我尽量按实操顺序来写命令和配置字段基于我自己使用的版本。开源项目迭代快如果你的版本有差异以官方文档和changelog为准。1. 项目选型和整体思路为什么本地部署OpenClaw1.1 OpenClaw解决什么问题本地部署这件事本身就是一个取舍。直接用云端的Agent服务当然省事注册好账号、填个模型API Key就能跑但代价是工作流、对话记录、技能脚本全放在别人的服务器上你对自己agent的运行环境几乎没有掌控力。一旦平台调整接口策略、修改收费规则或者收紧数据政策你只能跟着改没有任何商量余地。OpenClaw走的是另一个方向。agent本体、会话文件、技能定义全部落在你自己的机器上模型层可以接本地的Ollama也可以接DeepSeek、千问这类以API方式访问的模型服务。好处首先是数据不出门特别适合办公电脑上处理内部资料、不想让对话内容经过第三方服务的场景。其次是可定制空间大系统提示词、工具调用、消息渠道都能自由改跑成一个真正适配你工作方式的agent而不是被平台预设的玩法绑住。1.2 部署形态怎么选同样一套代码在Windows、Linux、macOS上跑起来的体验差距不小。如果你有一台常开的Linux服务器或Mini主机原生部署是最干净的方案没有桌面环境抢占资源进程管理也简单。macOS用户尤其是Apple Silicon的机器直接本机跑也很顺畅M系列芯片跑中小尺寸模型速度还可以接受。Windows用户的选择就比较关键了。社区里专门做了一个面向Windows的安装入口就是大家常说的Windowshub安装方式它把依赖检查和启动流程做了封装上手体验友好一些但底层其实还是依赖WSL2环境。除了这个你也可以手动装WSL2再跑Ubuntu或者用Docker Desktop起容器。我的建议是如果只是想在本地试着跑通走WSL2或Docker都行如果打算把agent当常驻服务用尽量放Linux原生环境省得后面处理一堆Windows特有的文件锁和路径问题排查起来也轻松。1.3 模型层怎么选型OpenClaw本身不做模型推理它依赖一个模型运行时来真正干活。最省心的本地方案是Ollama一条命令把模型服务拉起来和OpenClaw之间走OpenAI兼容协议配置非常简单。选模型的时候主要看内存16G以下就老实跑1.5B到3B量级的量化模型16G到32G可以试7B到8B32G以上再考虑14B以上的大模型。实际办公场景里我觉得qwen系列的中小尺寸模型表现比较均衡中文理解、指令跟随都做得不错DeepSeek的蒸馏小模型也值得一试。如果不追求纯本地直接把模型提供方的地址换成兼容OpenAI的云端API也可以配置方式完全一样只改base_url和api_key就能切过去前期调试链路甚至更省心。2. 环境准备先把地基打牢2.1 硬件与操作系统检查部署前花十分钟确认一下机器情况能避免后面一大堆莫名其妙的报错。OpenClaw本身是常驻服务系统层面至少留4GB内存给它自己模型占用的内存另算。量化模型的内存占用可以粗略估算7B模型Q4量化差不多5GB上下加上系统开销一台16G内存的机器跑7B模型是够用的。磁盘方面把项目文件、模型缓存和日志空间一起算上建议预留20GB以上模型文件动不动好几个G别装到一半发现磁盘满了。CPU要求不高4核以上就行没有GPU也能跑就是推理速度会慢一些但不影响配置过程。操作系统以Ubuntu 22.04或24.04最稳macOS建议Apple SiliconWindows用户走WSL2别用WSL1后面那个session文件锁报错跟它关系很大。2.2 安装运行时依赖以Linux为例先更新系统再装基础工具Python环境建议直接用3.11或3.12OpenClaw主体逻辑要求Python 3.10以上版本太老会导致依赖装不上或者装上了运行时行为不正常。sudo apt update sudo apt install -y curl git python3 python3-pip python3-venv build-essential装依赖时报错多半就是build-essential没装一些Python包需要本地编译缺了编译工具会直接失败。Windows用户走WSL2的安装过程和Ubuntu完全一样唯一要额外确认的是WSL版本必须是2用wsl --status可以看到版本号。WSL1的文件锁行为和Linux原生差异很大跑OpenClaw这种带并发会话管理的程序特别容易出问题。2.3 安装并启动Ollama模型运行时我推荐先用Ollama它是目前本地模型服务里最省事的一个。官方脚本一行装完装好后先启动服务默认监听11434端口。首次拉取模型可以选qwen2.5:7b这种视网络情况可能要等一阵所以我建议先拉一个小的验证链路比如qwen2.5:1.5b跑通了再换大模型。ollama serve ollama pull qwen2.5:1.5b ollama list注意Ollama默认只监听127.0.0.1如果OpenClaw和Ollama在同一个台机器上不用改如果模型服务跑在另一台服务器或者容器里就要把OLLAMA_HOST设成0.0.0.0并放行防火墙端口。我习惯用Docker方式跑Ollama时额外设一个OLLAMA_KEEP_ALIVE24h避免模型空闲后自动卸载否则agent每次冷启动后的第一轮回复都会特别慢体验很不好。2.4 安装OpenClaw本体环境就绪后就可以装OpenClaw了。当前版本的操作是把官方仓库clone到本地在项目根目录执行安装脚本脚本会自动创建虚拟环境并生成基础配置。如果走的是Windowshub安装方式不用手动clone跑完安装器后项目会自动落在用户目录下并弹出一个欢迎页按提示初始化就行。这里有几个容易忽略的点。第一安装期间要保持网络稳定因为要从仓库拉代码和Python包依赖。第二装完必须手动执行一次初始化命令没有这一步就不会生成默认配置文件直接启动会报“找不到配置”。第三启动命令尽量用绝对路径或者先激活虚拟环境再执行不然换个终端就提示找不到命令。装完建议跑一下版本对应的doctor检查命令它会帮你把Python环境、依赖项、配置文件挨个检查一遍很多潜在问题在启动前就暴露出来了。3. 核心配置拆解模型、渠道与Channel选择3.1 配置模型提供方第一次生成默认配置后需要编辑主配置文件把模型提供方的信息填进去。核心字段就四个provider标识、模型名、base_url、api_key。本地Ollama场景base_url写127.0.0.1:11434对应的v1路径api_key随便填个非空字符串就可以因为Ollama本地不校验Key。model_providers: ollama: base_url: http://127.0.0.1:11434/v1 api_key: local-dummy-key dashscope: base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 api_key: sk-xxx default_model: ollama/qwen2.5:7b如果同时配了多个provider模型名最好带上前缀比如ollama/qwen2.5:7b、dashscope/qwen-plus切换时不会搞混。这个前缀只是OpenClaw内部用来区分提供方的标识不同模型服务商对模型的命名规则差异很大统一一套自己的命令规范能省掉很多来回改配置的麻烦。3.2 Channel的概念与选择Channel是OpenClaw和普通命令行Agent拉开差距的地方。它能把agent挂到多个IM渠道上通过飞书、Teams、Telegram、Discord这些入口对话。每个渠道在配置里就是一个channel本质上定义了这个渠道的连接方式、消息入口、回调路径和消息长度策略。选择channel时核心要看你的使用习惯。办公用飞书就配飞书团队协作在Teams就接Teams自己玩就接Telegram或者干脆先在CLI channel里跑不接任何IM。配之前想清楚一个问题这个agent是给一个人用还是给一个群用。一个人用就配成单聊群聊场景要处理上下文归属和权限策略不同channel的群聊机制差别很大别一上来就全渠道铺开。我建议第一遍部署先把CLI跑通再接入一个最常用的IM渠道等稳定了再逐步扩展其他渠道。另外提一句OpenClaw的channel配置天然适合自托管优先的思路消息通过本机的webhook入口进出不需要经过外部中转服务数据链路全程在自己设备上。3.3 会话、超时与输出长度除了模型和渠道还有几个容易被忽略但实际很重要的全局参数它们决定了agent跑得顺不顺。第一个是session文件锁超时默认60秒。如果多个进程同时访问同一个会话文件或者上一个进程异常退出后锁没释放就会出现“agent failed before reply: session file locked”的报错这个下面专门讲。第二个是输出长度限制。很多IM渠道对单条消息长度有硬性上限比如飞书单条消息超过一定字符就可能被截断。OpenClaw提供了长回复分段或摘要策略需要在配置里打开并设置触发阈值别等真实使用发现消息发不全再来查。第三个是并发数。默认并发不高如果你在多个渠道同时跟agent对话建议按实际使用量调大请求并发但要注意本地模型能不能扛得住Ollama同时处理多个推理请求时显存和内存占用会快速上升。4. 从安装到首次运行完整实操流程4.1 初始化并创建第一个agent配置写好之后先初始化再创建agent。我的习惯是建一个测试agent名字就叫test模型指定到刚才拉下来的小模型。这个动作在命令行里一条就能完成创建成功后在CLI channel里直接对话输入一句问候看agent能不能正常回复且日志里没有报错。开通CLI通道非常关键。第一次跑CLI往往是最花时间的环节因为前面所有配置是否正确都会在这里集中暴露provider填错了、base_url写错了、模型名不对全都在这一步现形。反而后面接IM渠道并不会新增太多复杂性因为模型链路已经通了IM只是多一个消息出入口而已。4.2 验证模型连通性如果CLI对话报错先不要急着改配置直接测试模型服务本身。用curl访问Ollama的接口看模型列表能否正常返回再手工调一次chat completion接口确认模型进程确实在服务。curl http://127.0.0.1:11434/v1/models curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5:1.5b,messages:[{role:user,content:ping}]}这个动作能把问题边界划得很清楚是模型服务没起来还是OpenClaw配置不对。我遇到好多次所谓的“连接不上模型”最后排查就是Ollama压根没在运行或者防火墙没放行11434端口。所以养成习惯先curl模型端点再查OpenClaw日志最后才动配置文件别一上来就乱调参数。4.3 接入飞书或Teams渠道CLI跑通之后就可以接入第一个IM渠道了。以飞书为例先去飞书开放平台创建一个应用拿到App ID和App Secret在事件订阅里配置消息接收地址指向OpenClaw监听的webhook路径。然后在OpenClaw配置里新增一个lark channel填入App ID、App Secret和回调路径启动服务即可。channels: cli: enabled: true lark: enabled: true app_id: cli_xxx app_secret: xxx webhook_path: /webhook/larkTeams的接入逻辑类似先在Teams应用注册端创建机器人配置消息端点再在channel里填机器人的凭据。整个过程分成“外部应用配置”和“OpenClaw内部配置”两段最容易出错的是外部平台的事件订阅地址和OpenClaw实际监听的路径不一致两边对不上消息自然进不来。4.4 给agent加一个实用技能一个裸跑起来的agent并不一定能干很多活OpenClaw的价值很大程度在技能扩展上。举个例子写一个自定义工具统计指定目录下的文件数量并生成报告。定义好工具的名称、描述和输入输出格式然后在系统提示词里告诉agent“需要统计文件时调用file_report”这个工具。def file_report(path: str) - str: import os count sum(len(files) for _, _, files in os.walk(path)) return ftotal files: {count}建工具时有个原则输入描述写得越明确模型调用准确率越高。“输入应当是被统计的绝对路径”就比“一个路径”好用得多。工具调用准确率本质上取决于模型的理解能力和描述清晰度框架本身只是提供一套调用编排机制真正决定agent有没有用的是你怎么定义工具、怎么组织它的能力边界。5. 常见问题与排查技巧实录5.1 session file locked 报错这条报错几乎每个跑OpenClaw的人都会撞上一次完整信息长这样agent failed before reply: session file locked (timeout 60000ms)成因不复杂多个agent进程或多个channel同时写同一个会话文件或者上一个进程异常退出后文件锁没有释放新进程等锁超过60秒就报错。最常见的场景是在同一目录下重复启动了多个实例或者CLI会话没正常退出就直接强杀进程。解决思路从三个方向入手。一检查系统里是否还有残留的OpenClaw进程有就全部杀掉再重启。二在配置里调大锁等待时间60秒改成120秒给高并发场景留出余量。三把会话存储从默认的文件模式迁到兼容的SQLite后端锁粒度更细并发读写不容易互相卡死。如果三步都做了还偶发再看看项目目录是不是挂在IO性能很差的存储上比如某些网络盘锁文件的创建和释放本身就慢超时也就在所难免。5.2 飞书消息截断问题飞书消息被截断是接入渠道后最容易被发现的毛病。根源是单条消息长度超过了飞书的上限而OpenClaw默认不一定对长回复做分段处理。解决办法分两层。第一层在配置里打开长回复分段开关设置合适的触发长度阈值让它生成完一段就停下再由框架拆成几条标准长度的消息依次发出。第二层在系统提示词里约束模型输出风格比如明确要求“回答简洁超过400字自动分点”。很多模型喜欢一口气把所有内容堆在一个文本块里提示词约束能显著减少超长输出。我实际测下来两件事一起做截断问题基本消失。5.3 模型冷启动慢或首次回复超时Ollama默认在模型空闲一段时间后把它从内存里卸载第一次请求需要重新加载慢是正常的。表现就是“启动agent后的第一条消息很慢第二条就快了”。解决方式是设置OLLAMA_KEEP_ALIVE为较大的时间值或者干脆设为-1让模型常驻内存代价是内存占用一直较高。如果机器内存不富裕设置成30分钟比较平衡如果这台机器专门给agent用直接常驻就好。5.4 其他高发问题速查现象可能原因处理方式连接模型失败/连接被拒Ollama未启动或端口未监听检查ollama serve进程和11434端口模型返回404模型名写错或model不存在用ollama list核对模型名工具调用不生效工具描述不清楚或系统提示词未提及重新编写工具描述明确触发条件渠道消息进不来webhook路径不一致或应用未发布核对开放平台事件订阅地址与配置文件端口冲突本地已有服务占用端口改配置文件端口或停掉占用进程排查这类问题我的习惯是先查日志再动配置。OpenClaw的日志会明确告诉你哪一步失败、失败原因是什么比瞎猜快得多。遇到问题先把日志翻到最后几十行再对着上面的原因分类去查大多数情况都能快速定位到具体环节。我个人跑下来的体会是部署OpenClaw最忌一上来就追求完整配置。第一次部署先用一个小模型把链路跑通确认CLI能对话再接一个常用IM渠道等这套流程稳定了再慢慢加工具、换大模型、扩展更多渠道。第二次部署的时候整个流程压缩到半小时以内完全没问题。还有个小建议日志目录和会话存储跟项目目录分开更新前把配置备份一下工具和技能逐个加每加一个顺手测一条消息这样出问题的时候排查范围很小agent用起来也会越来越顺。