Linux app

기준일: 2026-07-26
공식 기준: Linux app

Linux app 문서는 OpenClaw 공식 문서(platforms/linux)를 한국어로 정리한 가이드입니다. Linux support + companion app status 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Linux support + companion app status

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

문서 구성

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

• Desktop companion
• Quick Chat
• Canvas
• CLI and SSH alternative
• Node capabilities
• 설치
• Gateway service (systemd)
• Memory pressure and OOM kills
• 관련 문서

상세 내용

본문

The Gateway is fully supported on Linux and requires Node. Bun can still be used as a dependency installer or package-script runner, but it cannot run OpenClaw because it does not provide node:sqlite.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Desktop companion

The OpenClaw Linux companion is a Tauri desktop app for a local Gateway. It:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• installs the OpenClaw CLI and managed Node runtime when they are missing; release builds install the stable channel automatically, while development builds ask for the channel first
• attaches to a healthy Gateway before attempting service changes
• delegates install, start, stop, and restart operations to the CLI-managed systemd user service
• discovers nearby Bonjour Gateways and opens each Control UI in a route-scoped window, so several
• opens the Gateway-served Control UI with its resolved authentication URL
• opens the Control UI in onboarding mode after its first-run install, which
• renders agent-driven Canvas and bundled A2UI content for a colocated CLI node host
• remains available from the system tray when its window is closed

cd apps/linux/src-tauri
pnpm dlx @tauri-apps/cli@2.11.4 build --bundles deb,appimage

Quick Chat

Open Quick Chat with Ctrl+Shift+Space or the Quick Chat tray item. The agent chip shows the configured avatar, emoji, or monogram; select it to switch agents. Messages use the selected agent's main session and honor global session scope. The native Rust client owns a persistent Ed25519 device identity. It uses the CLI handoff's shared token or password only to bootstrap pairing, then stores and prefers the Gateway-issued device token on later connections. The identity and device token live in the app config directory in a mode 0600 file; Quick Chat's WebView receives neither credentials nor the WebSocket.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Canvas

Linux Canvas uses two cooperating processes. openclaw node run remains the single Gateway node connection; the bundled linux-canvas plugin forwards canvas.* calls to the running desktop app over a user-only Unix socket. The app owns one on-demand WebView window, including the bundled A2UI renderer and action bridge back to the agent.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

CLI and SSH alternative

The CLI remains the simplest option for a headless server, a VPS, or a remote Gateway:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Node capabilities

The bundled Linux Node plugin gives the CLI openclaw node service device capabilities without requiring the desktop app. Commands are advertised to the Gateway only when their capability is enabled and the required local tool exists.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Capability	Default	Requirement
Desktop notifications (system.notify)	On	notify-send from libnotify and a desktop notification session
Camera photos and clips (camera.*)	Off	FFmpeg, V4L2 camera access, and PulseAudio or PipeWire for clip audio
Location (location.get)	Off	GeoClue2 and its where-am-i demo

{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          notify: { enabled: true },
          camera: { enabled: true },
          location: { enabled: true },
        },
      },
    },
  },
}

openclaw nodes pending
openclaw nodes approve <requestId>

설치

주요 항목:

• Getting Started
• Install & updates
• 선택: Bun package workflow, Nix, Docker

Gateway service (systemd)

openclaw gateway install renders a systemd user unit by default. Full service guidance, including the system-level unit variant for shared or always-on hosts, lives in the Gateway runbook.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw onboard --install-daemon
openclaw gateway install
openclaw configure   # select "Gateway service" when prompted

openclaw doctor

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
StartLimitBurst=5
StartLimitIntervalSec=60

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=control-group

[Install]
WantedBy=default.target

systemctl --user enable --now openclaw-gateway[-<profile>].service

Memory pressure and OOM kills

On Linux, the kernel picks an OOM victim when a host, VM, or container cgroup runs out of memory. The Gateway is a poor victim because it owns long-lived sessions and channel connections, so OpenClaw biases transient child processes to be killed first when possible.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Supervisor-managed command children
• PTY shell children
• MCP stdio server children
• OpenClaw-launched browser/Chrome processes (via the plugin SDK process runtime)

cat /proc/<child-pid>/oom_score_adj

관련 문서

주요 항목:

• Install overview
• Linux server
• Raspberry Pi
• Gateway runbook
• Gateway configuration

실습 체크리스트

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

자주 쓰는 명령·설정 예시

cd apps/linux/src-tauri
pnpm dlx @tauri-apps/cli@2.11.4 build --bundles deb,appimage

{
  plugins: {
    entries: {
      "linux-node": {
        config: {
          notify: { enabled: true },
          camera: { enabled: true },
          location: { enabled: true },
        },
      },
    },
  },
}

openclaw nodes pending
openclaw nodes approve <requestId>

openclaw onboard --install-daemon
openclaw gateway install
openclaw configure   # select "Gateway service" when prompted

openclaw doctor

[Unit]
Description=OpenClaw Gateway (profile: <profile>, v<version>)
After=network-online.target
Wants=network-online.target
StartLimitBurst=5
StartLimitIntervalSec=60

[Service]
ExecStart=/usr/local/bin/openclaw gateway --port 18789
Restart=always
RestartSec=5
RestartPreventExitStatus=78
TimeoutStopSec=30
TimeoutStartSec=30
SuccessExitStatus=0 143
OOMPolicy=continue
KillMode=control-group

[Install]
WantedBy=default.target

관련 링크

• 공식 원문: platforms/linux
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.