Zalo personal

기준일: 2026-07-26
공식 기준: Zalo personal

Zalo personal 문서는 OpenClaw 공식 문서(channels/zalouser)를 한국어로 정리한 가이드입니다. Zalo personal account support via native zca-js (QR login), capabilities, and configuration 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Zalo personal account support via native zca-js (QR login), capabilities, and configuration

한국어 가이드 범위: channels/zalouser 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

• 설치
• 빠른 설정
• What it is
• Naming
• Finding IDs (directory)
• Limits
• Inbound durability
• Access control (DMs)
• Group access (optional)
• Group mention gating
• Multi-account
• 환경 변수
• Typing, reactions, and delivery acknowledgements
• 트러블슈팅
• 관련 문서

상세 내용

본문

Status: experimental. This integration automates a personal Zalo account via native zca-js, in-process, with no external CLI binary.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

설치

Zalo Personal is an official external plugin, not bundled in core. Install it before use:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Pin a version: openclaw plugins install @openclaw/zalouser@<version>
• From a source checkout: openclaw plugins install ./path/to/local/zalouser-plugin
• Details: Plugins

openclaw plugins install @openclaw/zalouser

빠른 설정

1. Install the plugin (above). 2. Login (QR, on the Gateway machine):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• openclaw channels login --channel zalouser
• Scan the QR code with the Zalo mobile app.

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

What it is

주요 항목:

• Runs entirely in-process via the zca-js library (no external zca/openzca binary).
• Uses native event listeners (message, error) to receive inbound messages.
• Sends replies directly through the JS API (text/media/link).
• Designed for "personal account" use cases where the Zalo Bot API is not available.

Naming

Channel id is zalouser to make it explicit this automates a personal Zalo user account (unofficial). zalo is reserved for a potential future official Zalo API integration.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Finding IDs (directory)

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

Limits

주요 항목:

• Outbound text is chunked to 2000 characters (Zalo client limit).
• Streaming is not supported.
• Completed inbound message ids are retained for 30 days, bounded to the 1000 most recent entries per account.

Inbound durability

OpenClaw stores each raw zca-js message callback before processing it. Pending messages resume from the account queue after a Gateway restart, and processing stays serialized per direct chat or group.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Access control (DMs)

channels.zalouser.dmPolicy: pairing | allowlist | open | disabled (default: pairing).

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

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

Group access (optional)

channels.zalouser.groups..allow is a legacy field name; current config uses enabled. openclaw doctor --fix migrates allow to enabled automatically.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• 기본값: channels.zalouser.groupPolicy = "allowlist" (groups require an explicit allowlist entry).
• Open all groups: channels.zalouser.groupPolicy = "open".
• Block all groups: channels.zalouser.groupPolicy = "disabled".
• With groupPolicy = "allowlist":
• channels.zalouser.groups keys should be stable group IDs; names resolve to IDs on startup only when channels.zalouser.dangerouslyAllowNameMatching: true is enabled.
• channels.zalouser.groupAllowFrom controls which senders in allowed groups can trigger the bot; static sender access groups can be referenced with accessGroup:<name>.
• The configure wizard can prompt for group allowlists.
• Group allowlist matching is ID-only by default. Unresolved names are ignored for auth unless channels.zalouser.dangerouslyAllowNameMatching: true is enabled.
• channels.zalouser.dangerouslyAllowNameMatching: true is a break-glass compatibility mode that re-enables mutable startup name resolution and runtime group-name matching.
• groupAllowFrom does not fall back to allowFrom for normal group messages: leaving it empty on an allowlisted group opens that group to any sender. Authorized control commands (for example /new) are the exception; command sender checks fall back to allowFrom when groupAllowFrom is empty.

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

Group mention gating

주요 항목:

• channels.zalouser.groups.<group>.requireMention controls whether group replies require a mention.
• Resolution order: group id -> group:<id> alias -> group name/slug (name-based candidates only apply when dangerouslyAllowNameMatching: true) -> * -> default (true).
• Applies both to allowlisted groups and open group mode.
• Quoting a bot message counts as an implicit mention for group activation.
• Authorized control commands (for example /new) can bypass mention gating.
• When a group message is skipped because a mention is required, OpenClaw stores it as pending group history and includes it on the next processed group message.
• Group history limit: channels.zalouser.historyLimit, then messages.groupChat.historyLimit, then a fallback of 50.

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

Multi-account

Accounts map to zalouser profiles in OpenClaw state. Example:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

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

환경 변수

Profile selection can also come from environment variables:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Var	Purpose
ZALOUSER_PROFILE	Profile name to use when no profile is set in channel or account config.
ZCA_PROFILE	Legacy fallback, used only when ZALOUSER_PROFILE is not set.

Typing, reactions, and delivery acknowledgements

주요 항목:

• OpenClaw sends a typing event before dispatching a reply (best-effort).
• Message reaction action react is supported for zalouser in channel actions.
• Use remove: true to remove a specific reaction emoji from a message.
• Reaction semantics: Reactions
• For inbound messages that include event metadata, OpenClaw sends delivered + seen acknowledgements (best-effort).

트러블슈팅

주요 항목:

• openclaw channels status --probe
• Re-login: openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser
• Use numeric IDs in allowFrom/groupAllowFrom and stable group IDs in groups. If you intentionally need exact friend/group names, enable channels.zalouser.dangerouslyAllowNameMatching: true.
• Remove any external zca process assumptions; the channel now runs fully in-process via zca-js, with no external CLI binary.

관련 문서

주요 항목:

• Channels Overview - all supported channels
• Pairing - DM authentication and pairing flow
• Groups - group chat behavior and mention gating
• Channel Routing - session routing for messages
• Security - access model and hardening

실습 체크리스트

1. 공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/channels/zalouser
2. 관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
3. 설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
4. Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw plugins install @openclaw/zalouser

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

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

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

{
  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" },
      },
    },
  },
}

관련 링크

• 공식 원문: channels/zalouser
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.