“페어링”은 OpenClaw의 명시적인 접근 승인 단계입니다. 두 곳에서 사용됩니다.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
- DM 페어링(봇과 대화할 수 있는 사람)
- Node 페어링(Gateway 네트워크에 참여할 수 있는 기기/Node)
1) DM 페어링(인바운드 채팅 접근)
채널이 DM 정책pairing으로 구성되어 있으면, 알 수 없는 발신자는 짧은 코드를 받고 승인 전까지 해당 메시지는 처리되지 않습니다.
기본 DM 정책은 다음 문서에 설명되어 있습니다: 보안
dmPolicy: "open"은 유효한 DM 허용 목록에 "*"가 포함된 경우에만 공개입니다.
공개 열림 구성을 설정하고 검증하려면 해당 와일드카드가 필요합니다. 기존
상태에 구체적인 allowFrom 항목과 함께 open이 포함된 경우, 런타임은 여전히
해당 발신자만 허용하며, 페어링 저장소 승인은 open 접근을 넓히지 않습니다.
페어링 코드:
- 8자, 대문자, 혼동되는 문자 없음(
0O1I). - 1시간 후 만료됩니다. 봇은 새 요청이 생성될 때만 페어링 메시지를 보냅니다(발신자당 대략 한 시간에 한 번).
- 대기 중인 DM 페어링 요청은 기본적으로 채널당 3개로 제한됩니다. 추가 요청은 하나가 만료되거나 승인될 때까지 무시됩니다.
발신자 승인
commands.ownerAllowFrom도 승인된 발신자로 부트스트랩됩니다(예: telegram:123456789).
이를 통해 최초 설정 시 특권 명령과 exec 승인 프롬프트에 대한 명시적 소유자가 생깁니다.
소유자가 생긴 뒤에는 이후 페어링 승인은 DM 접근만 부여하며, 소유자를 더 추가하지 않습니다.
지원 채널: discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams, nextcloud-talk, nostr, openclaw-weixin, signal, slack, synology-chat, telegram, twitch, whatsapp, zalo, zalouser.
재사용 가능한 발신자 그룹
동일한 신뢰 발신자 집합을 여러 메시지 채널에 적용하거나 DM과 그룹 허용 목록 모두에 적용해야 하는 경우 최상위accessGroups를 사용하세요.
정적 그룹은 type: "message.senders"를 사용하며, 채널 허용 목록에서
accessGroup:<name>으로 참조됩니다.
상태가 저장되는 위치
~/.openclaw/credentials/ 아래에 저장됩니다.
- 대기 중인 요청:
<channel>-pairing.json - 승인된 허용 목록 저장소:
- 기본 계정:
<channel>-allowFrom.json - 기본이 아닌 계정:
<channel>-<accountId>-allowFrom.json
- 기본 계정:
- 기본이 아닌 계정은 범위가 지정된 허용 목록 파일만 읽고 씁니다.
- 기본 계정은 채널 범위의 범위 미지정 허용 목록 파일을 사용합니다.
페어링 허용 목록 저장소는 DM 접근용입니다. 그룹 권한 부여는 별도입니다.
DM 페어링 코드를 승인해도 해당 발신자가 자동으로 그룹
명령을 실행하거나 그룹에서 봇을 제어할 수 있게 되지는 않습니다. 첫 소유자 부트스트랩은
commands.ownerAllowFrom의 별도 구성 상태이며, 그룹 채팅 전달은 여전히
채널의 그룹 허용 목록을 따릅니다(예: 채널에 따라 groupAllowFrom, groups, 또는 그룹별
혹은 주제별 오버라이드).2) Node 기기 페어링(iOS/Android/macOS/헤드리스 Node)
Node는role: node를 가진 기기로 Gateway에 연결합니다. Gateway는
승인되어야 하는 기기 페어링 요청을 생성합니다.
Telegram을 통해 페어링(iOS에 권장)
device-pair Plugin을 사용하면 최초 기기 페어링을 Telegram에서 완전히 수행할 수 있습니다.
- Telegram에서 봇에게 메시지를 보냅니다:
/pair - 봇은 두 개의 메시지로 응답합니다. 안내 메시지와 별도의 설정 코드 메시지입니다(Telegram에서 복사/붙여넣기 쉽습니다).
- 휴대폰에서 OpenClaw iOS 앱을 엽니다 → 설정 → Gateway.
- QR 코드를 스캔하거나 설정 코드를 붙여넣고 연결합니다.
- Telegram으로 돌아가서:
/pair pending(요청 ID, 역할, 범위를 검토), 그런 다음 승인합니다.
url: Gateway WebSocket URL(ws://...또는wss://...)bootstrapToken: 초기 페어링 핸드셰이크에 사용되는 짧은 수명의 단일 기기 부트스트랩 토큰
- 전달된 기본
node토큰은scopes: []로 유지됩니다. - 전달된 모든
operator토큰은 부트스트랩 허용 목록으로 계속 제한됩니다.operator.approvals,operator.read,operator.talk.secrets,operator.write - 부트스트랩 범위 검사는 하나의 평평한 범위 풀이 아니라 역할 접두사가 붙습니다. operator 범위 항목은 operator 요청만 충족하며, operator가 아닌 역할은 여전히 자체 역할 접두사 아래의 범위를 요청해야 합니다.
- 이후 토큰 회전/폐기는 기기의 승인된 역할 계약과 호출자 세션의 operator 범위 모두에 의해 계속 제한됩니다.
wss:// Gateway URL을 사용하세요. 평문 ws:// 설정 코드는 loopback,
사설 LAN 주소, .local Bonjour 호스트, Android
에뮬레이터 호스트에 대해서만 허용됩니다. Tailnet CGNAT 주소, .ts.net 이름, 공개 호스트는
QR/설정 코드 발급 전에 여전히 닫힌 상태로 실패합니다.
Node 기기 승인
operator.admin으로 다시 시도합니다. 이를 통해 기존의 관리자 가능
페어링 기기가 devices/paired.json을 직접 편집하지 않고도 새
Control UI/브라우저 페어링을 복구할 수 있습니다. Gateway는 여전히 재시도된 연결을 검증하며,
operator.admin으로 인증할 수 없는 토큰은 계속 차단됩니다.
동일한 기기가 다른 인증 세부 정보(예: 다른
역할/범위/공개 키)로 다시 시도하면, 이전 대기 요청은 대체되고 새
requestId가 생성됩니다.
이미 페어링된 기기는 조용히 더 넓은 접근 권한을 얻지 않습니다. 더 많은 범위나 더 넓은 역할을 요청하며 다시 연결하면, OpenClaw는 기존 승인을 그대로 유지하고 새 대기 업그레이드 요청을 생성합니다. 승인하기 전에
openclaw devices list를 사용해 현재 승인된 접근 권한과 새로 요청된 접근 권한을 비교하세요.선택 사항: 신뢰할 수 있는 CIDR Node 자동 승인
기기 페어링은 기본적으로 수동으로 유지됩니다. 엄격하게 제어되는 Node 네트워크의 경우, 명시적 CIDR 또는 정확한 IP로 최초 Node 자동 승인을 사용하도록 선택할 수 있습니다.role: node 페어링 요청에만 적용됩니다.
Operator, 브라우저, Control UI, WebChat 클라이언트는 여전히 수동
승인이 필요합니다. 역할, 범위, 메타데이터, 공개 키 변경도 여전히 수동
승인이 필요합니다.
Node 페어링 상태 저장소
~/.openclaw/devices/ 아래에 저장됩니다.
pending.json(짧은 수명, 대기 요청은 만료됨)paired.json(페어링된 기기 + 토큰)
참고
- 레거시
node.pair.*API(CLI:openclaw nodes pending|approve|reject|remove|rename)는 별도의 Gateway 소유 페어링 저장소입니다. WS Node에는 여전히 기기 페어링이 필요합니다. - 페어링 레코드는 승인된 역할에 대한 지속 가능한 진실의 원천입니다. 활성 기기 토큰은 해당 승인된 역할 집합으로 계속 제한됩니다. 승인된 역할 외부의 흩어진 토큰 항목은 새 접근 권한을 만들지 않습니다.