OpenClaw 安装、Skill 配置优先级与 Workspace 总结OpenClaw是一个自托管的个人 AI 助理

1. OpenClaw 是什么

OpenClaw 是一个自托管的个人 AI 助理网关，可以把 WhatsApp、Telegram、Slack、Discord、飞书、微信、QQ、WebChat 等聊天入口连接到本地或服务器上的 AI Agent。官方说明里强调：Gateway 是控制层面，真正工作的主体是 Assistant/Agent。

官方推荐新安装用户直接运行：

openclaw onboard --install-daemon

该命令会通过向导配置 Gateway、workspace、channels、skills 等内容。

2. 安装方式

2.1 官方推荐安装方式

官方当前推荐使用全局 npm 安装：

npm install -g openclaw@latest

openclaw onboard --install-daemon

也可以使用 pnpm：

pnpm add -g openclaw@latest

openclaw onboard --install-daemon

官方要求 Node.js 版本为 Node 24 推荐，或者 Node 22.14+ 。

安装完成后，可以启动网关和控制台：

openclaw gateway --port 18789 --verbose

openclaw dashboard

默认本地控制台地址是：

http://127.0.0.1:18789/

官方文档也说明，openclaw dashboard 会打开浏览器控制台，用于聊天、配置和会话管理。

2.2 源码安装方式

源码安装方式，主要适合 Windows 本地开发和调试。安装前置要求包括 Node.js、npm、Git for Windows、PowerShell、Git Bash。特别强调：OpenClaw 的构建脚本依赖 Bash，所以 Windows 下需要配置 npm 使用 Git Bash。

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 根据实际 Git Bash 安装路径修改
npm config set script-shell "D:\Program Files\Git\bin\bash.exe"

pnpm install
pnpm run build
npm link

openclaw --version

验证版本：

openclaw --version
# 2026.3.3

3. 初始化配置 Onboarding

openclaw onboard --install-daemon

推荐选择：

Security: Yes
Onboarding mode: Manual
Setup: Local gateway (this machine)
Workspace: D:\.openclaw\workspace
Model/auth provider: Qwen
Port: 18789
Bind: Loopback 127.0.0.1
Auth: Token

Gateway 成功启动后，看到类似下面的日志表示成功：

listening on ws://127.0.0.1:18789

然后执行：

openclaw dashboard

即可打开控制台。

4. 模型配置

4.1 openclaw.json 配置位置

主配置文件通常位于：

~/.openclaw/openclaw.json

Windows 下是：

C:\Users<用户名>.openclaw\openclaw.json

4.2 DashScope / 通义千问配置示例

OpenAI 兼容模式配置如下：

{
  "gateway": {
    "mode": "local",
    "port": 18789,
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "models": {
    "mode": "merge",
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "apiKey": "${OPENAI_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen-turbo",
            "name": "Qwen Turbo"
          },
          {
            "id": "qwen-turbo-latest",
            "name": "Qwen Turbo Latest"
          },
          {
            "id": "qwen-max-latest",
            "name": "Qwen Max Latest"
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen-turbo"
      },
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "quant-analyst",
        "model": "dashscope/qwen-turbo-latest",
        "workspace": "~/.openclaw/workspace",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  }
}

特别提醒：OpenClaw 2026.3.3 不再使用旧的 models.default、models.flash、models.max 扁平结构，也不支持 agents.quant-analyst 这种对象形式，应改为 models.providers 和 agents.list。

5. 环境变量配置

5.1 PowerShell 临时环境变量

$env:OPENAI_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
$env:OPENCLAW_PROVIDER="openai"
$env:OPENAI_API_KEY="sk-your_api_key"

5.2 全局 `.env`

.env 加载优先级大致为：

1. 当前工作目录 CWD 下的 .env
2. 全局 ~/.openclaw/.env

Windows 下可创建：

C:\Users<用户名>.openclaw.env

内容示例：

OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
OPENCLAW_PROVIDER=openai
OPENAI_API_KEY=sk-your_api_key

如果 .env 不生效，建议可以直接把 API Key 写入 openclaw.json 的 apiKey 字段，但注意不要提交到 Git。

6. Skill 是什么

OpenClaw Skill 本质上是一个能力包，用来告诉 Agent 什么时候用工具、如何用工具、执行什么流程。官方文档说明：Skill 是一个目录，里面包含 SKILL.md，该文件由 YAML frontmatter 和 Markdown 指令组成。

典型结构：

my-skill/
├── SKILL.md
├── scripts/
├── templates/
└── resources/

SKILL.md 示例：

---
name: hello_world
description: A simple skill that says hello.
---

# Hello World Skill

When the user asks for a greeting, use the `echo` tool to say:
"Hello from your custom skill!".

官方文档说明，name 和 description 是核心字段，其中 description 会展示给 Agent，用于判断是否触发该技能。

7. Skill 与 Tool 的区别

官方文档把 OpenClaw 的扩展能力分为三层：

Tools   = Agent 实际调用的函数能力
Skills  = 教 Agent 什么时候、如何使用工具
Plugins = 打包 Channels、Tools、Skills、模型能力等

Tool 是结构化函数，例如 exec、browser、web_search、read、write、edit；Skill 则是注入到系统提示词中的 Markdown 指南，用来约束和指导 Agent 的行为。

总结：Skills 更像“专业知识封装 / 岗位 SOP”，Tools 则是“可执行函数”。

8. Skill 加载位置与优先级

8.1 官方当前优先级

官方文档给出的 Skill 加载来源如下：

1. skills.load.extraDirs
2. bundled skills
3. ~/.openclaw/skills
4. ~/.agents/skills
5. <workspace>/.agents/skills
6. <workspace>/skills

如果多个位置存在同名 Skill，最终优先级是：

<workspace>/skills
>
<workspace>/.agents/skills
>
~/.agents/skills
>
~/.openclaw/skills
>
bundled skills
>
skills.load.extraDirs

也就是说：workspace 下的 skills 优先级最高。

强调：如果 AI 看不到自定义 Skill，优先把 Skill 放到：

C:\Users<用户名>.openclaw\workspace\skills\

并在 openclaw.json 中显式指定 workspace，然后重启 Gateway。

9. Workspace 信息

9.1 OpenClaw 涉及的几个目录

目录分为三类：

1. OpenClaw 系统目录
   C:\Users<用户名>.openclaw\
   用于存放全局配置、日志、内置 Skills 等。

2. Agent 工作区 workspace
   由 openclaw.json 中的 workspace 字段指定。
   这是 Agent 实际运行目录，也是 Skills 优先加载的位置。

3. 启动目录
   执行 openclaw gateway 的目录。
   可能影响读取哪个 openclaw.json。

特别强调：Skills 不是从 clawhub install 的位置直接加载，而是从 Agent 配置的 workspace 加载。

skills推荐：

clawhub

cocoloop

servasyy_skills

9.2 workspace 的作用

如果配置如下：

{
  "agents": {
    "defaults": {
      "workspace": "~/.openclaw/workspace"
    },
    "list": [
      {
        "id": "quant-analyst",
        "workspace": "~/.openclaw/workspace",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  }
}

那么该 Agent 实际会从下面目录加载 Skill：

~/.openclaw/workspace/skills/

Windows 下对应：

C:\Users<用户名>.openclaw\workspace\skills\

9.3 多 Agent 下的 workspace

官方文档说明，多 Agent 场景中，每个 Agent 可以有自己的 workspace。不同 Agent 的 <workspace>/skills 是隔离的。

例如：

{
  "agents": {
    "list": [
      {
        "id": "writer",
        "workspace": "D:/openclaw/workspaces/writer",
        "skills": ["ppt-generator", "document-writer"]
      },
      {
        "id": "quant-analyst",
        "workspace": "D:/openclaw/workspaces/quant",
        "skills": ["akshare-kline", "talib", "backtrader"]
      }
    ]
  }
}

对应目录：

D:/openclaw/workspaces/writer/skills/
D:/openclaw/workspaces/quant/skills/

10. Skill 安装与配置

10.1 使用 ClawHub 安装

方式：

npm install -g clawhub

clawhub search "PPT"

clawhub install ppt-generator

默认会安装到：

C:\Users<用户名>.openclaw\skills\ppt-generator

但这个位置不一定是 Agent 实际加载的最高优先级目录。PDF 建议复制到 workspace：

mkdir C:\Users$env:USERNAME.openclaw\workspace\skills

Copy-Item -Path "C:\Users$env:USERNAME.openclaw\skills\ppt-generator" `
-Destination "C:\Users$env:USERNAME.openclaw\workspace\skills" -Recurse

然后验证：

openclaw skills list

10.2 直接安装到指定 workspace

clawhub install ppt-generator --workspace "D:\你的项目.openclaw"

但需要注意：你的 Agent 配置的 workspace 必须和这个路径一致，否则 Agent 仍然可能看不到该 Skill。

10.3 手动新增 Skill

推荐目录：

~/.openclaw/workspace/skills/stock-screener/
├── SKILL.md
└── scripts/
    └── screener.py

SKILL.md 示例：

---
name: stock-screener
description: "A 股选股筛选。直接执行 exec，命令 python skills/stock-screener/scripts/screener.py ..."
metadata:
  openclaw:
    requires:
      bins: ["python"]
    permissions: ["exec"]
    timeout: 60
---

# 选股技能

## 执行流程（必须遵守）

1. 收到选股请求后，直接执行 exec。
2. 命令：
   python skills/stock-screener/scripts/screener.py <条件参数>
3. 将脚本输出的 JSON 直接返回给用户。

禁止：安装依赖、检查环境。

然后在 openclaw.json 中注册：

{
  "agents": {
    "list": [
      {
        "id": "quant-analyst",
        "workspace": "~/.openclaw/workspace",
        "skills": [
          "akshare-kline",
          "talib",
          "backtrader",
          "stock-screener"
        ]
      }
    ]
  }
}

修改后执行：

openclaw skills list
openclaw gateway restart

或者重启：

openclaw gateway --port 18789

官方创建 Skill 文档也说明：新增 Skill 后可通过 /new 新会话或重启 Gateway 让 OpenClaw 重新加载，并用 openclaw skills list 验证。

11. Agent Skill 可见性规则

Skill 是否存在，和 Agent 是否能用，是两件事。

官方文档说明：

Skill location / precedence：决定同名 Skill 哪个版本生效。
Agent allowlist：决定某个 Agent 能看到哪些 Skill。

配置示例：

{
  "agents": {
    "defaults": {
      "skills": ["github", "weather"]
    },
    "list": [
      {
        "id": "writer"
      },
      {
        "id": "docs",
        "skills": ["docs-search"]
      },
      {
        "id": "locked-down",
        "skills": []
      }
    ]
  }
}

规则：

1. agents.defaults.skills 是默认 Skill 白名单。
2. agents.list[].skills 不写，则继承 defaults。
3. agents.list[].skills 写了非空数组，则它是最终集合，不会和 defaults 合并。
4. agents.list[].skills: [] 表示该 Agent 不暴露任何 Skill。
5. 不写 agents.defaults.skills，默认不限制 Skills。

12. Skill 配置项

官方文档说明，大部分 Skill 配置位于：

{
  "skills": {
    "allowBundled": ["gemini", "peekaboo"],
    "load": {
      "extraDirs": [
        "~/Projects/agent-scripts/skills"
      ],
      "watch": true,
      "watchDebounceMs": 250
    },
    "install": {
      "preferBrew": true,
      "nodeManager": "npm"
    },
    "entries": {
      "image-lab": {
        "enabled": true,
        "env": {
          "GEMINI_API_KEY": "GEMINI_KEY_HERE"
        }
      },
      "sag": {
        "enabled": false
      }
    }
  }
}

关键字段：

skills.allowBundled
只允许指定的 bundled skills 生效。

skills.load.extraDirs
额外扫描目录，优先级最低。

skills.load.watch
是否监听 Skill 目录变化，默认 true。

skills.install.nodeManager
Skill 安装使用 npm / pnpm / yarn / bun。

skills.entries.<skillKey>.enabled
启用或禁用某个 Skill。

skills.entries.<skillKey>.env
给 Skill 注入环境变量。

官方文档也说明，skills.entries.* 主要用于自定义或第三方 Skill 工作流。

13. Skill 匹配机制

OpenClaw 的 Skill 触发不是简单关键词匹配，而是依赖 LLM 理解：

1. Gateway 启动时读取 Agent 配置中的 skills 列表。
2. 读取每个 SKILL.md 的 description。
3. 将 Skill 摘要注入 System Prompt。
4. 用户发送消息。
5. LLM 根据用户意图和 Skill 描述决定是否使用某个 Skill。
6. 如需执行脚本，LLM 调用 exec 工具。
7. 脚本返回 JSON 或文本。
8. LLM 整理后回复用户。

特别强调：description 字段非常关键，是 LLM 判断是否使用该技能的首要依据。

14. 常见问题

14.1 openclaw 命令未识别

原因：源码安装时没有执行全局链接。

解决：

npm link

14.2 Windows 下 pnpm 无法执行

你之前遇到的错误：

pnpm.ps1，因为在此系统上禁止运行脚本

这是 PowerShell 执行策略限制。可以用以下方式处理：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

或者临时绕过：

powershell -ExecutionPolicy Bypass

也可以直接使用：

npm install

避免 pnpm 的 PowerShell 脚本问题。

14.3 spawn npm ENOENT

如果飞书插件安装时遇到：

Error: spawn npm ENOENT

可以手动安装插件：

npm install -g @openclaw/feishu
openclaw configure

然后选择 Feishu/Lark，并配置 App ID、App Secret、Domain 等。

14.4 Control UI assets missing

源码安装后如果提示：

Control UI assets missing

进入 UI 目录手动构建：

cd ui
npm install
npm run build
cd ..

PDF 中说明构建后会生成：

dist/control-ui/

14.5 AI 看不到自定义 Skill

优先检查：

1. Skill 是否放到了当前 Agent 的 <workspace>/skills/ 下。
2. openclaw.json 中 agents.defaults.workspace 是否正确。
3. 当前使用的 Agent 是否正确，例如 quant-analyst。
4. agents.list[].skills 是否包含该 Skill。
5. 是否重启 Gateway 或开启了 skills.load.watch。
6. 执行 openclaw skills list 查看是否加载。

修复路径：复制到 C:\Users<用户名>.openclaw\workspace\skills，显式指定 workspace，切换到正确 Agent，然后重启 Gateway。

14.6 项目目录和 workspace 不同步

修改项目里的：

skills/xxx/SKILL.md

但 Agent 实际读取的是：

~/.openclaw/workspace/skills/xxx/SKILL.md

所以修改后需要同步：

xcopy /E /Y "skills\akshare-kline*" "%USERPROFILE%.openclaw\workspace\skills\akshare-kline"
xcopy /E /Y "skills\talib*" "%USERPROFILE%.openclaw\workspace\skills\talib"
xcopy /E /Y "skills\backtrader*" "%USERPROFILE%.openclaw\workspace\skills\backtrader"

15. 推荐落地目录结构

Windows 推荐结构：

C:\Users<用户名>.openclaw\
├── openclaw.json
├── openclaw.json.bak
├── .env
├── skills\
│   └── ppt-generator\
├── workspace\
│   ├── skills\
│   │   ├── ppt-generator\
│   │   ├── akshare-kline\
│   │   ├── talib\
│   │   └── backtrader\
│   ├── output\
│   ├── data\
│   └── logs\
└── canvas\

更推荐把真正运行的 Skill 都放到：

C:\Users<用户名>.openclaw\workspace\skills\

因为它的优先级最高，也最符合 Agent 实际运行路径。

16. 推荐安装流程总览

方式一：官方推荐安装

node -v
npm -v

npm install -g openclaw@latest

openclaw onboard --install-daemon

openclaw gateway --port 18789 --verbose

openclaw dashboard

方式二：源码安装

git clone https://github.com/openclaw/openclaw.git
cd openclaw

npm config set script-shell "D:\Program Files\Git\bin\bash.exe"

pnpm install
pnpm run build
npm link

openclaw --version

openclaw onboard --install-daemon

openclaw gateway --port 18789

openclaw dashboard

方式三：安装并启用自定义 Skill

npm install -g clawhub

clawhub search "PPT"

clawhub install ppt-generator

mkdir C:\Users%USERNAME%.openclaw\workspace\skills

xcopy /E /Y "%USERPROFILE%.openclaw\skills\ppt-generator*" "%USERPROFILE%.openclaw\workspace\skills\ppt-generator"

openclaw skills list

openclaw gateway restart

17. 最关键结论

1. OpenClaw 官方现在推荐 npm install -g openclaw@latest 安装。
2. 源码安装需要 Node.js、Git、Git Bash，并配置 npm script-shell。
3. openclaw onboard --install-daemon 是推荐初始化方式。
4. 主配置文件是 ~/.openclaw/openclaw.json。
5. Agent 的 workspace 决定实际运行目录。
6. Skill 必须放到当前 Agent 的 workspace/skills 下才最稳。
7. Skill 优先级最高的是 <workspace>/skills。
8. agents.list[].skills 是该 Agent 的最终 Skill 白名单，不会和 defaults 自动合并。
9. 修改 Skill 后要新建会话、重启 Gateway，或依赖 skills.load.watch 自动刷新。
10. description 是 Skill 触发的核心，写得越明确，Agent 越容易正确调用。

OpenClaw 安装、Skill 配置优先级与 Workspace 总结