openclaw node

Gateway WebSocket에 연결하고 이 머신에서 system.run / system.which를 노출하는 헤드리스 node host를 실행합니다.

Node host를 사용하는 이유?

agent가 전체 macOS companion app을 설치하지 않고도 네트워크의 다른 머신에서 명령을 실행하도록 하려면 node host를 사용합니다.

일반적인 사용 사례:

  • 원격 Linux/Windows 머신에서 명령 실행 (빌드 서버, 랩 머신, NAS).
  • gateway에서 exec을 샌드박스 상태로 유지하되, 승인된 실행을 다른 host에 위임.
  • 자동화 또는 CI node를 위한 경량의 헤드리스 실행 대상 제공.

실행은 여전히 node host의 exec 승인 및 agent별 allowlist에 의해 보호되므로, 명령 액세스 범위를 명시적으로 유지할 수 있습니다.

Browser proxy (제로 구성)

Node host는 node에서 browser.enabled가 비활성화되지 않은 경우 자동으로 browser proxy를 광고합니다. 이를 통해 agent는 추가 구성 없이 해당 node에서 browser 자동화를 사용할 수 있습니다.

필요한 경우 node에서 비활성화하세요:

{
  nodeHost: {
    browserProxy: {
      enabled: false
    }
  }
}

Run (포그라운드)

openclaw node run --host <gateway-host> --port 18789

옵션:

  • --host <host>: Gateway WebSocket host (기본값: 127.0.0.1)
  • --port <port>: Gateway WebSocket port (기본값: 18789)
  • --tls: gateway 연결에 TLS 사용
  • --tls-fingerprint <sha256>: 예상되는 TLS 인증서 지문 (sha256)
  • --node-id <id>: node id 재정의 (페어링 token 지움)
  • --display-name <name>: node 표시 이름 재정의

Service (백그라운드)

헤드리스 node host를 사용자 서비스로 설치합니다.

openclaw node install --host <gateway-host> --port 18789

옵션:

  • --host <host>: Gateway WebSocket host (기본값: 127.0.0.1)
  • --port <port>: Gateway WebSocket port (기본값: 18789)
  • --tls: gateway 연결에 TLS 사용
  • --tls-fingerprint <sha256>: 예상되는 TLS 인증서 지문 (sha256)
  • --node-id <id>: node id 재정의 (페어링 token 지움)
  • --display-name <name>: node 표시 이름 재정의
  • --runtime <runtime>: 서비스 런타임 (node 또는 bun)
  • --force: 이미 설치된 경우 재설치/덮어쓰기

서비스 관리:

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

포그라운드 node host는 openclaw node run을 사용합니다 (서비스 없음).

서비스 명령은 머신 읽기 가능한 출력을 위해 --json을 허용합니다.

페어링

첫 번째 연결은 Gateway에서 보류 중인 node 페어 요청을 생성합니다. 다음을 통해 승인하세요:

openclaw nodes pending
openclaw nodes approve <requestId>

Node host는 node id, token, 표시 이름 및 gateway 연결 정보를 ~/.openclaw/node.json에 저장합니다.

Exec 승인

system.run은 로컬 exec 승인에 의해 제어됩니다:

  • ~/.openclaw/exec-approvals.json
  • Exec approvals
  • openclaw approvals --node <id|name|ip> (Gateway에서 편집)
← 문서로 돌아가기