Embedding OpenClaw

기준일: 2026-07-26
공식 기준: Embedding OpenClaw

Embedding OpenClaw 문서는 OpenClaw 공식 문서(gateway/embedding)를 한국어로 정리한 가이드입니다. Supervise the OpenClaw Gateway as a child process from Electron or another host app 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Supervise the OpenClaw Gateway as a child process from Electron or another host app

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

문서 구성

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

• Start the child with an embedding preset
• Electron shell snapshot warning
• Handle invalid config by exit code
• Wait for protocol readiness
• Interpret restart and shutdown
• Use RPC instead of state files
• Install; do not flatten
• 관련 문서

상세 내용

본문

An embedding host should supervise the installed openclaw executable, use the Gateway WebSocket protocol as its control plane, and treat the child process as a replaceable runtime. This keeps process ownership, readiness, failure recovery, and upgrades explicit without depending on OpenClaw's private state layout.

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

Start the child with an embedding preset

Use a real node_modules installation and spawn the package executable. A useful baseline for a host that owns discovery, restart, and channel lifecycle is:

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

Setting	Embedding effect
OPENCLAW_DISABLE_BONJOUR=1	Disables Gateway-owned LAN multicast advertising when the host owns discovery.
OPENCLAW_NO_RESPAWN=1	In an unmanaged embedding child, prevents OpenClaw from handing an update restart to a detached child. Routine restarts remain in process, so the host keeps ownership of the tracked PID.
OPENCLAW_EXEC_SHELL_SNAPSHOT=0	Disables login-shell snapshot capture for host exec commands.
OPENCLAW_SKIP_CHANNELS=1	Skips channel startup and reload. Set it only when the embedding app wants a control-plane or WebChat-only Gateway.

// Supply an absolute path to a real Node runtime managed by the host application.
declare const hostNodeExecutable: string;

const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));
const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");
const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {
  env: {
    ...process.env,
    OPENCLAW_DISABLE_BONJOUR: "1",
    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",
    OPENCLAW_NO_RESPAWN: "1",
    OPENCLAW_SKIP_CHANNELS: "1",
  },
  stdio: ["ignore", "inherit", "inherit"],
});

Electron shell snapshot warning

Shell snapshot capture runs process.execPath -e from a login shell. In a normal Node process, process.execPath is the Node executable. Under Electron, it is the Electron binary, which can interpret the invocation as an application launch and show an "Unable to find Electron app" popup. Set OPENCLAW_EXEC_SHELL_SNAPSHOT=0 in the Gateway child's environment, not only in the renderer process. For the same reason, hostNodeExecutable must point to a real Node runtime rather than Electron's process.execPath.

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

Handle invalid config by exit code

Gateway startup uses exit code 78 (EX_CONFIG) for configuration-class startup failures, including an invalid config. Branch on the exit code instead of scraping human-readable stderr:

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

Wait for protocol readiness

Use WebSocket signals instead of a log substring:

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

Interpret restart and shutdown

Before an orderly close, the Gateway broadcasts a shutdown event with reason and restartExpectedMs. A non-null restartExpectedMs means an in-process or supervised restart is expected; null means a terminal shutdown.

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

Use RPC instead of state files

Keep the Gateway as the only owner of OpenClaw state. Common embedding operations already have RPC methods:

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

Task	RPC methods
Session catalog and lifecycle	sessions.list, sessions.patch, sessions.delete
Transcript display	chat.history
Cost and usage reports	usage.cost, sessions.usage
Model credential status	models.authStatus
Configuration	config.get, config.patch

Install; do not flatten

The root openclaw package is not a single-file vendoring target. Bundled runtime files under dist/extensions retain bare self-imports such as openclaw/plugin-sdk/*, while the npm package intentionally excludes per-extension node_modules trees.

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

관련 문서

주요 항목:

• Building a Gateway client
• Gateway protocol
• Gateway CLI
• Gateway integrations for external apps

실습 체크리스트

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

자주 쓰는 명령·설정 예시

// Supply an absolute path to a real Node runtime managed by the host application.
declare const hostNodeExecutable: string;

const packageEntry = fileURLToPath(import.meta.resolve("openclaw"));
const openclawEntry = resolve(dirname(packageEntry), "..", "openclaw.mjs");
const gateway = spawn(hostNodeExecutable, [openclawEntry, "gateway", "--allow-unconfigured"], {
  env: {
    ...process.env,
    OPENCLAW_DISABLE_BONJOUR: "1",
    OPENCLAW_EXEC_SHELL_SNAPSHOT: "0",
    OPENCLAW_NO_RESPAWN: "1",
    OPENCLAW_SKIP_CHANNELS: "1",
  },
  stdio: ["ignore", "inherit", "inherit"],
});

관련 링크

• 공식 원문: gateway/embedding
• OpenClaw 문서 홈

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