OpenClaw連携

OpenClawとは？

OpenClawは、会話型AIエージェントを構築するためのオープンソースフレームワークです。名前付きスロットを持つモジュラープラグインシステムを採用しており、各スロットはエージェントパイプラインの特定の部分を制御します。

最も重要なスロットはcontextEngineです。これはLLM呼び出しの前にシステムプロンプトに注入されるコンテキストを決定するプラグインです。エージェントが何を記憶し、何を知り、何を感じるかを制御します。

プラグインシステムの仕組み

OpenClawのプラグインシステムはミドルウェアのように動作します。各プラグインは会話ターンの特定のポイントで発火するライフサイクルフックを実装します：

• bootstrap(sessionId): 新しいチャットセッション開始時に呼ばれます。プラグインは必要な接続や状態を初期化します。
• assemble(messages, tokenBudget): LLM呼び出しの前に毎回呼ばれます。プラグインはsystemPromptAddition（システムプロンプトに注入される追加コンテキスト）を返します。
• afterTurn(sessionId): LLMの応答後に呼ばれます。プラグインは会話を処理します（例：事実の抽出、状態の更新）。
• compact(sessionId): コンテキストの統合が必要な時に呼ばれます（例：短期記憶から長期記憶へのマージ）。
• dispose(): セッション終了時に呼ばれます。接続と状態をクリーンアップします。

デフォルトでは、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で、contextEngineスロットにどの登録済みエンジンを使用するかをOpenClawに指示します。"sonzai"という名前はプラグインが登録したものと一致する必要があります：

{
  "plugins": {
    "slots": {
      "contextEngine": "sonzai"
    },
    "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をメモリとして使用したいが感情追跡は不要な場合や、トークン使用量を削減したい場合に便利です：

{
  "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>ブロックをシステムプロンプトに注入します。セクションは優先度順に並べられ、トークンバジェットを超過した場合は優先度の低いものから削除されます：

• パーソナリティ（優先度1、最高）：キャラクター定義、主要特性、話し方のパターン、Big5プロファイル
• 関連する記憶（優先度2）：最新のユーザーメッセージに一致するセマンティック検索された事実
• 現在の感情（優先度3）：4次元感情状態（感情価、覚醒度、緊張度、親和度）
• 関係性（優先度4）：関係性の物語、愛情スコア、現在のユーザーとの相性
• 目標（優先度5）：アクティブな目標（成長、習熟、関係性、発見）
• 興味（優先度6）：信頼度レベル付きの検出された興味
• 習慣（優先度7、最低）：強度スコア付きの行動パターン

セッションキーの解決

プラグインはOpenClawのセッションキー形式からユーザーIDを自動的に抽出します。これにより、設定なしでユーザーごとの記憶と関係性が可能になります：

プログラマティックセットアップ（B2B）

マルチテナント デプロイメントでエージェントをプログラム的にプロビジョニングする場合、 @sonzai-labs/openclaw-context プラグインの setup() ヘルパーが使えます。OpenClaw 自体が JavaScript の context engine なので、プラグインは TypeScript 専用ですが、 裏側は冪等な REST 呼び出し 2 本（エージェント作成 + 設定ファイル書き込み）にすぎず、 どの言語からでも駆動できます。下の Python / Go ブランチは公式の Sonzai SDK を使って 同じ処理を行います。

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のライフサイクルフックに接続します。1回の会話ターンのフローは次の通りです：

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中に、コンテキストソース（記憶、パーソナリティ、感情、関係性、目標、興味、習慣）を取得し、優先度順にランク付けして、トークンバジェットに合わせてトリミングします。afterTurn中に、事実抽出と状態更新のために会話をMind Layerに送信します。エンジンはローカルでLLM呼び出しを実行しません。すべてのインテリジェンスはSonzai側にあります。

エクスポート

パッケージは以下の高度な使用向けエクスポートを提供します：

次のステップ

• プラグインを支えるメモリ＆コンテキストシステムについて学ぶ
• パーソナリティシステムと感情＆ムードでコンテキストソースを理解する
• プラグインの背後にある完全なREST APIはAPIリファレンスを参照
• OpenClawなしのSDKベース連携は連携ガイドを参照