원격 IDE 브리지에서 가장 무서운 건 에이전트가 홈 전체를 덮어쓰는 일과, 게이트웨이는 공개돼 있는데 반쯤 죽은 줄 모르는 일입니다. 읽기 전용 코드 루트·쓰기 scratch·루프백 게이트웨이·최소 권한 토큰·정기 프로브를 한 줄로 묶으면 원인 추적이 훨씬 덜 “신비”에 가까워집니다.

아래는 원격 Mac에 OpenClaw가 설치되어 있다고 가정합니다. 설치·개념은 고객센터 · OpenClaw 가이드를 참고하세요. VS Code·Cursor 등으로 SSH 단일 워크스페이스를 열고 로컬 IDE가 원격 툴체인을 쓰는 전제입니다. OpenClaw·자동화 특집에서 말한 게이트웨이·프리페치와 맞물려, 여기서는 권한 경계와 가시성을 채웁니다. 로컬 RAG·벡터 디스크 규율은 Mac 로컬 RAG 결정 매트릭스와 대조하면 좋고, 플랫폼 개요는 홈, 전용 노드가 필요하면 구매 페이지에서 리전·사양을 비교하세요.

설계 원칙(2026 최소 권한)

  • 게이트웨이는 루프백만: OpenClaw 게이트웨이는 127.0.0.1에 바인딩하고 SSH 리버스 터널·내부망으로만 IDE와 연결해 무보안 면을 공인망에 펼치지 않습니다.
  • 토큰은 scope 단위: workspace:read, 화이트리스트 exec 등 필요한 것만 부여합니다. 파일은 0600, OPENCLAW_TOKEN_FILE로 참조하고 저장소·셸 히스토리에는 넣지 않습니다.
  • 디렉터리 이분법: repo는 읽기 전용, scratch만 쓰기 허용. 빌드 산출물·프로브 로그·임시 캐시는 모두 샌드박스 아래로 모읍니다.
  • 변경은 diff 요약: 작업 전후 git diff --stat을 남겨 사람·자동화가 “얼마나 움직였는지”를 즉시 봅니다.
  • doctor 후 프로브: 먼저 openclaw doctor로 환경을 고친 뒤 curl /health로 짧은 주기 하트비트를 돌려, 프로세스만 살아 있고 반쪽인 상태를 가려냅니다.

재현 절차

1. 디렉터리·권한. 원격 Mac에서:

mkdir -p ~/ide-bridge/repo ~/ide-bridge/scratch/probe # 클론·동기화한 코드는 repo에 두고 쓰기 제거(예시) chmod -R a-w ~/ide-bridge/repo

특정 사용자만 쓰기를 허용하려면 ACL이나 게이트웨이 전용 계정을 쓰고 IDE 사용자는 읽기만 하게 나눌 수 있습니다. 핵심은 에이전트·자동화 기본 경로가 소스 트리를 바꾸지 않게 하는 것입니다.

2. 게이트웨이 토큰. 설치 버전에 맞는 OpenClaw 하위 명령으로 토큰을 발급해 ~/.openclaw/gateway.token에 저장하고 chmod 600을 적용합니다. ~/.zprofile 또는 launchd 환경에 export OPENCLAW_TOKEN_FILE="$HOME/.openclaw/gateway.token"를 넣고, export TOKEN=비밀 형태는 피합니다.

3. 게이트웨이 기동(루프백). 포트는 IDE 설정과 맞추면 됩니다.

openclaw gateway listen \ --bind 127.0.0.1:18765 \ --token-file "$HOME/.openclaw/gateway.token"

상시 실행은 launchd KeepAlive로 감싸 표준 출력을 ~/ide-bridge/scratch/logs/gateway.log 등으로 보냅니다.

4. IDE 워크스페이스. Remote-SSH 루트는 ~/ide-bridge/repo. OUT_DIR·임시 디렉터리·OpenClaw 캐시는 ~/ide-bridge/scratch로 지정해 읽기 전용 트리에서 빌드가 실패하거나 권한이 몰래 풀리는 일을 막습니다.

5. diff 요약 로그. 자동화 진입 스크립트 앞뒤에 다음을 넣습니다.

LOG=~/ide-bridge/scratch/probe/diff-$(date +%F).log { echo "=== $(date -Iseconds) pre ==="; git -C ~/ide-bridge/repo diff --stat; \ git -C ~/ide-bridge/repo diff --cached --stat; } >> "$LOG" # ... 작업 ... { echo "=== $(date -Iseconds) post ==="; git -C ~/ide-bridge/repo diff --stat; \ git -C ~/ide-bridge/repo diff --cached --stat; } >> "$LOG"

전체 git diff 없이도 파일 단위 변경 규모를 로그로 빠르게 보고 감사·롤백 판단에 씁니다.

6. doctor·헬스 프로브. 설정 변경 후 먼저:

openclaw doctor --json > ~/ide-bridge/scratch/probe/doctor-last.json

이어 launchd로 5분마다 헬스 엔드포인트를 호출합니다(헤더는 실제 인증 방식에 맞게 조정).

curl -fsS -H "Authorization: Bearer $(cat ~/.openclaw/gateway.token)" \ http://127.0.0.1:18765/health \ || echo "$(date -Iseconds) health FAIL" >> ~/ide-bridge/scratch/probe/health.log

실패 시 위 로그를 tail하고 게이트웨이 종료 코드와 함께 봅니다. 요금 페이지의 머신 사양과 무관하게 흔한 원인은 디스크 만충·포트 충돌입니다.

문제 해결 FAQ

헬스가 401/403? 토큰 파일 권한과 Authorization 헤더 형식을 확인하세요. 토큰 교체 후 IDE 쪽과 launchd 작업을 재시작해 이전 시크릿이 섞이지 않게 합니다.

IDE 저장 시 EROFS? 읽기 전용 repo에 쓰기를 시도한 경우입니다. 편집 대상을 쓰기 가능 worktree로 옮기거나 scratch로 보낸 뒤 파이프라인에서 병합하세요.

doctor가 모델·캐시 경로 오류? 캐시 루트를 ~/ide-bridge/scratch/openclaw-cache로 통일하고 설정에 명시해, 기본 경로가 읽기 전용 볼륨·네트워크 드라이브로 가는 것을 막습니다.

diff 통계가 항상 비어 있음? git -C가 .git이 있는 저장소 루트를 가리키는지 확인하세요. 서브모듈은 상위 밖에서 별도 기록하거나 git -C 서브모듈/경로를 씁니다.

게이트웨이가 간헐적으로 무반응? launchctl print·사용자 리소스 한도를 보고, 같은 머신에서 openclaw doctor와 수동 curl로 네트워크 문제인지 프로세스 교착인지 나눕니다.

요약: 최소 권한 샌드박스 = 읽기 전용 저장소 + 쓰기 scratch + 루프백 게이트웨이 + 최소 scope 토큰. 가시성 = doctor --json 기준선 + diff 요약 + 주기 /health. 이 순서로 두면 원격 Mac에서 IDE 브리지를 안정적으로 돌리면서도 한 번의 실험에 머신 전체를 맡기지 않습니다.