2026년 OpenClaw 첫 onboard 이후에도 깨짐: credentials, 환경 변수 우선순위, 모델 프로바이더 전환의 최소 루프와 층별 런북
onboard가 끝났다고 곧바로 운영 안정성이 보장되지는 않습니다. 게이트웨이를 돌리는 Unix 사용자가 동일한 ~/.openclaw/credentials/를 읽는지, systemd EnvironmentFile이 데몬 기동 전에 주입되는지, 모델 ID 접두사가 선택된 프로바이더와 맞는지가 「CLI에서는 chat 되는데 게이트웨이에서는 401/429」 같은 갈래를 만듭니다. RPC·probe는《공식 게이트웨이 probe·429 런북》, 연결·버전은《pairing》《split brain》《Docker Compose 토큰·환경》과 함께 보세요.
목차 (TOC)
1. 세 가지 갈래: HOME 밀림, 빈 credentials, 프로바이더 문자열
HOME 밀림: 터미널에선 사용자 A로 onboard했는데 launchctl/systemd는 사용자 B로 게이트웨이를 띄우면, A에게는 있는 credentials가 B에게는 비어 보일 수 있습니다.
빈 디렉터리: 폴더만 있고 키 파일이 없으면 doctor 힌트가 약하고 401은 모델 호출 단계에서야 드러납니다.
프로바이더 불일치: 설정의 모델 문자열과 openclaw models status 실제 라우팅이 어긋나면 로그에 provider mismatch류 서명이 남습니다. 429·무반응은《채널 프로브는 녹색인데 무반응》과 병행하세요.
- 먼저 게이트웨이 Unix 사용자를 확정합니다.
- 다음으로 환경 변수와 JSON 덮어쓰기를 맞춥니다.
- 마지막에 429와 채널 동작을 봅니다.
2. 의사결정 표: API Key, OAuth, 다중 프로바이더
여러 위치에 서로 다른 API Key를 두지 말고 단일 소스를 유지하세요. 그렇지 않으면 「수동 셸은 성공, 서비스는 옛값」 같은 거짓 양성이 남습니다.
| 축 | API Key 파일 | OAuth·브리지 | 다중 프로바이더 |
|---|---|---|---|
| 비밀 위치 | credentials + chmod 600 | 리프레시·콜백 URL | 파일 분리 또는 env 접두사 |
| 데몬 친화 | EnvironmentFile로 경로 명시 | 갱신 잡은 동일 사용자 | 라우팅 단일 소스 |
| 분리 순서 | ls 후 doctor | OAuth 로그 후 모델 | models status 후 channels |
3. How-to: onboard 후 일곱 단계 최소 루프
# 1) 게이트웨이 프로세스 사용자와 HOME
ps aux | grep -i openclaw
echo "$HOME"
ls -la ~/.openclaw/credentials/- plist/unit의 User=와 WorkingDirectory를 변경 티켓에 적습니다.
- 최소 권한으로 credentials를 보호하고 실수 커밋을 막습니다.
- 같은 셸에서
openclaw status와openclaw gateway status를 실행해 PATH 밀림을 피합니다. - 환경 변수 변경 뒤에는 게이트웨이 완전 재시작을 합니다(핫 리로드만으로는 부족할 수 있음).
- 프로바이더 전환은 최소 diff: 모델 문자열·라우트 블록·파일명을 동시에 맞춥니다.
openclaw doctor의 마스킹된 출력을 저장합니다.- 자격 증명 층이 정리되면 공식 사다리에 따라
gateway probe와 channels 영수증을 남깁니다.
# 2) systemd 예: OPENCLAW_HOME 명시
Environment=OPENCLAW_HOME=/home/oc/.openclaw4. 층별 분리와 로그 검색어
권장 순서는 openclaw status → openclaw gateway status → openclaw doctor → 로그에서 401 403 429 credential provider입니다. RPC가 녹색인데도 무반응이면 위 채널 글에서 플러그인 이중 토글을 확인합니다.
split brain: gateway status --deep에서 CLI와 서비스 바이너리 경로가 다르면 PATH·설치를 먼저 고칩니다. which openclaw가 unit과 다르면《설치 경로 비교》를 먼저 읽고 credentials 논의로 넘어갑니다.
5. 티켓에 남길 필드
실행 사용자, credentials 파일명 목록(마스킹 가능), doctor 요약, 모델 문자열 한 줄, 마지막 풀 재시작 시각, 설정 tarball 해시가 있으면 롤백이 쉬워집니다. Docker를 쓰면 컨테이너 uid와 볼륨 매핑을 Docker Compose 글과 맞춰 적으세요.
6. FAQ
질:Docker에서 credentials 볼륨은? 답:Docker Compose 글의 uid·볼륨 절을 보세요.
질:doctor를 건너뛸 수 있나요? 답:비권장입니다. 저수준 오류를 많이 모읍니다.
7. 정리와 원격 Mac 수렴
자격 증명 층이 맞아야 게이트웨이가 재현 가능한 환경에서 모델과 채널을 안정적으로 호출합니다. 노트북 절전·다중 HOME으로 관측이 흔들릴 수 있으니 시간 창을 티켓에 적으세요.
상시 게이트웨이와 감사 가능한 디렉터리를 기본으로 만들려면 SFTPMAC 원격 Mac 자료도 참고하세요. 공식 사다리와 이 글은 상호 보완이며, 자격 증명이 어긋난 채 429만 쫓지 마세요.