중급5분 소요openclawclinode

Node

Node 문서는 OpenClaw 공식 문서(cli/node)를 한국어로 정리한 가이드입니다. CLI reference for openclaw node (headless node host) 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

CLI reference for openclaw node (headless node host)

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

문서 구성

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

Why use a node host?
Browser proxy (zero-config)
Run (foreground)
Gateway auth for node host
Service (background)
페어링
Identity and pairing state
Exec approvals
관련 문서

상세 내용

openclaw node

Run a headless node host that connects to the Gateway WebSocket and exposes system.run / system.which on this machine.

Why use a node host?

Use a node host when you want agents to run commands on other machines in your network without installing a full macOS companion app there.

주요 항목:

Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
Keep exec sandboxed on the gateway, but delegate approved runs to other hosts.
Provide a lightweight, headless execution target for automation or CI nodes.

Browser proxy (zero-config)

Node hosts automatically advertise a browser proxy if browser.enabled is not disabled on the node. This lets the agent use browser automation on that node without extra configuration.

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

Run (foreground)

주요 항목:

--host <host>: Gateway WebSocket host (default: 127.0.0.1)
--port <port>: Gateway WebSocket port (default: 18789)
--context-path <path>: Gateway WebSocket context path (e.g. /openclaw-gw). Appended to the WebSocket URL.
--tls: Use TLS for the gateway connection
--no-tls: Force a plaintext Gateway connection even when the local Gateway config enables TLS
--tls-fingerprint <sha256>: Expected TLS certificate fingerprint (sha256)
--node-id <id>: Override the client instance ID stored in shared SQLite state (does not reset pairing)
--display-name <name>: Override the node display name

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

Gateway auth for node host

openclaw node run and openclaw node install resolve gateway auth from config/env (no --token/--password flags on node commands):

주요 항목:

OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD are checked first.
Then local config fallback: gateway.auth.token / gateway.auth.password.
In local mode, node host intentionally does not inherit gateway.remote.token / gateway.remote.password.
If gateway.auth.token / gateway.auth.password is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
In gateway.mode=remote, remote client fields (gateway.remote.token / gateway.remote.password) are also eligible per remote precedence rules.
Node host auth resolution only honors OPENCLAW_GATEWAY_* env vars.

Service (background)

Install a headless node host as a user service (launchd on macOS, systemd on Linux, Windows Task Scheduler on Windows).

주요 항목:

--host <host>: Gateway WebSocket host (default: 127.0.0.1)
--port <port>: Gateway WebSocket port (default: 18789)
--context-path <path>: Gateway WebSocket context path (e.g. /openclaw-gw). Appended to the WebSocket URL.
--tls: Use TLS for the gateway connection
--tls-fingerprint <sha256>: Expected TLS certificate fingerprint (sha256)
--node-id <id>: Override the client instance ID stored in shared SQLite state (does not reset pairing)
--display-name <name>: Override the node display name
--runtime <runtime>: Service runtime (node)
--force: Reinstall/overwrite if already installed

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

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

페어링

The first connection creates a pending device pairing request (role: node) on the Gateway.

openclaw devices list
openclaw devices approve <requestId>

openclaw node identity --json

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Identity and pairing state

The headless node separates its client instance ID from the signed device identity that the Gateway uses for pairing and routing. This state lives in the OpenClaw state directory (~/.openclaw by default, or $OPENCLAW_STATE_DIR when set):

State	Purpose
`state/openclaw.sqlite` (`node_host_config`)	Client instance ID, display name, and Gateway connection metadata. The client sends this ID as `instanceId`.
`state/openclaw.sqlite` (`device_identities`, `primary`)	Signed Ed25519 keypair and derived device ID. For signed connections, this device ID is the routed node ID and pairing identity.
`state/openclaw.sqlite` (`device_auth_tokens`)	Paired device tokens, keyed by cryptographic device ID and role.

Exec approvals

system.run is gated by local exec approvals:

주요 항목:

$OPENCLAW_STATE_DIR/exec-approvals.json, or
Exec approvals
openclaw approvals --node <id|name|ip> (edit from the Gateway)

실습 체크리스트

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

자주 쓰는 명령·설정 예시

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

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

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

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

openclaw devices list
openclaw devices approve <requestId>

openclaw node identity --json

Node

핵심 요약

CLI reference for openclaw node (headless node host)

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

문서 구성

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

Why use a node host?
Browser proxy (zero-config)
Run (foreground)
Gateway auth for node host
Service (background)
페어링
Identity and pairing state
Exec approvals
관련 문서

상세 내용

openclaw node

Run a headless node host that connects to the Gateway WebSocket and exposes system.run / system.which on this machine.

Why use a node host?

Use a node host when you want agents to run commands on other machines in your network without installing a full macOS companion app there.

주요 항목:

Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
Keep exec sandboxed on the gateway, but delegate approved runs to other hosts.
Provide a lightweight, headless execution target for automation or CI nodes.

Browser proxy (zero-config)

Node hosts automatically advertise a browser proxy if browser.enabled is not disabled on the node. This lets the agent use browser automation on that node without extra configuration.

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

Run (foreground)

주요 항목:

--host <host>: Gateway WebSocket host (default: 127.0.0.1)
--port <port>: Gateway WebSocket port (default: 18789)
--context-path <path>: Gateway WebSocket context path (e.g. /openclaw-gw). Appended to the WebSocket URL.
--tls: Use TLS for the gateway connection
--no-tls: Force a plaintext Gateway connection even when the local Gateway config enables TLS
--tls-fingerprint <sha256>: Expected TLS certificate fingerprint (sha256)
--node-id <id>: Override the client instance ID stored in shared SQLite state (does not reset pairing)
--display-name <name>: Override the node display name

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

Gateway auth for node host

openclaw node run and openclaw node install resolve gateway auth from config/env (no --token/--password flags on node commands):

주요 항목:

OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD are checked first.
Then local config fallback: gateway.auth.token / gateway.auth.password.
In local mode, node host intentionally does not inherit gateway.remote.token / gateway.remote.password.
If gateway.auth.token / gateway.auth.password is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
In gateway.mode=remote, remote client fields (gateway.remote.token / gateway.remote.password) are also eligible per remote precedence rules.
Node host auth resolution only honors OPENCLAW_GATEWAY_* env vars.

Service (background)

Install a headless node host as a user service (launchd on macOS, systemd on Linux, Windows Task Scheduler on Windows).

주요 항목:

--host <host>: Gateway WebSocket host (default: 127.0.0.1)
--port <port>: Gateway WebSocket port (default: 18789)
--context-path <path>: Gateway WebSocket context path (e.g. /openclaw-gw). Appended to the WebSocket URL.
--tls: Use TLS for the gateway connection
--tls-fingerprint <sha256>: Expected TLS certificate fingerprint (sha256)
--node-id <id>: Override the client instance ID stored in shared SQLite state (does not reset pairing)
--display-name <name>: Override the node display name
--runtime <runtime>: Service runtime (node)
--force: Reinstall/overwrite if already installed

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

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

페어링

The first connection creates a pending device pairing request (role: node) on the Gateway.

openclaw devices list
openclaw devices approve <requestId>

openclaw node identity --json

{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}

Identity and pairing state

State	Purpose
`state/openclaw.sqlite` (`node_host_config`)	Client instance ID, display name, and Gateway connection metadata. The client sends this ID as `instanceId`.
`state/openclaw.sqlite` (`device_identities`, `primary`)	Signed Ed25519 keypair and derived device ID. For signed connections, this device ID is the routed node ID and pairing identity.
`state/openclaw.sqlite` (`device_auth_tokens`)	Paired device tokens, keyed by cryptographic device ID and role.

Exec approvals

system.run is gated by local exec approvals:

주요 항목:

$OPENCLAW_STATE_DIR/exec-approvals.json, or
Exec approvals
openclaw approvals --node <id|name|ip> (edit from the Gateway)

실습 체크리스트

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

자주 쓰는 명령·설정 예시

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

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

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

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

openclaw devices list
openclaw devices approve <requestId>

openclaw node identity --json

Node

핵심 요약

문서 구성

상세 내용

openclaw node

Why use a node host?

Browser proxy (zero-config)

Run (foreground)

Gateway auth for node host

Service (background)

페어링

Identity and pairing state

Exec approvals

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Node

핵심 요약

문서 구성

상세 내용

openclaw node

Why use a node host?

Browser proxy (zero-config)

Run (foreground)

Gateway auth for node host

Service (background)

페어링

Identity and pairing state

Exec approvals

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드