Zalo 個人版

​

インストール

openclaw plugins install @openclaw/zalouser

• バージョンを固定: openclaw plugins install @openclaw/zalouser@<version>
• ソースチェックアウトから: openclaw plugins install ./path/to/local/zalouser-plugin
• 詳細: Plugin

​

クイックセットアップ

1. Plugin をインストールします（上記参照）。
2. ログインします（QR、Gateway マシン上）。
   • openclaw channels login --channel zalouser
   • Zalo モバイルアプリで QR コードをスキャンします。
3. チャネルを有効にします。

{
  channels: {
    zalouser: {
      enabled: true,
      dmPolicy: "pairing",
    },
  },
}

4. Gateway を再起動します（またはセットアップを完了します）。
5. DM アクセスのデフォルトはペアリングです。初回の連絡時にペアリングコードを承認してください。

​

概要

• zca-js ライブラリを介して、完全にプロセス内で実行されます（外部 zca/openzca バイナリは不要です）。
• 受信メッセージの受け取りには、ネイティブイベントリスナー（message、error）を使用します。
• JS API を介して返信を直接送信します（テキスト、メディア、リンク）。
• Zalo Bot API を利用できない「個人アカウント」のユースケース向けに設計されています。

​

命名

​

ID の検索（ディレクトリ）

openclaw directory self --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory groups list --channel zalouser --query "work"

​

制限

• 送信テキストは 2000 文字単位に分割されます（Zalo クライアントの制限）。
• ストリーミングはサポートされていません。
• 処理済みの受信メッセージ ID は 30 日間保持され、アカウントごとに最新 1000 件までに制限されます。

​

受信処理の耐久性

​

アクセス制御（DM）

• openclaw pairing list zalouser
• openclaw pairing approve zalouser <code>

​

グループアクセス（任意）

• デフォルト: channels.zalouser.groupPolicy = "allowlist"（グループには明示的な許可リストエントリが必要です）。
• すべてのグループを開放: channels.zalouser.groupPolicy = "open"。
• すべてのグループをブロック: channels.zalouser.groupPolicy = "disabled"。
• groupPolicy = "allowlist" の場合:
  • channels.zalouser.groups のキーには安定したグループ ID を使用してください。名前が起動時に ID に解決されるのは、channels.zalouser.dangerouslyAllowNameMatching: true が有効な場合のみです。
  • channels.zalouser.groupAllowFrom は、許可されたグループ内でどの送信者がボットを起動できるかを制御します。静的な送信者アクセスグループは accessGroup:<name> で参照できます。
• 設定ウィザードでは、グループ許可リストの入力を求めることができます。
• グループ許可リストの照合は、デフォルトでは ID のみを使用します。channels.zalouser.dangerouslyAllowNameMatching: true が有効でない限り、解決されていない名前は認証で無視されます。
• channels.zalouser.dangerouslyAllowNameMatching: true は、変更可能な起動時の名前解決と実行時のグループ名照合を再び有効にする、緊急時用の互換モードです。
• groupAllowFrom は、通常のグループメッセージでは allowFrom にフォールバックしません。許可リストに登録されたグループでこれを空のままにすると、そのグループはすべての送信者に開放されます。認可済みの制御コマンド（例: /new）は例外です。groupAllowFrom が空の場合、コマンド送信者のチェックは allowFrom にフォールバックします。

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["1471383327500481391"],
      groups: {
        "123456789": { enabled: true },
        "Work Chat": { enabled: true },
      },
    },
  },
}

​

グループメンションによる制御

• channels.zalouser.groups.<group>.requireMention は、グループへの返信にメンションが必要かどうかを制御します。
• 解決順序: グループ ID -> group:<id> エイリアス -> グループ名/スラッグ（名前ベースの候補が適用されるのは dangerouslyAllowNameMatching: true の場合のみ）-> * -> デフォルト（true）。
• 許可リストに登録されたグループと、グループ開放モードの両方に適用されます。
• ボットのメッセージを引用すると、グループを起動する暗黙的なメンションとして扱われます。
• 認可済みの制御コマンド（例: /new）は、メンションによる制御を回避できます。
• メンションが必要なためグループメッセージがスキップされた場合、OpenClaw はそのメッセージを保留中のグループ履歴として保存し、次に処理されるグループメッセージに含めます。
• グループ履歴の上限: channels.zalouser.historyLimit、次に messages.groupChat.historyLimit、その後はフォールバック値の 50。

{
  channels: {
    zalouser: {
      groupPolicy: "allowlist",
      groups: {
        "*": { enabled: true, requireMention: true },
        "Work Chat": { enabled: true, requireMention: false },
      },
    },
  },
}

​

複数アカウント

{
  channels: {
    zalouser: {
      enabled: true,
      defaultAccount: "default",
      accounts: {
        work: { enabled: true, profile: "work" },
      },
    },
  },
}

​

環境変数

1. 設定内の明示的な profile。
2. ZALOUSER_PROFILE。
3. ZCA_PROFILE。
4. デフォルト以外のアカウントではアカウント ID、デフォルトアカウントでは default。

​

入力中表示、リアクション、配信確認

• OpenClaw は返信を送信する前に、入力中イベントを送信します（ベストエフォート）。
• メッセージリアクションアクション react は、チャネルアクション内の zalouser でサポートされています。
  • メッセージから特定のリアクション絵文字を削除するには、remove: true を使用します。
  • リアクションの動作: リアクション
• イベントメタデータを含む受信メッセージに対して、OpenClaw は配信済みおよび既読の確認を送信します（ベストエフォート）。

​

トラブルシューティング

• openclaw channels status --probe
• 再ログイン: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser

• allowFrom/groupAllowFrom には数値 ID を使用し、groups には安定したグループ ID を使用してください。友人名またはグループ名との完全一致が意図的に必要な場合は、channels.zalouser.dangerouslyAllowNameMatching: true を有効にします。

• 外部 zca プロセスを前提とする設定をすべて削除してください。現在、このチャネルは外部 CLI バイナリを使用せず、zca-js を介して完全にプロセス内で実行されます。

​

関連項目

• チャネルの概要 - サポートされているすべてのチャネル
• ペアリング - DM の認証とペアリングの流れ
• グループ - グループチャットの動作とメンションによる制御
• チャネルルーティング - メッセージのセッションルーティング
• セキュリティ - アクセスモデルと堅牢化