OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Regional platforms

Zalo 個人用

ステータス: 実験的。この連携はネイティブの zca-js を使用し、外部 CLI バイナリを使わずに、プロセス内で個人用 Zalo アカウントを自動操作します。

インストール

Zalo Personal は公式の外部 Plugin であり、コアには同梱されていません。使用前にインストールしてください。

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

クイックセットアップ

  1. Plugin をインストールします（上記参照）。
  2. ログインします（Gateway マシン上で QR を使用）。
    • openclaw channels login --channel zalouser
    • Zalo モバイルアプリで QR コードをスキャンします。
  3. チャンネルを有効にします。
json5
{  channels: {    zalouser: {      enabled: true,      dmPolicy: "pairing",    },  },}
  1. Gateway を再起動します（またはセットアップを完了します）。
  2. DM アクセスのデフォルトはペアリングです。最初の連絡時にペアリングコードを承認してください。

概要

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

命名

チャンネル ID は zalouser です。これは、個人用 Zalo ユーザーアカウントを自動操作する非公式連携であることを明示するためです。zalo は、将来提供される可能性がある公式 Zalo API 連携用に予約されています。

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

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

制限

  • 送信テキストは 2,000 文字単位に分割されます（Zalo クライアントの制限）。
  • ストリーミングには対応していません。

アクセス制御（DM）

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled（デフォルト: pairing）。

channels.zalouser.allowFrom には、安定した Zalo ユーザー ID を使用してください。静的な送信者アクセスグループ（accessGroup:<name>）も参照できます。対話型セットアップでは、入力した名前を Plugin のプロセス内連絡先検索によって ID に解決できます。

設定に未加工の名前が残っている場合、channels.zalouser.dangerouslyAllowNameMatching: true が有効なときに限り、起動時に解決されます。このオプトインがない場合、実行時の送信者チェックは ID のみを使用し、未加工の名前は認可時に無視されます。

次のコマンドで承認します。

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

例:

json5
{  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。

例:

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

複数アカウント

アカウントは、OpenClaw の状態内にある zalouser プロファイルに対応付けられます。例:

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

環境変数

プロファイルの選択には環境変数も使用できます。

変数 用途
ZALOUSER_PROFILE チャンネルまたはアカウント設定で profile が設定されていない場合に使用するプロファイル名です。
ZCA_PROFILE 以前のフォールバックです。ZALOUSER_PROFILE が設定されていない場合にのみ使用されます。

プロファイル名は、OpenClaw の状態に保存された Zalo ログイン認証情報を選択します。解決順序:

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

複数アカウントを設定する場合、1 つの環境変数によって複数のアカウントが同じログインセッションを共有しないよう、設定内の各アカウントに profile を設定することを推奨します。

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

  • 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 プロセスを前提とする設定をすべて削除してください。このチャンネルは現在、外部 CLI バイナリを使わず、zca-js により完全にプロセス内で動作します。

関連項目

Was this useful?
On this page

On this page