如果 2026 年你还在把 OpenClaw 这类 AI 助手完全跑在云端那我建议你花一个周末试试本地部署。这篇 OpenClaw 本地部署全指南就一个目标带你从环境准备走到实战运行。OpenClaw 是一个开源的个人 AI Agent 网关核心作用是打通大模型能力和消息渠道——模型可以是 Ollama 本地跑的 DeepSeek、千问渠道可以是命令行、飞书、Teams全靠一个配置中枢来调度。先交代一下我的背景方便你对照判断。我手上是一台闲置的迷你主机32GB 内存、无独立显卡、跑 Linux。之前用云端大模型 API 搭过一个私人助手功能没问题但数据全在别人服务器上离线就瘫痪越用越不踏实。后来看到社区里讨论 OpenClaw 本地部署索性把整套环境从头搭了一遍。过程中踩了不少坑最典型的就是agent failed before reply: session file locked (timeout 60000ms)和飞书输出被截断这两个都是社区里高频求助的问题后面我会完整复盘排查过程。这篇内容适合两类人一类是想在自己电脑或小服务器上跑私人 AI 助手的开发者另一类是想把团队机器人从云端迁回内网的小团队运维。文章不涉及云端 API 的使用纯本地方案跟着步骤走就能从零跑通。1. 部署前先搞清楚OpenClaw 到底解决什么问题1.1 一个网关而不是模型OpenClaw 这类项目最容易让人误解的地方是以为它自带模型。实际完全不是。它的定位更接近一个调度中枢Agent 模块负责理解任务、维护多轮对话上下文、调用工具Channel 模块负责跟外部渠道打交道。模型只是挂在后面的大脑可以是 OpenAI 这类云端 API也可以是 Ollama 拉下来的本地模型。你可以把两者的关系理解成模型是发动机OpenClaw 是变速箱加方向盘——它决定动力怎么输出、往哪走。为什么要多这一层因为如果没有这个网关你得为每一个渠道单独写一套对接逻辑飞书写一套接入、Teams 写一套接入、CLI 再写一套。OpenClaw 把这些全抽象成统一的 Channel 接口写一次配置就能同时挂好几个入口。这也是它跟单纯跑一个 chat 脚本的最大区别。1.2 本地部署的三个直接收益收益这东西不实际跑一个月体会不深但有三点是你第一天就能感知到的数据不出本机。对话记录、上传的文档、Agent 的 session 文件全部落在自己的磁盘上。对隐私敏感的个人用户和需要内网隔离的小团队这一条就是迁移的全部理由。长期成本趋近于零。硬件是一次性投入模型跑在本地没有按 token 计费的问题。即便你每天高强度对话电费也远远低于 API 账单。离线可用。没有外网也能跑内网环境里照样是完整的助手。这对出差、断网、以及网络受限的办公场景非常关键。1.3 什么情况下别碰本地部署我也得泼点冷水。如果你的使用场景以复杂推理为主比如让 AI 写长代码、做深度分析当前本地小模型的水平跟一线云端模型还是差一截。再者本地部署有维护成本升级、排查、换模型都要自己来。我个人建议的门槛是内存低于 16GB 就别勉强低于 8GB 直接放弃。模型不是跑不起来是跑起来之后 Agent 的上下文和工具调用会一起抢内存体验会很差。顺便提一句经常有人问我 OpenClaw 和 WorkBuddy 哪个好。我的看法是两者定位不完全一样OpenClaw 更偏自己掌控一切的调试乐趣WorkBuddy 更偏开箱即用。如果你本身就在折腾本地部署这条路OpenClaw 的社区资料和渠道丰富度会舒服得多。2. 环境准备硬件、系统依赖和模型选型三张清单2.1 硬件底线的真实数据先说结论CPU 8 核以上内存 16GB 起步、32GB 比较舒服磁盘至少留 20GB。GPU 不是必须——有 N 卡当然更好没有就老老实实跑量化模型。我的迷你主机是 32GB 内存加核显同时挂一个 14B 的千问和一个 7B 的 DeepSeek日常跑得很稳。内存怎么算给你一个粗算法7B 模型 Q4 量化大约占 4~5GB14B 模型 Q4 大约占 9~10GB再加上 OpenClaw 本体Node 进程通常占 300~600MB和系统开销16GB 机器跑一个 7B 就基本到顶了32GB 机器才能舒服地跑 14B 或者同时挂两个模型。如果你有 NVIDIA 显卡且显存 8GB 以上模型加载可以走 GPUCPU 和内存压力会小一些。2.2 操作系统与依赖清单OpenClaw 目前主流的跑法有三种原生 Linux、macOS、Windows 用 WSL2。Windows 直接裸装不是不行但会遇到各种路径和权限问题社区里问得很多的 openclaw windowshub 安装本质上还是建议在 WSL 或 Docker 里跑。我这里是 Linux 原生部署下面所有命令按 Linux 写。依赖这块最省心的组合是 Git Node.js 18或 Bun Ollama。还有一样东西容易被忽略curl。后面验证接口、调试的时候全靠它。Linux 上如果报缺依赖优先检查这几个包有没有装全。2.3 模型选型先想清楚用在哪Ollama 官方模型库里可以拉 DeepSeek、千问、Llama、Phi 等系列。我自己留了两个模型按场景区分模型参数量内存占用(Q4)适合场景deepseek-r1:7b7B~5GB日常对话、通用任务qwen2.5:14b14B~10GB中文处理、工具调用、代码选型逻辑很简单中文为主的场景优先千问推理链路长的场景优先 DeepSeek。如果你只有 16GB 内存那建议只装一个 7B 级别的模型别贪。模型文件体积不小7B 的 GGUF 大概 4~5GB14B 大概 9GB下载前先看看磁盘可用空间。如果你的业务偏向特定垂直场景也可以关注 MiniMax H3 这类专精模型在 Ollama 的可用版本但通用场景下 DeepSeek 和千问的组合已经足够。2.4 Ollama 安装与自检Ollama 的安装基本是一行命令curl -fsSL https://ollama.com/install.sh | sh装完后拉模型ollama pull deepseek-r1:7b ollama pull qwen2.5:14b验证两步走ollama list看模型列表curl http://127.0.0.1:11434/api/tags看 API 是否在线。如果你打算让 OpenClaw 跑在另一台机器上、模型单独部署记得把 Ollama 监听地址改成局域网可访问设置环境变量OLLAMA_HOST0.0.0.0再重启服务。这一步很多人漏掉表现就是 OpenClaw 配置没问题但请求一直超时。3. 安装与初始化从拉代码到跑通第一个对话3.1 安装方式怎么选OpenClaw 官方提供源码克隆和包管理器两种安装方式我推荐源码克隆。原因很简单这个项目迭代很快源码方式git pull就能更新包管理器版本往往滞后。Docker 也可以适合不想污染宿主机环境的人但排查问题时会多一层黑盒本地调试我还是建议原生跑。还有一个现实原因我踩过一次 Docker 网络模式配置不当导致连不上 Ollama 的坑排查起来特别费劲。git clone OpenClaw官方仓库地址 cd OpenClaw npm install仓库地址以 GitHub 上 OpenClaw 官方页面为准不同时期组织名可能会有变化别收藏一堆过时的教程链接。安装依赖时看清 README 要求的是 npm 还是 bun不要凭感觉来。3.2 首次初始化的正确姿势装完依赖先别急着配渠道第一步是初始化配置。启动初始化命令不同版本可能叫openclaw init或claw init以官方文档为准会引导你设置 Agent 名称、人格描述、默认模型。这里我建议 Agent 人格写得具体一点它是谁、擅长什么、回答风格是什么。别小看这段文字它直接影响后续所有对话的质量相当于模型的 system prompt。初始化完成后配置目录下会生成一个主配置文件。这个文件是整个 OpenClaw 的中枢后面所有改动都要动它改完需要重启进程才能生效。建议养成习惯每次大改之前先备份一份。我吃过一次亏有一次改渠道配置把文件结构写坏了进程起不来最后靠备份回滚才救回来。3.3 先用命令行渠道验证很多新手一上来就急着接飞书、Teams结果两边都没配好出了问题都不知道是模型的问题还是渠道的问题。我的建议是第一步永远先跑 CLI 渠道。CLI 是最简单的通道配置里只声明一个 channel 类型然后把 Agent 服务跑起来直接在终端里对话。这一步能验证四件事OpenClaw 进程能不能正常启动、能不能连上 Ollama、模型能不能正常响应、session 系统能不能创建会话文件。这四个环节里任何一个出错都会在 CLI 上暴露出来而且错误信息最原始、最好查。等 CLI 跑通了再往上叠渠道排查范围就小很多。3.4 第一次对话可能遇到的问题第一次对话如果直接卡住不发最常见的三个原因Ollama 服务没起来、模型名写错、内存不够导致模型加载失败。前两个好排查第三个的表现是 Ollama 日志里出现llama runner进程被 killed 的记录。遇到这种情况别愣着先关掉别的占用内存的程序或者换个更小的量化版本模型再试。如果你用的是 7B 以下的小模型响应应该在一两秒内出来超过十秒就要考虑是不是模型加载太慢或者服务地址不对。4. 模型接入配置Ollama、DeepSeek、千问三套实战4.1 配置文件的模型区块逻辑OpenClaw 的模型配置核心就那几个字段provider供应商类型、base_url模型服务地址、model模型名、temperature温度、max_tokens最大输出。不同版本字段名可能有差异但思路是一样的。以 Ollama 为例核心配置长这样llm: provider: ollama base_url: http://127.0.0.1:11434 model: qwen2.5:14b temperature: 0.7 max_tokens: 2048这里的关键是 provider 和 base_url 要对应。Ollama 的接口默认监听 11434 端口OpenClaw 会往/api/chat这类端点发请求。如果你后面换成了别的模型服务比如接一个远程推理网关改 base_url 和 provider 就行Agent 层完全不用动。这就是解耦带来的好处。4.2 DeepSeek 本地版接入社区里问得很多的本地部署 DeepSeek在 Ollama 生态里指的就是deepseek-r1系列。接入配置把 model 换成deepseek-r1:7b就行。有一点要注意r1 是推理模型默认会输出一长串思维链。如果你只想要最终答案可以在 prompt 里加约束或者把 temperature 调低到 0.3 左右让输出更稳定、更聚焦。我实测在 7B 这个量级把 temperature 压到 0.3~0.4回答质量会比默认值明显提高。4.3 千问接入OpenClaw 配置千问这个搜索词热度一直很高其实配置逻辑和上面一模一样只是 model 名换成qwen2.5:14b。千问系列对中文的语义理解明显更顺工具调用的格式稳定性也好一些。如果你的 Agent 经常要调用外部工具我推荐用千问当主力。它还有个好处上下文窗口大长对话不容易断片。4.4 多模型切换的实用技巧OpenClaw 支持在配置里放多个模型配置或者通过环境变量覆盖。我的做法是维护两个配置文件一个默认千问一个切 DeepSeek想换就改一个环境变量再重启。实测下来日常问答千问体验更好需要深度推理的时候切 DeepSeek两者互补比死磕一个模型划算得多。切换脚本写成一行命令幸福感提升很明显。4.5 参数微调的几个数多轮对话场景temperature 建议 0.6~0.8太低会显得机械太高容易跑题。工具调用或任务执行场景建议压到 0.2 以下宁可保守也不要让 Agent 自由发挥。max_tokens 非常关键设置太小长回答会被截断这个后面讲飞书截断问题时还会再遇到。关于上下文长度Ollama 默认有窗口上限长对话中途掉记忆时优先检查是不是触到了上下文上限而不是怀疑 Agent 出了 Bug。5. Channel 接入实战命令行、飞书、Teams5.1 选择 Channel 的核心逻辑OpenClaw agent 怎么选择 channel这个问题我一直觉得问反了。不是 Agent 选 Channel而是你在配置里声明挂哪些 Channel启动时 OpenClaw 自动注册。你声明 CLI它就开一个交互终端你声明飞书它就启动一个飞书机器人服务你声明 Teams它就连接 Teams Bot。本质上 Channel 是一个列表挂多少取决于你的需要。5.2 命令行永远的第一选择CLI 渠道配置量最小却是排查问题的最佳工具。它的优势是日志直接打印在终端上模型返回什么、Agent 中间做了什么一眼就能看到。我建议所有新手完成初始化后至少用 CLI 跑一周把 Agent 的脾气摸清楚再接渠道。别嫌它丑它是你排错时最可靠的阵地。5.3 飞书接入与截断问题的根源接飞书的大致流程是去飞书开放平台创建企业自建应用拿到 App ID 和 App Secret配置机器人能力然后把这个应用添加进目标群或用户会话。OpenClaw 配置里填好凭据启动后它会通过长连接接收消息。很多人卡在这一步多半是权限没开全机器人至少要有接收消息的权限如果 Agent 需要发图片或卡片还要额外开对应权限。飞书一个非常典型的坑是输出截断社区里OpenClaw 在飞书输出容易被截断说的就是它。根因有两层一是模型 max_tokens 设得大回答很长但飞书单条消息有长度上限二是 OpenClaw 通过机器人接口发消息时长文本容易被网关拆分不完整。解决办法后面第 6 章会细讲这里先记住一个原则接飞书之前先把 max_tokens 和分段输出逻辑调好。5.4 Teams 接入需要走一遍 Azure 注册OpenClaw 接入 Microsoft Teams 比飞书繁琐一些因为 Teams 的机器人靠 Bot Framework 体系需要在 Azure 门户注册一个 Bot 应用拿到 Bot ID 和密码然后把消息端点指向 OpenClaw 暴露出来的地址。如果你是纯本地环境、没有公网地址Teams 这步会比较痛苦因为它要求端点可被微软服务回调。所以我的建议是内网优先飞书或企业微信Teams 留给有公网或内网穿透条件的人。想接 Teams 的话先确认你的网络条件能撑起回调再开始注册不然会白折腾一晚上。5.5 多 Channel 并存的体验同时挂 CLI 和飞书是性价比最高的组合。CLI 用来调试飞书用来日常使用同一个 Agent、各自独立的会话上下文。这里有个小经验不同渠道之间的会话是隔离的你在飞书上聊到一半的记录不会出现在 CLI 的会话列表里。想共享上下文得靠 Agent 自己记忆或外部存储这个属于进阶玩法本篇先不展开。6. 实战运行中的高频问题session locked 与截断排查实录6.1 agent failed before reply: session file locked (timeout 60000ms)这个报错是 OpenClaw 社区里出现频率最高的一个问题我迁移后的第三天就撞上了。现象是Agent 收到消息后不回复日志里打出agent failed before reply: session file locked (timeout 60000ms)。先说根因。OpenClaw 用文件来持久化每个会话的状态每次读写会话文件时会加一个锁。当两个进程同时想写同一个会话文件或者上一个进程异常退出后锁没释放新的进程就会一直等等到默认 60 秒超时就直接失败。排查链路我给你完整走一遍第一步看进程。ps aux | grep openclaw如果发现有多个 OpenClaw 进程在跑那就是典型的并发冲突。常见原因是之前启动过一次没正常退出又开了一个新实例。第二步看会话文件和锁文件。去配置目录下找到 session 相关的目录ls -la看有没有残留的.lock文件。锁文件是上次进程退出没清理的痕迹。第三步处理。把多余进程杀掉删掉残留的.lock文件再重启。我那次的问题就是旧进程残留杀掉之后秒好。如果这个问题反复出现说明你可能经常用多种方式拉起多个实例。解决方案有两个方向一是保证同一时间只跑一个 OpenClaw 进程用 systemd 或进程守护工具统一管理二是把锁超时时间调大但这是治标不治本只要有多进程冲突迟早还会撞。6.2 飞书输出截断不只是调 max_tokens飞书截断问题我排查了很久最后发现是两层叠加。第一层模型侧max_tokens 设置过小回答长一点就被模型自己截断。这个好办把 max_tokens 从 2048 调到 4096 甚至更高。但注意调大之后会带来第二层问题飞书单条消息长度上限挡住了。第二层渠道侧飞书机器人发消息单条文本有长度限制超过就会被网关截掉。OpenClaw 的处理方式一般是把长输出拆成多条消息发送但如果你用的版本拆得不够细或者中间带了卡片格式就容易出现只发了前半段的情况。我的解决方案是组合拳先把模型 max_tokens 控制在一个合理范围比如 2000~3000 之间同时确保配置里启用了长文本自动分段。如果你需要单条超大输出那得换消息卡片或者改发文件的方式这个就属于定制开发了。另外还发现一个小规律飞书截断很多时候跟网络也有关系内网自建飞书机器人比走公网稳定得多。6.3 其他三个高频小坑model not foundOllama 里没这个模型或者模型名写错。ollama list核对一下。内存不足导致 Ollama 进程被杀看系统日志确认是 OOM换小模型或加 swap。时区错乱Agent 记录时间不对多半是宿主机时区没设对用timedatectl设置后再重启服务。这三个问题都不复杂但每个都足够让新手卡半天。排查顺序永远是先看日志再查配置最后怀疑环境。日志会告诉你大部分答案别一上来就重装。7. 调优与长期维护让它稳定跑三个月7.1 内存占用的持续压测本地部署最大的敌人是内存。我 32GB 的机器挂了一个 14B 模型加 OpenClaw 本体平时占用大概 12GB 左右。如果同时开太多会话或者模型 keep_alive 时间设置太长内存会被慢慢吃满。Ollama 有个参数叫 keep_alive控制模型在内存中保留的时间默认是 5 分钟。如果你的使用模式是时断时续的建议把 keep_alive 调短比如设置环境变量OLLAMA_KEEP_ALIVE5m避免闲置模型一直占内存。如果内存实在吃紧加一个 8GB 的 swap 分区也能救急但别指望它在高负载时给你多好的性能swap 频繁触发时整个系统都会卡。7.2 配置管理备份与回滚配置文件是 OpenClaw 的全部家当。我的习惯是每次改动前cp一份带日期的备份放在同级目录。改坏了直接回滚不用重新初始化。如果你用 Git 管理配置目录那就更好了每次改动都有历史记录出问题还能 diff 出来到底改了什么。7.3 会话文件的清理策略session 文件会随着对话增多而膨胀。长时间不清理启动和读写都会变慢。我一般一个月清一次保留近半个月的会话更早的压缩归档或直接删。清理前记得先备份有些对话记录后来想找回来就会发现备份的价值。7.4 升级时机与方式OpenClaw 迭代速度很快不建议每出一个版本就升级但也不建议长期不升。我的做法是看 Release Notes如果修复的 bug 恰好是我遇到的或者新增了我需要的 Channel就git pull然后重启。升级前一定先备份配置目录别偷懒。这条经验是我用一次升级把渠道配置搞坏之后总结出来的。7.5 善用日志与健康检查OpenClaw 的日志是排错的第一现场。如果服务是 systemd 托管的用journalctl -u openclaw -f实时跟踪输出如果是前台进程把输出重定向到日志文件。另外可以做一行健康检查脚本定时探测本地 Ollama 接口和 OpenClaw 进程状态挂了自动重启#!/bin/bash if ! curl -sf http://127.0.0.1:11434/api/tags /dev/null; then systemctl restart ollama fi if ! pgrep -f openclaw /dev/null; then systemctl restart openclaw fi这套东西配好之后基本可以做到半年不去动它。最后分享一个我实际用下来的习惯本地部署 OpenClaw 真正舒服的地方在于它可以 7x24 小时挂机。我现在把它同时挂到了命令行和飞书群里白天随手丢任务晚上回来让它输出一份当日总结。建议你也从命令行跑起等模型和 Agent 的脾气摸熟了再一个个接渠道不要一上来就摊大饼。希望这篇指南能让你少走点弯路早点把属于自己的 AI 助手跑起来。