如果 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~5GB，14B 模型 Q4 大约占 9~10GB，再加上 OpenClaw 本体（Node 进程通常占 300~600MB）和系统开销，16GB 机器跑一个 7B 就基本到顶了，32GB 机器才能舒服地跑 14B 或者同时挂两个模型。如果你有 NVIDIA 显卡且显存 8GB 以上，模型加载可以走 GPU，CPU 和内存压力会小一些。
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:7b | 7B | ~5GB | 日常对话、通用任务 |
| qwen2.5:14b | 14B | ~10GB | 中文处理、工具调用、代码 |
选型逻辑很简单：中文为主的场景优先千问，推理链路长的场景优先 DeepSeek。如果你只有 16GB 内存，那建议只装一个 7B 级别的模型，别贪。模型文件体积不小，7B 的 GGUF 大概 4~5GB，14B 大概 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_HOST=0.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 接入实战：命令行、飞书、Teams
5.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 found：Ollama 里没这个模型，或者模型名写错。ollama list核对一下。- 内存不足导致 Ollama 进程被杀：看系统日志确认是 OOM，换小模型或加 swap。
- 时区错乱：Agent 记录时间不对，多半是宿主机时区没设对，用
timedatectl设置后再重启服务。
这三个问题都不复杂，但每个都足够让新手卡半天。排查顺序永远是：先看日志，再查配置，最后怀疑环境。日志会告诉你大部分答案，别一上来就重装。
7. 调优与长期维护：让它稳定跑三个月
7.1 内存占用的持续压测
本地部署最大的敌人是内存。我 32GB 的机器，挂了一个 14B 模型加 OpenClaw 本体，平时占用大概 12GB 左右。如果同时开太多会话或者模型 keep_alive 时间设置太长，内存会被慢慢吃满。Ollama 有个参数叫 keep_alive，控制模型在内存中保留的时间，默认是 5 分钟。如果你的使用模式是时断时续的，建议把 keep_alive 调短，比如设置环境变量OLLAMA_KEEP_ALIVE=5m，避免闲置模型一直占内存。如果内存实在吃紧，加一个 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 助手跑起来。
