OpenClaw 插件开发指南

核心概念

钩子机制

OpenClaw 提供多种钩子用于拦截和处理事件：

请求-响应关联

使用 runId 关联请求和响应：

typescript
const inFlightRequests = new Map();

api.on(llm_input, (event: any) => {
const runId = event.runId;
inFlightRequests.set(runId, { timestamp: Date.now(), input: event });
});

api.on(llm_output, (event: any) => {
const runId = event.runId;
const request = inFlightRequests.get(runId);
// 成功配对，记录完整的请求-响应
inFlightRequests.delete(runId);
});

插件结构

~/.openclaw/extensions/plugin-name/
├── openclaw.plugin.json # 插件清单
├── index.ts # 主入口
├── logger.ts # 工具模块（可选）
└── README.md # 文档（可选）

清单示例

json
{
id: plugin-name,
name: 插件名称,
version: 1.0.0,
main: index.ts,
description: 插件描述
}

主入口模板

typescript
type OpenClawPluginApi = {
config?: any;
pluginConfig?: unknown;
logger: { info: (msg: string) => void; warn: (msg: string) => void; error: (msg: string) => void };
on: (hookName: string, handler: (event: any, ctx?: any) => void, opts?: { priority?: number }) => void;
};

const plugin = {
id: plugin-name,
name: 插件名称,
description: 插件描述,

register(api: OpenClawPluginApi) {
// 获取配置
const config = api.config?.plugins?.entries?.[plugin-name]?.config ?? {};

// 注册钩子
api.on(llm_input, (event) => { / 处理请求 / });
api.on(llm_output, (event) => { / 处理响应 / });
},
};

export default plugin;

常见模式

日志记录

typescript
// JSONL 格式，按日期分割文件
const logPath = path.join(basePath, ${new Date().toISOString().split(T)[0]}.jsonl);
fs.appendFileSync(logPath, JSON.stringify(entry) + \n);

配置管理

typescript
const DEFAULT_CONFIG = {
enabled: true,
logPath: ~/.openclaw/logs/plugin-name,
};

const config = { ...DEFAULT_CONFIG, ...rawConfig };

注意事项

钩子生命周期

• - llmoutput 依赖于正常的会话终止
• 如果会话被中断（网关重启、用户发送新消息），llmoutput 可能不会触发
• 需针对中断场景进行设计，避免资源泄漏

调试方法

bash

检查网关日志以确认钩子触发

检查插件加载

配置位置

在 openclaw.json 中启用插件：

json
{
plugins: {
entries: {
plugin-name: {
enabled: true,
config: {
option1: value1
}
}
}
}
}

示例：LLM API 日志记录器

完整示例请访问 https://github.com/cicadaFang/openclaw-llm-api-logger

功能特性：

• - 记录所有 LLM API 请求和响应
• JSONL 格式日志，按日期分割
• 使用 runId 关联请求和响应
• 记录 durationMs 和 usage 等指标