OpenClaw

OpenClaw

明廷盛 嘻嘻😁
  2026-06-26 12:57:17 2026-06-26 12:57:17 Created   2026-06-18 15:06 2026-06-18 15:06 Updated    2.4k Words  11 Mins  

第零章 写在前面

官网: 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

第三节 CLI对话

① 作用 ② 格式 ③ 示例
开启新对话 openclaw chat --session <新名称> openclaw chat --session work
恢复上一次对话 openclaw chat（默认 session=main） openclaw chat
查看历史对话列表 openclaw sessions openclaw sessions --limit 25
跳转指定历史对话 openclaw chat --session <key> openclaw chat --session work
删除指定历史对话 无内置命令，需手动删文件 默认在 ~/.openclaw/sessions/ 下找对应 session 目录删除
  • session key 不写默认 main，所以 openclaw chat 永远是同一场对话
  • 想开新对话换一个 key 就行：openclaw chat --session test-001
  • chat 是别名，tui / terminal 也一样

第二章 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

第三节 我们的脚手架

  • 方便读取: "resolveJsonModule": true
{
  "compilerOptions": {
    "resolveJsonModule": true,
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "declaration": true,
    "outDir": "dist",
    "skipLibCheck": true
  },
  "include": [
    "src/**/*.ts"
  ]
}
  • 需要修改: ①name
{
  "name": "openclaw-plugin-web-11",
  "version": "0.1.0",
  "type": "module",
  "private": true,
  "scripts": {
    "build": "tsc -p tsconfig.json"
  },
  "files": [
    "dist",
    "openclaw.plugin.json"
  ],
  "peerDependencies": {
    "openclaw": ">=2026.5.17"
  },
  "dependencies": {
    "typebox": "^1.1.38"
  },
  "devDependencies": {
    "openclaw": "latest",
    "typescript": "^5.9.0"
  },
  "openclaw": {
    "extensions": [
      "./dist/index.js"
    ]
  }
}
  • 需要修改: ①id ②name ③description ④configSchema ⑤uiHints
{
  "id": "web-11",
  "name": "web 11",
  "description": "搜索网站插件",
  "version": "0.1.0",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "website" :{
        "type":"string",
        "description": "只能配一个网址"
      }
    }
  },
  "uiHints": {
    "website" :{
      "label": "网址",
      "description": "只能配一个网址"
    }
  },
  "activation": {
    "onStartup": true
  },
  "contracts": {
  }
}

  • 说明: 这里演示的是注册一个command
import { Type } from "typebox";
import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import manifest from "../openclaw.plugin.json" with { type: "json" }; // 直接读 manifest

const plugin: any = definePluginEntry({
  id: manifest.id,
  name: manifest.name,
  description: manifest.description,
  configSchema: manifest.configSchema as any,
  register(api) {
    // 配置读取
    const config = (api.pluginConfig ?? {}) as {
      website?: string;
    }

    
    api.registerCommand({
      name: "show-website",
      description: "展示用户配置的网站",
      handler: () => {
        return { text: `你配置的是${config.website ?? "未配置"}` };
      }
    })
  },
});

export default plugin;

第三章: 配置文件(openclaw.plugin.json)

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

第一节 uiHints

3.1.1 Hello 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"
    }
  },
}

3.1.2 uiHints配置数组

  • 需求: 配置多个股票网址接口
  • 文件: openclaw.plugin.config
"uiHints": {
    "apiEndpoints": {
      "label": "接口列表",
      "help": "配置多个接口地址，格式: [{\"name\": \"名称\", \"url\": \"地址\"}]"
    }
  },
  • 文件: openclaw.plugin.config
"configSchema": {
    "type": "object",
    "properties": {
      "apiEndpoints": {
        "type": "array",
        "description": "接口地址列表，每一项包含 name 和 url",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "description": "接口名称"
            },
            "url": {
              "type": "string",
              "description": "接口地址"
            }
          }
        }
      }
    }
  • 文件: index.ts
const config = (api.pluginConfig ?? {}) as {
  enabled?: boolean;
  apiEndpoints?: Array<{ name: string; url: string }>; // 改成数组类型，每项包含 name 和 url。
};

第四章 Plugin(index.ts)

①能够注册哪些? link

2.4.1 注册Tool

2.4.2 注册 Command

// ── 3. Command: 注册可通过 / 触发的命令 ──
// "我正在查看股票, 有相关设置吗?"
/**
 * @doc https://docs.openclaw.ai/plugins/sdk-overview#tools-and-commands
 */
// 命令 A: /stock-endpoints — 列出所有接口
api.registerCommand({ // 注册列出所有接口的命令。
  name: "stock-endpoints", // 声明命令名称，用户输入 /stock-endpoints 触发。
  description: "列出所有已配置的接口地址", // 声明命令说明。
  agentPromptGuidance: ["用户询问有哪些接口时，建议使用 /stock-endpoints 命令查看。"], // 注入到 system prompt 的提示。
  handler: () => { // 不需要参数，直接返回所有接口列表。
	if (endpoints.length === 0) return { text: "当前没有配置任何接口地址。" }; // 数组为空时返回提示。
	const lines = endpoints.map((e) => `- ${e.name}: ${e.url}`); // 每行一个接口：名称: 地址。
	return { text: lines.join("\n") }; // 用换行符拼接返回。
  },
});

// 命令 B: /stock-endpoint <名称> — 按名称查接口
api.registerCommand({ // 注册按名称查接口的命令。
  name: "stock-endpoint", // 声明命令名称，用户输入 /stock-endpoint 股票行情 触发。
  description: "按名称查看指定接口地址。用法: /stock-endpoint <接口名称>", // 声明命令说明。
  acceptsArgs: true, // 允许接收参数（即 <接口名称> 这部分）。
  agentPromptGuidance: ["用户想查看某个具体接口的地址时，建议使用 /stock-endpoint <名称> 命令。"],
  handler: (ctx) => { // ctx.args 就是用户输入的接口名称。
	const keyword = (ctx.args ?? "").trim(); // 去掉首尾空格。
	if (!keyword) return { text: "请输入接口名称，例如 /stock-endpoint 股票行情。可用的有: " + endpoints.map((e) => e.name).join(", ") }; // 没输入名称时提示可用的。
	const found = endpoints.find((e) => e.name === keyword); // 在数组中查找 name 匹配的项。
	if (!found) return { text: `未找到名为"${keyword}"的接口。可用的有: ` + endpoints.map((e) => e.name).join(", ") }; // 找不到时提示可用的。
	return { text: `${found.name} 的接口地址: ${found.url}` }; // 找到了返回地址。
  },
});

2.4.3 注册 Service

第三章 接入LLM

  • Title: OpenClaw
  • Author: 明廷盛
  • Created at : 2026-06-26 12:57:17
  • Updated at : 2026-06-18 15:06:00
  • Link: https://blog.20040424.xyz/2026/06/26/⏸️VibeCoding/OpenClaw/
  • License: All Rights Reserved © 明廷盛
On this page
OpenClaw
  1. 第零章 写在前面
  2. 第一章 Hello OpenClaw
    1. 第一节 下载OpenClaw
    2. 第二节 运行OpenClaw
      1. 1.2.1 什么是GateWay(网关)
      2. 1.2.2 GateWay常用命令
    3. 第三节 CLI对话
  3. 第二章 Plugin
    1. 第一节 常用命令
    2. 第二节 Hello Plugin
      1. STEP1: 利用脚手架
      2. STEP2: 删除不必要的内容
      3. STEP3: build并重启gateway
    3. 第三节 我们的脚手架
  4. 第三章: 配置文件(openclaw.plugin.json)
    1. 第一节 uiHints
      1. 3.1.1 Hello uiHints
      2. 3.1.2 uiHints配置数组
  5. 第四章 Plugin(index.ts)
    1. 第四节: 能力注册 link
    2. 第五节: 工具和命令 link
      1. 2.4.1 注册Tool
      2. 2.4.2 注册 Command
    3. 第六节: 基础设施 link
      1. 2.4.3 注册 Service
    4. 第七节: 工作流插件的主机 Hook link
  6. 第三章 接入LLM