最近在折腾 OpenClaw 的本地部署前后踩了几天坑总算把整个流程理顺了。这篇东西不是官方文档的复述是我自己从零开始、在 Windows 和 Linux 两台机器上分别跑通全流程的记录包括环境准备、模型对接、Channel 配置、常见报错排查这些照着做基本能少走一大半弯路。如果你正准备把 OpenClaw 跑在本地电脑上或者已经在部署过程中被各种报错折磨这篇文章应该能帮到你。先说明一下OpenClaw 在社区里也有人叫它“龙虾”是一个开源的 AI Agent 框架核心作用是把你本地的 LLM比如通过 Ollama 跑的千问、DeepSeek接上各种即时通讯渠道让你用聊天软件就能指挥本地模型干活。适合三类人想完全离线跑 AI 助手的隐私敏感用户、需要把 Agent 接入飞书/Teams 等团队协作场景的开发者、以及单纯想低成本玩大模型的折腾党。1. 搭建前必须搞懂的几件事1.1 为什么选本地部署而不是直接用云 API在开始动手之前先聊清楚一个问题你为什么要本地部署我最初的目的很简单——不想把对话内容发到第三方服务器而且本地跑从长期看成本更可控。本地部署 OpenClaw 最大的优势有两个。第一是数据安全所有对话记录、Prompt、工具调用日志都留在自己机器上适合处理内部资料、代码片段这类敏感内容。第二是稳定性不依赖外部 API 的可用性和限流策略就算外网断了局域网内照样能用飞书或 Teams 继续指挥 Agent。代价也很明显你需要一台配置还行的电脑至少 16GB 内存32GB 更舒服以及一个量化过的本地模型。别指望本地跑个 7B 模型能有 GPT-4 那样的智能水平但在特定任务上比如按照固定格式整理日报、检索本地知识库、执行预设的自动化流程完全够用。1.2 OpenClaw 的核心架构一张图看懂各组件关系我花了比较长时间才把 OpenClaw 的架构理清楚其实它不复杂核心就三块内核OpenClaw Core负责管理会话、调用工具、编排多轮对话逻辑。你可以把它理解成“大脑中枢”所有任务调度都在这里完成。通道Channel负责对接各种 IM 平台比如飞书、Microsoft Teams、Discord、Slack。Channel 的作用是“翻译官”把平台的消息格式转换成内核能理解的内部消息格式。模型后端LLM Backend通过 Ollama 或其他兼容接口加载本地模型。内核向模型后端发请求拿到回复后再通过 Channel 发回聊天窗口。三者之间的关系可以这样理解你在飞书里发一条消息飞书 Channel 收到消息后转换成标准格式交给内核处理。内核判断该调哪个工具、要不要向模型请求回答然后调用模型后端生成结果最终原路返回。整个链路是“IM平台 → Channel → Core → LLM Backend → Core → Channel → IM平台”。这个架构带来的直接好处是解耦——你想换模型就直接改 Ollama 里的模型文件想换聊天平台就换 Channel 配置互不影响。2. 环境准备Windows 和 Linux 两条路线2.1 最低硬件要求与系统兼容性先说硬性条件这是我在两台不同配置的机器上实测下来的结果组件最低要求推荐配置备注CPU4 核8 核以上推理时 CPU 也会全力跑内存16GB32GB内存不够直接决定你能不能跑 7B 以上模型硬盘20GB 空闲50GB 以上 SSD模型文件动辄 4-7GB别用机械盘GPU不需要NVIDIA 显卡可选没有 GPU 也能跑但速度会慢不少系统Windows 10/11、Ubuntu 20.0464 位系统macOS 也能跑但不是主流方案如果你用的是飞牛fnOS这类 NAS 系统也可以装但流程稍有区别后面会单独提。核心思路是一样的先确认系统里有 Node.js18 以上或者 Python 3.10然后安装 Ollama最后部署 OpenClaw 本体。2.2 Ollama 部署模型从哪来、怎么下OpenClaw 本身不带模型它是一个管理框架真正干活的是后端模型。我目前主力用的是 Ollama原因很简单它把模型管理做到了真正的傻瓜级。Ollama 的安装不用多说官网下载对应系统的安装包Windows 直接装 exeLinux 用安装脚本装完以后先验证一下是否正常工作。在终端执行ollama list如果显示空列表说明安装成功但还没下载模型。下载模型前先想清楚你更需要中文能力还是通用能力。如果你主要做中文办公场景千问系列是不错的选择如果你更看重通用代码能力DeepSeek 或者 Llama 系可以纳入考虑。以我目前的主力配置为例千问 7B 量化版ollama pull qwen2.5:7b这一步会下载几个 GB 的文件网速正常的话大约 10-20 分钟。下完以后立刻验证一下ollama run qwen2.5:7b输入任意问题如果模型能正常回复就可以退出并进入下一步。处理不了中文问答就先检查是不是模型选错比如选了纯英文优化的版本或者本地内存不足导致模型加载失败。这一步不验证好后面 OpenClaw 接上了也是白接。2.3 Windows 上安装 OpenClaw 的完整流程Windows 上的安装其实比大多数教程写的更简单但坑也最多尤其是路径和权限。官方推荐的 Windows 安装方式是通过 WindowShub一个 Windows 下的终端管理工具拉取安装脚本实际操作分这几步以管理员身份打开 PowerShell执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser不执行这一步的话后面的安装脚本会被系统默认策略拦住。检查 Node.js 版本node -v如果提示找不到命令去 Node.js 官网下载 LTS 版本一路默认安装即可。安装 OpenClawnpm install -g openclaw这里注意如果你之前装过旧版本先卸载干净再装新的。否则你会碰到各种奇奇怪怪的依赖冲突。卸载命令npm uninstall -g openclaw验证安装是否成功openclaw --version有版本号输出说明装好了。这时候别急着配置先初始化工作目录——我建议专门建一个openclaw-workspace文件夹避免配置文件散落各处后面备份和迁移也方便。初始化命令openclaw init运行后会在当前目录生成配置文件一般是openclaw.json或config.yaml具体看你选择的配置格式这时 OpenClaw 的本体已经就绪了。2.4 Linux 服务器部署要点Ubuntu/Debian如果你的运行环境是 Linux步骤更直接一些。以 Ubuntu 22.04 为例先确保装了 Git 和 curlsudo apt update sudo apt upgrade -y sudo apt install -y git curl build-essential然后克隆 OpenClaw 仓库如果官方仓库更新以仓库地址为准我用的社区镜像分支git clone https://github.com/openclaw/openclaw.git cd openclaw接下来有两种安装方式直接用 npm 全局安装或者拉 Docker 镜像。我个人比较推荐 Docker 方式因为隔离性好卸载也干净。OpenClaw 提供的容器化部署命令大致是docker pull openclaw/openclaw:latest docker run -d --name openclaw \ -p 3456:3456 \ -v /your/config/path:/app/config \ openclaw/openclaw:latest注意挂载配置目录时宿主机路径一定用绝对路径且授权给当前用户可读写。很多人第一次启动容器失败都是因为配置文件目录权限不对容器内进程无法读取。如果你用的是飞牛 NAS本质也是 LinuxDocker 兼容性没问题建议直接走 Docker 路线进飞牛的 Docker 管理界面填一下镜像名然后把端口映射和目录挂载配好就行。3. 模型对接让 OpenClaw 真正会“说话”3.1 通过 Ollama 接入千问 / DeepSeekOpenClaw 默认的模型配置是通过环境变量或配置文件里的model字段指定的。我建议直接在配置里写环境变量方便以后切换模型。在 OpenClaw 的配置文件中找到与模型相关的设置项填入后端地址和模型名{ model: { provider: ollama, baseUrl: http://localhost:11434, name: qwen2.5:7b, temperature: 0.7 } }如果你用的是 DeepSeek 本地版ollama pull deepseek-r1:7b然后把上面配置里的name换成deepseek-r1:7b即可。注意一点不同的 Ollama 模型标签对应不同量化级别和参数量别只看名字就下要看清楚是 7B 还是 14B是 Q4 量化还是 Q8这直接决定你的内存撑不撑得住。3.2 调整上下文长度和生成参数避免答非所问模型接上之后我发现一个实际问题OpenClaw 在长对话中容易“失忆”。具体表现是前面聊得好好的几轮以后它开始重复问你已经给过答案的问题。这个问题通常不是模型本身笨而是上下文窗口太短或者是配置里的maxTokens限制太紧。在 Ollama 里你可以在启动模型时指定上下文长度ollama run qwen2.5:7b --num-ctx 8192如果是通过 OpenClaw 的配置文件控制找到生成参数相关字段{ model: { maxTokens: 2048, temperature: 0.7, topP: 0.9, stream: true } }这几个参数的经验值日常对话温度用 0.7 比较自然但如果你用它跑代码生成或结构化整理温度调到 0.2-0.3 会更稳定。topP保持 0.9 就好太高容易啰嗦。maxTokens决定了单次回复的最长长度如果模型经常说到一半被切断可以把值往上调。3.3 macOS 本地跑模型需要注意的地方在 macOS 上部署的思路其实和 Linux 一脉相承但有几点体验差异很大。首先是 Ollama 的安装Mac 版有专门的应用包装完之后菜单栏会常驻一个小图标那是 Ollama 的后台服务别手滑退掉其次是模型选择Mac 的 GPU 是共享显存理论上内存够大就能跑比较大的模型但实际跑起来会发现降频发热是常态建议 M 系列芯片从 7B 模型起步别一上来就挑战 32B。如果你还打算在 Mac 上给 OpenClaw 装代理通道比如接 Teams那么建议不要用系统自带的网络设置去搞全局代{过}理直接在 OpenClaw 的 channel 配置里指定网络出口更干净也不会影响其他程序。4. Channel 配置打通飞书、Teams、Discord4.1 怎么选 Channel核心逻辑是什么OpenClaw 里一个很容易搞混的概念是“Agent”和“Channel”。简单来说Agent 是逻辑主体Channel 是连接渠道。一个 Agent 可以同时在多个 Channel 上工作也就是说你可以在飞书里和它聊天同时也通过 Teams 向同一个 Agent 发任务。选择 Channel 的维度其实就四句话团队用什么聊天软件就用什么通道一个人用 IM 效率最低配合 Web UI 更顺手需要隐私隔离就选自建通道调试阶段宁可先跑本地控制台通道。我的建议是刚开始调试时先只开一个本地测试通道确认模型响应正常后再接飞书或 Teams。这样可以避免把“模型配置问题”和“消息通道问题”混在一起排查。安装一个 Channel 本身的步骤在 OpenClaw 里通常是用一句命令完成的比如openclaw channel add channel-name这个命令会引导你进行授权不同平台的授权逻辑不同飞书需要你创建一个企业自建应用并配置权限Teams 需要你在 Azure 门户注册一个 bot 应用Discord 则是创建一个 Bot 并粘贴 Token。授权完成后OpenClaw 会把凭证信息加密存储在配置目录里不会二次问你要。4.2 接飞书的具体步骤和常见坑我在飞书上的接入过程比较顺利大体上四个步骤进入飞书开放平台创建企业自建应用在应用权限里开启“接收消息”和“发送消息”两个权限配置事件订阅URL 填 OpenClaw 暴露的公网地址或局域网地址按你的实际部署方式在 OpenClaw 里执行openclaw channel add feishu然后按提示填入 App ID 和 App Secret之后就可以在飞书里私聊你的机器人试试效果了。坑点主要有一个很多人以为事件订阅 URL 填完就万事大吉其实飞书会发送一个验证请求如果你的 OpenClaw 服务没有正在运行验证永远不通过。所以顺序应该是“先启动 OpenClaw再配置事件订阅 URL”启动后立刻去飞书后台点击验证。另一个我遇到过的坑是飞书消息长度限制。OpenClaw 在飞书里输出长文时容易被截断原因是飞书对单条消息长度有硬性限制超过之后会直接切断。这个问题的解决办法不是去改 OpenClaw 的源码而是开启消息分段发送功能。在配置文件里找到 channel 相关设置开启消息分段大概字段名是enableMessageSplitting或者类似含义的开关并且在飞书后台确保机器人有“发送富文本”的权限不然分段以后的消息可能变成纯文本格式。4.3 接入 Microsoft Teams 的实操记录Teams 的接入比飞书麻烦一些要在 Azure 门户走一圈。我第二次配的时候大概花了半小时主要时间都耗在权限理解上。核心流程是到 Azure 门户注册一个应用 → 启用 Bot Channel → 获得 App ID 和 Client Secret → 回到 OpenClaw 配置。{ channels: { teams: { enabled: true, appId: your-app-id, appSecret: your-client-secret, tenantId: your-tenant-id } } }注意一个细节Teams 的 Bot 认证里tenantId是可选项但如果你的组织启用了条件访问策略不填就有可能导致认证失败。填了以后如果出现代{过}理或防火墙报错优先检查网络出口策略。接完 Teams 以后我测试了一下私聊和群聊场景。私聊场景下Teams 默认会给机器人发所有消息群聊场景下需要你手动在团队里添加机器人并且标签机器人的方式是在消息中Bot名称。很多群聊没反应的原因其实就是忘了 或是 Bot 没有被加到那个频道里。4.4 其他 ChannelDiscord/Slack简述Discord 和 Slack 的接入思路都是一样的创建一个 Bot → 拿到 Token → 在 OpenClaw 里加 Channel → 把 Bot 拉进服务器/频道。只不过 Discord 的 Token 是在 Discord Developer Portal 里创建 Bot 后拿到的而 Slack 需要你先建一个 App 并开启 Socket Mode。从我的实际体验看自建本地 Agent 最常用的其实还是飞书和 Teams。Discord 更适合个人玩家或者小圈子的极客环境Slack 则是海外团队用得比较多。如果你的使用场景是纯自用我更推荐用 OpenClaw 自带的 Web Chat 界面如果支持的话省去授权和公网暴露的麻烦。5. 实战运行第一次启动到稳定跑起来5.1 初始化配置与目录结构弄完了模型和 Channel 配置接下来就是正式启动了。第一次启动之前建议先把配置内容完整检查一遍。我的配置文件最终长这样省略敏感信息版{ agent: openclaw, model: { provider: ollama, baseUrl: http://localhost:11434, name: qwen2.5:7b }, channels: { feishu: { enabled: true, appId: ..., appSecret: ... } }, storage: { sessionDir: ./sessions, logDir: ./logs } }注意这个sessionDir字段这就是后面要重点处理的会话文件目录。OpenClaw 会把每个对话会话记成一个文件如果有人没有正常退出文件就会一直处于锁定状态这个后面会解释。检查完毕以后首次启动openclaw start如果是 Docker 部署则docker start openclaw docker logs -f openclaw看到类似“started”或“listening on port 3456”的日志就说明主程序正常了。5.2 验证模型响应和 Channel 连通性主程序起来了不代表一切正常。我习惯分四层验证第一层本地控制台测试。看 OpenClaw 的控制台日志里有没有报错。第二层直接调用模型接口测试。在浏览器访问http://localhost:11434/api/generate或检查 Ollama 日志确认模型服务正常。第三层通过测试 Channel 向 Agent 发消息。这一步能确认内核消息路由没问题。第四层通过真实 IM 平台发消息。确认 Channel 到平台的链路是通的。我建议至少跑通前三层再继续否则遇到问题的时候很难定位到底出在哪一环。第一次跑通飞书对话的时候我确实有一种“世界被打开”的感觉。在飞书里跟自己的本地模型聊天的体验跟网页版聊天完全不一样——更像是跟一个接入你工作流的同事说话可以直接在聊天窗口里让它整理纪要、查资料、输出结构化内容。5.3 让它跑在后台systemd 和 Docker 的守护配置本地部署要想长期稳定跑不能每次都开一个终端窗口挂着。Linux 下最稳的方式是配置 systemd 服务。新建一个服务文件openclaw.service[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Useryourusername WorkingDirectory/path/to/openclaw ExecStart/usr/bin/openclaw start Restartalways RestartSec10 [Install] WantedBymulti-user.target然后执行sudo systemctl enable openclaw sudo systemctl start openclaw以后就不用管了开机自启、崩溃自动拉起。Windows 下没有 systemd我一般用两种方式一种是任务计划程序开机触发或登录触发另一种是开一个专门的 PowerShell 窗口跑openclaw start用 NSSMNon-Sucking Service Manager把它注册成 Windows 服务也很省心。6. 高频报错与排查技巧实录6.1 “session file locked”报错起因和解决热词里有一个很典型的报错agent failed before reply: session file locked (timeout 60000ms)。我第一次遇到这个报错的时候完全懵了——明明什么都没干怎么就锁定了实际上OpenClaw 的会话管理机制是每个会话对应一个 JSON 文件当某个进程正在处理这个会话时文件会被加锁防止并发写坏数据。如果你的上一次对话进程没有优雅退出比如直接关掉终端、机器强制重启锁没有释放新请求进来时发现锁文件还在就会出现这个报错。解决办法分三个层次最简单删掉锁文件。在会话目录下找到对应的.lock文件或同名的锁标记删掉后重启 OpenClaw。更稳妥查一下是不是真的还有 OpenClaw 进程在跑。用ps aux | grep openclawLinux或任务管理器Windows确认没有残留进程后再删。治本在配置里开启会话空闲自动释放。把sessionTimeout调整到一个合理值比如 300 秒让长时间没有活动的会话自动释放锁。我用的是 300 秒太短会导致长任务被误杀太长则可能堆积很多死锁。如果你用的是 Docker 部署这个报错的频率更高因为容器异常退出时文件锁往往来不及释放。你可以在启动容器时加--restart unless-stopped或者加一个启动时清理锁文件的脚本。6.2 飞书输出截断分段发送与富文本前面已经提到了飞书单条消息长度限制导致的截断问题这里再补充一下具体的操作过程。首先在 OpenClaw 的配置里找到飞书 Channel 的设置开启消息分段发送如果配置文件里没有这个字段说明当前版本支持得比较隐晦需要手动在feishu配置块里加enableMessageSplitting: true。有个细节很容易忽略飞书机器人默认权限只允许发纯文本导致分段后每段被当作文本消息发送长段落中的换行、加粗全部丢失。解决办法是到飞书开放平台为机器人添加“获取群组中所有消息”“发送消息”等完整权限同时在事件订阅里开启im.message.receive_v1。权限没到位就算 OpenClaw 里配置了分段也没用。6.3 启动时报错找不到模块与基本排查套路无论 Windows 还是 Linuxnpm 全局安装后概率遇到的一个问题就是——明明装好了启动时报 “Cannot find module ‘xxx’”。这种问题绝大多数情况下是 Node.js 版本和依赖版本冲突或者全局包的路径没有被系统识别。两个排查命令# 检查全局安装路径 npm config get prefix # 检查路径是否在环境变量里 echo $PATH如果全局路径不在 PATH 里Linux 可以临时加上export PATH$PATH:$(npm config get prefix)/binWindows 则在系统环境变量里把 Node.js 的全局node_modules目录添加进去然后重开终端。如果还是不行干脆换个思路用npx openclaw start直接调用能绕开大部分路径问题。6.4 高频问题速查表问题表现可能原因推荐解法Ollama 模型下载缓慢网络问题或并发限制检查下载源分批下载小模型或手动下载后导入启动后无响应端口被占用改端口号或查占用进程lsof -i:3456飞书机器人不回复事件订阅 URL 未验证或权限不齐重启 OpenClaw重新验证订阅 URL检查应用权限Teams 登录后无反应Azure Bot 渠道未正确配置重新注册 Bot确认 App ID/Secret检查租户信息内存占用过高导致卡顿模型过大或并发会话多换更小量化模型限制并发会话数长时间没回复后连接中断会话超时或网络空闲断开调整 sessionTimeout检查 IM 平台的连接保持策略这些坑我都一个个踩过而且很多问题在中文社区找不到答案只能对着日志一步一步试。所以我在文中尽量把报错信息和当时的环境写清楚了方便你搜索时对号入座。7. 从能用到好用OpenClaw 的进阶玩法7.1 多个 Channel 协同与独立 Agent 配置当你跑通了一个 Agent 和一条 Channel下一步通常是多 Channel 协同。OpenClaw 本身支持在配置里定义多个 Agent并为每个 Agent 指定不同的模型、不同的场景描述、不同的 Channel 权限。比如{ agents: [ { name: daily-assistant, model: { provider: ollama, name: qwen2.5:7b }, channels: [feishu], systemPrompt: 你是一个帮团队写周报和日报的助手 }, { name: code-helper, model: { provider: ollama, name: deepseek-r1:7b }, channels: [teams], systemPrompt: 你是一个代码审查助手专注解释和生成代码 } ] }这样就可以实现飞书里跑日常办公助手、Teams 里跑代码助手相互之间隔离互不干扰。这对团队场景非常实用每个人各用各的机器人但底层模型都在同一台机器上资源利用更高效。7.2 结合 RAGFlow 做本地知识库问答如果你已经有一套本地知识库比如公司内部文档、产品手册可以考虑把 OpenClaw 和 RAGFlow 或者其他知识库引擎搭在一起。基础思路是OpenClaw 收到问题时先用 RAGFlow 检索相关知识片段再把这些片段作为上下文附带发送给模型。我用下来的体验是这个组合能大幅减少模型失真回答。没有本地知识库的时候模型遇到不清楚的问题就是一本正经地编接上知识库以后至少知道在文档里找依据。配置方式不复杂在 OpenClaw 里加一个知识库工具调用然后把 RAGFlow 的 API 地址和 API Key 填进去就行。如果你只是想快速体验这个能力也可以先手动把文档塞进 Prompt 上下文里但别试太长文档一旦超过上下文长度模型就开始胡言乱语了。7.3 OpenClaw 与 WorkBuddy、MiniMax H3 的横向对比最近社区里很多人问 OpenClaw 和 WorkBuddy 怎么选MiniMax H3 本地部署能不能接 OpenAI 接口。我的判断是OpenClaw 的优势在于开源、配置灵活、Channel 多适合自己折腾WorkBuddy 那种集成度高的工具更适合不想花太多时间在配置上的人但可定制性弱不少。MiniMax H3 的情况比较特殊它对中文优化做得很好如果你有充足的内存起码 32GB非常建议拿它跑一个专门的 Agent 来处理中文长文任务。只要它提供兼容 OpenAI 的 API 格式接 OpenClaw 就是改baseUrl和name两个字段的事。7.4 后续可以这样扩展这里先分享一个我个人常用的扩展方向让 OpenClaw 定时干活。比如每天早上 9 点自动整理昨天的项目日志或者每小时轮询某个接口并把变化推送到飞书群里。这个思路利用的是 OpenClaw 作为 Agent 的任务调度能力不需要额外写复杂代码在配置里加一个定时任务描述就能开始尝试。不过别一上来就搞太复杂的自动化先让它干一件最简单的事比如每天定时在工作群里说一句“早上好今日待办已生成”跑几天确认稳定了再逐步加更多能力。我刚开始就是贪多结果一次加了五个任务排查起来费了很多时间。最后再给你几个经验总结OpenClaw 这套东西如果你只是照着一篇教程从头到尾跑一遍大概率会遇到教程里没写的问题。我这里分享几个自己摸索出来的经验。第一所有配置文件改完以后重启 OpenClaw 之前先做语法检查。JSON 格式多一个逗号少一个括号启动时就报错有时候错误信息还特别隐晦。用openclaw config validate如果有这个命令检查一下能省掉大量查错时间。第二日志永远是你最好的老师。不要一上来就上网搜报错信息先看 OpenClaw 自己的日志找到出错的组件到底是模型还是 Channel 还是内核再去解决问题。排查工具分清了“链路”之后绝大多数问题都能在十分钟内定位。第三如果你有 NAS 或闲置的 Linux 小主机强烈建议把 OpenClaw 部署在上面而不是主力电脑。因为本地模型一旦跑起来风扇狂转、内存吃紧是常有的事放在 NAS 或远程小主机上体验会舒服很多。飞牛上部署 OpenClaw 就是大众做法只要你的 NAS 支持 Docker 就能跑起来。最后一句话收束一下吧本地 AI Agent 的真正价值不在于它能回答多难的问题而在于它把大模型的力量收敛到了一个你可以完全控制的边界里。这台机器只属于你模型只属于你对话记录也只属于你。在折腾 OpenClaw 的这个过程中你真正获得的不是一个跑通的机器人而是一套属于你自己的 AI 工具箱。