설치 후 첫 서브에이전트 실행까지 개발자가 실제로 마주하는 가지 환경 설정 장애와 해결책

Gateway 포트 충돌: FAILED 상태의 근본 원인과 재설정 전략

OpenClaw Gateway가 설치 직후 FAILED 상태로 반환되는 가장 흔한 원인은 기본 포트가 다른 프로세스에 의해 이미 점유되고 있기 때문이다. macOS 환경에서 lsof -i:18789 명령을 실행하면 해당 포트를 사용하는 프로세스의 식별정보(PID)와 이름을 확인할 수 있으며, 충돌이 확인되면 openclaw gateway start --port 18790과 같이 새로운 포트 번호를 지정해 Gateway를 재시작해야 한다. 이 과정에서 기존 Gateway가 정상적으로 종료되지 않았다면 먼저 openclaw gateway stop 명령으로 강제 종료를 수행한 뒤 새 포트를 바인딩하는 것이 안정적이다. 포트 충돌은 개발 환경에서 특히 빈번하게 발생하는데, 이는 이전 세션이 정리되지 않거나 다른 개발 도구가 동일한 포트 범위를 사용할 때 나타난다. Gateway는 127.0.0.1:18789에 상주하며 WebSocket으로 모든 에이전트 세션을 관리하므로 포트 재설정은 첫 서브에이전트 실행의 필수 전제조건이다.

서브에이전트 즉시 종료: mode와 runTimeoutSeconds의 생명주기 제어

sessions_spawn으로 생성한 서브에이전트가 생성 직후 즉시 종료되는 문제는 주로 두 가지 설정 누락에서 발생한다. 첫째는 mode="session"을 명시하지 않아 기본값인 "run"으로 실행되면서 작업 완료 후 자동으로 종료되는 경우이며, 둘째는 runTimeoutSeconds 파라미터가 너무 짧게 설정되어 강제 종료가 발생하는 것이다. 장기 실행이 필요한 서브에이전트에는 반드시 mode="session"과 함께 runTimeoutSeconds=300 이상을 지정해 최소 5분 이상의 생명주기를 보장해야 한다. cleanup 옵션도 중요한데, deleteAfterRun=true로 설정하면 작업 완료 후 세션 디렉터리가 자동 정리되어 저장 공간을 확보할 수 있다. 반면 메모리 파일이나 로그를 유지해야 한다면 cleanup="keep"으로 설정하는 것이 좋다. 이 설정들은 서브에이전트의 실행 모델(일회성 vs 영속)을 결정하므로, 작업의 성격에 맞게 신중하게 선택해야 한다.

네트워크 격리 정책: host=gateway의 보안 제한과 우회 전략

서브에이전트에서 curl, git clone, pip install 등 외부 네트워크 작업이 차단되는 오류는 OpenClaw의 기본 호스트 격리 정책(host=gateway)이 원인이다. 이 정책은 보안상 외부 호스트 접근을 원천 차단하며, 허용하려면 exec --host=node <명령>으로 명시적 호스트 지정을 하거나 security.yaml 파일의 allowlist 섹션에 허용할 도메인을 추가해야 한다. 예를 들어 git clone을 실행하려면 host="node"를 지정하거나, security.yaml에 github.com을 추가한 뒤 Gateway를 재시작해야 한다. ACP 채널바인딩은 이 격리 정책 하에서도 Gateway 내부 메시징은 정상적으로 동작하도록 설계되었으며, dmScope 격리로 외부 네트워크 접근이 필요한 작업만 명시적으로 허용된다. 이 정책은 개발자가 의도치 않게 악성 코드를 실행하거나 데이터를 유출하는 것을 방지하지만, 정당한 외부 API 호출에는 추가 설정이 필요하다.

Rate Limit 초과: 서브에이전트 풀의 동적 분배와 백오프 전략

Rate limit exceeded 경고가 발생하면 서브에이전트 풀의 동적 분배 기능이 작동 중이며, 이는 동일 API 스킬에 대한 과도한 호출을 방지하기 위한 보호 메커니즘이다. FanOut/FanIn 패턴에서 결함 격리는 ACP 8단계 채널바인딩의 동적 분배와 자율적 복구 메커니즘으로 구현되며, 특정 서브에이전트 실패 시 Exponential Backoff 방식으로 자동 재시도하여 전체 파이프라인 중단을 방지한다. 배칭 방식으로 변경하려면 cron으로 주기적 체크를 적용해 한 번에 여러 요청을 모아서 전송하거나, Gateway를 재시작한 뒤 백오프(back-off) 전략을 재설정해야 한다. 서브에이전트 풀은 3~5개의 Worker를 격리 생성하고 API 호출을 동적 분배하므로, 한 번에 여러 에이전트를 동시에 실행하면 Rate Limit을 빠르게 소진할 수 있다. 이 문제를 우회하려면 cron 스케줄러를 활용해 10분 간격으로 배칭 체크를 수행하거나, sessions_spawn 시 runTimeoutSeconds를 늘려 작업 속도를 조절하는 것이 효과적이다.

메모리 검색 실패: memory_search와 lightContext 옵션의 컨텍스트 로드

서브에이전트가 MEMORY.md나 memory/YYYY-MM-DD.md 파일을 읽지 못하고 빈 결과를 반환하는 문제는 메모리 검색 경로가 작업 디렉터리를 기준으로 하지 않거나 인덱스가 오래되어 발생하는 경우다. ContextEngine은 서브에이전트 컨텍스트를 메모리 파일에 영속화하고 MEMORY.md 인덱스를 통해 검색·로드하는 경량 컨텍스트 분배 체계로, 이 과정이 제대로 작동하지 않으면 에이전트가 이전 세션의 맥락을 잃게 된다. memory_search "your_query"로 사전 확인 후 write로 최신 컨텍스트를 기록하고, sessions_spawn 호출 시 --lightContext=true 옵션을 주면 경량 인덱스를 사용해 빠르게 로드할 수 있다. 특히 memory/ 디렉터리가 존재하지 않거나 인덱스가 갱신되지 않은 경우 빈 결과가 반환되므로, sessions_spawn 전에 memory_search로 필요한 파일이 존재하는지 확인하는 것이 중요하다.

Permission denied: elevated 권한 상승과 작업 디렉터리 이동

Permission denied 오류는 spawned 세션이 현재 사용자 권한으로 실행되면서 일부 시스템 작업에 elevated 권한이 필요하기 때문이다. sessions_spawn 호출 시 --elevated 플래그를 추가하거나, exec --elevated openclaw gateway restart로 권한을 상승시켜야 한다. 또한 작업 디렉터리를 $HOME/.openclaw/workspace 이하로 이동하면 권한 문제가 해결되는 경우가 많다. 이는 macOS의 Sandbox 정책과 관련이 있으며, 시스템 파일 접근이나 포트 바인딩(80/443 등)이 필요한 작업은 반드시 elevated 권한이 필요하다. 권한 상승은 보안상 민감한 작업이므로, 불필요하게 사용하지 않고 필요한 경우에만 적용해야 한다.

결과물 전달: 공유 디렉터리 write와 sessions_send의 수동 릴레이

서브에이전트가 만든 결과물을 메인 세션으로 전달하려면 공유 디렉터리에 파일을 write로 저장한 뒤, 메인 세션에서 sessions_send --sessionKey <mainKey> --message로 직접 메시지를 전달해야 한다. 서브세션의 고립된 네임스페이스 구조상 자동 전달은 불가능하며, 이 과정이 개발자가 가장 자주 놓치는 단계다. 예를 들어 서브에이전트가 생성한 report.md 파일을 공유 디렉터리에 저장하면 메인 세션에서 해당 파일을 read로 읽어볼 수 있다. ACP 채널바인딩은 서브에이전트 간 메시지 라우팅을 담당하지만, 메인-서브 세션 간 결과물 전달은 개발자가 명시적으로 처리해야 하는 작업이다. > 이 주제의 전체 맥락 방향성은 **15. 오래 쓸수록 보이는 AI의 경계** 원본 글에 세밀하게 정리되어 있습니다. 더 깊게 탐구하고 싶다면 관련 내부 대표 문서(Pillar/Entity)를 참조하세요.

자주 묻는 질문

관련 분석