OpenClaw 这阵子在 AI Agent 圈子里热度涨得很快但真正动手部署过的人都知道“安装完成”和“稳定跑起来”之间差着一大截。我前后花了两天时间把 Windowshub、WSL2 校验、千问配置、channel 选择、session 文件锁、飞书输出截断这些坑逐个踩了一遍才把这个 Agent 框架真正用得顺手。这篇笔记不打算复述官方文档只讲我实际部署过程中最容易被卡住的环节、排查思路和最终采用的方案。无论你是刚从搜索框点进来想部署 OpenClaw还是已经装完但卡在某个报错上这篇都应该能帮你省下不少时间。1. 部署前要做的选择OpenClaw 应该跑在什么环境里1.1 它在 Agent 生态里到底是个什么位置OpenClaw 是一个可自托管的 AI Agent 框架核心特点是“一个 Agent 管所有入口”。它采用主进程加 Agent 子进程的架构主进程负责配置、会话调度和外部通道接入Agent 子进程负责具体任务执行和模型调用。所有对话历史以 session 文件落盘这就解释了为什么后面会出现 session 文件锁的问题。它和前身 Clawdbot 的演进关系不用太纠结你只需要知道OpenClaw 把“模型接入”“工具调用”“IM 通道接入”“多 Agent 管理”这几件事统一到了一套配置文件里。也就是说你配置一次千问模型就能同时让这个 Agent 跑在飞书、Discord、终端和自带的网页界面 Lair 上不用为每个入口单独写一套对接代码。我判断一个 Agent 框架值不值得用主要看三件事能不能自由换模型、能不能同时接多个聊天通道、会话上下文能不能自己掌握。OpenClaw 在这三点上都做得比较彻底尤其是自托管这一点数据和配置都在你手里这是很多云端 Agent 平台给不了的。1.2 和 WorkBuddy 这类产品怎么选很多人会在 OpenClaw 和 WorkBuddy 之间犹豫这两个东西表面看都是 Agent 工具实际路线差别很大。我把两者的对比列成一张表方便你按自己的情况判断。对比维度OpenClawWorkBuddy部署方式自托管为主数据在自己服务器或本机偏 SaaS 托管开箱即用模型自由度任意 OpenAI 兼容接口可接千问、DeepSeek 等通常由平台内置模型或指定接口定制能力配置文件深度可改可自己加工具和通道面向普通用户定制空间有限使用门槛需要懂一点命令行和配置门槛低界面化操作适合场景技术型用户、团队内部自建、对数据敏感快速验证需求、不想碰运维的人我的建议很直接如果你不想碰配置文件对数据主权也没那么敏感WorkBuddy 这类托管产品确实更省事。但如果你想自己掌控整个 Agent 的运行逻辑想把千问、飞书、会话数据都放在自己手里OpenClaw 是更合适的方向。我最终选 OpenClaw就是因为想在会话管理、模型参数和通道接入上有完全的控制权。1.3 Windows、Linux 与 Docker我最终怎么选OpenClaw 官方支持三种部署形态我实际都试过各有各的取舍。部署形态优点缺点适合谁Docker 容器环境隔离清理方便需要理解容器卷和端口映射熟悉容器的人Linux systemd稳定适合 7x24 小时运行服务器上调试不方便有云服务器或 NAS 的人Windows WSL2日常电脑就能跑有图形界面安装链路长WSL2 校验容易出问题主要用 Windows 办公的人我自己是在 Windows 11 上用 Windowshub 部署的因为日常工作主力机就是 Windows方便随时打开 Lair 网页界面跟 Agent 交互。如果你手头有一台 Linux 服务器那我更推荐 systemd 方式稳定性会好不少也不容易被 Windows 更新和 WSL2 状态干扰。2. Windows 部署与 WSL2 校验第一只拦路虎2.1 Windowshub 安装到底做了什么Windowshub 是 OpenClaw 在 Windows 上的安装器它的工作原理不是直接跑一个 exe 进程而是先检查 WSL2 环境然后在 WSL2 内部拉起容器来跑 OpenClaw。所以 Windowshub 本质上做的是“环境检测 容器编排”这两件事。安装流程本身不复杂从官网下载 Windowshub 安装包双击运行等待它检测环境和拉取镜像完成后会自动映射端口。默认的 Lair 网页界面跑在 18789 端口浏览器打开就能看到 Agent 的可视化交互界面。整个过程对用户隐藏了 WSL2 和容器的细节正常情况下是很省心的。但问题恰恰出在那个“环境检测”步骤上一旦检测不通过安装器会直接抛错而且错误提示非常不友好这就是大量用户卡住的地方。2.2 could not safely verify the wsl2 environment 的完整排查这个报错字符串是could not safely verify the wsl2 environment.意思是安装器无法确认 WSL2 环境是安全可用的。大部分人在这一步的直觉是去下载 WSL 补丁或者重装 Windowshub但实际原因往往更基础。我按自己的排查顺序整理成下面几步。先在 PowerShell 里执行wsl --status看输出里是否明确写着Default Version: 2并且能列出至少一个 Linux 发行版。如果wsl --status提示 WSL 命令未找到说明系统根本没启用 WSL 功能需要先安装。执行wsl --update更新 WSL 内核这个步骤非常容易忽略。Windows 10 和部分 Windows 11 系统默认携带的 WSL 内核版本比较旧Windowshub 会认为这个环境不可信。再用wsl --list --verbose确认默认发行版存在并且 STATE 列是 Running 或 Stopped 状态。如果列表为空需要先安装一个 Ubuntu 发行版。在 PowerShell 里执行wsl --install -d Ubuntu-24.04首次启动时设置一个 Linux 用户名和密码。如果以上都没问题还报错检查 Windows 功能里的“虚拟机平台”是否开启。PowerShell 管理员模式执行bcdedit /set hypervisorlaunchtype auto然后重启电脑。这一步对老电脑特别关键虚拟化技术没有完全启用时WSL2 根本无法正常工作。我还遇到过一个比较隐蔽的情况系统里装了 Docker DesktopDocker 自己的 Hyper-V 后端和 Windows 的虚拟化配置产生冲突导致 Windowshub 检测到 WSL2 状态异常。如果电脑上装了 Docker Desktop建议先把 Docker Desktop 退出再尝试安装 Windowshub。完成上述所有步骤后重新执行wsl --status确认默认版本是 2 且有发行版再跑一次 Windowshub。正常情况下就不会再出现这个报错。2.3 如果你有 Linux 服务器可以直接参考这套流程如果你的主力环境是 Linux 服务器部署步骤比 Windows 简单得多。官方安装脚本一行命令搞定然后执行环境自检和 Agent 创建。curl -fsSL https://openclaw.ai/install.sh | bash openclaw doctor openclaw agent new demoopenclaw doctor会检查环境、配置、模型接口是否可达这个命令在遇到任何部署问题时都应该第一时间跑一遍。创建 Agent 后可以用openclaw agent list查看当前所有 Agent 的状态。如果你希望 OpenClaw 开机自启、异常退出后自动拉起用 systemd 托管比较稳妥。下面是一个最小可用的 service 配置路径以你自己实际的安装位置为准。[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple ExecStart/usr/local/bin/openclaw serve Restartalways RestartSec5 EnvironmentPATH/usr/local/bin:/usr/bin:/bin [Install] WantedBymulti-user.target把这个文件放到/etc/systemd/system/openclaw.service然后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw就能像管理普通系统服务一样管理 OpenClaw 了。3. 配置千问OpenClaw 接上 Qwen 的完整过程3.1 先搞清楚配置文件的结构OpenClaw 的配置核心是一个 JSON 文件顶层按 agents 节点组织每个 Agent 又包含 model 和 channels 两个关键子节点。model 节点决定这个 Agent 用哪个模型、走哪个接口channels 节点决定这个 Agent 接哪些聊天入口。很多人在配置千问时失败是因为默认配置里写的是 OpenAI 官方接口。OpenClaw 之所以能接千问靠的是 DashScope 提供的 OpenAI 兼容接口也就是说只要把 baseURL 指到 DashScope 的兼容端点OpenAI 协议就能直接复用。3.2 接上千问的具体配置先去阿里云百炼控制台开通 DashScope 服务并创建 API Key这个 Key 就是下面配置里的 apiKey 字段。然后编辑 OpenClaw 配置文件找到或创建对应 Agent 的 model 节点改成下面的内容。{ agents: { demo: { model: { provider: { id: openai, options: { baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1, apiKey: sk-你的DashScope密钥, model: qwen-plus } } } } } }这里最关键的是 provider.id 保持openai不动因为 OpenClaw 通过这个 id 来决定走 OpenAI 协议而 DashScope 兼容这个协议。baseURL 必须填 DashScope 的兼容模式地址最后面那个/v1不能漏掉。改完配置后重启 OpenClaw 服务然后打开 Lair 页面给 Agent 发一句话试试。如果 Agent 正常回复说明千问已经接通如果报错优先检查 apiKey 是否正确、baseURL 末尾是否带/v1。千问系列模型的选择上我建议普通对话和工具调用用qwen-plus它对工具调用的支持比较稳定追求更高推理质量而且在预算允许的情况下可以换qwen-max只是简单问答不想计较延迟用qwen-turbo更便宜。3.3 模型配置里容易踩的坑配置模型时最容易遇到的一个问题是模型名写错了导致 404。DashScope 的模型名是完整字符串比如qwen-plus不带日期后缀的版本名通常会在服务端自动映射到最新版。如果你填了不存在的名字OpenClaw 会直接报 model not found这种错误和网络没关系先检查模型名。还有一点需要注意OpenClaw 的 Agent 要调用工具和文件操作能力时模型本身必须支持工具调用。千问系列里qwen-plus和qwen-max都没问题但如果你换了某个不支持工具调用的小模型Agent 会出现“只会对话、不会干活”的奇怪表现。模型参数里我习惯调一个maxOutputTokens防止 Agent 一次生成超长内容。这个参数在配置里的位置和 provider.options 同层很多版本支持直接写maxOutputTokens: 1000。尤其是接飞书通道时这个参数关系到下面的消息截断问题后面会展开说。4. Channel 选择机制让 Agent 在正确的出口回复4.1 Channel 到底是什么OpenClaw 里的 channel 可以理解成 Agent 对外交互的一个入口。默认情况下每个 Agent 都有 default 通道这个通道包含本地会话和 Lair 网页界面。除此之外你可以给 Agent 绑定飞书、Discord、Telegram 等 IM channel。每个 Agent 是可以同时绑定多个 channel 的这也是 OpenClaw 比较爽的地方。你在飞书里问它一句它就在飞书里回你你在 Lair 网页里问它它就在网页里回。回复出口不是随机选的而是根据消息从哪个 channel 进来就回哪个 channel。4.2 Agent 怎么选择 channel部署时绑定和运行时切换部署时用openclaw agent new创建 Agent 时命令会交互式询问要接入哪些 channel你按提示选择就好。也可以事后在配置文件里手动给 channels 节点加内容比如给刚才的 demo Agent 加一个飞书 channel。{ agents: { demo: { channels: { default: {}, feishu: { appIdEnv: os_feishu_app_id, appSecretEnv: os_feishu_app_secret } } } } }飞书开放平台的 appId 和 appSecret 不建议直接明文写在配置里用环境变量引用更安全。对应的环境变量在服务启动前设置好OpenClaw 会按变量名读取。运行时切换 channel最直观的方式是在 Lair 网页界面的通道选择器里切换选完以后你在网页里的对话就会走对应的通道出口。部分版本还支持在对话里用斜杠指令切换具体以你当前版本的帮助说明为准。实际使用中的一个关键经验是不需要刻意让 Agent 去“选择”channel它的行为规则很简单哪个通道进来的消息就回哪个通道。如果你发现它回复的通道不对优先检查消息是从哪个入口发起的而不是去调模型提示词。4.3 我在 channel 配置上踩过的坑第一个坑是同一个飞书应用不能同时被多个 Agent 绑定。OpenClaw 在处理飞书消息时如果拿同一个 appId 的凭证对应两个 Agent消息投递会变得不可控有时候 A 不回有时候 B 不回。每个 Agent 最好配独立的飞书应用或者用 workspaceId 区分开。第二个坑是 channel 的权限配置。飞书用户进群聊天时如果 Agent 的 channel 配置里没有开启 chat 或 history 权限它可能收到消息但不回复或者回复了但不带上下文。权限字段大多在 channels 配置的 permissions 节点下控制。第三个坑和管理会话有关。如果你同时在 Lair 网页和飞书里跟同一个 Agent 说话就有概率触发 session 文件锁问题。这是我自己最惨痛的一次踩坑下一节单独说。5. session 文件锁死agent failed before reply 的一次完整排查5.1 现象等了 60 秒只等到一句报错某天我在 Lair 网页里跟 demo Agent 聊天聊到一半忘了关页面然后又跑去飞书里 同一个 Agent。等了大约一分钟飞书里弹出一句agent failed before reply: session file locked (timeout 60000ms)大白话翻译一下Agent 在回复你之前就失败了原因是会话文件被锁住等待 60 秒超时。这个报错网上讨论不少但真正把它讲清楚的不多。5.2 我的排查链路我先执行openclaw agent list看了一下 demo Agent 的状态显示在线说明主进程没问题。于是问题大概率出在会话子进程上。继续在进程列表里找残留的 Agent 子进程。Linux 上用ps aux | grep openclawWindows 上用Get-Process | Where-Object {$_.Name -like *openclaw*}。结果显示确实有多个 openclaw-agent 子进程在跑其中一个是网页端会话遗留的另一个是飞书触发的新进程。然后我去看了会话文件的存储目录。OpenClaw 的会话数据一般在用户目录下的.openclaw目录里按 Agent 名建子目录里面再按会话 ID 存文件。每个活跃会话旁边会有一个锁文件用于保证同一时间只有一个进程在写这个会话。问题到这里就清楚了网页端会话没有正常退出它持有的锁文件一直没释放飞书端新起的 Agent 进程尝试去写同一个会话文件时拿到不到锁等待 60 秒后超时报错。5.3 根因与解决方式根因本质上是多入口并发写同一个会话。OpenClaw 的会话机制设计成单写者模式同一会话同一时间只允许一个 Agent 子进程操作这是为了保护上下文一致性但代价就是多端同时对话时会出现锁竞争。我的处理方式是先退出所有相关 Agent 子进程然后清理那个会话的锁文件。如果你的 Agent 名是 demo可以这样操作# 确认没有正在使用的会话 openclaw agent list # 停止相关子进程根据实际进程名调整 pkill -f openclaw-agent # 进入会话目录删除锁文件 cd ~/.openclaw/agents/demo/sessions ls -la rm -f *.lock如果清理锁文件后问题还在说明会话文件本身可能已经损坏最直接的办法是把这个会话文件备份后删除让 Agent 重新创建一个干净会话。注意删掉会话等于丢掉这段上下文非必要不建议一上来就删。如果你用 Docker 部署找.openclaw目录的位置取决于你挂载卷时的目标路径默认情况下是容器内/root/.openclaw。在宿主机上直接操作挂载目录里的 sessions 文件夹即可。5.4 怎么避免再次发生从那以后我立了一个规矩同一个 Agent同一时间只从一个入口对话。在网页里聊完就先把网页会话退出再去飞书里开新对话。不要贪方便两边一起开。另一个习惯是如果 Agent 出现异常卡顿不要急着去删配置先执行openclaw doctor再检查进程列表通常都能定位到锁或者残留进程的问题。删配置是最后手段而且解决不了锁竞争。6. 飞书输出截断长回复的另一个边界6.1 明明模型生成了全部内容飞书却只发了一半用飞书接入 OpenClaw 后我发现一个很烦的问题Agent 回答长问题时飞书里收到的消息经常是后半段被硬生生砍掉或者到某个位置突然结束连个提示都没有。搜索热词里那条“openclaw在飞书输出容易被截断”说的就是它。根因在飞书那边的消息体长度限制不是模型的问题。飞书自定义机器人的单条消息体限制大约是 4096 字节中文字符按 UTF-8 编码一个就要 3 字节也就是说大约 1300 到 1400 个汉字就触顶了。OpenClaw 检测到超长后为了保证消息能发出去会直接在限制处截断于是你看到的就是一段戛然而止的内容。6.2 有效的处理方案我试过几种方案最终留下两条最实用的。第一条是从生成源头上控制长度。把 Agent 的maxOutputTokens调低到一个合理范围比如 1000 到 1500同时在系统提示词里明确要求“回复使用短段落、要点式表达、不要展开长文”。千问模型对指令的遵循能力不错配合限制后大部分回复都能控制在飞书的安全长度内。第二条思路是把长内容“外置”。遇到需要输出大段代码、长报告、完整配置文件的场景让 Agent 不要直接在聊天里输出全文而是用文件写入工具把内容写成一个文件然后在飞书里只回复下载链接或者文件路径。这样既绕过了消息长度限制还方便后续归档和分享。飞书这边还有一个方案是换企业自建应用开启卡片消息或者富文本能力。卡片的可承载内容范围比普通文本消息大不少但从我的测试来看并非没有限制而且配置成本更高个人使用场景下优先级不高。6.3 不同处理方式的对比方式成本效果我的建议调低 maxOutputTokens 提示词约束低中等能覆盖大多数日常问答首选先试这个长内容写文件再发链接中高适合代码和长文有工具调用需求时必用换企业自建应用开卡片高中等仍有上限特殊场景再考虑我把 maxOutputTokens 设置在 1200再配合“要点式回复”的提示词以后飞书截断出现的频率已经很低。剩下的偶发情况基本都发生在 Agent 忍不住要写完整代码的时候这时候就让它走文件方案。7. 部署完成后的运维习惯与一点个人心得OpenClaw 跑起来以后真正影响稳定性的往往不是部署那一下而是后续的使用习惯。我把这段时间沉淀下来的几条经验放在这里不算什么高深技巧都是实打实换来的教训。第一openclaw doctor是个好东西Agent 行为异常、配置改了不生效、模型调用报错先跑一遍诊断比对着日志瞎猜效率高很多。第二.openclaw目录值得定期备份。这个目录里装着所有 Agent 配置、环境变量引用、会话历史。升级 OpenClaw 或者重装系统之前先把这个目录整个备份一份能避免很多不可逆的损失。第三API Key 这类敏感信息能走环境变量就不要明文写在配置文件里。配置文件是会被同步、被分享、被传到服务器上的而环境变量只在当前会话里存活安全边界清楚得多。第四一个 Agent 尽量对应一个常驻入口。开太多通道和并发会话表面上很酷实际运行中你会不断遇到 session 锁、消息错乱、上下文丢失这类问题。Agent 框架的边界是客观存在的尊重它用起来会顺手得多。如果你现在还在从 Windowshub 一路踩坑遇到 WSL2 校验失败就先去跑一遍wsl --status遇到锁问题就先查进程遇到飞书截断就先限输出长度。把这些问题逐个理顺OpenClaw 其实可以成为一个相当可靠的日常助手。后面我如果折腾出更顺手的配置组合再来更新这篇笔记。
