맥 미니를 서버처럼 쓰면서 SSH로 원격 접속해 Claude Code를 쓰려고 했더니, 분명히 로그인했는데 “Missing API Key”가 뜨면서 /login을 다시 실행하라는 메시지가 반복됐다. 뭔가 이상하다 싶어서 원인을 찾아봤다.
왜 이런 일이 생기나
Claude Code는 로그인 정보(OAuth 토큰)를 macOS Keychain에 저장한다. 그런데 SSH 세션은 GUI 데스크탑 환경이 아니라서, Keychain에 접근하려면 화면에 팝업이 떠야 하는데 그게 불가능하다. 결국 SSH로 접속한 상태에서는 Keychain이 잠겨 있어서 로그인 정보를 읽지 못하고, 매번 다시 로그인하라고 나오는 것이다.
이 문제는 나만 겪은 게 아니라 GitHub의 Claude Code 이슈 트래커에도 수십 개의 관련 보고가 올라와 있을 정도로 흔한 문제다.
해결법: security unlock-keychain
가장 간단한 해결책은 SSH 접속 후 아래 명령어를 한 번 실행하는 것이다.
security unlock-keychain ~/Library/Keychains/login.keychain-db
실행하면 Mac 로그인 비밀번호를 입력하라는 프롬프트가 뜨고, 입력하면 Keychain이 잠금 해제된다. 이후 Claude Code를 실행하면 정상적으로 로그인된 상태로 동작한다.
참고: 이 명령어는 Apple이 기본 제공하는
security명령어다. 보안 우회가 아니라, 로컬에서 Keychain을 열 때와 똑같이 비밀번호를 한 번 입력하는 방식이다.
더 편하게: .zshrc에 자동화하기
SSH 접속할 때마다 명령어를 일일이 입력하기 귀찮다면, .zshrc(또는 .bashrc)에 아래 코드를 추가해두면 된다.
# SSH 접속 시 Keychain 자동 잠금 해제
if [ -n "$SSH_CONNECTION" ] && [ -z "$KEYCHAIN_UNLOCKED" ]; then
security unlock-keychain ~/Library/Keychains/login.keychain-db
export KEYCHAIN_UNLOCKED=true
fi
$SSH_CONNECTION 변수는 SSH 세션에서만 존재하기 때문에, 로컬 터미널에서는 이 코드가 실행되지 않는다. $KEYCHAIN_UNLOCKED는 같은 세션 안에서 중복 실행을 방지하는 역할을 한다.
설정 후 source ~/.zshrc로 적용하면, 다음 SSH 접속부터는 비밀번호 한 번 입력으로 Claude Code를 바로 쓸 수 있다.
정리
| 상황 | 증상 | 해결 |
|---|---|---|
| SSH 접속 후 Claude Code 실행 | “Missing API Key”, /login 반복 요구 | security unlock-keychain 실행 |
| 매번 직접 입력하기 번거로울 때 | — | .zshrc에 SSH 감지 자동 실행 코드 추가 |
SSH로 Mac을 원격 조작하면서 Claude Code를 쓰고 싶다면 이 방법 하나면 충분하다. Keychain 문제는 Claude Code만의 이슈가 아니라, Keychain을 쓰는 CLI 도구라면 SSH 환경에서 공통으로 나타나는 현상이니 참고해두면 다른 상황에서도 응용할 수 있다.