自己研究搭了一个自动化的 skill，感觉以后可以不用上电脑啥的，直接自然语言执行了，给大家参考参考已经碰到的一些坑

OpenClaw 新手入门使用指南

一、文档说明

本文档基于 OpenClaw 官方安装规范与实际操作会话整理，完全适配 Windows 系统，采用官方推荐的「PowerShell 管理员一键脚本」完成安装，涵盖系统前置检查、官方安装流程、自定义 Skill 开发、核心问题排查全环节，是零基础用户快速上手 OpenClaw 并开发自定义技能的实操手册。

---

二、前置系统要求（官方强制）

安装前必须满足以下条件，否则会导致安装失败或功能异常：

1. 核心依赖：Node.js 版本 ≥ 22（OpenClaw 运行的基础，一键脚本会自动校验此版本）；
2. 执行环境：Windows PowerShell（必须以管理员身份运行），或 WSL2（Ubuntu）；
3. 硬件建议：内存 ≥ 4GB，保障网关与自定义技能流畅运行；
4. 网络环境：通畅的网络，用于下载安装脚本、核心依赖包及浏览器驱动。

---

三、Windows 官方一键安装流程（PowerShell 管理员版）

步骤 1：启动管理员权限 PowerShell

右键点击「开始菜单」→ 选择「Windows PowerShell (管理员)」或「终端 (管理员)」，在弹出的权限确认窗口中选择「是」。

步骤 2：执行官方一键安装脚本

在管理员 PowerShell 中复制并执行以下命令，脚本会自动完成全流程安装：

powershell

iwr -useb https://openclaw.ai/install.ps1 | iex

脚本自动执行的核心动作

1. 版本校验：检查本地 Node.js 版本，若版本 < 22 会提示升级，需先完成 Node.js 升级后再重新执行脚本；
2. 全局安装：自动全局安装 OpenClaw 核心包；
3. 初始化配置：启动配置向导，自动生成用户目录下的 .openclaw 配置文件夹。

步骤 3：验证安装结果

执行以下命令，确认 OpenClaw 已成功安装：

powershell

openclaw --version

成功标志：终端输出具体版本号（如 2026.2.26），无「命令未找到」「模块缺失」等报错。

步骤 4：启动 OpenClaw 网关

执行以下命令，启动 OpenClaw 核心网关服务：

powershell

openclaw gateway

启动成功提示：

plaintext

openclaw gateway started successfully
Gateway listening on ws://127.0.0.1:18789
Browser control server on http://127.0.0.1:18791/

网关启动后，可通过浏览器访问 http://127.0.0.1:18791/ 打开 OpenClaw 控制界面。

四、自定义 Skill 开发（以 playwright_skill 为例）

1. 官方强制目录结构

Skill 必须放置在以下目录结构中，否则 OpenClaw 无法扫描加载：

plaintext

C:\Users\你的用户名\.openclaw\
└── workspace\               # 初始化自动生成的官方工作区目录
    └── skills\              # 手动创建：Skill 根目录
        └── playwright_skill\ # 自定义技能目录（名称可自定义）
            ├── SKILL.md      # 🚨 核心标识文件（必须存在，无则不加载）
            ├── main.py       # 技能入口脚本（必须存在）
            ├── test_demo.py # 业务脚本（如 Playwright 测试用例，按需创建）
            └── requirements.txt # Python 依赖声明（有第三方包时需创建）

2. 核心文件编写

（1）SKILL.md（官方强制，技能标识文件）

markdown

---
name: "playwright_skill"       # 技能名称，与目录名保持一致
description: " pytest 自动化测试"
version: "1.0.0"
author: "你的名字"
tags: ["测试", "自动化", "pytest", "playwright"]
metadata:
  openclaw:
    main: "main.py"            # 入口脚本（默认 main.py，可省略）
    retry: 0                   # 禁用自动重试（避免脚本反复执行）
    timeout: 120               # 延长执行超时至 120 秒
    slash_commands:            # 配置专属斜杠命令（精准触发）
      - name: "playwright-test"
        description: "执行pytest 自动化测试"
    requires:
      bins: ["python", "playwright", "chrome"] # 声明依赖的二进制文件
    permissions:
      - "exec"                 # 允许执行外部命令
      - "browser"              # 允许控制浏览器
      - "file.read"            # 允许读取文件
      - "file.write"           # 允许写入文件
---

## playwright_skill 使用说明
本技能用于执行房源管理页面的自动化测试，基于 Playwright 和 pytest 实现浏览器操作与用例验证。

### 触发方式
1.  **精准触发（推荐）**：在 OpenClaw 聊天框输入 `/playwright-test`
2.  **自然语言触发**：使用 `playwright_skill` 执行房源 pytest 测试

3. 依赖与浏览器安装

在 PowerShell 中进入技能目录并执行以下命令：

powershell

# 进入技能目录
cd C:\Users\你的用户名\.openclaw\workspace\skills\playwright_skill

# 安装 Python 依赖
pip install -r requirements.txt

# 安装 Playwright 及 Chrome 浏览器（解决浏览器缺失问题）
python -m playwright install --force chrome

---

五、Skill 加载与触发验证

1. 重启网关（修改文件后必须执行）

powershell

# 先按 Ctrl+C 停止旧网关，再重新启动
openclaw gateway

2. 检查 Skill 加载状态

powershell

openclaw status

成功标志：终端输出中出现 Skills 栏目，且显示 playwright_skill。

3. 触发 Skill

• 精准触发（推荐，避免找错文件）：在 OpenClaw 聊天框输入 /playwright-test；
• 自然语言触发：输入「使用 playwright_skill 执行房源 pytest 测试」。

---

六、核心问题排查与解决方案

表格

问题现象	根本原因	解决方案
安装提示「Node.js 版本不足」	本地 Node.js 版本 < 22，不满足官方要求	下载安装 Node.js 22+ 版本后，重新执行一键安装脚本
Skill 未加载，openclaw status 无 Skills 栏	1. Skill 路径错误（缺少 workspace 目录）；2. 无 SKILL.md 核心文件；3. Playwright 环境未安装	1. 将 Skill 迁移至 ~/.openclaw\workspace\skills\；2. 按规范创建 SKILL.md；3. 执行 python -m playwright install --force chrome
执行 playwright install 提示「路径未识别」	1. 路径拼写错误（使用双反斜杠 \\）；2. Playwright 未安装	1. 使用 python -m playwright install --force chrome 替代路径调用；2. 先执行 pip install playwright 安装核心包
Skill 执行时脚本反复运行	main.py 的 handler() 函数未返回包含 success 字段的结构化结果，触发 OpenClaw 重试机制	确保 handler() 函数所有分支都返回 {"success": True/False, ...} 格式的字典
触发时调用到其他文件 / 技能	多个技能触发词相似，导致 LLM 匹配混淆	1. 使用专属斜杠命令（如 /playwright-test）触发；2. 自然语言触发时带上技能名称（如「使用 playwright_skill 执行测试」）
Python 多版本环境冲突	操作在不同 Python 环境（如 Conda 与系统 Python）间切换，依赖安装错位	1. 用 where python 确认当前环境路径；2. 所有操作在同一 Python 环境（如 Conda base）下执行
升级提示「降级风险」	当前版本（如 2026.2.26）高于检测到的 latest 版本	输入 No 终止升级，保留当前稳定版本，避免配置损坏

---

七、关键注意事项

1. 安装前提：必须先满足「Node.js ≥ 22」，否则一键脚本会直接中断；
2. 权限要求：Windows 安装必须使用管理员 PowerShell，否则权限不足导致安装失败；
3. 规范优先：SKILL.md 是 Skill 加载的核心标识，路径 / 文件缺失会直接导致 Skill 无法被识别；
4. 结构化返回：main.py 的 handler() 函数必须返回包含 success 字段的字典，否则会触发重试机制；
5. 精准触发：多技能场景下，优先使用斜杠命令，避免触发词混淆导致调用错误。

---

八、最终验证

完成以上所有步骤后，验证以下核心功能正常：

1. openclaw gateway 可正常启动，网关监听地址为 ws://127.0.0.1:18789；
2. openclaw status 输出中显示 Skills 栏目，且包含 playwright_skill；
3. 可通过 /playwright-test 或自然语言精准触发技能，返回清晰的成功 / 失败结构化结果，无反复执行问题；
4. Playwright 自动化测试流程可正常启动浏览器并执行用例。