龙虾 OpenClaw 技能安装后“看不到”：目录结构、权限与重启 Gateway 的坑

问题现象

你刚刚完成 OpenClaw 的安装，但发现技能在 Gateway 界面中“看不到”，或者技能列表为空，或者技能图标未加载。这种问题通常不是 OpenClaw 本身出错，而是由于目录结构、权限配置或 Gateway 服务未正确重启导致的。本文将手把手带你排查并解决这个问题。

一、确认 OpenClaw 已正确安装

在继续排查之前，先确认 OpenClaw 已成功安装。OpenClaw 的安装目录通常位于：

/opt/openclaw

进入该目录，检查是否存在以下关键文件或目录：

• openclawd（服务主程序）
• config/（配置目录）
• skills/（技能目录）
• logs/（日志目录）

如果这些目录或文件缺失，说明安装未完成或未正确解压。请重新运行安装脚本或从官方源重新下载安装包。

二、检查技能目录结构是否正确

OpenClaw 的技能文件必须放置在正确的目录下，否则 Gateway 无法识别。技能目录结构应如下：

/opt/openclaw/skills/
├── skill1/
│   ├── skill1.json
│   ├── skill1.py
│   └── icon.png
├── skill2/
│   ├── skill2.json
│   ├── skill2.py
│   └── icon.png

检查步骤：

1. 进入 skills 目录：

   cd /opt/openclaw/skills

2. 列出目录内容：

   ls -la

   确认是否存在以 skillX/ 命名的子目录，且每个子目录中包含 skillX.json、skillX.py 和 icon.png。

3. 检查文件权限：

   ls -la skill1/

   确认文件权限是否为可读可执行（例如：-rwxr-xr-x）。如果不是，执行：

   chmod 755 skill1/
   chmod 644 skill1/*.json
   chmod 644 skill1/*.py
   chmod 644 skill1/icon.png

三、检查 Gateway 配置文件是否引用了技能目录

OpenClaw 的 Gateway 配置文件通常位于：

/opt/openclaw/config/gateway.json

打开该文件，检查是否包含以下内容：

{
  "skills": {
    "path": "/opt/openclaw/skills"
  }
}

如果 path 字段为空或指向错误目录，Gateway 将无法加载技能。请修改为：

{
  "skills": {
    "path": "/opt/openclaw/skills"
  }
}

保存后，重启 Gateway 服务（见下文）。

四、检查 Gateway 日志以定位问题

Gateway 的日志文件位于：

/opt/openclaw/logs/gateway.log

打开该文件，查看是否有以下错误信息：

• Failed to load skill directory
• Permission denied
• File not found

这些信息将帮助你快速定位问题所在。

五、重启 Gateway 服务

在完成上述检查后，必须重启 Gateway 服务，才能使配置和技能目录生效。

重启步骤：

1. 停止 Gateway 服务：

   /opt/openclaw/bin/openclawd stop

2. 启动 Gateway 服务：

   /opt/openclaw/bin/openclawd start

3. 验证服务状态：

   /opt/openclaw/bin/openclawd status

   输出应为 Running，表示服务已正常启动。

六、验证技能是否在 Gateway 界面中可见

1. 打开浏览器，访问 Gateway 的 Web 管理界面（默认地址为 http://localhost:8080）。
2. 登录后，进入“技能管理”或“技能列表”页面。
3. 检查是否能看到你刚刚安装的技能（如 skill1、skill2）。
4. 如果仍然看不到，返回日志文件检查是否有新的错误信息。

七、常见坑点总结

八、附录：技能目录结构模板

以下是一个标准技能目录结构模板，供你参考：

/opt/openclaw/skills/
├── skill1/
│   ├── skill1.json
│   ├── skill1.py
│   └── icon.png
├── skill2/
│   ├── skill2.json
│   ├── skill2.py
│   └── icon.png

示例：skill1.json

{
  "name": "skill1",
  "version": "1.0",
  "description": "这是一个示例技能",
  "author": "OpenClaw Team",
  "icon": "icon.png",
  "main": "skill1.py"
}

示例：skill1.py

def run():
    print("Skill1 is running...")

九、总结

OpenClaw 技能“看不到”的问题，本质是目录结构、权限配置或 Gateway 服务未正确重启导致的。通过以下步骤，你可以快速定位并解决问题：

1. 确认 OpenClaw 已正确安装。
2. 检查技能目录结构是否完整。
3. 检查 Gateway 配置文件是否引用了正确的技能路径。
4. 检查 Gateway 日志以获取错误信息。
5. 重启 Gateway 服务。
6. 验证技能是否在 Web 界面中可见。

只要按步骤执行，90% 的问题都能迎刃而解。如果仍有问题，请提供日志文件内容，我可以进一步帮你分析。