OpenClaw部署实战:日志迁移bug与qmd安装问题深度解决
一、引言:OpenClaw部署问题概述
本系列文章旨在系统记录在部署OpenClaw过程中遇到的典型问题与解决方案。本期聚焦两个核心难题:一是网关(gateway)日志的滚动记录配置异常;二是qmd组件的安装与集成障碍。本文基于Windows 11操作系统,搭配OpenClaw版本2026.3.28进行说明,为遇到类似问题的用户提供参考路径。
二、日志迁移问题:网关日志路径设置bug
OpenClaw在运行过程中主要生成两类日志文件,各自承担不同的记录功能。
- 会话(session)日志:用于保存用户界面与“小龙虾”代理的交互对话历史,默认存储路径为
.\.openclaw\agents\main\sessions。 - 网关(gateway)日志:用于记录网关服务的日常运行状态与动态信息,默认存储路径为
C:\Users\你的用户名\.openclaw\logs\openclaw-YYYY-MM-DD.log。
会话日志的迁移配置相对直接。用户只需通过两个步骤即可完成:首先在配置文件openclaw.json中更新workspace路径;其次设置系统级环境变量OPENCLAW_HOME。
- 以管理员权限启动PowerShell,设置环境变量:
[Environment]::SetEnvironmentVariable("OPENCLAW_HOME", "D:\openclaw\config", "Machine") - 随后,修改workspace的指向路径:
openclaw config set agents.defaults.workspace "D:\openclaw\config\.openclaw\workspace"
网关日志的路径配置则较为棘手。根据官方文档,应通过设置logging.file参数来实现路径自定义。然而,在实际操作中发现,即使按照指南修改配置代码,日志文件仍无法成功重定向至新位置。这已被确认为当前版本的一个官方bug。

因此,对于网关日志路径问题,最稳妥的方案是等待官方发布修复补丁,而非尝试不稳定的临时解决方案。
三、qmd部署问题:安装与配置挑战
qmd组件能够有效优化“小龙虾”在处理任务时的token消耗效率。虽然2026.3.28版本的OpenClaw预留了qmd的调用接口,但需要用户自行下载并部署。这一过程在Windows环境下常遇到以下几个障碍。
3.1 /bin/sh缺失问题:跨平台兼容性挑战
当用户使用bun工具拉取qmd后,尝试测试其是否安装成功时,往往会遇到如下错误提示:
error: interpreter executable "/bin/sh" not found in %PATH%
该错误的根源在于,qmd最初是针对Unix/Linux环境设计的,其启动脚本会尝试寻找/bin/sh这个可执行文件。在Windows系统中,该路径并不存在,即使系统安装了Git Bash,其sh.exe通常位于其他目录。
解决此问题有两种常见思路:
- 方法一:在qmd根目录放置sh.exe
将Git Bash提供的
sh.exe复制到运行qmd的根目录下。需要注意的是,Windows系统本身不提供sh.exe,需通过安装Git Bash来获得。 - 方法二:创建符号链接欺骗系统
以管理员身份打开命令提示符(cmd),执行以下命令,创建一个指向Git Bash二进制文件目录的符号链接:
执行此方法后,通常可以在命令行中单独运行qmd。然而,在集成到OpenClaw进行部署时,系统可能仍然报告mklink /D C:\bin "D:\Program Files\Git\bin""/bin/sh" not found错误。因此,许多用户转向第二种更为深入的解决方案。
3.2 shell执行问题:qmd.cmd修改陷阱
第二种解决方案的核心是通过npm包管理器拉取qmd,然后修改其启动脚本。
- 注意事项:在开始前,请先移除之前通过bun安装的qmd。
- 参考指引:具体修改步骤可查阅外部技术博客(例如:https://blog.csdn.net/m0_60387100/article/details/159208307)。
- 前置操作:确保将Git Bash的安装路径(如
"D:\Program Files\Git\bin")添加到系统的PATH环境变量中。
关键步骤在于修改位于"PATH/npm/global"目录下的qmd.cmd文件(其中PATH指代用户设置的npm全局安装路径)。常见做法是将其内容改为直接通过Node.js运行核心的JavaScript文件:
@echo off
node "PATH\npm\global\node_modules\@tobilu\qmd\dist\cli\qmd.js" %*
但将此修改应用于OpenClaw部署时,可能会触发新的错误:
Error: qmd.cmd wrapper resolved, but no executable/Node entrypoint could be resolved without shell execution.
此错误表明OpenClaw能够定位到qmd.cmd,但要求该文件必须通过shell(即sh.exe)来启动,不能绕过shell直接由PowerShell或cmd调用,这使问题变得更加复杂。
深入分析qmd的启动链可以发现一个绕弯的逻辑:
"PATH\npm\global\qmd.cmd"文件的作用是调用shell(sh)来执行"PATH\npm\global\node_modules\@tobilu\qmd\bin\qmd"。- 而
"PATH\npm\global\node_modules\@tobilu\qmd\bin\qmd"这个文件本身又是一个脚本,其作用是调用Node.js来执行"PATH\npm\global\node_modules\@tobilu\qmd\dist\cli\qmd.js"。
因此,对于2026.3.28版本的OpenClaw,位于"PATH/npm/global"的qmd.cmd文件不应被修改,因为它负责正确调用sh.exe,这是启动链条中不可或缺的一环。
3.3 最终解决方案:修改qmd文件为JavaScript
如果保持qmd.cmd不变,OpenClaw在部署时便能顺利找到并调用它。但随后,OpenClaw会试图用Node.js直接执行"PATH\npm\global\node_modules\@tobilu\qmd\bin\qmd"文件。问题在于,该文件是一个Unix shell脚本格式的文件,Node.js无法解析其语法,从而导致如下错误:
SyntaxError: Invalid or unexpected token
最终的解决方案是针对这个特定版本的OpenClaw,修改"PATH\npm\global\node_modules\@tobilu\qmd\bin\qmd"文件本身,将其内容替换为Node.js能够直接执行的JavaScript代码。修改后的内容示例如下:
#!/usr/bin/env node
import { pathToFileURL } from 'url';
import { dirname, join } from 'path';
import { fileURLToPath } from 'url';
const __filename = fileURLToPath(import.meta.url);
const __dirname = dirname(__filename);
const DIR = dirname(__dirname);
const qmdJs = join(DIR, 'dist', 'cli', 'qmd.js');
// 使用 pathToFileURL 将 Windows 绝对路径转换为 file:// URL
import(pathToFileURL(qmdJs));
通过此项修改,OpenClaw便能成功部署并调用qmd组件。不过,这种修改的副作用是在普通的命令提示符(cmd)窗口中无法再直接运行qmd命令,这可以被视为一种针对特定集成环境的“曲线救国”方案。