1. OpenClaw 是什么一个能跑 AI 代理的本地运行时1.1 为什么叫“框架”而不是“应用”OpenClaw 是一个开源的 AI 代理运行框架名字挺直白——Open 是开放Claw 是爪子组合起来就是“伸出爪子去抓取任务”。它和市面上常见的 AI 聊天工具有一个本质区别聊天工具的核心交互是“对话框”你问一句它答一句而 OpenClaw 的核心交互是“任务目标”你把想做的事情描述清楚它自己拆解步骤、调用大模型、读写本地文件、触发外部工具最终把结果交付给你。我在第一次上手时也有同样的困惑这东西到底算什么后来用了一段时间才明白它更像是一套“Agent 基础设施”——一个用来承载自主代理Agent的本地运行时。你定义的每一个 Agent本质上是一段可配置的逻辑流程它绑定什么模型、允许访问哪些工具、通过什么渠道对外收发消息、会话数据存在哪里这些都由你在 OpenClaw 的配置文件中控制。它不是又一个拿来即用的聊天网页而是一个你可以随意改动的底座。从热搜里能看出很多人是被“部署”“本地运行”“多渠道接入”这些词吸引过来的。事实也确实如此OpenClaw 装上之后Agent 跑在自己的机器上数据不出本地逻辑透明可控模型可以随意切换甚至混用。对那些有数据隐私要求、想把 AI 嵌入到日常工作流里的人而言这种掌控感是云端网页版给不了的。1.2 适合谁用能解决哪些实际问题先别急着复制安装命令对照一下自己的需求看是否真的需要装它。我总结了四类典型用户手里有多个大模型 API比如千问、各类 GPT 兼容接口想在一个框架里统一调度和切换想把 Agent 接到 Microsoft Teams、Obsidian 这类日常工具里让 AI 自动发消息、整理笔记需要一个本地定时运行的自动化代理处理日报汇总、文件归档、网页信息抓取这类重复劳动对 Agent 的底层行为有控制欲比如“这个任务必须走哪条 channel”“那个 Agent 必须用哪个模型”。最近常有人拿“openclaw 和 workbuddy 哪个好”来问。我的看法是workbuddy 更像开箱即用的助手偏向把简单任务快速跑通OpenClaw 则更强调控制和扩展性适合愿意花时间调教底层的人。两者不是谁取代谁的关系而是两条路线。如果你追求“装上就能用”OpenClaw 的前期投入确实比傻瓜式工具大一些但如果你要的是长期可演进的自有 Agent 体系这套投入是值得的。2. 装之前先打地基依赖环境与版本选择2.1 必装依赖清单一个都不能少OpenClaw 本身是用现代脚本语言写的但它依赖一堆基础组件。我在给一台服务器和一台 Windows 办公机分别部署时把依赖坑踩了个遍这里直接给你一份精简清单运行时Node.js 18 或 20 的 LTS 版本以及随附的 npm脚本层Python 3.10 及以上且能直接在命令行调用版本管理GitWindows 下建议装 Git for Windows数据库可选但推荐MySQL 8.x用于保存会话和 Agent 状态编辑器可选VSCode主要是方便编辑 YAML 配置终端工具Windows 推荐 Windows TerminalLinux 直接用系统自带终端即可。为什么 Node.js 和 Python 都要OpenClaw 的主进程跑在 Node 上而它内部大量工具链和插件是通过 Python 脚本调用的。只装其中一个启动时可能看不出来问题一旦 Agent 执行到某个需要调用 Python 的环节就会直接报“找不到解释器”之类的错误。所以我的建议是两个运行时都装好省得后期返工。2.2 环境变量与国内镜像源配置这一步是新手最容易翻车的地方。特别是 Windows 用户装完 Python 和 Node.js 后打开命令行输入python或者npm系统提示“不是内部或外部命令”——十有八九是环境变量没配置对。解决办法不是手动去“系统属性”里瞎点而是采用最稳妥的路径安装 Python 时勾选“Add Python to PATH”Node.js 安装包默认就会写入环境变量Git 安装时选择“Add to PATH”。装完这三样重启终端分别执行python --version、node -v、npm -v能正常输出版本号环境就通了。然后是包管理器的镜像源问题。OpenClaw 安装过程会拉取大量 npm 依赖直接走默认源在小水管网络下很容易超时中断。这里不需要任何特殊手段只需要把 npm 默认 registry 切换到国内镜像即可npm config set registry https://registry.npmmirror.comPython 侧的 pip 也一样pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple这两条命令干的事是把“软件下载服务器”换成一个离你更近、带宽更稳定的地址。换完之后再装依赖速度体感差异非常明显。我自己第一次完整装完花了将近四十分钟切完镜像后十分钟出头就搞定了。2.3 数据库选型会话数据到底存哪OpenClaw 的会话文件默认存在本地目录单机使用完全没问题。但你如果打算把它部署到服务器上、多个终端同时连或者跑比较复杂的多 Agent 协作场景建议一开始就接上 MySQL。这里不展开数据库安装的每一步只提醒三个关键点。第一字符集必须选 utf8mb4否则存中文会话内容会乱码第二要给 OpenClaw 单独建一个账号不要用 root 直接连第三创建一张初始数据库名字随意比如openclaw配置时填上地址、端口、账号、密码即可。为什么强调“一开始就接”因为 OpenClaw 的会话管理在 SQLite 和 MySQL 之间切换不是改一行配置那么简单它涉及表结构初始化和历史数据迁移。已经跑了一段时间再用到一半去迁库纯属给自己找事。我在生产环境部署时直接选了 MySQL省掉了后续迁移的麻烦。3. 安装实操Windows 和 Linux 两条路线都走一遍3.1 Windows 下安装 OpenClaw 的完整步骤Windows 安装的核心思路是准备好依赖拿到源码安装依赖启动服务。和装一个普通开发项目没有本质区别按顺序操作就行。第一步创建一个干净的目录比如D:\openclaw在目录里打开终端执行git clone OpenClaw官方仓库地址 .仓库地址以官方文档为准这里不方便贴具体链接。克隆完成后目录下会有一份package.json这就是项目入口。第二步安装依赖。两条命令npm install pip install -r requirements.txtnpm 那条在切过镜像源之后会快很多。pip 那条是把 Python 侧的依赖一次性装好。装的过程中如果有报错多半是某个原生模块需要编译Windows 下最容易缺的是 Visual Studio Build Tools。我的建议是直接提前装好 VS Build Tools 的“使用 C 的桌面开发”工作负载后面会省掉一堆奇奇怪怪的编译报错。第三步初始化配置。项目里通常有一个config.example.yaml或者类似文件把它复制一份改成config.yamlcp config.example.yaml config.yaml第四步启动服务openclaw start或者用 Node 直接拉起主进程。首次启动会检查依赖完整性、初始化会话目录、打印出本地访问地址。看到“started”或“listening”字样就说明跑起来了。Windows 下最容易忽略的是防火墙弹窗。第一次监听端口时系统会问“是否允许应用通过防火墙”记得要点“允许”否则局域网内的其他设备没法访问。3.2 Ubuntu 服务器部署步骤服务器部署和 Windows 大同小异但有几个点更严格。我在 Ubuntu 22.04 LTS 上完整走了一遍步骤记录如下。先更新系统索引并安装基础工具sudo apt update sudo apt install -y git curl build-essential python3 python3-pipNode.js 不要用 apt 自带的老版本建议走 nvm 装curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 20 nvm alias default 20然后同样克隆 OpenClaw 仓库、安装依赖。这里有个和 Windows 不同的点生产环境建议用 systemd 管理进程否则你一关 SSHOpenClaw 就跟着停了。写一个 service 文件托管到 systemd可以实现开机自启、崩溃自动拉起[Unit] DescriptionOpenClaw Agent Server Afternetwork.target [Service] Typesimple Useryourname WorkingDirectory/opt/openclaw ExecStart/usr/bin/node server.js Restartalways RestartSec5 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target装上之后systemctl enable openclaw机器重启它也会自己起来。顺带说一句经常有人问“飞牛安装 openclaw”。飞牛 OS 本身就是基于 Debian 的 Linux 系统直接按 Ubuntu 这条路走没有本质区别注意目录权限和 systemd 配置就行。3.3 一键部署脚本到底做了什么如果你只想快速跑通OpenClaw 社区提供了一键部署脚本官方支持的安装命令通常长这样bash (curl -sL 官方脚本地址)我建议不要盲目执行先搞清楚脚本做了什么。以我查看过的部署脚本逻辑来看它大致干了这么几件事检测当前系统的发行版和架构检查 Node.js、Python、Git 是否已安装缺失则自动安装克隆项目代码到固定目录安装 npm 和 pip 依赖生成默认配置文件不覆盖已有配置创建 systemd serviceLinux 下或注册 Windows 服务启动服务并打印访问地址。一键脚本最大的价值是省时间尤其是重复部署多台机器时。但它有两个问题一是你无法确认脚本每一步干了什么存在被植入风险二是脚本默认配置不一定适合你的网络环境。我的习惯是第一次手动装一遍把每个环节都摸透之后再用一键脚本做批量复制。这样出了问题你也知道去哪排查。4. 核心配置从能跑到好用只差这几步4.1 配置大模型以千问为例OpenClaw 装好只是万里长征第一步它本身不带任何模型能力必须接入一个大模型 API 才能真正干活。这里以国内用户很容易拿到的阿里云千问DashScope为例讲一下配置逻辑。先到阿里云百炼平台申请一个 API Key。然后打开 OpenClaw 的config.yaml找到模型配置段。整体思路是指定 provider服务商、model模型名、api_key密钥、base_url接口地址。千问的 OpenAI 兼容模式地址是https://dashscope.aliyuncs.com/compatible-mode/v1配置文件大致长这样model: provider: dashscope name: qwen-plus api_key: sk-你的密钥 base_url: https://dashscope.aliyuncs.com/compatible-mode/v1改完后重启服务测试一下 Agent 是否能正常回复。如果报 401 或者 403优先检查是不是密钥复制错了如果报连接超时检查服务器能不能访问阿里云的接口地址。一个实用的建议不要只配一个模型。OpenClaw 支持多模型配置你可以把qwen-turbo配成轻量任务的默认模型把qwen-max这类更强模型留给复杂推理场景。实际跑下来轻量模型负责日常文本处理、重模型负责复杂逻辑分析成本和速度都能平衡。4.2 Agent 的 Channel 选择逻辑Channel 是理解 OpenClaw 的关键概念。我习惯把它解释成“Agent 对外发声的通道”Agent 不直接面对用户而是把消息发到某个渠道用户在那个渠道里看到并回复它。channel 决定了 Agent 和外部世界交互的边界。配置文件里通常会有一个 channels 段channels: - type: cli enabled: true - type: teams enabled: true - type: obsidian enabled: false - type: web enabled: true每个 Agent 启动时你可以指定它走哪个 channel。新手最常问“agent 怎么选择 channel”答案就在启动命令的参数里openclaw run --agent your_agent --channel teams或者通过配置文件给某个 Agent 绑定固定 channel。我的建议是日常调试用 CLI 或 Web 渠道因为即时反馈最快稳定运行后再接到 Teams、Obsidian 这些正式渠道里。调试阶段直接上 Teams每次消息都要走一遍外部服务排查问题会慢很多。4.3 接入 Teams 和 Obsidian 的实战配置接入 Microsoft Teams 是不少公司用户的需求——早晨让 Agent 自动在团队频道里推送日报。实现方式是在 Azure 门户注册一个应用拿到应用 ID 和客户端密钥然后在 OpenClaw 的配置里填写这两个值并指定运行模式。相关配置大致长这样teams: client_id: 你的应用ID client_secret: 你的客户端密钥 tenant_id: 你的租户ID之后用 Teams 账号登录对应频道添加机器人应用Agent 就能在这个频道里收发消息了。这里要特别提醒Azure 注册应用和配置机器人的流程权限项非常多最容易漏的是“Application permissions”里的 Team.ReadBasic.All 和 ChannelMessage.Send 这两项授权。漏了之后的表现很诡异——机器人看起来在线但一调用接口就报权限错误。我当时卡了半个小时最后发现就是少勾了一个权限。接入 Obsidian 则是另一类场景适合用 AI 自动整理笔记。Obsidian 社区有一个 Local REST API 插件装上后开启服务OpenClaw 就可以通过本地 HTTP 接口往 Vault 里写 Markdown 文件。配置非常简单就三个值Vault 路径、端口、API Key。配上之后你可以让 Agent 定时把工作日报、会议纪要整理成规范笔记放进 Obsidian 库。这条链路给我的体感是AI 写笔记这件事难点从来不是写而是“写完能不能落到你舒服的位置”。OpenClaw 把写文件这个动作交给了可配置的 channel这个设计很合我胃口。5. 常见问题与排查实录我踩过的坑都在这5.1 “session file locked (timeout 60000ms)”深度排查这个报错在 OpenClaw 的群里出现的频率非常高agent failed before reply: session file locked (timeout 60000ms)翻译成人话就是Agent 尝试获取会话文件的锁等了 60 秒一直没等到直接放弃了。会话锁机制本身是防止多个进程同时读写同一个会话文件导致数据损坏属于正常设计。出现这个错误几乎可以断定是有哪个地方占了锁没有释放。按我的排查顺序你照做即可看有没有多个 OpenClaw 进程在跑。Windows 按 CtrlShiftEsc 打开任务管理器看 node 进程Linux 执行ps aux | grep openclaw。如果有多个杀掉多余的只留一个主进程。清掉残留的锁文件。锁文件一般在会话目录下以.lock结尾Linux 下通常在~/.openclaw/sessions/目录。停掉服务后手动删掉对应的.lock文件再重启。注意锁文件是程序退出时自动释放的正常情况不需要手动删只有异常退出断电、强制 kill才会残留。检查是不是网络磁盘。如果会话目录放在 NFS 或者 SMB 挂载的共享盘上文件锁往往不会正常释放这个错误会特别频繁。解决办法是把数据目录改到本地磁盘。修改超时时间作为临时规避手段。在配置里把 timeout 调大例如session_timeout: 120000能缓解但不根治锁竞争的根本原因还得查。这个坑我印象太深了。有次在服务器上同时起了两个 OpenClaw 实例做测试结果两个实例抢占同一个会话文件报错刷屏。后来我养成了一个习惯任何场景下一个数据目录只允许一个 OpenClaw 实例访问。5.2 Agent 无响应的通用排查清单“Agent 不回话”是最让人抓狂的因为报错信息经常没有。这里分享一个按优先级排序的排查清单模型链路是否通用 curl 直接测一下配置的 base_url 和密钥能通才是真通别在 OpenClaw 里反复试错频道是否是真启用状态有时候配置里写enabled: true但外面服务比如 Teams 机器人没注册成功没就绪消息根本送不进来日志级别有没有看够把 OpenClaw 的日志级别调到 debug大部分“无响应”其实是被某些异常静默吞掉了细节依赖进程是否存活内存不够或者被系统 OOM kill主进程还活着但子进程挂了也会表现为无响应dmesg | tail看一下有没有 OOM 记录端口是否冲突多个实例监听同一端口服务会起不来或者行为异常。说实话Agent 框架的排查思路和排查传统 Web 服务高度一致——看日志、看进程、看网络、看资源。别把它想得太特殊按顺序查就是了。5.3 环境变量配置错误导致启动失败的补救这个坑在 Windows 上特别典型。装完 Python 和 Node 之后终端里能跑通python但 OpenClaw 启动时仍然提示找不到模块或者找不到命令。原因通常是你所在的终端环境变量刷新时机不对。Windows 修改环境变量后已经打开的终端不会自动获取新值必须新开一个终端窗口才会生效。很多人的操作顺序是装完 Python → 继续在同一个旧终端里跑 OpenClaw → 报错 → 怀疑安装有问题。解决办法简单得离谱重新打开终端再执行一遍安装启动命令。如果是已经新开终端仍然报错那就需要手动确认环境变量是否写入。python -c import sys; print(sys.executable)这条命令能输出当前 Python 解释器的实际路径。如果输出的路径和你安装的不一致说明 PATH 里存在多个 Python 版本比如 Windows 应用商店的占位版和官网正规版冲突。解决方法是在系统环境变量的 PATH 里把官网版本的路径调到更靠前的位置。Linux 下遇到同类问题多是因为没有重新加载 shell 配置source ~/.bashrc这个问题虽然低级但一旦碰上耽误的时间真不少。我自己就在一台机器上同时存在了三个 Python 版本排查了快一个小时才搞清楚最后把多余的版本卸载了个干净。最后说点实在的OpenClaw 的安装配置单看每一步都不难装依赖、拉代码、改配置、启动。难的是把这些步骤放在你的具体环境里能一次跑通。我个人的体会是第一次折腾时留出半天时间是合理的真别想着“五分钟部署完”。但熬过最初阶段把模型和 channel 都理顺之后这套系统带来的自由度非常值得。最后再分享一个小技巧配置文件的修改请务必放到 git 里管理。每改动一次提交一次写清楚改了啥。Agent 配置这种东西经常是调了一个模型参数两天后想退回发现忘了原来是怎么写的。有 git 历史保护你的试错成本几乎为零。这个习惯比任何安装技巧都重要真的。