前一阵子折腾 OpenClaw从最早在 Windows 上踩 WSL2 的坑到后来换到 Linux 服务器上跑稳定前后花了一周多时间。这中间网上中文资料少很多问题都是自己翻日志、看 issue 一点点试出来的。最近看到不少人在问“OpenClaw 怎么部署”“能不能只接本地模型”“和 WorkBuddy 比怎么样”干脆把整个部署过程、踩坑记录、配置心得整理成一篇给想自托管 AI Agent 的朋友做个参考。先说清楚 OpenClaw 是个什么东西以及它解决的问题。OpenClaw 本质上是一个自托管的 AI Agent 网关也有人叫它 Agent Harness它把大模型、消息渠道、工具调用、记忆系统四部分组合在一起让你可以跑一个真正干活、能对话、能查资料、能操作外部服务的 AI 助理。和直接装个 ChatBox 客户端不一样OpenClaw 更像是一个常驻后台的服务你可以把它接到飞书、Discord、Telegram 这些聊天软件上用日常聊天的方式指挥它干活。最大的优势是数据完全掌握在自己手里模型可以选本地部署的 Ollama、DeepSeek也可以选云端 API消息记录、记忆数据都在自己的机器上不经过任何第三方平台。这篇文章适合谁看想自己搭一个私有的 AI 助理、想把 AI Agent 接入团队聊天工具做自动化运维、对本地部署大模型有需求但不想被各种商业平台绑定的开发者。我会从环境准备、安装步骤、模型接入、Channel 配置、Skill 扩展机制到常见错误排查一步步带你把这只“龙虾”养起来。1. 部署前的技术认知OpenClaw 的架构与选型逻辑1.1 Agent、LLM 与 AI 模型的关系很多刚接触 OpenClaw 的人会卡在一个概念上OpenClaw、大模型、Agent 这三者到底什么关系这里我用一个比较直白的类比解释。大模型比如 DeepSeek、千问、Llama相当于人的大脑负责思考和生成回复但它自己没法打电话、查文件、发消息。OpenClaw 相当于身体和神经系统负责把大脑的指令翻译成具体动作比如读取某个文件、调用某个 API、向飞书群发一条消息。而 Agent 是“大脑 身体”组合后的完整产物也就是一个能感知环境、做出决策、执行动作的智能体。所以当有人问“DeepSeek 是不是 Agent”时答案是DeepSeek 是 LLM是 Agent 的一个组成部分。你在 OpenClaw 里配置 DeepSeek只是给这台“身体”装上了一颗“大脑”。同理任何单独的大模型都不能直接替代 OpenClaw 这类框架它们是上下游的关系。理解了这一点后面配置模型的时候就明白为什么既要有 OpenClaw又要单独装 Ollama 或者申请 API Key。1.2 OpenClaw 的核心组成模块从实际使用角度来看OpenClaw 可以拆成五个部分。Harness中枢负责调度所有模块处理消息的路由、技能的分发、上下文的管理是整个服务的核心进程。它决定了 Agent 如何处理一个请求比如收到飞书消息后先要判断要不要调用 Skill、要不要查记忆然后才把结果送回给大模型生成最终回复。LLM Provider大脑接入层OpenClaw 不内置模型它只是提供一个标准接口来对接各种大模型。可以接本地 Ollama、也可以接 OpenAI 兼容的 API 服务甚至接国内厂商的在线 API。Channel通道层这是 Agent 的“感官和手脚”。飞书、Discord、Telegram、Slack 都是 ChannelOpenClaw 通过它们收消息、发消息、处理事件请求。每个 Channel 需要单独配置。Skill技能层技能是 OpenClaw 最有意思的部分相当于给 Agent 装各种插件。比如一个“查天气”的 Skill一个“执行 Shell 命令”的 Skill一个“读取 GitHub 仓库”的 Skill。用户可以自己开发、安装、管理这些技能让 Agent 不只是聊天而是真正能干活。Memory记忆层记忆模块让 Agent 在对话结束后仍然能记住关键信息。比如用户告诉它“我是运维组的常用服务器是 10.0.0.8”这个信息就会被写入记忆下次对话时 Agent 能直接调用不需要重新教一遍。这五部分缺一不可。很多人部署 OpenClaw 失败通常不是安装有问题而是不理解每个模块需要分别配置。以为装好主程序就完事了结果模型没接Channel 没通自然跑不起来。2. 环境准备从硬件选型到 WSL2 配置2.1 硬件与操作系统的选择OpenClaw 本身是一个 Node.js 应用对硬件的要求其实不高主要还是取决于你跑什么模型。如果只做 Agent 编排模型调用远端的 API比如 DeepSeek 在线版、OpenAI那么一台 4 核 8G 内存的小主机就够了。如果你要跑本地模型比如通过 Ollama 跑 7B 或 14B 参数规模的模型那就要看显存了。我先给一个体验较好的配置参考使用场景CPU内存显卡硬盘纯 Agent 编排 云端模型2 核即可4GB不需要20GBAgent 本地 7B 模型4 核16GB6GB 以上显存50GBAgent 本地 14B/32B 模型8 核32GB12GB 以上显存100GB多用户团队使用8 核以上32GB视模型而定100GB操作系统方面OpenClaw 官方支持 Linux、macOS、Windows通过 WSL2。我的建议是能上 Linux 就上 Linux不管是 Ubuntu 22.04/24.04 还是 Debian都比 Windows 那条路顺畅得多。为什么OpenClaw 在 Linux 下是一个标准的 Node.js 服务依赖很少systemd 管起来也很方便。而在 Windows 下因为它内部会调用 WSL2 环境来管理部分依赖和信息验证容易出现“could not safely verify the WSL2 environment”这类问题给自己添堵。2.2 Windows 下 WSL2 的坑与正确配置如果你只有 Windows 机器也不是不能弄但必须先把 WSL2 配置正确。我踩过的坑基本都集中在几个点上。第一WSL2 内核版本。OpenClaw 在验证 WSL2 环境时本质上是在检查内核版本和 WSL 基础能力如果你用的是自带的老旧 WSL 内核验证就会失败。解决办法是升级到 WSL 2.0 以上版本在 PowerShell 里执行wsl --update wsl --set-default-version 2第二内核启用 systemd。很多安装脚本依赖 systemd 来管理服务默认的 WSL 镜像不一定开了 systemd。你需要在/etc/wsl.conf里加一段[boot] systemdtrue然后在 PowerShell 里执行wsl --terminate 你的发行版名称重启 WSL再进去验证systemctl list-units是否正常。第三网络模式。WSL2 默认的 NAT 网络会让 OpenClaw 里某些依赖“本地地址访问”的操作失败特别是需要在 Windows 宿主机和 WSL 虚拟机之间做端口转发的时候。如果遇到这类问题可以在.wslconfig里设置镜像网络模式[wsl2] networkingModemirrored设置完同样要重启 WSL 才生效。Linux 下的准备就轻松多了先把 Git、Node.js、Docker按需装好即可sudo apt update sudo apt install -y git curl curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v这里多说一句Node.js 版本不要太老我实测 OpenClaw 在 Node.js 22 上工作最稳定18 的部分旧版本会出现 session 锁相关的问题。3. 安装与初始化把 OpenClaw 跑起来3.1 两种安装方式对比OpenClaw 官方提供两种常见安装方式手动 Git Clone 后 npm install以及通过一键脚本。我两种都试过结论是看你的使用场景。一键脚本适合第一次安装、不打算深度定制的小伙伴。它会把 OpenClaw 核心、基础配置、示例 Skill 都装好省事。但它的问题在于不够透明装完往往还需要手动调整配置。Git Clone 方式看起来多敲几条命令但你能清楚地看到每个文件装到了哪里后面想改配置、升级版本都心里有数。我是第二次重装时就直接用 Git 方式了。下面以 Git 方式为例。先找一个放代码的目录mkdir -p ~/opt cd ~/opt git clone OpenClaw 仓库地址 openclaw cd openclaw npm install安装依赖这一步时间比较长耐心等就好。如果网络环境不好可以把 npm 源切换到国内镜像注意这里是可控的软件源切换提速明显npm config set registry https://registry.npmmirror.com装完以后先初始化配置文件cp .env.example .env然后编辑.env这是整个部署过程中最关键的一步。3.2 模型接入从 Ollama 到 OpenAI 兼容 APIOpenClaw 的模型接入采用配置驱动的模式你在.env或界面配置里指定用哪个 Provider、哪个模型、API 地址和 Key 是什么。本地部署的话我的首选是 Ollama。Ollama 的安装很简单curl -fsSL https://ollama.com/install.sh | sh装完后拉取你想用的模型比如 DeepSeek 系列ollama pull deepseek-r1:7b ollama pull qwen2.5:14b然后在 OpenClaw 的配置里指定模型 Provider 为 Ollama、模型名称对应上面的标签API 地址默认是http://localhost:11434。如果 OpenClaw 和 Ollama 不在同一台机器上记得把地址改成实际 IP并且把 Ollama 的监听地址设为0.0.0.0# 在 /etc/systemd/system/ollama.service 里设置 EnvironmentOLLAMA_HOST0.0.0.0:11434重启 Ollama 后生效。这里有个小经验局域网里其他机器要访问 Ollama光改监听还不够防火墙要放行 11434 端口这个很基础但容易漏。如果你用的是 DeepSeek 在线 API 或者 OpenAI 付费 API那就更简单了直接在配置里填 API Endpoint 和 Key不需要本地模型。还有一个不错的选择是支持 OpenAI 协议的各种网关服务比如 One API 之类的它们可以统一管理多个后端模型。因为 OpenClaw 是走 OpenAI 兼容协议的所以这种代理网关也能直接接入等于你在 OpenClaw 里配一个地址后面切换后端模型只需要在网关上改不需要重启 OpenClaw。3.3 首次启动与验证配置完模型后首次启动可以先用前台模式跑方便直接看日志node src/index.js看到类似Agent initialized、Channel connected的日志说明核心进程起来了。这时候可以先在终端里直接发一条消息测试。OpenClaw 通常会带一个终端交互模式可以在 CLI 里直接和 Agent 对话这种模式很适合用来验证模型和记忆链路是否正常。确认终端对话没问题后再考虑接入 Channel。这样区分的好处是出问题的时候你能快速定位是模型的问题还是 Channel 的问题而不是锅都糊了才开盖子。4. Channel 配置实战让 Agent 走进飞书4.1 飞书 Channel 配置全流程把 Agent 接到飞书是很多人实际使用频率最高的做法因为飞书在团队协作里太常用了。配置流程并不复杂但牵扯到飞书开放平台、权限、事件订阅每个环节都有容易出错的地方。第一步去飞书开放平台创建企业自建应用。创建成功后拿到 App ID 和 App Secret这两个值后面要填到 OpenClaw 的配置里。第二步配置权限。在“权限管理”里开启这些权限读取用户信息、读取消息、发送消息、接收群消息、上传图片或文件。如果 Agent 要发文件一定要开通“上传图片或文件”的权限否则 Skill 执行完返回文件时会发不出去。第三步配置事件订阅。OpenClaw 接收飞书消息依赖事件回调你要在飞书后台配置一个回调地址。这里会涉及公网可访问的问题。如果 OpenClaw 部署在有公网 IP 的服务器上直接把回调地址指向你的域名或 IP 加端口即可。如果只在局域网内那就需要内网穿透工具这个之后我可以单独写一篇这里先提个醒。第四步把 App ID、App Secret 和回调地址配置到 OpenClaw 的 Channel 配置里然后重启服务。飞书事件订阅要做验证OpenClaw 一般会处理这个握手流程你只要确认回调地址能通就行。4.2 Channel 选择与多通道并存的取舍OpenClaw 支持多个 Channel你可以同时接飞书、Discord、Telegram。但我不建议一开始就把所有 Channel 都接上原因很简单每个 Channel 都要单独配置权限和事件订阅一旦出问题排查要花几倍的时间。我建议的节奏是先在飞书里跑通一个完整的“消息进来-模型处理-Skill 调用-回复出去”闭环再考虑接第二个 Channel。因为核心链路是同一套Channel 之间的差异只在接入协议一个通了另一个也就是配置半天的事。另外不同 Channel 的消息格式和能力差异很大。比如飞书有消息卡片Telegram 有 inline keyboardOpenClaw 对每个 Channel 的适配程度不一定相同。如果你主要用飞书就多关注飞书相关的输出格式问题比如长消息截断这个我在第六节会专门讲。5. Skill 与 Memory让“龙虾”长出手脚和记忆5.1 Skill 开发与配置入门没有 Skill 的 Agent 只是个聊天机器人有了 Skill 才谈得上“Agent”。OpenClaw 的 Skill 机制本质上就是一组预定义的指令和工具函数Agent 根据用户请求决定要不要调用、调用哪个。安装一个现成的 Skill 通常很简单把 Skill 目录放到默认的技能目录下然后在配置里声明即可。以“执行 Shell 命令”这个 Skill 为例配置大概长这样{ name: shell-executor, description: Execute shell commands on the host machine, parameters: { command: { type: string, description: Shell command to execute } }, permission: ask }这里的permission字段很重要我建议设为ask也就是 Agent 想执行命令时先征求你的确认。直接设成allow很危险如果 Agent 被恶意提示词引导可能执行意料之外的命令。安全永远不要在“方便”前面妥协。开发自定义 Skill 也不难核心就是写清楚两个东西这个技能是干什么的description 写成让模型能理解的自然语言以及它需要哪些参数。大模型会依据描述来决定是否调用这个技能所以描述写得越清楚Agent 越会正确使用。5.2 Memory 机制与长期记忆管理Memory 是 OpenClaw 区别于普通聊天机器人的重要能力。默认情况下大模型是一次性的对话结束就忘光。Memory 模块会把重要信息持久化跨会话、跨渠道地保留。OpenClaw 的 Memory 实现一般有两种一种是把对话历史摘要后保存在本地文件或向量数据库里另一种是让 Agent 在对话中主动记住关键事实比如用户自我介绍、常用配置等。实测下来想让记忆真正好用关键是定期清理。记忆会无限膨胀太多无用信息反而会干扰 Agent 的判断。我一般每个月清理一次把过时的、重复的、不再使用的信息删掉只留下稳定的、经常用到的那些。如果你接入了 MCPModel Context Protocol生态Memory 可以直接复用 MCP 的 Memory 服务后面扩展性会更强。OpenClaw 对 MCP 的支持意味着你不需要自己实现所有工具社区里大量的 MCP 服务器文件访问、数据库查询、浏览器操作等都可以直接插进来用。5.3 本地模型 MCP 自动化的无限扩展把 Ability 再延展一步MCP 机制让 OpenClaw 有点像自动化运维平台的大脑。有人在网上提问“AI Agent 与 PLC 编程”说白了就是通过 Agent 来操控工业设备。OpenClaw 配合 MCP 确实能做到类似的事只要 MCP 服务能把 PLC 的寄存器读写、状态读取封装成标准工具Agent 就能通过自然语言控制它。自动化运维也是同一个逻辑。传统运维你要写脚本、配 crontab、接告警有了 Agent MCP你可以直接跟它说“检查所有服务器的磁盘使用率超过 80% 的发告警到飞书群”Agent 会自动调用对应的 Skill 和 MCP 工具去执行。这确实好用但前提是你对权限控制有清晰认知明确哪些操作要人工确认哪些可以自动执行。6. 常见问题与排查技巧实录6.1 session file locked 巨坑排查很多人在跑 OpenClaw 时遇到过这条报错agent failed before reply: session file locked (timeout 60000ms) openclaw这个报错我一开始也懵了很久。它的意思是会话文件被锁住了60 秒内没有拿到锁直接超时。什么情况下会锁文件多半是同一个 Agent 实例同时被多个请求触发或者上一个会话还没结束下一个请求又进来了文件锁竞争导致超时。排查思路三步走。第一步看是不是有多个 OpenClaw 进程在同时运行ps aux | grep openclaw查一下如果有多个全部停掉只留一个。第二步看是不是有卡死的会话去 session 目录里清理掉 stale 的.lock文件。第三步如果高并发场景下经常出现可以调大锁等待的超时时间比如从 60000 改成 120000。改完以后通常能缓解但长期还是要靠减小并发会话数来解决。6.2 WSL2 环境验证失败的解决办法另一个高频报错是openclaw could not safely verify the WSL2 environment.这个问题基本只出现在 Windows 上。OpenClaw 在 Windows 下会用 WSL2 跑一些依赖外部环境的组件但在验证环境时发现内核、systemd、网络配置不符合预期。解决办法我在 2.2 节已经提过升级 WSL 内核、开启 systemd、设置镜像网络。如果你已经做过这些还是不行干脆换一种思路在 WSL2 里开一个 Ubuntu 虚拟机所有依赖装到 Ubuntu 里面然后通过 systemd 把 OpenClaw 跑成服务不要依赖 WSL 的进程转发。这种方法我实测最稳。6.3 飞书长消息截断问题“OpenClaw 在飞书输出容易被截断”这是飞书 Channel 的经典问题。飞书对单条消息长度有限制通常是文本内容 150KB 左右但实际体验中超过一定长度就会出现显示不全或发送失败。两个常用办法。一个是让 Agent 学会分块输出通过在 Skill 或人设里加一条规则“如果回复内容太长分成多条消息发送每条不超过 2000 字”。另一个是在 OpenClaw 的飞书 Channel 配置里开启自动分段。我用下来感觉设置 1500-2000 字的输出上限比较稳既照顾飞书限制又不会碎片化到看起来太零散。6.4 性能调优与内存占用控制OpenClaw 本身内存占用不高真正吃内存的是本地模型。如果你同时跑 OpenClaw Ollama 14B 模型16G 内存会比较紧张建议给 Ollama 限制并发数减少显存/内存峰值OLLAMA_NUM_PARALLEL1 OLLAMA_MAX_LOADED_MODELS1另外OpenClaw 的会话文件会随时间增多建议配置日志轮转和会话数据清理。我写过一个简单的 crontab0 3 * * * find /path/to/openclaw/sessions -type f -mtime 7 -delete定时清理 7 天前的会话文件避免磁盘被写满。如果你有长期保留某个关键会话的需求先把那个会话导出备份再删别一上来就全清了。6.5 Agent 接入常见问题速查表症状常见原因解决办法Agent 不回复飞书消息事件订阅回调地址不通检查回调地址公网可达性Agent 回复内容与其他用户无关Memory 跨会话混用为不同用户/群配置独立会话Skill 执行超时外部命令等待时间过长调高 Skill 的超时时间本地模型回复很慢显存不够或并发过高降低模型规模、限制并发对话内容总是被截断输出长度超限设置分段输出Agent “忘记”了之前的设定Memory 未开启或已清理检查 Memory 配置及写入规则7. 安全加固与日常维护建议7.1 权限最小化配置AI Agent 的最大风险不是模型本身而是它获得的权限。当 Agent 能操作 Shell、读取文件、调用 API 时一条成功的提示注入就可能让你的机器被人拿走。我的经验是严格遵循最小权限原则。第一Skill 权限分级。所有高风险的 Skill 默认设为ask甚至deny只有确认安全之后才提升为allow。第二运行用户隔离。不要用 root 跑 OpenClaw创建一个专用用户给它最小范围的目录读写权限。第三网络隔离。如果只是内网用户使用就通过防火墙限制 OpenClaw 只监听内网接口不要暴露在公网。7.2 数据备份与版本升级OpenClaw 的数据分为三类配置.env、skill 配置、会话文件、记忆数据。会话和记忆数据是你最重要的资产恢复不了相当于白训练了。我每天用 tar 打包一次tar czf ~/backup/openclaw_$(date %F).tar.gz -C ~/opt openclaw/sessions openclaw/memory openclaw/.env版本升级方面因为 OpenClaw 迭代比较快我建议先看 ChangeLog 里的 breaking changes再升级。直接拉最新代码跑大概率没问题但偶尔会碰到配置格式变化导致启动失败的情况。升级前先备份配置升完测试一条消息再接入正式渠道。7.3 本地部署与云端方案怎么取舍很多人在问“OpenClaw 和 WorkBuddy 哪个好”“用云端 Agent 不行吗”。我的看法是这取决于你对数据的敏感度和可玩性的要求。如果是个人体验、学习 AI Agent 开发本地部署一定是首选它没有订阅费用、没有数据隐私问题、可以随便折腾。如果是团队生产环境尤其是要对接企业内部敏感数据自托管也更安全。但代价是你得自己维护模型、网络、服务器监控都是你的活。反正我在跑熟 OpenClaw 之后最大的感受是它确实把“本地 AI Agent”这件事的门槛拉低了很多。接上 DeepSeek、配上飞书群、写好几个 Skill它就从一个玩具变成了一个得力的数字同事。除了飞书群里偶尔还能看到它发运维报告大多数时候你甚至意识不到它是一堆跑在自己服务器上的代码。如果你按这篇文章走一遍遇到任何报错先别急着搜“为什么”第一件事永远是看日志。OpenClaw 的日志信息量很大90% 的问题在日志里都有明确提示。剩下的 10%看看这次的 session 锁问题、WSL2 问题、飞书回调问题基本就是我前面写的那几个坑照着排查一般都能解决。
