OpenClaw 集成

OpenClaw 是一个用于构建对话式 AI 智能体的开源框架。它采用带有命名插槽（slots）的模块化插件系统，每个插槽控制智能体管道的特定部分。

最重要的插槽是 contextEngine。 这个插件负责决定在每次 LLM 调用之前注入系统提示词的上下文内容。 它控制智能体记住什么、知道什么、以及感受到什么。

OpenClaw 的插件系统类似中间件。每个插件实现生命周期钩子， 在对话轮次的特定节点触发：

默认情况下，OpenClaw 附带一个基本的上下文引擎，将记忆存储为本地 Markdown 文件。 Sonzai 插件将其替换为 Mind Layer — 无需额外代码即可为智能体提供持久记忆、人格进化、情绪追踪和关系建模。

插件注册机制

安装 @sonzai-labs/openclaw-context 后， 该包会导出一个 register() 函数作为默认导出。 启动时，OpenClaw 加载所有已安装的插件并调用其 register 函数。 我们的插件以 "sonzai" 名称注册上下文引擎工厂：

// @sonzai-labs/openclaw-context 内部（不需要开发者编写）
export default function register(api) {
  api.registerContextEngine("sonzai", () => {
    return new SonzaiContextEngine(client, config);
  });
}

然后在 openclaw.json 中，告诉 OpenClaw 哪个已注册的引擎用于 contextEngine 插槽。 名称 "sonzai" 必须与插件注册的名称匹配：

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"    // ← 与 register() 中注册的名称匹配
    },
    "entries": {
      "sonzai": {                  // ← 传递给插件的配置
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid"
      }
    }
  }
}

流程如下：安装 npm 包 → OpenClaw 发现并调用 register() → 插件以 "sonzai" 注册 → 配置将其分配给 contextEngine 插槽。

1. 获取 API 密钥

从 Sonzai 项目设置获取 API 密钥。在设置向导中输入后，它将保存到 openclaw.json 中。

2. 安装插件

# 通过 OpenClaw CLI 安装
openclaw plugins install @sonzai-labs/openclaw-context

# 或直接使用包管理器安装
npm install @sonzai-labs/openclaw-context
# bun add @sonzai-labs/openclaw-context

3. 运行设置向导

设置向导将引导你将 OpenClaw 项目连接到 Mind Layer：

npx @sonzai-labs/openclaw-context setup

向导将：

• 要求输入 API 密钥（或从环境中检测 SONZAI_API_KEY）
• 询问是否有现有的智能体 ID，或选择名称创建新的
• 在 Mind Layer 上验证 API 密钥
• 将 API 密钥和插件配置保存到 openclaw.json

设置完成后，openclaw.json 将如下所示：

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "a1b2c3d4-..."
      }
    }
  }
}

4. 开始聊天

像往常一样启动 OpenClaw。插件注册为 sonzai 上下文引擎并自动接管上下文组装：

openclaw chat

就这样。所有对话现在都流经 Mind Layer — 智能体从第一条消息开始就拥有持久记忆、人格和情绪。

所有设置都在 openclaw.json 的 plugins.entries.sonzai 下配置。 环境变量可作为覆盖使用。

可以通过 disable 映射选择性地禁用特定上下文来源。 当你需要 Mind Layer 的记忆功能但不需要情绪追踪， 或者想要减少 token 使用时很有用：

{
  "plugins": {
    "entries": {
      "sonzai": {
        "enabled": true,
        "apiKey": "sk-your-api-key",
        "agentId": "your-agent-uuid",
        "disable": {
          "mood": true,
          "personality": false,
          "relationships": true,
          "memory": false,
          "goals": true,
          "interests": true,
          "habits": true
        }
      }
    }
  }
}

使用上述配置，只会注入人格和记忆上下文 — 适合将 Mind Layer 作为纯记忆和人格存储使用。

每个轮次中，插件会向系统提示词注入一个结构化的 <sonzai-context> 块。各部分按优先级排序， 超出 token 预算时从最低优先级开始移除：

插件自动从 OpenClaw 的会话密钥格式中提取用户身份。 无需任何配置即可实现按用户的记忆和关系：

对于需要以编程方式配置智能体的多租户部署， 可以直接使用 setup() 函数：

import { setup } from "@sonzai-labs/openclaw-context";

const result = await setup({
  apiKey: "sk-project-key",
  agentName: "customer-support-bot",
  configPath: "/path/to/openclaw.json",
});

console.log(result.agentId);   // 确定性 UUID（tenantID + agentName 的 SHA1）
console.log(result.written);   // true — 配置文件已更新

Sonzai 上下文引擎插入 OpenClaw 的生命周期钩子。 以下是单个对话轮次的流程：

OpenClaw Runtime                SonzaiContextEngine              Sonzai Mind Layer
      |                                    |                                |
      |-- bootstrap(sessionId) ----------->|                                |
      |                                    |-- resolve agent + session ---->|
      |                                    |<-- session state cached -------|
      |                                    |                                |
      |-- assemble(messages, budget) ----->|                                |
      |                                    |-- fetch context (memory,       |
      |                                    |   personality, mood,           |
      |                                    |   relationships) ------------>|
      |                                    |<-- ranked context blocks ------|
      |                                    |                                |
      |<-- systemPromptAddition -----------|   (priority-ordered,           |
      |                                    |    budget-trimmed)             |
      |                                    |                                |
      |  [LLM call with enriched prompt]   |                                |
      |                                    |                                |
      |-- afterTurn(sessionId) ----------->|                                |
      |                                    |-- send conversation ---------> |
      |                                    |   Mind Layer extracts facts,   |
      |                                    |   updates mood, evolves        |
      |                                    |   personality automatically    |
      |                                    |                                |
      |-- compact(sessionId) ------------->|                                |
      |                                    |-- merge short-term → long-term>|
      |                                    |<-- compacted ------------------|

上下文引擎处理与 Mind Layer 的所有通信。 在 assemble 期间，获取上下文来源（记忆、人格、情绪、关系、目标、兴趣、习惯）， 按优先级排序并裁剪至 token 预算。在 afterTurn 期间，将对话发送回 Mind Layer 进行事实提取和状态更新。 引擎不在本地运行 LLM 调用 — 所有智能都在 Sonzai 端。

该包提供以下高级用途的导出：