1. 为什么我在本地办公电脑上跑一个龙虾先说句实在话OpenClaw 这套东西第一眼看上去很像又一个大而全的 AI Agent 平台网上铺天盖地的都是AI 接管电脑数字员工这类口号实际部署的路数却被写得稀碎。我最初也是抱着试试的心态想着反正本地已经有 Ollama 和几个开源模型不如把这个龙虾有人叫 OpenClaw有人叫龙虾其实都是同一个项目装到办公电脑上让它去处理一些需要组合工具的杂活。但真正动手之后我才发现OpenClaw 的价值恰恰在于本地优先这四个字。它不像某些云端 Agent 平台那样需要把数据送到第三方服务而是可以完全跑在你自己控制的机器上模型走本地 Ollama工具调用、浏览器自动化、飞书/Teams 消息收发也都由你在配置文件里说了算。对于经常接触内部文档、客户资料的人这个特性意味着数据不出本机安全性直接高了一个档次。这篇博文不是官方文档的复读也不是照着仓库 README 念一遍。我会把我实际部署过程中踩过的坑、试错后的取舍、以及那些文档里没写但你迟早会遇到的问题按一条完整的踩坑链路整理出来。适合谁看适合准备在 Windows、Mac、Linux 甚至 NAS 上跑 OpenClaw并希望接上 DeepSeek、千问或者本地 Ollama 模型的人。不管你是第一次听说龙虾还是已经装到一半卡在报错上这篇文章应该都能给你一点参考。2. 部署前的环境准备不要把第一步走成最后一步2.1 硬件门槛到底需要什么配置OpenClaw 本身是一个控制编排框架真正吃资源的是它调用的本地大模型。如果你完全没有显卡又非要跑 27B 的千问那体验会非常痛苦。我的建议是分三种情况看纯 CPU 环境只适合跑 7B 以下的量化模型或者干脆把 OpenClaw 当成一个中转大脑模型请求转发到远程 API。有 8GB 以上显存的消费级显卡可以跑 Q4 量化的 7B~14B 模型DeepSeek-R1-Distill-Qwen-7B、Qwen2.5-7B 这类都比较顺畅。内存 32GB 以上、显存 16GB 以上可以尝试 27B~32B 级别的模型但推理延迟会明显升高Agent 的响应速度会变成瓶颈。实测下来OpenClaw 本身的常驻内存占用其实不高编译后的核心进程大概 300~500MB。它真正的问题是会话恢复当多轮对话历史很长且你同时挂了浏览器操作、飞书机器人、Teams 等多个 channel 时内存会涨得很快。所以如果你的办公电脑只有 16GB 内存建议在配置文件里限制对话历史轮数或者只开两个 channel否则很容易触发下文要说的 session 锁问题。2.2 运行时选择Docker、二进制还是源码OpenClaw 官方目前提供三种部署姿势源码运行、Docker Compose 部署、以及各个平台的一键安装脚本。我的建议是办公电脑上优先用 DockerNAS 上也优先用 Docker只有你自己要改核心代码才选源码。Docker 方案的最大优势是隔离环境和一条命令回滚。OpenClaw 的依赖关系比较复杂它同时涉及 Node 子进程、Python 工具脚本、浏览器自动化组件直接装在宿主机上一旦版本冲突排错非常痛苦。我见过有人在 Windows 上装了 Python 3.12 和 Node 22结果 OpenClaw 内部某个依赖还停留在旧的 API 上跑起来全是诡异报错最后把系统搞乱了。用 Docker 镜像的话这些依赖全锁在容器里宿主只需要一个 Docker 引擎就行。如果你执意要用源码跑请务必注意安装依赖时不要用npm install一把梭因为项目里有一部分 Python 侧的依赖是独立管理的需要单独处理。很多人卡在启动阶段不是代码问题而是这两套依赖只装了一半。2.3 本地模型选型DeepSeek、千问还是 Minimax H3OpenClaw 本身不绑定模型你可以把它理解成一套大脑插槽只要模型支持 OpenAI 兼容的接口就能接进来。热词里有 DeepSeek、千问、Minimax H3我分别说下我的实际感受。DeepSeek 系列如果走本地部署推荐 DeepSeek-R1-Distill-Qwen-7B指令遵循能力在 Agent 场景里表现不错工具调用的 JSON 输出比较稳定。如果你有云端 API 的预算也可以把 DeepSeek 的官方 API 作为 provider 配进 OpenClaw本地只负责流程控制这样延迟会低很多。千问Qwen系列Qwen2.5-7B-Instruct 在我这边的表现是最听话的多轮对话不容易跑偏尤其是让龙虾去操作浏览器时它给出的步骤更符合直觉。本地显存够的话Qwen2.5-14B 会更稳但为了这么个 Agent 把显存吃满是否划算你要自己掂量。Minimax H3属于比较新的模型很多人问怎么在 OpenClaw 里接。它通常走的是在线 API配置方式跟 OpenAI provider 类似填入 API Key 和 base_url 就行。我不建议在本地强行部署 H3 系列的原始权重参数规模太大家用环境扛不住除非你有专门的 GPU 服务器。3. 安装 OpenClaw 的三种路径与踩坑记录3.1 Windows 办公电脑别用 PowerShell 硬跑在 Windows 上安装 OpenClaw最省事的是用 WSL2 装 Docker Desktop然后在 WSL 里跑容器。直接在本机 PowerShell 里跑官方安装脚本不是不行但会遇到两个问题一是 Windows 的路径分隔符会让某些 Node 脚本报错二是浏览器自动化组件在 Windows 桌面环境中权限不够稳定经常出现页面打不开但进程还在的情况。我的操作路径是这样的安装 WSL2Ubuntu 22.04分配 8GB 内存。在 WSL 内安装 Docker Engine而不是 Docker Desktop因为办公电脑上 Desktop 的许可证和资源占用都麻烦一些。克隆 OpenClaw 仓库到 WSL 的~/openclaw目录。复制模板配置文件修改模型 provider 和 channel 配置。执行docker-compose up -d启动。启动后不要急着关终端第一次启动要拉镜像、初始化 SQLite 数据库、启动浏览器自动化服务整个过程在普通网络环境下可能需要十几分钟。我当时以为卡死了差点 CtrlC实际上只要日志在动就没问题。3.2 Linux 服务器 / NAS飞牛、群晖都能装Linux 部署是最顺的基本就是 Docker 一条路。热词里有人问飞牛安装 openclaw实际上飞牛 OS 是基于 Debian 的 NAS 系统只要它的套件中心支持 Docker就能照常跑容器。唯一要注意的是端口映射OpenClaw 默认管理端口不要跟 NAS 已有的 Web 服务冲突我习惯把管理端口映射到 8765然后通过反向代理走域名访问。群晖、威联通也是同理。这些 NAS 的 Docker 管理界面虽然方便但环境变量配置往往要一个字段一个字段填容易漏。我建议绕过 GUI直接在 SSH 里用docker compose文件启动这样配置可以版本化管理换机器迁移也方便。3.3 一键脚本到底能不能用官方提供了一键安装脚本这个脚本在干净的 Linux 或 macOS 上确实好用。但在 Windows 上运行它本质上是调用一堆依赖到用户目录出了问题极难定位。另一个坑是脚本默认会安装最新版 Node 和 Python如果你机器上已经有其他项目依赖的旧版本全局升级后那批项目就挂了。所以我给个偏保守的建议部署环境越干净越用脚本影响范围越大越用 Docker。办公电脑上千万不要图省事跑一键脚本。4. 把大脑接进来模型 Provider 配置的完整思路4.1 OpenAI 兼容接口是万能钥匙OpenClaw 支持多种模型后端但我在实际配置时发现一条规律几乎所有模型都能通过 OpenAI 兼容接口接进来。无论是官方 API还是一些开源模型框架提供的本地 mock 接口只要给我一个base_url和api_keyOpenClaw 就能用。配置结构大致是这样llm: provider: openai-compatible model: qwen2.5-7b-instruct api_key: ollama base_url: http://host.docker.internal:11434/v1 temperature: 0.7 max_tokens: 4096这里有个关键细节如果你用 Ollama 作为后端api_key随便填一个非空值就行Ollama 不校验 key。base_url一定要用容器访问宿主机的特殊域名在 Docker Desktop 环境下是host.docker.internal在纯 Linux 容器里可能要改成宿主机 IP。很多人配置完模型调用报连接失败十有八九是这个地址写错了。4.2 在线 API 与本地模型的混合使用我在生产环境里更喜欢混合路由简单任务走本地 7B 模型省时间复杂任务转发到云端模型。OpenClaw 支持配置多个 provider并在 agent 级别指定模型。比如让龙虾在处理内部文档摘要时用本地千问在生成代码时用云端 DeepSeek。做法是在config.yaml里定义多个 LLM 条目然后在 agent 配置里引用agents: default: llm: local-qwen code: llm: cloud-deepseek这个模式特别适合办公场景本地模型负责不敏感且重复性的操作云端模型负责真正需要推理的任务。一来控制成本二来避免把敏感数据全部送到外部 API。4.3 千问接入配置里最容易错的两个字段热词里专门有openclaw 配置千问说明这里坑不少。我复盘下来常见错误就两个model字段写成了不带-Instruct的简写。OpenClaw 会把这个字符串原样传给 Ollama而 Ollama 上的模型 tag 通常是qwen2.5:7b-instruct所以model: qwen2.5-7b-instruct并不等于 Ollama 的 tag很可能报 model not found。严格对应的话写成qwen2.5:7b-instruct或者干脆qwen2.5加任务参数。上下文长度设置不当。千问的 7B 模型默认上下文可能只有 8K但 OpenClaw 的会话会叠加系统提示词、工具定义和对话历史很快就把上下文撑爆。建议在配置里显式设置num_ctx: 8192同时在 OpenClaw 侧限制轮数。5. Agent 与 Channel让龙虾知道往哪儿爬5.1 channel 到底是什么很多人在问openclaw agent 怎么选择 channel说明这一块确实是理解分水岭。在 OpenClaw 里channel 指的是 Agent 的进出口也就是消息从哪进来、结果往哪输出。它可以是命令行终端、HTTP API、飞书机器人、Teams Bot、Discord、Telegram甚至是一个定时触发器。选 channel 没有绝对标准我一般按这个逻辑自己调试用命令行或 Web UI。给团队用走飞书或 Teams这样大家不用装额外工具。做自动化任务用 HTTP 接口或定时触发让龙虾自己按编排流程干活。5.2 把龙虾接入飞书、Teams 的实操接入飞书时我踩过的坑是事件订阅地址必须公网可达。OpenClaw 跑在办公电脑上没有公网 IP飞书后台会要求一个 HTTPS 回调地址。解决办法是在飞书开放平台创建一个自建应用然后把回调地址指向你内网穿透出来的域名并且在 OpenClaw 配置里开启飞书 channel。配置核心字段大概是channels: feishu: enabled: true app_id: cli_xxxx app_secret: xxxx encrypt_key: xxxx verification_token: xxxxTeams 的接入跟飞书大同小异只是要在 Azure 门户注册应用、配置 Bot、拿到 App ID 和 Client Secret。如果你公司在用 Microsoft 365Teams channel 的代价是要有一个能创建 Bot 的账号权限普通用户自己去搞会卡在 API 权限审批上。5.3 飞书输出容易被截断的根因热词里专门有一条openclaw 在飞书输出容易被截断这个问题我遇到过而且非常烦。现象是Agent 生成的长回复超过一定长度后飞书那边只有前半段后面戛然而止没有任何报错。排查链路是这样的先抓 OpenClaw 侧的日志看是否完整生成了回复。如果日志是完整的说明问题出在飞书消息接口的 45 秒超时或消息长度限制上。飞书消息接口对单条文本长度有上限OpenClaw 默认没做拆分一条超长消息直接发过去飞书只保留前半段。解决办法有两个方向第一在 OpenClaw 配置里把max_output_size调低让 Agent 分段产出第二给飞书 channel 加一个分片发送的中间层把长消息按固定长度切成多条。前者的副作用是 Agent 可能觉得表达不完整后者的实现稍微复杂但效果最稳。我在团队里用的就是后者的思路切分长度设为 3600 字节实测没有再出现截断。5.4 其他 channel 的互通技巧OpenClaw 的 channel 之间不是孤立的。我经常做一件事在飞书里给龙虾发一句把刚才的搜索整理一份发到 Teams 群这就需要配置里把两个 channel 同时启用并且给每个 channel 一个唯一的 agent 入口。如果你的 channel 选错了Agent 会找不到从哪来直接回复一个会话不存在。还有一个点当多个用户同时调用同一 channel 时OpenClaw 会根据发送者 ID 建立不同的 session。这个 session 机制就和下面要讲的大坑直接相关。6. 会话锁与启动失败那串 60000ms 报错的前因后果6.1 报错在什么场景下出现agent failed before reply: session file locked (timeout 60000ms) 这句话我在本地部署的第二天就见到了而且是在最不该出问题的时候——我在两个终端里同时打开同一个 agent 的会话一个是用 Web UI 聊天另一个是命令行发指令。后来我发现报错的原因是 OpenClaw 为每个 session 维护一个独立的 JSONL 会话文件文件用独占锁的方式控制读写。当两个进程同时尝试写同一个 session 文件时后到的进程会等待锁释放默认等 60000 毫秒。如果 60 秒内前一个进程没有释放锁就直接抛出这个错误。更隐蔽的场景是上一个对话还没有完全跑完比如 Agent 还在等模型响应你又发了第二条消息。由于模型推理比较慢session 文件一直处于锁定状态第二条消息等不到锁就直接失败了。6.2 排查链路与修复方案我复盘了一下完整的排查链路应该按这个顺序走看进程列表里是否有多个 openclaw 实例在跑。不同终端分别用lerun或npm start启动就会有多个实例抢占同一个 session 目录。看~/.openclaw/sessions/目录下对应的.lock文件是否存在。如果文件还在但进程已经不在了叫是上次异常退出留下的僵尸锁。确认是否同一个 session 同时被两个 channel 使用。飞书和 Web UI 的 session key 如果都指向同一 agent就会在同一文件上撞锁。修复方案分三步先杀掉所有 OpenClaw 进程把 sessions 目录里的.lock文件删掉相当于把闸门重置。修改配置确保 session 文件的路径按用户维度区分不要所有 channel 共用一个 session 文件。把锁超时时间调大比如从 60000ms 改成 300000ms至少能避免模型推理慢导致的假死。但这只是缓兵之计根本解法还是保证同一个 session 同一时间只有一个调用者。这个问题的本质是 OpenClaw 默认的 session 并发模型比较保守宁可拒绝也不写坏文件。理解了这一点你就知道为什么网上有人建议一个 agent 只挂一个 channel一个时刻只处理一条消息。6.3 其他启动失败的常见诱因除了会话锁我安装时还遇到过端口被占用。OpenClaw 的默认端口如果已经被其他服务占掉启动后管理界面打不开但进程状态看起来正常。务必检查netstat -tlnp。数据库目录没有写权限。装在 NAS 上时最容易遇到因为共享目录权限默认只读。这个报错通常发生在初始化数据库阶段日志里会冒出 Permission denied。浏览器子进程无法启动。OpenClaw 的电脑操作能力依赖无头浏览器在 Docker 里缺少--privileged或 GPU 加速库时浏览器起不来Agent 执行工具调用就会一直卡在 pending。7. OpenClaw、Dify 和 Workbuddy同台竞技之后我的选择7.1 三者定位并不相同OpenClaw 最近经常被人拿来跟 Dify、Workbuddy 比较。我的看法是它们完全不是一类东西。Dify 是偏向流程编排的 LLM 应用平台你可以在上面拖拽出知识库问答、工作流、Agent 甚至 RAG 管道它更像是一个应用开发平台。Workbuddy 则更偏向消息助手和 CRM 场景主打的是跟团队协作工具的深度集成。而 OpenClaw 更像个个人数字替身它能直接操作浏览器、命令行、文件系统在本地跟你的电脑环境进行真实交互而不仅仅是处理和生成文本。用我自己的话说Dify 适合做对外服务的应用Workbuddy 适合做团队内消息驱动的任务协作OpenClaw 适合做把我的电脑变成可编程的机器人。7.2 同场实测的一些体会我在同一台机器上部署过 Dify 和 OpenClaw后者在自主执行方面明显更鲁棒。Dify 的 Agent 节点逻辑上依赖 Dify 自身的流程控制一旦某个工具调用超时整个流程就卡在设计好的节点上很难旁路。OpenClaw 的 Agent 则有更强的即时决策能力在同一个任务里它可以自己决定先调用浏览器还是先读取文件展现出来更像一个在干活的人。Workbuddy 我也简单试过。它在接入 Teams 和邮件方面做得比较顺手但它的定位决定了它不会帮你操作本机软件。如果只是需要群聊里自动回复、整理周报Workbuddy 上手更快如果要自动打开浏览器查资料、填表单、跑脚本OpenClaw 更合适。7.3 我的选择逻辑现在我的办公电脑上装的是 OpenClaw原因是它把本地模型和本地操作这两件事融合得最好。Dify 很好但它的强项不在接管电脑而且 Dify 的本地部署资源占用也不小。Workbuddy 不适合我因为我不需要一个额外的消息聚合中心。反过来如果你是在做企业内部知识库、客服问答我建议你优先看 Dify如果你公司已经重度使用 Teams并且你需要的是一个能聊天的助手那么 Workbuddy 可以给你一个更低的起点。选型不要看热度要看你的任务到底发生在哪个边界里。8. 一些让本地部署更舒服的调优细节8.1 给 Agent 加独立的模型上下文预算OpenClaw 的会话上下文是共享的如果不做限制早期一个长任务会把上下文占满后面的工具调用就没有空间了。我的习惯是在每个 agent 的配置里设置独立的上下文轮数默认不要超过 20 轮。对于需要长文档分析的任务单独建一个analysisagent把轮数放宽到 50但同时只允许它访问特定目录避免它乱动文件。8.2 定时任务与手动触发的混合如果你想让龙虾每天上午九点自动汇总一份报告可以配一个 cron 类型的 channelchannels: schedule: enabled: true jobs: - name: daily-report cron: 0 9 * * * agent: reporter input: 生成昨天的项目进展摘要这样就不需要人盯着发消息。但注意定时任务开始的时候一定要确保没有其他会话锁在使用同一个 agent否则就会触发前面说的 60000ms 报错。我通常让定时任务使用独立 agent 身份从源头避免碰撞。8.3 日志级别与控制台输出OpenClaw 默认日志在终端里刷得又密又快重要错误容易被淹没。建议把日志写入文件并设置成 info 级别。排查会话锁问题时日志里的session locked出现时间能帮你判断是谁在抢占锁。我习惯只保留最近七天的日志定期清理避免日志文件把磁盘憋爆。8.4 升级与回滚策略本地部署的一个隐形风险是升级后配置格式不兼容。我在升级之前都会把config.yaml和 sessions 目录整个打包备份。官方发新版本后不要急着在生产环境升先在测试容器里升一次确认配置项没有破坏再动线上。这个习惯帮我躲过了至少两次配置字段改名引发的启动即失败事故。写在最后的一点个人体会OpenClaw 这类本地部署的 Agent 框架最大的门槛其实不在安装而在于把模型调用、消息通道、本机操作、会话管理这四件事的联动逻辑理清楚。很多人被那个 60000ms 的会话锁报错劝退但只要理解了 session 文件锁的设计意图它就不再是玄学。我现在的办公流程里OpenClaw 负责每天定时抓取行业资讯、整理会议纪要、自动汇总飞书群里的待办偶尔还帮我跑一些浏览器脚本。它没有传说中那么智能但胜在完全可控——模型在本地数据在本地触发规则也在本地。如果你也打算在办公电脑上部署一个龙虾建议从最小配置起步先接一个本地模型、一个命令行 channel、一个飞书机器人跑通之后再逐步加能力。每加一层都先把该层的日志和会话机制弄清楚。这样下来你得到的不仅是一个能跑的 AI Agent更是一条你自己完全能 debug 的链路。
