AiClaw의 최신 로컬 런타임 작업은 자체 호스팅(self-hosted) 에이전트 시스템에서 빠르게 나타나는 실제 문제를 해결합니다. 즉, 서버 프로세스는 정상적으로 실행되고 있지만, 이미 설치된 에이전트 CLI가 런타임이 이를 실행하려고 할 때 보이지 않거나 신뢰할 수 없는 경우가 발생한다는 것입니다.

2026년 7월 18일자 fix: harden local runtime and retries 커밋에서 AIClaw는 로컬 런타임 경로와 명령어 해석 계층을 강화하여, 로컬 에이전트 실행이 여전히 명시적이고 감사 가능(auditable)하면서도 사용자의 실제 로그인 셸처럼 작동하도록 만들었습니다.

문제점: 서비스의 PATH가 터미널의 PATH보다 보통 더 나쁩니다

AiClaw는 서버를 호스팅하는 기기에서 로컬 에이전트 CLI를 직접 실행하도록 설계되었습니다. 이제 README에 이 계약(contract)을 명시했습니다:

• 내장된 Local 런타임은 시작 시 자동으로 생성됩니다;
• AIClaw는 현재 사용자의 로그인 셸 PATH를 복구합니다;
• 표준 패키지 관리자 위치들을 추가합니다;
• 감지된 CLI를 별도의 데몬이나 셸 경유 없이 인프로세스(in-process)로 실행합니다.

이것이 중요한 이유는 서비스 매니저들이 종종 좁은 PATH로 프로세스를 시작하기 때문입니다. macOS에서 launchd가 대표적인 예시입니다. CLI는 사용자의 터미널에서는 작동할 수 있지만, 서버 프로세스가 다음을 시도할 때 동일한 실행 파일 경로를 보지 못할 수 있습니다:

• 사용 가능한 런타임을 감지할 때;
• 나중에 선택된 CLI를 시작할 때;
• 재시작 후 재연결할 때;
• 대화형 셸이 아닌 백그라운드 서비스에서 실행될 때.

그 결과는 최악의 신뢰성 버그입니다. 감지는 한 가지를 말하지만, 실행은 다른 것을 수행합니다.

코드 변경 사항

새로운 internal/runtimeclient/environment.go 파일이 로컬 런타임에 대한 환경 처리를 중앙 집중화했습니다.

AIClaw는 더 이상 원시 서비스 환경(raw service environment)을 신뢰하지 않고 다음과 같이 작동합니다:

1. 현재 환경을 기반으로 읽습니다.
2. shell -ilc를 사용하여 로그인 셸의 PATH를 복구합니다.
3. 이를 다음과 같은 일반적인 설치 위치와 병합합니다:

• /opt/homebrew/bin
• /usr/local/bin
• ~/.local/bin
• ~/go/bin
• ~/.volta/bin
• ~/Library/pnpm
• ~/.asdf/shims
• ~/.mise/shims

4. 이 동일하게 해결된 환경을 CLI 감지 및 실제 실행 모두에 재사용합니다.

이 “감지와 실행에 사용되는 동일한 환경”이라는 점이 진정한 개선점입니다. AIClaw는 더 이상 한 조회 경로를 사용하여 CLI가 사용 가능하다고 보고했다가 나중에 다른 프로세스 환경으로 이를 실행하지 않습니다.

셸(shell) 래퍼보다 좋은 이유

AIClaw는 여전히 런타임 명령을 command + args로 직접 실행합니다. 셸을 통해 전달하지 않습니다.

이는 몇 가지 유용한 속성을 유지합니다:

• 인수 처리의 예측 가능성이 유지됩니다;
• 따옴표(quoting) 관련 버그를 피할 수 있습니다;
• 런타임 표면이 더 작습니다;
• 실행 모델을 로그와 테스트에서 검사하기가 더 쉽습니다.

따라서 이 변경은 “모든 것을 실행하는 데 셸을 사용한다”는 것이 아닙니다. 변경점은 “로그인 환경의 유용한 부분을 복구한 다음, 실행은 직접 유지한다”는 것입니다.

작지만 중요한 macOS 개선 사항

실용적인 macOS 전용 규칙도 있습니다. 요청된 명령이 codex일 경우, AIClaw는 다음과 같은 ChatGPT 앱 내부에 번들된 서명된 Codex CLI를 선호합니다:

/Applications/ChatGPT.app/Contents/Resources/codex

이는 이전의 타사 설치가 여전히 PATH에 있을 수 있는 기기에서 중요합니다. 만약 절대적인 CLI 경로를 명시적으로 구성하면, 그것이 여전히 우선권을 가집니다. 하지만 일반적인 기본 사례의 경우, AIClaw는 이제 번들되고 앱 관리되는 바이너리를 선호합니다.

테스트가 검증하는 내용

새로운 런타임 환경 테스트는 중요한 실패 모드를 다룹니다:

• 병합된 login-shell 및 fallback 경로는 최종 PATH에 보존되며;
• non-PATH 환경 변수는 온전하게 유지됩니다;
• 명령어 해석은 제공된 환경을 일관되게 사용합니다;
• 누락된 CLI는 사용자에게 로그인-쉘의 PATH를 알려주는 실행 가능한 오류를 생성합니다;
• macOS에서는 사용 가능한 경우 번들된 Codex가 선호됩니다.

이것이야말로 런타임 플러밍(runtime plumbing)에 적합한 테스트 커버리지입니다. 단순히 내부 도우미 기능을 확인하는 것이 아니라, 사용자가 실제로 느끼는 동작을 점검하기 때문입니다.

AIClaw 사용자에게 의미하는 바

AIClaw를 로컬에서 실행하고 내장 런타임을 통해 Codex, Claude Code, Cursor, CodeBuddy, Hermes 또는 OpenClaw를 사용하려면, 이제 워크플로우가 더 간단해졌습니다:

1. CLI를 평소처럼 자신의 사용자 계정 아래에 설치하고 인증합니다.
2. AIClaw를 시작합니다.
3. Runtimes 페이지에서 감지된 CLI를 확인합니다.
4. 실행 모드를 Local로 설정하여 에이전트를 생성합니다.
5. 동일한 장치에 별도의 런타임 데몬을 추가할 필요 없이 작업을 실행합니다.

최근 UI 문구도 동작에 맞춰 업데이트되었습니다. AIClaw가 프로세스 PATH만 스캔한다고 말하는 대신, 이제 양식은 현재 사용자의 로그인-쉘 PATH를 복원하고 거기서 스캔한다는 것을 설명합니다.

이 기능이 중요하다고 생각하는 이유

로컬 우선(Local-first) 에이전트 제품들은 보통