faq
OpenClaw CLI로 처음 서브에이전트를 실행하기 전 반드시 확인해야 할 환경 설정 &
자주 묻는 질문
빠른 답변
OpenClaw CLI로 처음 서브에이전트를 실행하려면 먼저 Node.js v18 이상과 npm/yarn이 설치되어 있는지 확인한 뒤, 반드시 openclaw gateway start 명령으로 Gateway를 먼저 시작하고 그다음 openclaw agent --agent codex --message 명령으로 첫 번째 에이전트를 호출하는 2단계 순서를 따라야 합니다. Gateway가 미실행 상태에서 에이전트를 호출하면 WebSocket 연결 실패가 발생하므로 이 순서를 정확히 따르면 첫 코딩 위임이 즉시 성공하며, session-target 옵션을 활용하면 용도에 따라 유연하게 세션을 관리할 수 있습니다.
OpenClaw CLI 설치 전 필수 사전 조건: Node.js와 npm/yarn 환경 확인
OpenClaw CLI를 처음 설치하고 실행하기 전에 반드시 확인해야 할 가장 기본적인 사전 조건은 시스템에 Node.js v18 이상의 런타임과 npm 또는 yarn 패키지 매니저가 제대로 설치되어 있는지를 검증하는 과정입니다. Node.js가 설치되어 있지 않거나 버전이 낮으면 openclaw gateway start 명령이나 openclaw agent 서브에이전트 호출 명령 모두 정상적으로 동작하지 않으므로, 이는 서브에이전트를 실행하기 전 반드시 선행해야 할 가장 기본적이고 필수적인 사전 조건입니다. 터미널에서 node --version과 npm --version 또는 yarn --version 명령을 실행하여 현재 설치된 버전을 확인하고, 버전이 낮다면 먼저 Node.js를 설치해야 합니다.
Gateway 먼저 실행이 핵심: 2단계 패턴의 올바른 순서 이해하기
OpenClaw의 표준 실행 순서는 반드시 openclaw gateway start 명령으로 Gateway를 먼저 시작한 뒤에, 그 다음 단계로 openclaw agent --agent codex --message 명령을 사용하여 서브에이전트를 호출하는 2단계 패턴을 반드시 따라야 합니다. 이 순서를 뒤바꾸거나 건너뛰고 바로 에이전트를 호출하면 WebSocket 연결 실패 오류가 발생합니다. Gateway는 모든 세션 상태를 소유하고 관리하는 중앙 집중식 런타임으로, WebSocket 서버로 동작하여 모든 서브에이전트 연결을 중계하므로 Gateway가 미실행 상태에서의 에이전트 호출은 구조적으로 실패할 수밖에 없습니다. 따라서 첫 번째 코딩 위임을 성공적으로 수행하려면 반드시 이 순서 패턴을 정확히 이해하고 따르는 것이 중요합니다.
child_process.spawn과 실시간 피드백 루프가 만드는 즉각적 개발 경험
Node.js child_process.spawn의 비동기 스트리밍 출력 기능은 서브에이전트 풀이 코딩 위임의 실시간성을 보장하는 핵심적인 기술적 기반입니다. 이 구조를 통해 에이전트의 실행 결과를 실시간으로 스트리밍하여 빌드 에러나 진행 상황을 수 밀리초 단위로 확인하고 방향을 조정할 수 있으며, 이는 코드가 완성될 때까지 기다리지 않아도 되는 바이브코딩의 즉각적 피드백 경험을 가능하게 하는 핵심 메커니즘입니다. codex, visionary, coder, tester 등 각 전문 에이전트가 자신의 영역에만 집중하므로 단일 AI 대비 전체 코딩 처리량이 비약적으로 향상되며, 이는 바이브코딩이 단순한 유행어가 아니라 지금 당장 실행 가능한 패러다임임을 보여주는 핵심 증거입니다.
서브에이전트 호출 기본 문법과 session-target 옵션으로 유연하게 활용하기
서브에이전트 호출의 기본 문법은 openclaw agent --agent codex --message "<작업_지시>"로, codex 에이전트가 첫 번째 진입점이 됩니다. 이 한 줄의 명령만으로 코딩 작성 역할을 AI 에이전트에게 직접 이전할 수 있으며, 개발자의 역할은 의도 전달과 방향 조율로 한정되어 코딩 구현이 아닌 고수준 조율에 집중하는 바이브코딩의 패러다임을 체감하게 하는 핵심 순간입니다. OpenClaw CLI는 session-target(main/isolated/current) 옵션으로 실행 환경을 지정할 수 있어, 메인 세션에서는 장기 프로젝트를 관리하고 격리된 세션에서는 단일 태스크를 수행하고 현재 활성 세션은 전환하는 등 용도에 따른 유연한 세션 관리가 가능하며, Gateway가 모든 세션 상태를 소유하고 관리하므로 연결된 클라이언트는 지속적인 컨텍스트를 유지할 수 있습니다.
> 이 주제의 전체 맥락 방향성은 **바이브코딩에서 오픈클로까지** 원본 글에 세밀하게 정리되어 있습니다. 더 깊게 탐구하고 싶다면 관련 내부 대표 문서(Pillar/Entity)를 참조하세요.
관련 분석
ACP 영속화가 바이브코딩 세션의 컨텍스트 분열을 방지하는 구조적 원리OpenClaw 의 ACP 런타임은 sessionKey 를 파일로 영구 저장하여 재연결 시 이전 컨텍스트를 로드하고 복원한다. 주요 변수와 진행 중인 작업을 memory/*.md 혹은 MEMORY.md 에 주기적으로오픈클로 에이전트 오케스트레이션 구조와 전통 IDE 비교 분석OpenClaw는 Gateway가 로컬 127.0.0.1:18789에서 WebSocket 서버로 동작해 모든 채널을 단일 제어 평면에서 라우팅하고, auth‑profiles.json을 통해 인증 정보를 공유하여 보안바이브코딩의 컨텍스트 분열을 막는 OpenClaw 의 6 대 기술 원리와 ACP 영속화 아키텍처OpenClaw 는 ContextEngine 의 4 단계 라이프사이클 훅과 ACP SQLite 제어면을 통해 바이브코딩 세션의 컨텍스트 분열을 구조적으로 방지한다. 서브에이전트 종료 시 부모 컨텍스트를 자동 복원하는OpenClaw ContextEngine 라이프사이클 훅이 바이브코딩 세션의 컨텍스트 분열을 방지하는 원리OpenClaw ContextEngine은 라이프사이클 훅 프레임워크를 통해 서브에이전트 간 컨텍스트 생성·병합·복원·스냅샷 시점을 중앙 조율하여, 바이브코딩 세션에서 발생하는 컨텍스트 분열을 자동으로 감지하고 롤백execFileAsync와 spawn의 이중 실행 모드가 바이브코딩 피드백 루프를 어떻게 형성하는가Node.js에서 execFileAsync는 Promise 기반 비동기 실행, spawn은 스트림 기반 실시간 출력을 제공한다. 두 API를 병행하면 병렬 검증을 가능하고, stdout·stderr를 독립 수집해 피