10 minute read

OpenClaw 简介

自2025年11月由PSPDFKit创始人Peter Steinberger作为周末项目启动(最初名为Clawd/Clawdbot),OpenClaw(曾短暂更名为Moltbot)在2026年1月迅速走红,成为当年上半年增长最快的开源AI智能体框架之一。该项目GitHub星数已超过13万(部分报道接近15万),其最大亮点在于真正实现了“本地优先、本地执行”的自主任务能力,而非单纯的云端聊天。

OpenClaw不是传统AI聊天助手,而是一个运行在用户本地硬件(Mac、PC、服务器)上的自动化中枢。它通过消息类应用(如WhatsApp、Telegram、iMessage、Discord等)接收自然语言指令,能够执行真实电脑操作:读写文件、运行命令、操作浏览器、管理邮件日历、甚至自主编写新技能。

项目遵循“对话优先”而非“配置优先”的设计哲学,让非程序员也能通过日常聊天指挥复杂流程。其核心架构围绕四个主要模块构建:

  • Gateway(网关):负责消息路由,连接各种聊天应用与本地系统
  • Agent(智能体):基于强大LLM(最常用Claude系列)的核心决策与规划引擎
  • Memory(记忆):提供长期上下文记忆,支持跨会话、跨任务的连续理解
  • Skills(技能):可扩展的工具集和动作能力,由社区持续贡献(如shell执行、文件操作、邮件发送、代码编写等)

这种“本地+自主+开放”的组合,让OpenClaw在隐私敏感用户和开发者中极受欢迎,同时也因高权限执行能力引发了大量安全讨论。

OpenClaw 安装

二进制安装

# Recommended: global install (npm/pnpm)
npm install -g openclaw@latest
# or: pnpm add -g openclaw@latest

# Onboard + install the service (launchd/systemd user service)
openclaw onboard --install-daemon

源代码安装

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm ui:build # auto-installs UI deps on first run
pnpm build
openclaw onboard --install-daemon
  • 安装 pnpm

Corepack 是 Node.js 官方推出的一个“包管理器管理器”。如果你已经安装了 Node.js,可以使用内置的 Corepack(最省事的方法)。

corepack enable
corepack prepare pnpm@latest --activate

配置


▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄▄
██░▄▄▄░██░▄▄░██░▄▄▄██░▀██░██░▄▄▀██░████░▄▄▀██░███░██
██░███░██░▀▀░██░▄▄▄██░█░█░██░█████░████░▀▀░██░█░█░██
██░▀▀▀░██░█████░▀▀▀██░██▄░██░▀▀▄██░▀▀░█░██░██▄▀▄▀▄██
▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
                  🦞 OPENCLAW 🦞

┌  OpenClaw onboarding
│
◇  Security ──────────────────────────────────────────────────────────────────────────────╮
│                                                                                         │
│  Security warning — please read.                                                        │
│                                                                                         │
│  OpenClaw is a hobby project and still in beta. Expect sharp edges.                     │
│  This bot can read files and run actions if tools are enabled.                          │
│  A bad prompt can trick it into doing unsafe things.                                    │
│                                                                                         │
│  If you’re not comfortable with basic security and access control, don’t run OpenClaw.  │
│  Ask someone experienced to help before enabling tools or exposing it to the internet.  │
│                                                                                         │
│  Recommended baseline:                                                                  │
│  - Pairing/allowlists + mention gating.                                                 │
│  - Sandbox + least-privilege tools.                                                     │
│  - Keep secrets out of the agent’s reachable filesystem.                                │
│  - Use the strongest available model for any bot with tools or untrusted inboxes.       │
│                                                                                         │
│  Run regularly:                                                                         │
│  openclaw security audit --deep                                                         │
│  openclaw security audit --fix                                                          │
│                                                                                         │
│  Must read: https://docs.openclaw.ai/gateway/security                                   │
│                                                                                         │
├─────────────────────────────────────────────────────────────────────────────────────────╯

大部分都可以保持默认,按照提示完成配置即可。我这里模型使用的 Kimi Code。

OpenClaw 使用

OpenClaw TUI

OpenClaw 网关仪表盘

运行网关

openclaw gateway

🦞 OpenClaw 项目架构分析

Kimi Code 生成的。

架构图

架构详解

  一、项目概览

   属性         说明
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   项目名称     OpenClaw - Personal AI Assistant
   核心定位     本地优先的个人 AI 助手网关系统
   技术栈       TypeScript/Node.js (ESM) + Swift (Apple) + Kotlin (Android)
   代码规模     ~30万行 TypeScript 源码
   包管理       pnpm (workspace)
   运行时要求   Node.js ≥ 22

  ──────────────────────────────────────────────────────────────────────────
  二、整体架构图

  ┌─────────────────────────────────────────────────────────────────────────┐
  │                         CLIENT LAYER                                    │
  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────────┐ │
  │  │  macOS App  │  │   iOS App   │  │ Android App │  │    Web UI       │ │
  │  │   (Swift)   │  │   (Swift)   │  │   (Kotlin)  │  │   (Lit/HTML)    │ │
  │  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └────────┬────────┘ │
  │         └─────────────────┴─────────────────┴─────────────────┘          │
  │                              │                                          │
  │                         WebSocket / HTTP                                │
  │                              │                                          │
  └──────────────────────────────┼──────────────────────────────────────────┘
                                 ▼
  ┌─────────────────────────────────────────────────────────────────────────┐
  │                      GATEWAY LAYER (Node.js)                            │
  │  ┌─────────────────────────────────────────────────────────────────┐   │
  │  │                     CLI Interface (Commander)                    │   │
  │  │   onboard │ gateway │ agent │ message │ cron │ browser │ doctor  │   │
  │  └─────────────────────────────────────────────────────────────────┘   │
  │                               │                                         │
  │  ┌────────────────────────────┼─────────────────────────────────────┐  │
  │  │                    CORE MODULES                                    │  │
  │  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │  │
  │  │  │   Agents   │ │  Channels  │ │   Browser  │ │  Auto-Reply    │ │  │
  │  │  │  (Pi RPC)  │ │  (Plugins) │ │  (CDP/PW)  │ │   Engine       │ │  │
  │  │  └────────────┘ └────────────┘ └────────────┘ └────────────────┘ │  │
  │  │  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌────────────────┐ │  │
  │  │  │   Config   │ │   Memory   │ │    TTS     │ │    Canvas      │ │  │
  │  │  │  (Zod)     │ │ (sqlite-vec│ │(ElevenLabs)│ │   (A2UI)       │ │  │
  │  │  └────────────┘ └────────────┘ └────────────┘ └────────────────┘ │  │
  │  └────────────────────────────────────────────────────────────────────┘  │
  └─────────────────────────────────────────────────────────────────────────┘
                                 │
  ┌──────────────────────────────┼──────────────────────────────────────────┐
  │                         EXTENSION LAYER                                 │
  │  ┌──────────┬──────────┬──────────┬──────────┬──────────┬─────────────┐ │
  │  │ WhatsApp │ Telegram │  Discord │  Slack   │  Signal  │  iMessage   │ │
  │  │ (Baileys)│ (grammY) │(discord.)│  (Bolt)  │(signal-cli)│  (imsg)   │ │
  │  └──────────┴──────────┴──────────┴──────────┴──────────┴─────────────┘ │
  │  ┌──────────┬──────────┬──────────┬──────────┬──────────┬─────────────┐ │
  │  │GoogleChat│  Matrix  │   Zalo   │  Teams   │BlueBubble│    Nostr    │ │
  │  └──────────┴──────────┴──────────┴──────────┴──────────┴─────────────┘ │
  └─────────────────────────────────────────────────────────────────────────┘
                                 │
  ┌──────────────────────────────┼──────────────────────────────────────────┐
  │                      EXTERNAL SERVICES                                  │
  │  ┌──────────┬──────────┬──────────┬──────────┬──────────┬─────────────┐ │
  │  │Anthropic │  OpenAI  │  Google  │   Groq   │  Venice  │  Ollama     │ │
  │  │  (Claude)│ (GPT-4)  │ (Gemini) │          │          │  (Local)    │ │
  │  └──────────┴──────────┴──────────┴──────────┴──────────┴─────────────┘ │
  └─────────────────────────────────────────────────────────────────────────┘

  ──────────────────────────────────────────────────────────────────────────
  三、核心模块详解

  1. CLI 层 (src/cli/)

  src/cli/
  ├── program/           # CLI 程序构建
  │   ├── build-program.ts    # Commander 程序入口
  │   ├── command-registry.ts # 命令注册
  │   └── register.*.ts       # 各子命令注册
  ├── gateway-cli/       # Gateway 管理
  ├── browser-cli/       # 浏览器控制
  ├── nodes-cli/         # 节点/设备管理
  ├── cron-cli/          # 定时任务
  └── deps.ts            # 依赖注入

  设计特点:

  • 使用 Commander.js 构建命令行界面
  • 依赖注入模式 (createDefaultDeps)
  • 统一的配置管理和错误处理

  2. Agent 层 (src/agents/)

  src/agents/
  ├── pi-embedded-runner/    # Pi Agent 运行时
  │   ├── run/              # 执行逻辑
  │   ├── model.ts          # 模型管理
  │   └── payloads.ts       # 消息负载
  ├── tools/                # Agent 工具集
  │   ├── browser-tool.ts   # 浏览器控制
  │   ├── web-search.ts     # 网络搜索
  │   ├── sessions-send-tool.ts # 消息发送
  │   └── image-tool.ts     # 图像处理
  ├── auth-profiles/        # 认证配置管理
  ├── skills/               # 技能系统
  └── sandbox/              # 沙箱环境

  关键技术:

  • 基于 @mariozechner/pi-agent-core 的 RPC 模式
  • 流式响应处理 (pi-embedded-subscribe.ts)
  • 工具调用系统 (Tool Calling)
  • 内存压缩和上下文管理

  3. 渠道层 (src/channels/, src/web/)

  src/channels/
  ├── plugins/              # 渠道插件系统
  │   ├── types.*.ts       # 插件类型定义
  │   ├── onboarding/      # 各渠道 onboarding
  │   ├── normalize/       # 消息标准化
  │   └── outbound/        # 消息发送
  ├── registry.ts          # 渠道注册表
  ├── allowlists/          # 白名单管理
  └── command-gating.ts    # 命令权限控制

  src/web/                 # WhatsApp Web (Baileys)
  src/discord/            # Discord 集成
  src/telegram/           # Telegram (grammY)
  src/slack/              # Slack (Bolt)
  src/signal/             # Signal (signal-cli)
  src/imessage/           # iMessage
  src/line/               # LINE

  设计模式:

  • Adapter 模式:每个渠道实现标准适配器接口
  • Plugin 架构:通过 extensions/ 目录扩展渠道
  • 消息标准化:统一的消息格式转换

  4. 配置系统 (src/config/)

  src/config/
  ├── types.*.ts           # 类型定义(按功能拆分)
  ├── zod-schema.*.ts      # Zod 验证模式
  ├── sessions.ts          # 会话管理
  └── config.ts            # 配置加载/保存

  特点:

  • 使用 Zod 进行运行时类型验证
  • 配置文件存储在 ~/.openclaw/
  • 支持多账号、多渠道配置

  5. 自动回复引擎 (src/auto-reply/)

  src/auto-reply/
  ├── reply/               # 回复处理
  │   ├── agent-runner.ts  # Agent 执行器
  │   ├── queue/           # 消息队列
  │   ├── commands-*.ts    # 内置命令处理
  │   └── session.ts       # 会话管理
  ├── commands-registry.ts # 命令注册
  └── dispatch.ts          # 消息分发

  核心功能:

  • 消息队列和路由
  • 分块流式响应
  • 内置命令系统 (!status, !models, !compact 等)
  • 提及/回复触发器

  6. 浏览器自动化 (src/browser/)

  src/browser/
  ├── pw-session.ts        # Playwright 会话
  ├── pw-tools-core.ts     # 浏览器工具核心
  ├── routes/              # HTTP API 路由
  ├── cdp.ts               # Chrome DevTools Protocol
  └── server.ts            # 浏览器控制服务

  ──────────────────────────────────────────────────────────────────────────
  四、插件/扩展系统

  插件目录结构 (extensions/)

   插件             功能
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   whatsapp         WhatsApp 渠道 (Baileys)
   discord          Discord 渠道
   telegram         Telegram 渠道
   slack            Slack 渠道
   signal           Signal 渠道
   imessage         iMessage 渠道
   matrix           Matrix 渠道
   msteams          Microsoft Teams
   voice-call       语音通话
   memory-lancedb   向量存储 (LanceDB)
   lobster          自定义功能

  插件 SDK (src/plugin-sdk/)

  提供标准化的扩展接口:

  • ChannelAdapter - 渠道适配器
  • ChannelConfigAdapter - 配置适配器
  • ChannelMessagingAdapter - 消息适配器
  • ChannelOutboundAdapter - 外发消息适配器

  ──────────────────────────────────────────────────────────────────────────
  五、多平台应用架构

  apps/
  ├── macos/               # macOS Menu Bar App
  │   └── Sources/
  │       ├── OpenClaw/    # 主应用 (SwiftUI)
  │       ├── OpenClawIPC/ # XPC 通信
  │       └── OpenClawProtocol/ # 协议定义
  ├── ios/                 # iOS App (SwiftUI)
  ├── android/             # Android App (Kotlin)
  └── shared/              # 共享代码
      └── OpenClawKit/     # 跨平台工具包

  通信机制:

  • macOS: XPC + WebSocket
  • iOS/Android: WebSocket + REST API

  ──────────────────────────────────────────────────────────────────────────
  六、数据流架构

  1. 入站消息流:
     Channel API → Normalize → Allowlist Check → Queue → Agent Runner → Stream Reply

  2. 出站消息流:
     CLI/API → Target Resolution → Channel Adapter → Send API

  3. Agent 执行流:
     User Input → Pi Agent RPC → Tool Call → Execute → Stream Response

  ──────────────────────────────────────────────────────────────────────────
  七、关键技术决策

   领域         技术选择           说明
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   运行时       Node.js 22+        ESM 原生支持
   类型验证     Zod                运行时类型安全
   CLI 框架     Commander.js       成熟的 Node.js CLI
   HTTP 框架    Hono               轻量级,Edge 友好
   浏览器控制   Playwright + CDP   完整的浏览器自动化
   向量存储     sqlite-vec         嵌入式向量搜索
   配置格式     YAML + JSON        人类可读配置
   测试框架     Vitest             快速,V8 覆盖率

  ──────────────────────────────────────────────────────────────────────────
  八、安全架构

  1. DM 配对机制: 默认 dmPolicy="pairing",未知发送者需配对码
  2. 白名单系统: 基于 allowFrom 的细粒度访问控制
  3. 命令门控: 区分普通/特权命令
  4. 沙箱执行: Agent 工具在受限环境中运行

  ──────────────────────────────────────────────────────────────────────────
  九、部署模式

   模式        说明
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Gateway     后台守护进程 (launchd/systemd)
   CLI         命令行交互
   Docker      容器化部署
   macOS App   菜单栏应用 (内置 Gateway)

  ──────────────────────────────────────────────────────────────────────────
  十、总结

  OpenClaw 是一个设计精良的个人 AI 助手网关系统,其核心架构特点包括:

  1. 模块化设计:清晰的模块边界,每个渠道/功能独立实现
  2. 插件化扩展:通过 extensions 机制支持无限扩展
  3. 多平台统一:一套核心代码支持 CLI/Web/Mobile/Desktop
  4. 本地优先:数据存储在本地,保护隐私
  5. 流式响应:完整的流式处理架构,支持实时交互

  该架构非常适合作为个人 AI 基础设施,将多个消息渠道和 AI 模型统一整合到一个可控制的本地网关中。

Skill 编写指南

  一、什么是 Skill?

  Skill 是模块化的能力包,用于扩展 AI Agent 的功能。它通过 YAML Frontmatter + Markdown 的形式,向模型传授特定领域的知识、工作流程和工具使用方法。

  ┌─────────────────────────────────────────────────────────────────┐
  │                         Skill 架构                               │
  ├─────────────────────────────────────────────────────────────────┤
  │  SKILL.md (必需)                                                 │
  │  ├── YAML Frontmatter (元数据: name, description, metadata)       │
  │  └── Markdown Body (使用说明、命令示例、工作流程)                  │
  ├─────────────────────────────────────────────────────────────────┤
  │  可选资源                                                        │
  │  ├── scripts/     - 可执行脚本 (Python/Bash/...)                 │
  │  ├── references/  - 参考文档 (API 文档、配置说明等)               │
  │  └── assets/      - 资源文件 (模板、图片等)                       │
  └─────────────────────────────────────────────────────────────────┘

  ──────────────────────────────────────────────────────────────────────────
  二、Skill 文件结构

  最小 Skill 示例

  my-skill/
  └── SKILL.md

  完整 Skill 示例

  my-skill/
  ├── SKILL.md                 # 主文件(必需)
  ├── scripts/
  │   └── helper.sh           # 辅助脚本
  ├── references/
  │   └── api-docs.md         # API 参考文档
  └── assets/
      └── template.txt        # 模板文件

  ──────────────────────────────────────────────────────────────────────────
  三、SKILL.md 详解

  3.1 基础结构

  ---
  name: my-skill                    # Skill 名称 (必需)
  description: 描述这个 Skill 的作用  # 描述 (必需),用于触发 Skill
  homepage: https://example.com     # 可选:主页链接
  metadata:                         # OpenClaw 扩展元数据
    {
      "openclaw":
        {
          "emoji": "🚀",
          "os": ["darwin", "linux"],
          "requires": { "bins": ["curl"], "env": ["API_KEY"] },
          "primaryEnv": "API_KEY",
        },
    }
  ---

  # My Skill

  ## 快速开始

  使用示例:

  ```bash
  curl -s "https://api.example.com/data"

  详细说明

  ...


  ### 3.2 Frontmatter 字段参考

  | 字段 | 必需 | 说明 |
  |------|------|------|
  | `name` | ✅ | Skill 名称,小写字母/数字/连字符 |
  | `description` | ✅ | 描述 Skill 功能和触发场景(**这是主要触发机制**) |
  | `homepage` | ❌ | 主页 URL |
  | `metadata` | ❌ | OpenClaw 扩展元数据(JSON 格式)|
  | `user-invocable` | ❌ | `true\|false`,是否可作为 `/slash` 命令 |
  | `disable-model-invocation` | ❌ | `true\|false`,是否禁止模型自动调用 |

  ### 3.3 OpenClaw Metadata 详解

  ```json
  {
    "openclaw": {
      "emoji": "🛠️",                    // macOS UI 显示的图标
      "homepage": "https://...",        // 网站链接
      "os": ["darwin", "linux"],        // 限制平台 (darwin/linux/win32)
      "always": true,                   // 总是加载(跳过其他检查)

      "requires": {
        "bins": ["gh", "curl"],         // 必需的命令(必须在 PATH 中)
        "anyBins": ["docker", "podman"], // 至少需要一个
        "env": ["GITHUB_TOKEN"],        // 必需的环境变量
        "config": ["browser.enabled"]   // 必需的配置项
      },

      "primaryEnv": "GITHUB_TOKEN",     // 主环境变量名

      "install": [                      // 安装指引(macOS UI 使用)
        {
          "id": "brew",
          "kind": "brew",
          "formula": "gh",
          "bins": ["gh"],
          "label": "Install GitHub CLI"
        },
        {
          "id": "npm",
          "kind": "node",
          "package": "some-cli",
          "bins": ["some-cli"]
        }
      ]
    }
  }

  ──────────────────────────────────────────────────────────────────────────
  四、Skill 类型与示例

  4.1 简单命令型 Skill

  weather/SKILL.md - 查询天气

  ---
  name: weather
  description: Get current weather and forecasts (no API key required).
  homepage: https://wttr.in/:help
  metadata: { "openclaw": { "emoji": "🌤️", "requires": { "bins": ["curl"] } } }
  ---

  # Weather

  Two free services, no API keys needed.

  ## wttr.in (primary)

  Quick one-liner:

  ```bash
  curl -s "wttr.in/London?format=3"
  # Output: London: ⛅️ +8°C

  Format codes: %c condition · %t temp · %h humidity · %w wind


  ### 4.2 带脚本的 Skill

  **tmux/SKILL.md** - 控制 tmux 会话
  ```markdown
  ---
  name: tmux
  description: Remote-control tmux sessions for interactive CLIs
  metadata:
    { "openclaw": { "emoji": "🧵", "os": ["darwin", "linux"], "requires": { "bins": ["tmux"] } }
  ---

  # tmux Skill

  Use tmux only when you need an interactive TTY.

  ## Quickstart

  ```bash
  SOCKET_DIR="${OPENCLAW_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/openclaw-tmux-sockets}"
  mkdir -p "$SOCKET_DIR"
  SOCKET="$SOCKET_DIR/openclaw.sock"
  tmux -S "$SOCKET" new -d -s "my-session"

  Helper Scripts

  Use {baseDir} to reference the skill folder:

  {baseDir}/scripts/find-sessions.sh -S "$SOCKET"
  {baseDir}/scripts/wait-for-text.sh -t session:0.0 -p 'pattern'


  **tmux/scripts/find-sessions.sh**:
  ```bash
  #!/usr/bin/env bash
  set -euo pipefail

  # 脚本内容...

  4.3 带 References 的 Skill

  github/SKILL.md - GitHub CLI 操作

  ---
  name: github
  description: "Interact with GitHub using the `gh` CLI"
  metadata:
    {
      "openclaw":
        {
          "emoji": "🐙",
          "requires": { "bins": ["gh"] },
          "install":
            [
              { "id": "brew", "kind": "brew", "formula": "gh", "bins": ["gh"] },
              { "id": "apt", "kind": "apt", "package": "gh", "bins": ["gh"] },
            ],
        },
    }
  ---

  # GitHub Skill

  Use the `gh` CLI to interact with GitHub.

  ## Pull Requests

  Check CI status:
  ```bash
  gh pr checks 55 --repo owner/repo

  Advanced Topics

  See references/advanced.md for:

  • Working with GitHub Actions
  • GraphQL API queries
  • Managing releases


  ---

  ## 五、Skill 加载优先级

  OpenClaw 从多个位置加载 Skill,优先级从高到低:

  1. <workspace>/skills/           # 工作空间 Skill (最高)
  2. ~/.openclaw/skills/           # 托管/本地 Skill
  3. <bundled>/skills/             # 内置 Skill (最低)
  4. skills.load.extraDirs (config) # 额外目录


  **冲突解决**: 同名 Skill,优先级高的覆盖低的。

  ---

  ## 六、高级特性

  ### 6.1 Slash 命令支持

  使 Skill 可作为 Discord/Slack 的 `/slash` 命令:

  ```markdown
  ---
  name: my-skill
  description: My skill description
  user-invocable: true              # 允许用户通过 / 调用
  command-dispatch: tool            # 直接分派到工具
  command-tool: my_tool             # 目标工具名
  command-arg-mode: raw             # 参数传递模式
  ---

  6.2 渐进式披露设计

  使用 references/ 目录按需加载详细文档:

  # Main SKILL.md (保持精简 <500 行)

  ## Quick Start
  基础用法...

  ## Advanced Features
  - **Form filling**: See [references/forms.md](references/forms.md)
  - **API Reference**: See [references/api.md](references/api.md)
  - **Examples**: See [references/examples.md](references/examples.md)

  6.3 配置注入

  在 ~/.openclaw/openclaw.json 中为 Skill 提供配置:

  {
    skills: {
      entries: {
        "my-skill": {
          enabled: true,
          apiKey: "my-api-key",           // 映射到 primaryEnv
          env: {
            CUSTOM_VAR: "value"
          },
          config: {
            endpoint: "https://api.example.com"
          }
        }
      }
    }
  }

  ──────────────────────────────────────────────────────────────────────────
  七、完整编写流程

  Step 1: 创建目录

  mkdir -p ~/.openclaw/workspace/skills/my-skill
  cd ~/.openclaw/workspace/skills/my-skill

  Step 2: 编写 SKILL.md

  ---
  name: my-skill
  description: One-line description of what this skill does and when to use it.
  metadata:
    {
      "openclaw":
        {
          "emoji": "🎯",
          "requires": { "bins": ["required-cli"] },
        },
    }
  ---

  # My Skill

  ## What it does

  Brief description.

  ## Usage

  ```bash
  required-cli --option value

  Tips

  • Tip 1
  • Tip 2



  Step 3: 添加脚本(可选)

  mkdir scripts
  cat > scripts/helper.sh << 'EOF'
  #!/usr/bin/env bash
  echo "Helper script"
  EOF
  chmod +x scripts/helper.sh

  Step 4: 测试

  # 重启 Gateway 或刷新 Skills
  openclaw skills refresh

  # 测试使用
  openclaw agent --message "use my-skill to do something"

  ──────────────────────────────────────────────────────────────────────────
  八、最佳实践

  ✅ Do's

  1. 简洁至上 - SKILL.md 保持精简,详细内容放 references/
  2. 明确触发条件 - description 要清楚描述何时使用该 Skill
  3. 使用 {baseDir} - 引用 Skill 内部文件时用这个占位符
  4. 提供代码示例 - 模型更喜欢具体的命令示例
  5. 测试脚本 - 所有脚本必须经过实际测试

  ❌ Don'ts

  1. 不要包含多余文件 - 不要 README.md、CHANGELOG.md 等
  2. 不要解释 AI 是什么 - 模型已经知道自己是 AI
  3. 不要过度限制 - 只在真正需要时才设置 requires
  4. 不要重复信息 - SKILL.md 和 references/ 不要重复

  ──────────────────────────────────────────────────────────────────────────
  九、Skill 存储位置速查

   类型        路径                  用途
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
   Bundled     <openclaw>/skills/    内置 Skill,随安装更新
   Managed     ~/.openclaw/skills/   用户级 Skill,所有 Agent 共享
   Workspace   <workspace>/skills/   工作空间 Skill,仅当前 Agent
   Plugin      <plugin>/skills/      插件提供的 Skill

  ──────────────────────────────────────────────────────────────────────────
  十、参考资源

  • 技能仓库: https://clawhub.com
  • 内置 Skill: /Users/junjian/GitHub/openclaw/skills/ (50+ 个示例)
  • Skill Creator: /Users/junjian/GitHub/openclaw/skills/skill-creator/SKILL.md
  • 文档: https://docs.openclaw.ai/tools/skills

  ──────────────────────────────────────────────────────────────────────────
  现在你可以开始编写自己的 OpenClaw Skill 了!建议从修改现有的简单 Skill(如 weather)开始,逐步掌握 Skill 设计的最佳实践。

2026年新年对联

2026年新年对联PDF已生成!

文件信息:

  • 📄 文件名:2026新年对联.pdf
  • 📦 大小:389 KB
  • 📍 位置:/Users/junjian/.openclaw/workspace/

对联内容:

位置 内容
🏮 横批 蛇年大吉
📜 上联(贴右侧) 灵蛇起舞辞旧岁
📜 下联(贴左侧) 骏马奔腾迎新春

寓意说明:

  • 2026年为农历丙午年(马年)
  • 上联”灵蛇起舞辞旧岁”送别蛇年
  • 下联”骏马奔腾迎新春”迎接马年
  • 横批”蛇年大吉”延续传统祝福

另外还保留了 2026新年对联-打印版.html,你可以用浏览器打开直接打印!

Discord 配置

https://discord.com/developers/applications/

Updated: