OpenClaw 게이트웨이는 모델 API 키, 웹훅 서명 시크릿, 채널 토큰을 환경에서 읽습니다—그러나 launchd가 개입하면 macOS에서 “환경”은 모호해집니다. 이 2026 플레이북은 키체인 저장과 dotenv 파일을 비교하고, 대화형 셸에 새지 않게 LaunchAgent에 시크릿을 연결하는 방법을 보여 주며, 팀 채팅에 자격 증명을 붙여 넣지 않고 헤드리스 클라우드 Mac mini M4 호스트를 준수 상태로 유지하는 순환 단계를 정리합니다.
최초 부트스트랩은 OpenClaw macOS 설치 가이드와 짝을 이룹니다. 원격 접근 경로를 디버깅할 때 토큰 복사만 하려고 바인드 주소를 넓히고 싶다면 SSH 터널 원격 관리를 함께 읽으세요. 지속 위생은 운영 런북 로그·업그레이드와 맞추어 시크릿 순환이 바이너리 업데이트와 같은 변경 기록에 남게 하세요.
저장 방식 비교
| 메커니즘 | 강점 | 약점 |
|---|---|---|
| macOS 키체인 | OS 보호 항목 ACL; 기본적으로 전 세계 읽기 아님 | 헤드리스 프롬프트는 일회 GUI 또는 security CLI 규율 필요 |
디스크 .env |
빠른 로컬 반복 | 백업이 홈 전체를 통째로 복사하는 경우가 많음—유출 경로 |
Plist EnvironmentVariables |
launchd 네이티브; IaC에서 재현 가능 | 여전히 평문 저장—plist 권한을 600으로 제한 |
시크릿 유형 라우팅 표
| 시크릿 유형 | 권장 저장소 | 순환 주기 |
|---|---|---|
| LLM 프로바이더 API 키 | 키체인 또는 볼트 에이전트 → 프로세스 시작 시 env | 60~90일 또는 퇴사 시 |
| 웹훅 HMAC 시크릿 | 채널당 키체인 항목 | 90일; 컷오버 중 이중 키 |
| 비민감 플래그 | Plist 또는 git의 설정 JSON | 앱 릴리스와 버전 관리 |
절대 금지: 프로덕션 키를 Slack, 이메일, 화면 녹화에 붙여 넣지 마세요. 그랬다면 즉시 순환—“비공개” 메시지여도 시크릿은 탄 것으로 가정하세요.
반복 가능한 시크릿 부트스트랩 여덟 단계
- 서비스 사용자 생성: 게이트웨이 전용 비관리자 계정; 홈 디렉터리 모드
700. - 대역 외 키 생성: 볼트 UI나 프로바이더 콘솔 사용; 셸 기록에 echo 금지.
- 키체인에 삽입: 시크릿당 하나의 항목, 설명 라벨, 게이트웨이 바이너리만 접근.
- 실행 명령 래핑:
security find-generic-password -w로 키체인에서 env를 export한 뒤 OpenClaw를 exec하는 작은 셸—값이 아니라 stderr만 로그. - LaunchAgent가 래퍼 참조: ProgramArguments는 래퍼를 가리킴; plist에 평문 시크릿 없음.
- 드라이런 검증: 게이트웨이 기동, 헬스 엔드포인트 확인, 이전 키는 마이그레이션 시 프로바이더 UI에서 폐기.
- 순환 문서화: 티켓 템플릿에 의존 채널·롤백 창 ≤ 30분.
- 분기 감사: 키체인 경로 밖에서 실수로
sk-또는ANTHROPIC문자열이 있는지 디스크 grep.
팀이 실제로 지키는 수치 가드레일
숫자 세 개를 고르고 내부 README에 공표하고 코드 리뷰로 강제하세요: 디스크 평문 시크릿 파일 최대 개수(프로덕션 0), 장수 토큰 최대 수명(기본 90일), 게이트웨이 계정 sudo 권한 엔지니어 최대 2명. 계약자 접근이 필요하면 키체인 ACL을 영구 넓히지 말고 유지보수 창에 맞춰 SSH 키를 시간 제한하세요.
- Plist 권한: 시크릿 경로를 담은 파일은
chmod 600—본문이 키체인에 있어도. - 래퍼 타임아웃: 키체인 조회는 2초 안에 끝나야 함; 더 길면 헤드리스에서 UI 프롬프트가 막힌 신호—한 번 VNC로 해결 후 재테스트.
- 시크릿 최대 나이: 180일 넘게 순환 없으면 다음 스프린트 계획에 강제 티켓.
시크릿을 찍지 않는 감사 로깅
컴플라이언스는 “누가 키를 건드렸나?”를 묻지 “키가 뭐냐?”를 묻지 않습니다. 게이트웨이 로그에 각 자격 출처(키체인 항목 UUID, 볼트 경로, 순환 배치 ID)의 해시 지문을 남기고 리터럴 토큰은 금지하세요. OpenClaw가 오류를 낼 때 상류 API 키가 반사될 수 있는 쿼리 파라미터는 마스킹하세요. 많은 HTTP 클라이언트가 전체 URL을 실수로 로그합니다. SOC 스타일 통제라면 핫 스토리지 최소 30일, 콜드 1년 보관을 검토하세요. 로그는 비상 계정만 SSH 세션 녹화와 짝지으세요. 일상 엔지니어링은 라이브 시크릿 붙여 넣기보다 커밋 검토된 설정 변경에 의존하게 하세요.
dev/stage/prod 게이트웨이가 여러 개면 각각 다른 키체인 파티션을 두고 ~/Library/Keychains 디렉터리를 호스트 간에 복사하지 마세요—macOS는 손상으로 보거나 헤드리스에서 끝없이 프롬프트합니다. 대신 항목 이름을 내부 위키에 문서화해 당직이 security find-generic-password -a service -s LABEL로 존재만 확인하고 바이트는 노출하지 않게 하세요.
임대 Mac에서의 헤드리스 macOS 함정
클라우드 Mac에는 책상 앞에서 “항상 허용”을 누를 사람이 드뭅니다. 최초 키체인 승인은 VNC로 끝내고 이틀차 편집은 SSH에 맡기세요. 여러 엔지니어가 한 계정을 쓰면 ACL이 흐려지니 환경별로 게이트웨이를 쪼개 자격 증명을 공유하지 마세요. 디버깅용으로 사람이 읽을 env가 잠깐 필요하면 /tmp 대신 로그아웃 시 지우는 램디스크 파일을 쓰세요. 일부 이미지에서는 /tmp가 재부팅 후에도 남습니다.
NodeMac은 홍콩·일본·한국·싱가포르·미국에서 SSH와 VNC를 모두 갖춘 전용 Mac mini M4 하드웨어를 임대합니다. 실무적 분업은 자동화는 SSH, TCC 프롬프트는 VNC입니다. 프로덕션 시크릿을 스테이징 실험과 다른 호스트에 두는 폭발 반경 분리는 지역별 요금을 비교하면 사고 대응보다 쌉니다. 볼트 주도 배포를 플릿에 자동화하기 전에 도움말 문서의 SSH 키 온보딩을 읽으세요.
자주 묻는 질문
시크릿 값을 LaunchAgent plist와 같은 git 저장소에 둬도 되나요?
plist 구조는 예, 시크릿 값은 절대 아니요—구조와 비민감 키만 커밋하세요. 민감 값은 설치 시점에 볼트 API와 통신하는 CI 배포 잡으로 주입하세요.
API 사용 이중 과금 없이 키를 어떻게 순환하나요?
프로바이더 콘솔에 새 키를 구 키 옆에 추가하고, 구 키가 유효한 동안 새 키체인 항목으로 게이트웨이를 배포한 뒤 24시간 녹색 트래픽을 관찰하고 레거시 키를 폐기하세요. 래퍼 스크립트 오타 하나로 반쯤 실패하는 자정 컷오버를 피합니다.
Mac mini M4는 OpenClaw 시크릿 처리에 강한 플랫폼입니다. Apple Silicon은 효율적인 상시 데몬을 돌리고, 네이티브 키체인은 서비스 정체성과 맞물리며, 물리적 격리는 컴플라이언스 질문지를 복잡하게 만드는 하이퍼바이저 측채널 잡음을 피합니다. NodeMac은 HK·JP·KR·SG·US에서 SSH/VNC로 전용 Mac mini를 제공해 게이트웨이가 예측 가능한 금속 위에 있습니다. 온디맨드 임대로 보안 팀이 지역별로 “시크릿 기준” 호스트를 하드웨어 다섯 벽장을 사지 않고도 복제할 수 있습니다.