English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

CLI commands

채널

openclaw channels

Gateway에서 채팅 채널 계정과 해당 런타임 상태를 관리합니다.

관련 문서:

일반 명령

openclaw channels list
openclaw channels status
openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123
openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels logs --channel all

상태 / 기능 / 확인 / 로그

  • channels status: --probe, --timeout <ms>, --json
  • channels capabilities: --channel <name>, --account <id>(--channel과 함께만 사용), --target <dest>, --timeout <ms>, --json
  • channels resolve: <entries...>, --channel <name>, --account <id>, --kind <auto|user|group>, --json
  • channels logs: --channel <name|all>, --lines <n>, --json

channels status --probe는 라이브 경로입니다. 도달 가능한 Gateway에서는 계정별 probeAccount와 선택적 auditAccount 검사를 실행하므로, 출력에 전송 상태와 works, probe failed, audit ok, audit failed 같은 프로브 결과가 포함될 수 있습니다. Gateway에 도달할 수 없으면 channels status는 라이브 프로브 출력 대신 구성 전용 요약으로 대체됩니다.

채널 소켓 상태 신호로 openclaw sessions, Gateway sessions.list, 또는 에이전트 sessions_list 도구를 사용하지 마세요. 해당 표면은 저장된 대화 행을 보고하며, 제공자 런타임 상태를 보고하지 않습니다. Discord 제공자를 다시 시작한 후에는 연결되어 있지만 조용한 계정이 정상일 수 있으며, 다음 수신 또는 발신 대화 이벤트가 발생하기 전까지 Discord 세션 행이 나타나지 않을 수 있습니다.

계정 추가 / 제거

openclaw channels add --channel telegram --token <bot-token>
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
openclaw channels remove --channel telegram --delete

channels remove는 설치되었거나 구성된 채널 Plugin에서만 작동합니다. 설치 가능한 카탈로그 채널에는 먼저 channels add를 사용하세요. 런타임 기반 채널 Plugin의 경우, channels remove는 구성 업데이트 전에 실행 중인 Gateway에도 선택한 계정 중지를 요청하므로, 계정을 비활성화하거나 삭제해도 재시작 전까지 이전 리스너가 활성 상태로 남지 않습니다.

일반적인 비대화형 추가 표면은 다음과 같습니다.

  • bot-token 채널: --token, --bot-token, --app-token, --token-file
  • Signal/iMessage 전송 필드: --signal-number, --cli-path, --http-url, --http-host, --http-port, --db-path, --service, --region
  • Google Chat 필드: --webhook-path, --webhook-url, --audience-type, --audience
  • Matrix 필드: --homeserver, --user-id, --access-token, --password, --device-name, --initial-sync-limit
  • Nostr 필드: --private-key, --relay-urls
  • Tlon 필드: --ship, --url, --code, --group-channels, --dm-allowlist, --auto-discover-channels
  • 지원되는 경우 기본 계정 env 기반 인증에 사용하는 --use-env

플래그 기반 추가 명령 중 채널 Plugin을 설치해야 하면, OpenClaw는 대화형 Plugin 설치 프롬프트를 열지 않고 채널의 기본 설치 소스를 사용합니다.

플래그 없이 openclaw channels add를 실행하면 대화형 마법사가 다음을 물을 수 있습니다.

  • 선택한 채널별 계정 ID
  • 해당 계정의 선택적 표시 이름
  • Bind configured channel accounts to agents now?

지금 바인딩을 확인하면, 마법사는 구성된 각 채널 계정을 어느 에이전트가 소유해야 하는지 묻고 계정 범위 라우팅 바인딩을 씁니다.

나중에 openclaw agents bindings, openclaw agents bind, openclaw agents unbind로도 같은 라우팅 규칙을 관리할 수 있습니다(agents 참조).

단일 계정 최상위 설정을 아직 사용 중인 채널에 기본값이 아닌 계정을 추가하면, OpenClaw는 새 계정을 쓰기 전에 계정 범위 최상위 값을 채널의 계정 맵으로 승격합니다. 대부분의 채널은 해당 값을 channels.<channel>.accounts.default에 배치하지만, 번들 채널은 기존의 일치하는 승격 계정을 대신 보존할 수 있습니다. Matrix가 현재 예입니다. 이름이 지정된 계정이 이미 하나 있거나 defaultAccount가 기존 이름 지정 계정을 가리키면, 승격은 새 accounts.default를 만들지 않고 해당 계정을 보존합니다.

라우팅 동작은 일관되게 유지됩니다.

  • 기존 채널 전용 바인딩(accountId 없음)은 계속 기본 계정과 일치합니다.
  • channels add는 비대화형 모드에서 바인딩을 자동 생성하거나 다시 쓰지 않습니다.
  • 대화형 설정은 선택적으로 계정 범위 바인딩을 추가할 수 있습니다.

구성이 이미 혼합 상태(이름 지정 계정이 있고 최상위 단일 계정 값도 아직 설정됨)였다면, openclaw doctor --fix를 실행하여 계정 범위 값을 해당 채널에 선택된 승격 계정으로 이동하세요. 대부분의 채널은 accounts.default로 승격합니다. Matrix는 기존 이름 지정/기본 대상을 대신 보존할 수 있습니다.

로그인 및 로그아웃(대화형)

openclaw channels login --channel whatsapp
openclaw channels logout --channel whatsapp
  • channels login은 --verbose를 지원합니다.
  • channels login과 logout은 지원되는 로그인 대상이 하나만 구성된 경우 채널을 추론할 수 있습니다.
  • channels logout은 도달 가능한 경우 라이브 Gateway 경로를 선호하므로, 채널 인증 상태를 지우기 전에 활성 리스너를 중지합니다. 로컬 Gateway에 도달할 수 없으면 로컬 인증 정리로 대체됩니다.
  • Gateway 호스트의 터미널에서 channels login을 실행하세요. 에이전트 exec는 이 대화형 로그인 흐름을 차단합니다. whatsapp_login 같은 채널 네이티브 에이전트 로그인 도구를 사용할 수 있으면 채팅에서 사용해야 합니다.

문제 해결

  • 광범위한 프로브에는 openclaw status --deep을 실행하세요.
  • 안내형 수정에는 openclaw doctor를 사용하세요.
  • openclaw channels list가 Claude: HTTP 403 ... user:profile을 출력합니다 → 사용량 스냅샷에 user:profile 범위가 필요합니다. --no-usage를 사용하거나, claude.ai 세션 키(CLAUDE_WEB_SESSION_KEY / CLAUDE_WEB_COOKIE)를 제공하거나, Claude CLI로 다시 인증하세요.
  • Gateway에 도달할 수 없으면 openclaw channels status는 구성 전용 요약으로 대체됩니다. 지원되는 채널 자격 증명이 SecretRef를 통해 구성되었지만 현재 명령 경로에서 사용할 수 없는 경우, 해당 계정을 구성되지 않은 것으로 표시하는 대신 성능 저하 메모와 함께 구성된 것으로 보고합니다.

기능 프로브

정적 기능 지원과 함께 제공자 기능 힌트(사용 가능한 경우 intents/scopes)를 가져옵니다.

openclaw channels capabilities
openclaw channels capabilities --channel discord --target channel:123

참고:

  • --channel은 선택 사항입니다. 생략하면 모든 채널(확장 포함)을 나열합니다.
  • --account는 --channel과 함께만 유효합니다.
  • --target은 channel:<id> 또는 원시 숫자 채널 ID를 허용하며 Discord에만 적용됩니다.
  • 프로브는 제공자별입니다. Discord intents + 선택적 채널 권한, Slack 봇 + 사용자 scopes, Telegram 봇 플래그 + Webhook, Signal 데몬 버전, Microsoft Teams 앱 토큰 + Graph 역할/scopes(알려진 경우 주석 포함). 프로브가 없는 채널은 Probe: unavailable을 보고합니다.

이름을 ID로 확인

제공자 디렉터리를 사용해 채널/사용자 이름을 ID로 확인합니다.

openclaw channels resolve --channel slack "#general" "@jane"
openclaw channels resolve --channel discord "My Server/#support" "@someone"
openclaw channels resolve --channel matrix "Project Room"

참고:

  • 대상 유형을 강제하려면 --kind user|group|auto를 사용하세요.
  • 여러 항목이 같은 이름을 공유하면 확인은 활성 일치를 선호합니다.
  • channels resolve는 읽기 전용입니다. 선택한 계정이 SecretRef를 통해 구성되었지만 해당 자격 증명을 현재 명령 경로에서 사용할 수 없는 경우, 명령은 전체 실행을 중단하지 않고 메모와 함께 성능 저하된 미해결 결과를 반환합니다.
  • channels resolve는 채널 Plugin을 설치하지 않습니다. 설치 가능한 카탈로그 채널의 이름을 확인하기 전에 channels add --channel <name>을 사용하세요.

관련 항목