OpenClaw

第零章 写在前面

官网: link

第一章 Hello OpenClaw

第一节 下载OpenClaw

下载

node --version
npm install -g openclaw

echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
exec zsh
openclaw --version

第二节 运行OpenClaw

1.2.1 什么是GateWay(网关)

• 作用: OpenClaw是通过GateWay运行的, 你网页18789看到的是gateway dashboard可视化界面;
  • ①言外之意就是想要用OpenClaw, 得先把gateway跑起来
  • ②修改任何内容(plugin, skill)也得重启gateway

1.2.2 GateWay常用命令

作用	指令	示例
查看gateway的状态	openclaw gateway status	openclaw gateway status
开启gateway	openclaw gateway start	openclaw gateway start
关闭gateway	openclaw gateway stop	openclaw gateway stop
重启gateway	openclaw gateway restart	openclaw gateway restart

第二章 Plugin

第一节 常用命令

作用	指令	示例 (voice-cal这个插件为例子)
列出已安装的插件	openclaw plugins list	openclaw plugins list
查看插件详细信息	openclaw plugins info <id>	openclaw plugins info voice-call
启用插件	openclaw plugins enable <id>	openclaw plugins enable voice-call
禁用插件	openclaw plugins disable <id>	openclaw plugins disable voice-call
卸载插件	openclaw plugins uninstall <id>	openclaw plugins uninstall voice-call
更新指定插件	openclaw plugins update <id>	openclaw plugins update voice-call
更新所有插件	openclaw plugins update --all	openclaw plugins update --all
	第二节 Hello Plugin
脚手架	openclaw plugins init "<文件名称>" --name "<插件名称>"	openclaw plugins init "test-01" --name "Test 01"
检查插件加载情况	openclaw plugins inspect <id> --runtime --json	openclaw plugins inspect my-plugin --runtime --json

第二节 Hello Plugin

STEP1: 利用脚手架

• 位置: ~/.openclaw/extentions (没有自己建)
• 文件结构:

test-01/
├── tsconfig.json          # tsc 编译配置：告诉 tsc 把 src/*.ts → dist/*.js
├── package.json           # npm 包元数据：名称/版本/脚本/依赖/入口路径
├── openclaw.plugin.json   # 插件 manifest：id/名称/配置/工具列表（Dashboard 发现）
├── README.md              # 说明文档，可删
└── src/
    ├── index.ts           # 插件入口源码：定义工具 + 执行逻辑
    └── index.test.ts      # vitest 单元测试，可删

openclaw plugins init "test-01" --name "Test 01"

STEP2: 删除不必要的内容

有用的文件就三个 ①package.json ② openclaw.plugin.json ③index.ts 其中②③最重要

• 最终文件结构

test-01/
├── tsconfig.json          # tsc 编译配置：告诉 tsc 把 src/*.ts → dist/*.js
├── package.json           # npm 包元数据：①删掉了 plugin:build/plugin:validate/test 脚本；②删掉了 vitest 开发依赖（没 test 就不需要）
├── openclaw.plugin.json   # 插件 manifest：id/名称/配置/工具列表（Dashboard 发现）
└── src/
    └── index.ts           # 插件入口源码：definePluginEntry 注册 tool/cli/command/service/hook

• 只用修改package.json: 共计两处修改

{
  "name": "openclaw-plugin-test-01",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc -p tsconfig.json"
    //(1/2) 这里删除了plugin:build; plugin:vaild; test脚本  
  },
  "files": [
    "dist",
    "openclaw.plugin.json",
    "README.md"
  ],
  "peerDependencies": {
    "openclaw": ">=2026.5.17"
  },
  "dependencies": {
    "typebox": "^1.1.38"
  },
  "devDependencies": {
    "openclaw": "latest",
    "typescript": "^5.9.0"
    //(2/2) 这里删除了vitest依赖  
  },
  "openclaw": {
    "extensions": [
      "./dist/index.js"
    ]
  }
}

STEP3: build并重启gateway

注意⚠️: openclaw 读的不是你这个文件下的index.ts; 而是 build 产生的 dist文件夹目录下的index.ts
插件修改了没有更新?: 你修改后 build 了吗?

npm install
npm run build
openclaw gateway restart

第三节: openclaw.plugin.json

openclaw.plugin.json是 openclaw 插件专属的配置文件 link
总共有几个配置项? 表格

1. uiHints:

uiHints 是"给已有配置项加标签"，不是"凭空创建配置项" 。Dashboard 只会为 configSchema.properties 里声明的字段渲染 uiHints 。
立即推===> uiHints和configSchema的properties字段都要配置

{
  "id": "test-plugin",
  "name": "Test Plugin",
  "description": "Add Test Plugin tools to OpenClaw.",
  "version": "0.1.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "hhh": {"type": "string"}   // 1/2
    }
  },
  "uiHints": {
    "hhh": {                     // 2/2
      "label": "HHH",
      "help": "xixix"
    }
  },
}

第四节: index.ts

2.4.1 注册Tool

2.4.2 注册 CLI / Command

2.4.3 注册 Service

2.4.4 注册

第三章