1. 项目概述：这不是一个“装软件”的操作，而是一次数字员工的本地化落地实践

OpenClaw 这个名字最近在技术圈和自动化办公领域出现频率陡增，但很多人点开 GitHub 仓库第一眼看到的不是文档，而是满屏的 Python 依赖、Docker Compose 文件和一堆带 .env 后缀的配置项——瞬间就退了。我去年底开始接触 OpenClaw，最初也以为它只是另一个 RPA 工具的换皮版本，直到真正把它跑通在一台 Windows 笔记本上，用它自动整理周报、抓取竞品价格、把飞书群里的会议纪要转成结构化表格，才意识到：它不是“替代人工”，而是把人从重复性认知劳动中解放出来，让“数字员工”这个概念第一次在我自己的工作流里有了体温和呼吸。

所谓“数字员工”，不是科幻片里会端茶倒水的机器人，而是能理解你日常任务意图、调用真实工具（Excel、浏览器、邮件客户端、内部系统 API）、执行多步骤操作、出错时主动反馈、甚至能根据历史行为自我优化的一套可部署、可调试、可审计的本地化智能体系统。OpenClaw 的核心价值，恰恰在于它把大模型能力、工具调用框架、任务编排引擎和轻量级 UI 全部打包进一个可离线运行的架构里，不依赖任何云服务，所有数据不出本地硬盘。这在金融、政务、法务等对数据主权极度敏感的场景里，是决定性的优势。Windows 环境下的部署难点，从来不是“能不能装”，而是“怎么让它在没有 Linux 基础的普通办公电脑上，稳定、安静、不弹窗、不卡顿地持续工作”。我试过 7 种不同组合：纯 Python 虚拟环境、WSL2、Docker Desktop + WSL2 后端、Docker Desktop + Hyper-V 后端、Minikube、Rancher Desktop，最后锁定了一套实测下来最省心、最兼容、重启后自动恢复、连 IT 部门同事都能看懂日志的方案。这篇内容，就是我把这半年踩过的所有坑、调过的所有参数、写过的所有批处理脚本，全部摊开给你看的实操手记。它不讲高深理论，只告诉你哪一步该敲什么命令、为什么必须加那个参数、哪个文件改错一个字符就会导致整个服务起不来、以及最关键的——如何让这个“数字员工”在你下班后继续替你干活。

2. 整体设计思路与方案选型逻辑：为什么放弃 WSL2 和纯 Docker，选择“Docker Desktop + 原生 Windows 容器”组合

部署方案的选择，本质上是在“可控性”、“兼容性”和“维护成本”三者之间做动态权衡。很多教程一上来就推 WSL2，理由很充分：Linux 环境原生支持、Docker 生态成熟、社区问题多。但我在实际给销售、HR、财务部门同事部署时发现，WSL2 在 Windows 上存在三个无法绕开的硬伤：第一，WSL2 的网络栈是虚拟 NAT，当 OpenClaw 需要调用公司内网的 OA 系统或 ERP 接口时，经常出现 DNS 解析失败或连接超时，排查起来需要打开 WSL2 的 /etc/resolv.conf 、修改 wsl.conf 、重启 WSL2 内核，普通用户根本无从下手；第二，WSL2 默认使用 ext4 文件系统，而 Windows 主机上的 Excel 表格、PDF 报告等文件放在 NTFS 分区，跨文件系统读写性能衰减严重，OpenClaw 处理一个 50MB 的销售报表 PDF 时，mineru 解析模块耗时从 8 秒飙升到 42 秒；第三，也是最致命的，WSL2 的后台进程在 Windows 锁屏或休眠后会被系统强制终止，而 OpenClaw 的定时任务（比如每天早 8 点自动汇总日报）一旦中断，就不会自动续跑，必须手动 wsl --shutdown 再 wsl 启动，这对非技术人员等于宣判死刑。

那纯 Docker Desktop 呢？Docker Desktop for Windows 默认使用 WSL2 作为后端，本质上还是绕不开上面的问题。但很多人不知道，Docker Desktop 从 4.19 版本开始，悄悄启用了对“Windows Containers”（Windows 原生容器）的实验性支持。这意味着你可以让容器直接运行在 Windows 内核之上，共享主机的网络栈、文件系统和进程管理器，完全规避 WSL2 的所有短板。我花了三周时间对比测试：同一台 i5-1135G7/16GB/512GB SSD 的笔记本，运行 OpenClaw 的 claw-worker 服务，在 WSL2 模式下平均内存占用 2.1GB，CPU 占用峰值 78%，而切换到 Windows Containers 模式后，内存稳定在 1.4GB，CPU 峰值压到 42%，最关键的是，锁屏 8 小时后回来，服务依然在后台静默运行，日志里没有任何异常断连记录。

所以最终方案定为： Docker Desktop（启用 Windows Containers 后端） + OpenClaw 官方镜像（openclaw/openclaw:latest） + Windows 原生服务管理（nssm.exe） 。这个组合的底层逻辑非常清晰：Docker Desktop 提供标准化的容器生命周期管理，Windows Containers 消除跨系统兼容性鸿沟，nssm.exe 则把容器进程注册为 Windows 系统服务，实现开机自启、崩溃自恢复、日志统一收集。它不追求技术炫酷，只确保一件事：你的数字员工，能像 Windows 自带的“Windows Update Medic Service”一样，安静、可靠、不打扰地为你工作。下面所有步骤，都基于这个确定的架构展开，每一步的参数、路径、配置，都是经过至少 5 台不同品牌、不同 Windows 版本（Win10 21H2 / Win10 22H2 / Win11 22H2 / Win11 23H2）设备交叉验证过的。

3. 核心细节解析与实操要点：从零开始构建稳定运行环境的 7 个关键动作

部署 OpenClaw 的成败，往往取决于安装前那十几分钟的环境准备。很多人卡在第一步 docker run 报错，翻遍日志全是 failed to create endpoint 或 port already in use ，其实问题根本不在于 OpenClaw，而在于 Windows 自身的几个隐藏开关没打开。下面这 7 个动作，缺一不可，顺序也不能乱，我把它称为“Windows 数字员工启动七步咒”。

3.1 动作一：彻底关闭 Windows Hypervisor Platform（WHP）与 Windows Sandbox

这是最容易被忽略，却最致命的一步。Docker Desktop 的 Windows Containers 模式，要求系统必须使用 Windows Container Isolation （进程隔离），而不是 Hyper-V 隔离。而 Windows Sandbox、WSL2、甚至某些杀毒软件（如 Bitdefender）的“高级威胁防护”功能，都会默认启用 WHP，它会抢占容器所需的底层资源，导致 Docker 启动失败或容器网络异常。

操作路径：
设置 → 应用 → 可选功能 → 更多 Windows 功能
取消勾选 Windows Hypervisor Platform 和 Windows Sandbox ，点击“确定”，等待系统提示重启。注意：这里不是禁用 Hyper-V（Hyper-V 是虚拟机平台，可以保留），而是禁用 WHP 这个更底层的组件。重启后，在 PowerShell 中执行 Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Hyper-V ，确认状态为 Disabled ，而 Get-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux （即 WSL）的状态可以是 Enabled 或 Disabled ，都不影响后续操作。

提示：如果你的公司 IT 策略强制开启了 WHP（常见于使用 Microsoft Defender Application Guard 的企业环境），请跳过此步，直接采用“Docker Desktop + WSL2”方案，并在后续配置中手动指定 --network=host 参数来绕过 NAT 问题。但这会牺牲一部分稳定性，属于不得已的备选方案。

3.2 动作二：将 Docker Desktop 切换至 Windows Containers 模式并验证

安装完 Docker Desktop 后，右下角托盘图标右键，选择 Switch to Windows containers 。这个操作会触发 Docker 引擎重启，过程约 30 秒。成功切换后，打开 PowerShell，执行：

docker info | Select-String "Operating System"

输出必须包含 Windows 字样，且 OSType 显示为 windows 。如果显示 linux ，说明切换失败，需要检查上一步是否彻底关闭了 WHP。此时不要强行 docker run ，先执行 docker run --rm mcr.microsoft.com/windows/nanoserver:1809 cmd /c "echo Hello from Windows Container" ，如果返回 Hello from Windows Container ，证明基础环境已通。

3.3 动作三：预拉取并重命名 OpenClaw 官方镜像，规避国内网络波动

OpenClaw 的官方镜像 openclaw/openclaw:latest 存储在 GitHub Container Registry（ghcr.io）上。国内直连下载速度极不稳定，经常卡在 99% 或直接超时。更麻烦的是，官方镜像没有提供针对 Windows 的多架构标签（multi-arch）， latest 标签默认指向 Linux amd64 架构，直接 docker pull 会拉取错误镜像，导致容器启动时报 exec user process caused: exec format error 。

解决方案是：先用一台网络稳定的机器（或手机热点）拉取镜像，再通过 docker save / docker load 导入。但更高效的做法是，利用 Docker 的 --platform 参数强制指定平台，并配合国内镜像加速。我在阿里云容器镜像服务上创建了一个公开的代理仓库 registry.cn-hangzhou.aliyuncs.com/openclaw-mirror/openclaw:win-latest ，它会自动同步 ghcr.io 上的最新 Windows 兼容镜像。执行以下命令：

docker pull --platform windows/amd64 registry.cn-hangzhou.aliyuncs.com/openclaw-mirror/openclaw:win-latest
docker tag registry.cn-hangzhou.aliyuncs.com/openclaw-mirror/openclaw:win-latest openclaw/openclaw:latest

这样，后续所有 docker run 命令都无需再加 --platform 参数，系统会自动识别为 Windows 容器。

3.4 动作四：创建专用的 Docker 数据卷（Volume）并设置 NTFS 权限

OpenClaw 的核心数据包括：用户上传的文件（PDF/Excel）、技能（Skill）代码、运行日志、以及 Redis 缓存。这些数据必须持久化，否则容器重启后一切归零。Docker 的 -v 参数映射到 Windows 路径时，权限管理是个黑洞。我见过太多案例，因为映射路径是 C:\Users\Public\Documents\OpenClaw ，结果容器内的 claw-worker 进程没有写入权限，日志里疯狂刷 Permission denied 。

正确做法是：使用 Docker 原生 Volume，由 Docker Daemon 统一管理权限。执行：

docker volume create openclaw_data
docker volume create openclaw_logs
docker volume create openclaw_skills

然后，在 docker run 命令中，用 -v openclaw_data:/app/data 这样的方式挂载。Docker 会自动在 C:\ProgramData\Docker\volumes\ 下创建对应目录，并赋予容器进程完全控制权限。这是 Windows 容器环境下最安全、最省心的数据持久化方式。

3.5 动作五：编写健壮的 .env 配置文件，覆盖所有 Windows 特有路径

OpenClaw 的 .env 文件是它的“神经系统”，控制着数据库连接、Redis 地址、文件存储路径、API 密钥等所有关键参数。官方模板里的路径全是 Linux 风格（ /app/data ），直接照搬会导致容器找不到目录。必须全部重写为 Windows 风格的绝对路径，并注意转义。

我的生产环境 .env 关键片段如下（保存为 C:\OpenClaw\.env ）：

# 数据库（使用 SQLite，避免额外部署 MySQL）
DATABASE_URL=sqlite:///C:/app/data/claw.db

# Redis（使用官方 Windows 兼容镜像）
REDIS_URL=redis://redis:6379/0

# 文件存储根目录（必须是容器内路径，Docker Volume 会自动映射）
STORAGE_ROOT=C:/app/data/storage

# 日志路径（指向容器内路径，Volume 会映射到宿主机）
LOG_FILE=C:/app/logs/claw.log

# Windows 特有：禁用 Linux 信号处理，启用 Windows 服务模式
WINDOWS_SERVICE_MODE=true

# 飞书接入（如果需要）
FEISHU_BOT_WEBHOOK=https://open.feishu.cn/open-apis/bot/v2/hook/xxxxx

特别注意 STORAGE_ROOT 和 LOG_FILE ，它们是容器内的路径，但必须用 Windows 风格的斜杠（ / ）和盘符（ C: ），这是 OpenClaw Python 代码里硬编码的路径分隔符逻辑决定的，不能写成 C:\app\data\storage 。

3.6 动作六：定制 docker-compose.yml ，显式声明 Windows 容器特性

OpenClaw 官方提供的 docker-compose.yml 是为 Linux 设计的，直接在 Windows 上运行会出问题。必须进行三处关键修改：

1. 添加 platform 声明 ：在 services.claw-web 和 services.claw-worker 下，增加 platform: windows/amd64 ；
2. 调整网络模式 ：将 network_mode: host 改为 network: "default" ，并显式定义一个 openclaw-network ，避免与 Windows 主机网络冲突；
3. 挂载 Volume 方式 ：将 - ./data:/app/data 改为 - openclaw_data:/app/data ，强制使用我们前面创建的 Volume。

精简后的 docker-compose.yml 核心部分如下：

version: '3.8'
services:
  redis:
    image: redis:7.2-windowsservercore-ltsc2022
    platform: windows/amd64
    volumes:
      - openclaw_redis:/data
    networks:
      - openclaw-network

  claw-web:
    image: openclaw/openclaw:latest
    platform: windows/amd64
    environment:
      - DATABASE_URL=sqlite:///C:/app/data/claw.db
      - REDIS_URL=redis://redis:6379/0
      - STORAGE_ROOT=C:/app/data/storage
    volumes:
      - openclaw_data:/app/data
      - openclaw_logs:/app/logs
      - openclaw_skills:/app/skills
    ports:
      - "8080:8080"
    depends_on:
      - redis
    networks:
      - openclaw-network

  claw-worker:
    image: openclaw/openclaw:latest
    platform: windows/amd64
    command: ["worker"]
    environment:
      - DATABASE_URL=sqlite:///C:/app/data/claw.db
      - REDIS_URL=redis://redis:6379/0
      - STORAGE_ROOT=C:/app/data/storage
    volumes:
      - openclaw_data:/app/data
      - openclaw_logs:/app/logs
      - openclaw_skills:/app/skills
    depends_on:
      - redis
    networks:
      - openclaw-network

volumes:
  openclaw_data:
  openclaw_logs:
  openclaw_skills:
  openclaw_redis:

networks:
  openclaw-network:
    driver: nat

3.7 动作七：用 nssm.exe 将 docker-compose 封装为 Windows 服务

这才是让“数字员工”真正成为“员工”的最后一步。 docker-compose up -d 只是前台启动，关掉 PowerShell 窗口，服务就停了。必须把它注册为 Windows 服务，才能实现真正的后台守护。

首先，下载 nssm（Non-Sucking Service Manager）：访问 https://nssm.cc/download ，下载 nssm-2.24.zip ，解压后将 nssm.exe 复制到 C:\Windows\System32\ 目录下（需要管理员权限）。然后，以管理员身份打开 PowerShell，执行：

# 创建一个启动脚本，避免 nssm 直接调用 docker-compose 时的路径问题
Set-Content -Path "C:\OpenClaw\start-claw.bat" -Value @"
@echo off
cd /d C:\OpenClaw
docker-compose down
docker-compose up -d
"@

# 使用 nssm 注册服务
nssm install OpenClawService
# 在弹出的 GUI 窗口中，按以下填写：
# - Path: C:\Windows\System32\cmd.exe
# - Startup directory: C:\OpenClaw
# - Arguments: /c "C:\OpenClaw\start-claw.bat"
# - Service name: OpenClawService
# - Display name: OpenClaw Digital Employee
# - Description: Local deployment of OpenClaw digital employee for Windows
# - Log on tab: 选择 "This account"，输入你的 Windows 用户名和密码（必须是能运行 Docker 的账户）
# - Service recovery tab: 第一次失败、第二次失败、后续失败，全部选择 "Restart the service"
# - 点击 "Install service"

安装完成后，在 services.msc 里就能看到 OpenClaw Digital Employee 服务，设置为“自动（延迟启动）”，即可实现开机即用、崩溃自愈。

4. 实操过程与核心环节实现：从启动到第一个技能运行的完整链路

现在，所有前置条件都已就绪。下面我将带你走一遍从空白系统到成功运行第一个“自动整理周报”技能的完整实操链路。这不是一个理想化的演示，而是我记录下来的、发生在真实 Windows 10 专业版（22H2）笔记本上的每一步操作、每一个命令、每一次观察到的现象，以及背后的原因。

4.1 第一步：初始化环境与首次启动

以管理员身份打开 PowerShell，导航到你的 OpenClaw 工作目录（例如 C:\OpenClaw ），执行：

# 确保 Docker Desktop 已运行且处于 Windows Containers 模式
docker info | Select-String "OSType"

# 拉取并标记镜像（如果之前没做）
docker pull --platform windows/amd64 registry.cn-hangzhou.aliyuncs.com/openclaw-mirror/openclaw:win-latest
docker tag registry.cn-hangzhou.aliyuncs.com/openclaw-mirror/openclaw:win-latest openclaw/openclaw:latest

# 创建所有必需的 Volume
docker volume create openclaw_data
docker volume create openclaw_logs
docker volume create openclaw_skills
docker volume create openclaw_redis

# 启动服务（此时会自动创建网络和容器）
docker-compose up -d

执行 docker-compose up -d 后，不要立刻刷新网页。先观察命令行输出。正常情况下，你会看到类似这样的信息：

[+] Running 4/4
 ⠿ Network openclaw-openclaw-network  Created
 ⠿ Volume "openclaw_openclaw_data"     Created
 ⠿ Container openclaw-redis-1          Started
 ⠿ Container openclaw-claw-web-1       Started

注意，这里没有 claw-worker 容器。这是故意为之的设计： claw-web 容器负责 Web UI 和 API，而 claw-worker 是后台任务处理器，它需要在 Web UI 初始化完成后，由用户在界面上手动触发“启动 Worker”按钮，或者通过 API 调用。这是为了防止在数据库尚未初始化完成时，Worker 就开始消费 Redis 队列，导致任务失败。

接下来，执行 docker ps ，你应该能看到两个正在运行的容器： openclaw-redis-1 和 openclaw-claw-web-1 。如果只有 redis ，而 claw-web 显示 Restarting 或 Exited ，那么问题大概率出在 .env 文件的路径配置上，请立即检查 STORAGE_ROOT 和 DATABASE_URL 是否为正确的 Windows 风格路径。

4.2 第二步：访问 Web UI 并完成初始配置

打开浏览器，访问 http://localhost:8080 。首次加载会稍慢（约 10-15 秒），因为容器正在初始化 SQLite 数据库和编译前端资源。页面加载成功后，你会看到一个简洁的登录界面。默认用户名是 admin ，默认密码是 admin123 （这是官方设定，首次登录后必须修改）。

登录后，首先进入“系统设置”页面。这里有两个关键配置必须完成：

1. 存储配置 ：在“文件存储”选项卡下，确认“存储类型”为 Local ，并且“存储路径”显示为 C:/app/data/storage 。如果显示为空或错误路径，说明 .env 文件中的 STORAGE_ROOT 没有生效，需要检查 docker-compose.yml 中的 volumes 挂载是否正确。
2. Redis 配置 ：在“缓存配置”选项卡下， Redis URL 应该自动填充为 redis://redis:6379/0 。点击右侧的“测试连接”按钮，如果返回 Success ，说明 claw-web 容器与 redis 容器网络连通；如果失败，检查 docker-compose.yml 中 claw-web 的 depends_on 和 networks 配置。

完成这两项后，点击页面右上角的“启动 Worker”按钮。此时， docker ps 命令应该会多出一个 openclaw-claw-worker-1 容器，并且状态为 Up X minutes 。同时，在“系统状态”页面，你应该能看到 Worker Status 变为 Running ， Redis Status 为 Connected ， Database Status 为 OK 。这标志着整个数字员工的“心脏”和“大脑”已经协同工作。

4.3 第三步：创建并运行你的第一个技能（Skill）

OpenClaw 的灵魂在于“技能”。一个技能就是一个 Python 脚本，它定义了数字员工能做什么。我们来创建一个最简单的技能： 自动读取一个 Excel 文件，计算其中“销售额”列的总和，并将结果发送到飞书群 。

首先，在宿主机上，导航到 C:\OpenClaw\skills 目录（这个目录是由 openclaw_skills Volume 映射过来的）。创建一个新文件，命名为 sum_sales.py ，内容如下：

# -*- coding: utf-8 -*-
"""
技能名称：计算销售总额
描述：读取指定 Excel 文件，计算销售额列总和
触发方式：手动执行 / API 调用
"""
import pandas as pd
from openclaw import Skill, SkillContext

class SumSalesSkill(Skill):
    def execute(self, context: SkillContext):
        # 1. 从上下文中获取 Excel 文件路径（用户上传的文件）
        file_path = context.get_input("file_path")
        
        # 2. 使用 pandas 读取 Excel
        try:
            df = pd.read_excel(file_path)
        except Exception as e:
            context.set_error(f"读取 Excel 失败: {str(e)}")
            return
        
        # 3. 查找“销售额”列（兼容中文和英文表头）
        sales_column = None
        for col in df.columns:
            if "销售额" in str(col) or "sales" in str(col).lower():
                sales_column = col
                break
        
        if not sales_column:
            context.set_error("未找到销售额列")
            return
        
        # 4. 计算总和
        total = df[sales_column].sum()
        
        # 5. 将结果写入上下文，供后续步骤使用
        context.set_output("total_sales", float(total))
        
        # 6. 发送飞书通知（如果配置了 webhook）
        if context.config.get("FEISHU_BOT_WEBHOOK"):
            import requests
            payload = {
                "msg_type": "text",
                "content": {
                    "text": f"【数字员工报告】本周销售额总计：¥{total:,.2f}"
                }
            }
            try:
                requests.post(context.config["FEISHU_BOT_WEBHOOK"], json=payload, timeout=5)
            except:
                pass  # 飞书发送失败，不影响主流程

# 必须导出 skill 实例
skill = SumSalesSkill()

保存文件后，回到 Web UI，进入“技能管理”页面，点击“刷新技能列表”。几秒钟后，你应该能在列表中看到 sum_sales 这个技能，状态为 Active 。点击它，进入编辑页面，你可以看到技能的详细信息、输入参数定义（这里只有一个 file_path ）、以及执行日志。

现在，点击页面右上角的“执行”按钮。在弹出的对话框中，你需要上传一个包含“销售额”列的 Excel 文件。上传后，点击“确认执行”。此时，Web UI 会显示“执行中”，而 claw-worker 容器的日志（可通过 docker logs -f openclaw-claw-worker-1 查看）会实时打印出执行过程：

INFO:root:Executing skill sum_sales with inputs {'file_path': 'C:/app/data/storage/uploads/20240515_sales.xlsx'}
INFO:root:Reading Excel file...
INFO:root:Found sales column: 销售额
INFO:root:Calculated total: 123456.78
INFO:root:Sending Feishu notification...
INFO:root:Skill sum_sales executed successfully

如果一切顺利，几秒钟后，你的飞书群就会收到一条消息：“【数字员工报告】本周销售额总计：¥123,456.78”。这就是你的第一个数字员工，它刚刚完成了人生中的第一次正式工作。

4.4 第四步：配置定时任务，让数字员工“准时上班”

手动点击执行，显然不是“员工”的常态。我们需要让它每天早上 8 点，自动去公司共享盘拉取最新的销售报表，计算总和，并发到管理群。这就要用到 OpenClaw 的“计划任务”功能。

在 Web UI 中，进入“计划任务”页面，点击“新建任务”。填写以下信息：

• 任务名称 ：每日销售汇总
• 技能 ： sum_sales
• 执行时间 ： 0 0 8 * * * （Cron 表达式，表示每天 08:00:00 执行）
• 输入参数 ： {"file_path": "Z:\\Shared\\Reports\\weekly_sales.xlsx"}

这里的关键是 file_path 。 Z: 是你映射到公司共享盘的网络驱动器。为了让容器内的 Python 脚本能访问 Z: 盘，你必须在 docker-compose.yml 的 claw-worker 服务下，添加 volumes 挂载：

volumes:
  - openclaw_data:/app/data
  - openclaw_logs:/app/logs
  - openclaw_skills:/app/skills
  - Z:\Shared:C:\shared  # 将宿主机的 Z:\Shared 映射为容器内的 C:\shared

然后，修改 sum_sales.py 中的 file_path 获取逻辑，改为：

# 如果输入的 file_path 是网络路径，尝试映射到容器内路径
file_path = context.get_input("file_path")
if file_path.startswith("Z:\\"):
    file_path = file_path.replace("Z:\\", "C:\\shared\\")

这样，当计划任务触发时， claw-worker 就能顺利读取到共享盘上的最新文件。我实测下来，这个方案比用 smbprotocol 库在 Python 里直接挂载 SMB 共享要稳定得多，因为后者在 Windows 容器里经常遇到认证超时问题。

4.5 第五步：监控与日志，建立你的“数字员工健康档案”

一个可靠的数字员工，必须有完善的监控。OpenClaw 本身提供了基础的健康检查端点 /healthz ，但我们需要更细粒度的观察。我建立了三层监控体系：

1. 容器层监控 ：使用 Windows 自带的“性能监视器”（perfmon.msc），添加计数器 Docker Engine -> Container CPU Usage (%) 、 Docker Engine -> Container Memory Usage (MB) ，为 openclaw-claw-worker-1 设置警报阈值（CPU > 80% 持续 5 分钟，内存 > 1.2GB）。
2. 应用层监控 ：OpenClaw 的 claw-web 容器暴露了 /metrics 端点（Prometheus 格式）。我用一个轻量级的 prometheus-windows-exporter 服务，定期抓取这个端点，并将指标写入本地 SQLite 数据库，生成每日健康报告。
3. 业务层监控 ：在每个关键技能的 execute 方法末尾，添加一行日志： context.logger.info(f"SKILL_EXECUTION_SUCCESS|{skill.__class__.__name__}|{datetime.now().isoformat()}") 。然后，用 Windows 的“事件查看器”，创建一个自定义视图，过滤 Application 日志中包含 SKILL_EXECUTION_SUCCESS 的条目。这样，IT 部门同事不用懂 Docker，只要打开事件查看器，就能一眼看出“数字员工今天干了哪些活，有没有漏掉”。

这套监控体系，让我在一次真实的故障中快速定位问题：某天早上 8 点的销售汇总没发出来。我打开事件查看器，发现 SKILL_EXECUTION_SUCCESS 日志缺失；再查 claw-worker 容器日志，发现大量 ConnectionResetError ；最后查性能监视器，发现 claw-worker 的 CPU 使用率在 7:59 突然飙升到 100%。结论是：共享盘 Z: 在那个时间点发生了短暂的网络抖动，导致 Excel 读取超时。解决方案是，在技能代码里增加重试逻辑：

for attempt in range(3):
    try:
        df = pd.read_excel(file_path, engine='openpyxl')
        break
    except Exception as e:
        if attempt == 2:
            raise e
        time.sleep(2)

加了这个重试，问题再也没有复现过。

5. 常见问题与排查技巧实录：那些让你抓狂半小时，解决只需十秒的典型故障

在给超过 30 个不同部门部署 OpenClaw 的过程中，我整理了一份高频问题速查表。这些问题，90% 都源于 Windows 环境的特殊性，而非 OpenClaw 本身的 Bug。我把它们按“症状-原因-解决方案”的结构列出，并附上我亲测有效的独家技巧。

5.1 问题一： docker-compose up -d 后， claw-web 容器反复重启， docker logs 显示 sqlite3.OperationalError: unable to open database file

症状 ：容器状态在 Restarting 和 Created 之间循环，日志里反复出现数据库打不开的错误。

原因 ： .env 文件中的 DATABASE_URL 路径错误，或者 docker-compose.yml 中的 volumes 挂载没有生效，导致容器试图在只读的 /app 目录下创建 claw.db 文件。

解决方案 ：

1. 首先，确认 DATABASE_URL 是 sqlite:///C:/app/data/claw.db ，而不是 sqlite:///./data/claw.db 或 sqlite:///data/claw.db 。
2. 然后，进入容器内部，手动检查路径是否存在且可写：

   docker exec -it openclaw-claw-web-1 cmd
   dir C:\app\data
   

   如果提示 File Not Found ，说明 Volume 挂载失败。检查 docker-compose.yml 中 claw-web 的 volumes 部分，确保是 - openclaw_data:/app/data ，而不是 - ./data:/app/data 。
3. 独家技巧 ：在 docker-compose.yml 的 claw-web 服务下，添加一个 command 覆盖，让它启动前先创建目录：

   command: ["sh", "-c", "mkdir -p C:/app/data && mkdir -p C:/app/logs && exec gunicorn --bind 0.0.0.0:8080 --workers 2 --threads 4 --timeout 120 app:app"]
   

5.2 问题二：Web UI 打开后一片空白，F12 控制台报错 Failed to load resource: the server responded with a status of 404 () ，且请求的 JS/CSS 文件路径是 /static/js/main.xxxx.js

症状 ：页面 HTML 加载了，但所有静态资源 404，界面无法渲染。

原因 ：OpenClaw 的前端构建产物（ dist 目录）没有正确复制到容器内的 /app/static 目录。官方镜像默认是把 dist 打包进镜像的，但如果镜像拉取不完整，或者你使用了自定义构建的镜像，就可能出现这个问题。

解决方案 ：

1. 进入容器，检查静态文件是否存在：

   docker exec -it openclaw-claw-web-1 cmd
   dir C:\app\static
   

   如果 static 目录下没有 js 、 css 、 img 子目录，说明镜像有问题。
2. 独家技巧 ：不重拉镜像，直接用 docker cp 命令把宿主机上一份完整的 dist 目录拷贝进去：

   # 在宿主机上，下载官方 release 包，解压得到 dist 目录
   # 然后执行：
   docker cp C:\temp\dist\ openclaw-claw-web-1:C:\app\static
   docker restart openclaw-claw-web-1
   

   这招在客户现场网络极差、无法重拉镜像时，救了我无数次。

5.3 问题三：技能执行时， pandas.read_excel() 报错 ImportError: Missing optional dependency 'openpyxl'

症状 ：技能日志里明确报错，说缺少 openpyxl 库