OpenClaw中文社区

主题

Soul Evil Hook ​

Soul Evil 是 OpenClaw 的高级 Hook 系统，提供强大的自定义能力。

概述 ​

Soul Evil Hook 允许你在智能体运行的任何阶段注入自定义逻辑，实现复杂的业务需求。

功能 ​

  • 事件驱动 - 基于智能体生命周期事件
  • 上下文访问 - 访问完整的运行时上下文
  • 修改能力 - 修改消息、会话状态和工具调用
  • 链式执行 - 多个 Hook 可以链式执行

配置 ​

json5
{
  hooks: {
    entries: {
      "soul-evil": {
        script: "./hooks/soul-evil.js",
        priority: 100,  // 执行优先级（数值越小越先执行）
        events: [
          "agent:bootstrap",
          "before_agent_start",
          "after_agent_end",
          "before_tool_call",
          "after_tool_call"
        ]
      }
    }
  }
}

上下文对象 ​

javascript
{
  // 事件信息
  event: "before_agent_start",
  eventTime: "2026-01-30T00:00:00.000Z",
  
  // 会话信息
  session: {
    id: "session-123",
    agentId: "main",
    channel: "whatsapp"
  },
  
  // 消息
  messages: [...],
  
  // 工具调用（如果适用）
  toolCall: {
    name: "exec",
    parameters: {...}
  },
  
  // 工具结果（如果适用）
  toolResult: {...},
  
  // 配置
  config: {...}
}

Hook 函数签名 ​

javascript
async function soulEvilHook(context) {
  // 返回修改后的上下文，或返回 null 来跳过
  
  // 修改消息
  if (context.event === 'message:received') {
    context.messages.push({
      role: 'assistant',
      content: 'Hook added a message'
    });
  }
  
  // 修改工具调用
  if (context.toolCall) {
    context.toolCall.parameters = sanitizeParams(context.toolCall.parameters);
  }
  
  return context;
}

使用场景 ​

消息预处理 ​

javascript
async function(context) {
  if (context.event === 'message:received') {
    // 添加消息前缀
    context.messages.forEach(m => {
      if (m.role === 'user') {
        m.content = `[来自 ${context.session.channel}] ${m.content}`;
      }
    });
  }
  return context;
}

工具调用过滤 ​

javascript
async function(context) {
  if (context.toolCall) {
    const dangerous = ['exec', 'process'];
    if (dangerous.includes(context.toolCall.name)) {
      // 记录并可能阻止
      console.log(`Warning: Dangerous tool ${context.toolCall.name} called`);
    }
  }
  return context;
}

结果后处理 ​

javascript
async function(context) {
  if (context.event === 'after_agent_end') {
    // 添加结果摘要
    context.metadata.summary = generateSummary(context.messages);
  }
  return context;
}

调试 ​

启用调试日志：

bash
openclaw gateway --verbose

或在配置中：

json5
{
  hooks: {
    debug: true
  }
}

限制 ​

  • Hook 不能阻止智能体运行（除非返回错误）
  • 性能影响：每个 Hook 增加处理时间
  • 内存使用：注意不要在 Hook 中累积大量数据

相关文档 ​

基于 MIT 许可发布

Copyright © 2026-present OpenClaw中文社区