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。

Image

因此，对于网关日志路径问题，最稳妥的方案是等待官方发布修复补丁，而非尝试不稳定的临时解决方案。

三、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二进制文件目录的符号链接： 
    mklink /D C:\bin "D:\Program Files\Git\bin"
    执行此方法后，通常可以在命令行中单独运行qmd。然而，在集成到OpenClaw进行部署时，系统可能仍然报告"/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的启动链可以发现一个绕弯的逻辑：

  1. "PATH\npm\global\qmd.cmd" 文件的作用是调用shell（sh）来执行 "PATH\npm\global\node_modules\@tobilu\qmd\bin\qmd"。
  2. 而"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命令，这可以被视为一种针对特定集成环境的“曲线救国”方案。