OpenClaw Internal Hook 开发指南

什么是 Internal Hook？

Internal Hook 是 OpenClaw Gateway 内部的事件处理器，在 agent 生命周期事件（如 agent:bootstrap）触发时执行 JavaScript/TypeScript 代码。

用途：

• 在会话启动时注入上下文文件
• 检查和提醒用户待处理的事项
• 发送通知（Telegram、Webhook 等）
• 记录日志和审计

快速开始

1. 创建 Hook 目录

~/.openclaw/hooks/
└── my-hook/
    ├── HOOK.md      # Hook 元数据（可选但推荐）
    └── handler.js   # 主要处理逻辑（必须）

2. 编写 Handler

// ~/.openclaw/hooks/my-hook/handler.js
const handler = async (event) => {
  // 检查事件类型
  if (event.type !== 'agent' || event.action !== 'bootstrap') return;
  
  // 检查上下文
  if (!event.context?.workspaceDir) return;
  
  // 跳过 sub-agent
  if (event.sessionKey?.includes(':subagent:')) return;
  
  // 注入虚拟文件
  if (Array.isArray(event.context.bootstrapFiles)) {
    event.context.bootstrapFiles.push({
      path: 'MY_CONTEXT.md',
      content: '# Hello from hook!',
      virtual: true,
    });
  }
};

module.exports = handler;
module.exports.default = handler;

3. 注册 Hook

在 ~/.openclaw/openclaw.json 中添加：

{
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "my-hook": {
          "enabled": true
        }
      },
      "load": {
        "extraDirs": ["~/.openclaw/hooks"]
      }
    }
  }
}

4. 重启 Gateway

openclaw gateway restart

事件结构

agent:bootstrap 事件

{
  type: 'agent',
  action: 'bootstrap',
  sessionKey: 'agent:main:telegram:direct:YOUR_USER_ID',
  context: {
    workspaceDir: '~/.openclaw/workspace',
    bootstrapFiles: [
      { path: 'MEMORY.md', content: '...' },
      // 可以 push 新文件到这里
    ],
    cfg: { /* 配置对象 */ },
    sessionId: 'uuid',
    agentId: 'main'
  }
}

上下文字段

HOOK.md 元数据

---
name: my-hook
description: "What this hook does"
metadata:
  openclaw:
    emoji: "📚"
    events: ["agent:bootstrap"]
    requires:
      config: ["workspace.dir"]
---
# Hook 说明
...

核心模式

1. 安全检查（必须！）

const handler = async (event) => {
  // 检查事件对象
  if (!event || typeof event !== 'object') return;
  
  // 只处理 bootstrap 事件
  if (event.type !== 'agent' || event.action !== 'bootstrap') return;
  
  // 检查上下文
  if (!event.context || typeof event.context !== 'object') return;
  
  // 跳过 sub-agent
  if (event.sessionKey?.includes(':subagent:')) return;
  
  // 检查工作区
  const workspaceDir = event.context?.workspaceDir;
  if (!workspaceDir) return;
  
  // 继续处理...
};

2. 注入虚拟文件

if (Array.isArray(event.context.bootstrapFiles)) {
  event.context.bootstrapFiles.push({
    path: 'REMINDER.md',
    content: '# Reminder\nDo something!',
    virtual: true,
  });
}

3. 读取工作区文件

const fs = require('fs');
const path = require('path');

const memoryDir = path.join(workspaceDir, 'memory');
if (fs.existsSync(memoryDir)) {
  const files = fs.readdirSync(memoryDir).filter(f => f.endsWith('.md'));
  // 处理文件...
}

4. 发送 HTTP 请求（如 Telegram）

const https = require('https');

async function sendNotification(botToken, chatId, message) {
  const data = JSON.stringify({
    chat_id: chatId,
    text: message,
  });
  
  return new Promise((resolve) => {
    const options = {
      hostname: 'api.telegram.org',
      port: 443,
      path: `/bot${botToken}/sendMessage`,
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        // ⚠️ 关键：使用 Buffer.byteLength
        'Content-Length': Buffer.byteLength(data),
      },
    };
    
    const req = https.request(options, (res) => {
      let body = '';
      res.on('data', (chunk) => body += chunk);
      res.on('end', () => resolve(res.statusCode === 200));
    });
    
    req.on('error', (e) => {
      console.error('[hook] Error:', e.message);
      resolve(false);
    });
    
    req.write(data);
    req.end();
  });
}

5. 获取配置（从文件读取更可靠）

const fs = require('fs');

function getBotToken(accountName) {
  try {
    const configPath = path.join(os.homedir(), '.openclaw/openclaw.json');
    const content = fs.readFileSync(configPath, 'utf-8');
    const match = content.match(
      new RegExp(`"${accountName}"[\\s\\S]*?"botToken"\\s*:\\s*"([^"]+)"`)
    );
    return match?.[1] || null;
  } catch (e) {
    console.error('[hook] Config read error:', e.message);
    return null;
  }
}

调试方法

1. 添加日志

console.error('[my-hook] Debug:', JSON.stringify({
  sessionKey: event.sessionKey,
  workspaceDir: event.context?.workspaceDir,
}));

2. 查看日志

# 实时查看
tail -f ~/.openclaw/logs/gateway.err.log

# 搜索特定 hook
grep -i "my-hook" ~/.openclaw/logs/gateway.err.log | tail -20

3. 独立测试发送逻辑

node -e "
const https = require('https');
const data = JSON.stringify({
  chat_id: 'YOUR_CHAT_ID',
  text: 'Test message'
});
console.log('Byte length:', Buffer.byteLength(data));
// ... 发送逻辑
"

4. 测试 Hook 执行

发送 /new 命令触发 bootstrap 事件，然后检查日志。

常见陷阱

1. Content-Length 字节计算

问题：发送中文时 Telegram 返回 message text is empty

原因：data.length 是字符数，不是字节数。中文字符在 UTF-8 中占 3 字节。

// ❌ 错误
'Content-Length': data.length

// ✅ 正确
'Content-Length': Buffer.byteLength(data)

2. Markdown 解析问题

Telegram Markdown 解析很严格，特殊字符会导致失败。

解决方案：不使用 parse_mode，发送纯文本。

3. cfg 对象不完整

event.context.cfg 可能不包含完整配置。

解决方案：直接从配置文件读取。

4. 忘记导出 handler

// 必须导出
module.exports = handler;
module.exports.default = handler;

5. 忘记重启 Gateway

修改 hook 后必须重启：

openclaw gateway restart

完整示例

参见 references/complete-example.js 获取包含所有功能的完整 hook 示例。