메인 콘텐츠로 건너뛰기

​
openclaw node

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

​
노드 호스트를 사용하는 이유?

노드 호스트를 사용하면 에이전트가 전체 macOS 동반 앱을 설치하지 않고 네트워크 내의 다른 머신에서 명령어를 실행할 수 있습니다. 일반적인 사용 사례:
  • 원격 Linux/Windows 서버(빌드 서버, 연구실 머신, NAS)에서 명령어 실행.
  • 실행을 게이트웨이에서 샌드박스 격리한 상태로 유지하면서 승인된 실행을 다른 호스트에 위임.
  • 자동화 또는 CI 노드를 위한 가볍고 헤드리스 실행 타겟 제공.
실행은 여전히 노드 호스트의 실행 승인과 에이전트별 허용 목록으로 보호되므로, 명령 액세스를 범위 지정하고 명확하게 유지할 수 있습니다.

​
브라우저 프록시 (제로 구성)

노드 호스트는 browser.enabled 가 노드에서 비활성화되지 않은 경우 자동으로 브라우저 프록시를 광고합니다. 이를 통해 에이전트는 추가 구성 없이 해당 노드에서 브라우저 자동화를 사용할 수 있습니다. 필요할 경우 노드에서 비활성화하세요: 
{
  nodeHost: {
    browserProxy: {
      enabled: false,
    },
  },
}

​
실행 (포그라운드)

openclaw node run --host <gateway-host> --port 18789
옵션:
  • --host <host>: 게이트웨이 WebSocket 호스트 (기본값: 127.0.0.1)
  • --port <port>: 게이트웨이 WebSocket 포트 (기본값: 18789)
  • --tls: 게이트웨이 연결에 TLS 사용
  • --tls-fingerprint <sha256>: 예상 TLS 인증서 지문 (sha256)
  • --node-id <id>: 노드 id 재정의 (페어링 토큰 삭제)
  • --display-name <name>: 노드 표시 이름 재정의

​
서비스 (백그라운드)

헤드리스 노드 호스트를 사용자 서비스로 설치합니다. 
openclaw node install --host <gateway-host> --port 18789
옵션:
  • --host <host>: 게이트웨이 WebSocket 호스트 (기본값: 127.0.0.1)
  • --port <port>: 게이트웨이 WebSocket 포트 (기본값: 18789)
  • --tls: 게이트웨이 연결에 TLS 사용
  • --tls-fingerprint <sha256>: 예상 TLS 인증서 지문 (sha256)
  • --node-id <id>: 노드 id 재정의 (페어링 토큰 삭제)
  • --display-name <name>: 노드 표시 이름 재정의
  • --runtime <runtime>: 서비스 런타임 (node 또는 bun)
  • --force: 이미 설치된 경우 재설치/덮어쓰기
서비스 관리: 
openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall
포그라운드 노드 호스트(서비스 없음)에는 openclaw node run을 사용합니다. 서비스 명령어는 머신 판독 가능한 출력용으로 --json을 허용합니다. 인증 해석:
  • 먼저 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD를 확인합니다.
  • 그다음 로컬 config fallback인 gateway.auth.token / gateway.auth.password를 확인합니다.
  • 로컬 모드에서 node host는 의도적으로 gateway.remote.token / gateway.remote.password를 상속하지 않습니다.
  • gateway.auth.token / gateway.auth.password가 SecretRef로 명시적으로 구성되어 있는데 해석되지 않으면, node 인증 해석은 fail-closed 됩니다 (원격 fallback으로 가리지 않음).
  • gateway.mode=remote에서는 원격 우선순위 규칙에 따라 gateway.remote.token / gateway.remote.password가 참여합니다.
  • 레거시 CLAWDBOT_GATEWAY_* 환경 변수는 node host 인증 해석에서 무시됩니다.

​
페어링

첫 연결은 게이트웨이에 보류 중인 장치 페어링 요청(role: node)을 생성합니다. 다음을 통해 승인하세요: 
openclaw devices list
openclaw devices approve <requestId>
노드 호스트는 ~/.openclaw/node.json에 노드 id, 토큰, 표시 이름 및 게이트웨이 연결 정보를 저장합니다.

​
실행 승인

system.run은 로컬 실행 승인으로 보호됩니다:
  • ~/.openclaw/exec-approvals.json
  • 실행 승인
  • openclaw approvals --node <id|name|ip> (게이트웨이에서 편집)