Hook 机制

Hook 是 WinWork 平台提供的事件驱动扩展机制，允许在 Agent 生命周期的特定节点插入自定义逻辑。通过 Hook，开发者可以动态修改 Agent 行为，而无需修改 Agent 本身的配置。

核心概念

Hook 监听平台内部事件，当事件触发时执行预定义的处理逻辑。目前支持的事件：

事件名	触发时机	典型用途
agent:bootstrap	Agent 启动初始化	注入系统提示词
agent:session:start	新会话开始	会话级配置初始化
agent:tool:before	工具调用前	参数校验、权限检查
agent:tool:after	工具调用后	结果处理、日志记录

system-prompt-enhancer

system-prompt-enhancer 是最常用的内置 Hook，在 agent:bootstrap 事件触发时向 Agent 注入额外的系统提示词。

工作原理

注入模式

Hook 支持两种注入模式：

prepend（前置注入）：将内容添加到系统提示词的开头，适合注入高优先级指令。

append（后置注入）：将内容添加到系统提示词的末尾，适合注入补充说明。

配置方式

Hook 在 openclaw.json 的 hooks.internal.entries 下配置：

{
  "hooks": {
    "internal": {
      "entries": [
        {
          "name": "system-prompt-enhancer",
          "event": "agent:bootstrap",
          "mode": "append",
          "content": "你是一个专业的客服助手，始终保持友好、耐心的态度。"
        }
      ]
    }
  }
}

多条 Hook 配置

可以同时配置多个 Hook 条目，按数组顺序依次执行：

{
  "hooks": {
    "internal": {
      "entries": [
        {
          "name": "system-prompt-enhancer",
          "event": "agent:bootstrap",
          "mode": "prepend",
          "content": "## 身份设定\n你是 WinWork 平台的智能助手。"
        },
        {
          "name": "system-prompt-enhancer",
          "event": "agent:bootstrap",
          "mode": "append",
          "content": "## 回答规范\n- 使用简洁的语言\n- 重要信息用列表呈现\n- 涉及代码时提供示例"
        }
      ]
    }
  }
}

从文件加载内容

对于较长的提示词，支持从文件加载：

{
  "hooks": {
    "internal": {
      "entries": [
        {
          "name": "system-prompt-enhancer",
          "event": "agent:bootstrap",
          "mode": "append",
          "contentFile": "./prompts/company-guidelines.md"
        }
      ]
    }
  }
}

条件触发

通过 condition 字段设置触发条件：

{
  "hooks": {
    "internal": {
      "entries": [
        {
          "name": "system-prompt-enhancer",
          "event": "agent:bootstrap",
          "mode": "append",
          "condition": {
            "agentName": "customer-service-agent"
          },
          "content": "仅在客服 Agent 中注入此内容。"
        }
      ]
    }
  }
}

实际应用示例

企业合规要求

{
  "name": "system-prompt-enhancer",
  "event": "agent:bootstrap",
  "mode": "prepend",
  "content": "重要：你不得讨论竞争对手产品，不得透露公司内部系统架构，所有回答需符合公司信息安全规范。"
}

角色扮演设定

{
  "name": "system-prompt-enhancer",
  "event": "agent:bootstrap",
  "mode": "prepend",
  "content": "你是一名资深 DevOps 工程师，拥有 10 年云原生和 CI/CD 经验。在回答技术问题时，优先考虑可靠性和可维护性。"
}

团队知识注入

{
  "name": "system-prompt-enhancer",
  "event": "agent:bootstrap",
  "mode": "append",
  "contentFile": "./team-knowledge/coding-standards.md"
}

TIP

system-prompt-enhancer 与 Skill 的 SKILL.md 内容注入是互补的。Skill 提供能力描述，Hook 提供行为规范和上下文增强。

WARNING

过多的 Hook 注入会增加系统提示词长度，可能影响 Agent 性能和准确性。建议保持注入内容简洁，总长度控制在 2000 tokens 以内。