전체 가이드

SSH로 원격 서버에서 Claude Code에 로그인하는 방법

브라우저가 없는 서버에서 코드 붙여넣기 로그인, 1년짜리 setup-token, API 키로 SSH를 통해 Claude Code에 로그인하고, 휴대폰에서 시작한 세션에서도 로그인을 유지하는 방법.

기준 버전
CLI
0.2.17
프리뷰 ref
a2c45c8

요약

SSH로 접속하는 서버에서는 Claude Code가 브라우저를 열 수 없고, 노트북의 브라우저는 서버의 로컬 콜백에 닿을 수 없습니다. 방법은 세 가지입니다.

  1. 코드 붙여넣기 로그인. claude를 실행하고, 노트북이나 휴대폰에서 로그인 URL을 열어 로그인한 뒤, 브라우저에 표시된 코드를 터미널에 붙여 넣습니다. 가끔 앞에 앉는 머신에 적합합니다.
  2. 장기 토큰. 브라우저가 있는 컴퓨터에서 claude setup-token을 실행한 뒤 서버에 CLAUDE_CODE_OAUTH_TOKEN을 설정합니다. 아무도 앞에 앉지 않는 머신에 적합합니다.
  3. API 키. ANTHROPIC_API_KEY를 설정합니다. Claude Console을 통해 토큰 단위로 과금되며, 스크립트와 CI에 맞습니다.

로그인 화면에서 SSH로 URL을 복사할 수 없다면 바로 방법 2로 가세요.

문제

흔한 구성: Claude Code 세션이 다른 방에 있는 Linux 머신에서 실행됩니다. 저장소가 거기 있고 절전 모드에 들어가지 않습니다. 처음으로 SSH를 통해 거기서 claude를 실행하면 로그인 화면이 브라우저를 열라고 하는데, 그 머신에는 브라우저가 없습니다.

노트북 브라우저로 링크를 열 수는 있지만, 로그인 후 노트북의 localhost로 돌아가려 하고 거기에는 아무것도 수신 대기하고 있지 않습니다. 그러다 몇 주 뒤 자격 증명이 만료되면 다시 처음부터 해야 합니다. 어쩌면 기차에서 휴대폰으로요.

그래서 진짜 질문은 이것입니다. 어떻게 한 번 로그인하고, 어떻게 로그인 상태를 유지하며, 키보드 앞에 없을 때는 어떻게 하느냐.

방법 1: 코드 붙여넣기 흐름으로 SSH에서 Claude Code 로그인

일반적인 경로이며, Anthropic의 인증 문서도 SSH와 헤드리스 호스트용으로 이를 설명합니다.

ssh you@server
claude

로그인 화면에서:

  1. c를 눌러 로그인 URL을 복사하거나 선택합니다.
  2. 노트북이나 휴대폰의 브라우저에서 열고 로그인합니다.
  3. 브라우저가 서버의 콜백에 닿을 수 없으므로 리디렉션 대신 코드를 보여 줍니다.
  4. 그 코드를 Paste code here if prompted 프롬프트에 붙여 넣습니다.

번거로운 부분:

  • 복사 단축키는 서버의 클립보드에 복사합니다. SSH로는 닿을 수 없습니다. Claude Code 저장소의 GitHub 이슈에는 전체 화면 로그인 UI 안에서 URL이 줄바꿈되어 선택조차 할 수 없다는 보고가 있습니다. 그런 경우 방법 2를 쓰세요.
  • tmux와 폭이 좁은 터미널은 URL을 여러 줄로 감쌀 수 있습니다. 복사하기 전에 창을 넓히거나 창(pane)을 확대하세요.
  • 자격 증명은 만료됩니다. 만료되면 그 머신의 다음 세션은 다시 로그인 화면에서 멈추고, SSH로 이 과정을 반복해야 합니다.

방법 2: 장기 claude setup-token으로 Claude Code 로그인

아무도 앞에 앉지 않는 머신을 위해 Anthropic은 1년짜리 OAuth 토큰을 안내합니다. 브라우저가 있는 컴퓨터에서 한 번 만듭니다.

# on your laptop
claude setup-token

/login과 같은 브라우저 로그인이 열리고 토큰이 출력되지만 어디에도 저장되지 않습니다. 복사한 뒤 서버에서:

# on the server, in the environment the agent runs in
export CLAUDE_CODE_OAUTH_TOKEN=your-token
claude

Anthropic 문서가 이 토큰에 대해 말하는 것:

  • Pro, Max, Team, Enterprise 구독이 필요합니다.
  • 모델 요청만 할 수 있어 Claude Code Remote Control 세션을 시작하거나 claude.ai 커넥터를 가져올 수 없습니다. 로컬에 설정한 MCP 서버는 계속 동작합니다.
  • --bare 모드는 이를 읽지 않습니다. 스크립트가 --bare를 넘긴다면 대신 API 키를 쓰세요.

실용적인 참고 두 가지:

  • 토큰은 내 사용자만 읽을 수 있는 곳에 두세요. 공유 머신의 셸 프로필이 아니라 불러오는 0600 파일 같은 곳입니다. 읽을 수 있는 것은 무엇이든 내 구독을 쓸 수 있습니다.
  • 에이전트가 실제로 시작되는 곳에 설정하세요. Claude Code가 백그라운드 서비스로 실행된다면 대화형 셸에서 export한 변수는 거기에 없습니다. 토큰이 "SSH에서는 되는데 서비스에서는 안 되는" 흔한 이유입니다.

방법 3: 서버에서 Anthropic API 키 사용

export ANTHROPIC_API_KEY=sk-ant-...
claude

Claude Code가 키 승인을 한 번 묻고 이후로는 브라우저를 건너뜁니다. Claude Console을 통해 토큰 단위로 과금되며 Pro나 Max 구독과는 별개입니다. 스크립트와 예약 작업에 적합합니다.

휴대폰에서 시작한 세션에서도 Claude Code 로그인 유지하기

방법 1~3은 첫 로그인을 해결합니다. 어려운 것은 두 번째입니다. 한 달 뒤 휴대폰에서 시작한 세션이 SSH로 접속해 있지 않은 머신에서 만료된 로그인에 걸려 멈춰 있는 경우입니다.

서버의 Claude Code 세션을 휴대폰에서 시작하고 조작하며, SSH 앱을 열지 않고도 로그인에 막힌 세션을 확인하고 싶다면, Happier는 Claude Code, Codex 등 여러 에이전트를 휴대폰, 데스크톱, 웹에서 크로스 디바이스로 실행하고 오케스트레이션할 수 있는 오픈 소스 앱입니다.

에이전트는 내 컴퓨터나 서버에서 실행되고, 휴대폰, 데스크톱, 웹 앱이 여기에 연결됩니다. 설정 방법은 휴대폰에서 Happier 사용하기에 있습니다. GitHub에 공개되어 있고, 여기서 다운로드할 수 있으며, Discord도 있습니다.

로그인 쪽은 이렇게 동작합니다.

1) QR 코드를 스캔해 서버를 Happier와 페어링

서버에서:

curl -fsSL https://happier.dev/install | bash
happier auth login --method mobile

터미널에 QR 코드가 표시됩니다. 휴대폰의 Happier 앱으로 스캔하고 승인하세요. 이미 Happier CLI가 있는 노트북이라면 happier auth pair-remote --ssh you@server가 SSH를 통해 페어링해 줍니다.

2) Happier 앱에서 서버의 Claude Code에 로그인

앱에서 Settings → AI & Agents → AI backends → Claude를 열고, 컨텍스트 바에서 서버(Happier에서는 machine)를 고른 뒤 Authentication 섹션을 보세요. 그 컴퓨터에서 Claude Code가 로그인되어 있는지, 어떤 방식인지 보여 줍니다.

Log in(또는 Reauthenticate)은 Provider login terminal을 열어 서버에서 Claude Code를 실행하고 /login을 대신 보냅니다. 휴대폰에서 URL을 열고 로그인한 뒤 코드를 그 터미널에 붙여 넣습니다. SSH 앱 없이 하는 방법 1입니다. 다른 방법으로 로그인한 뒤에는 Check now로 상태를 새로 고칩니다.

3) Claude setup-token을 Happier에 한 번 저장

setup-token을 쓰고 싶다면 Happier가 연결된 서비스로 보관해 줄 수 있습니다.

claude setup-token          # on a computer with a browser
happier connect claude      # paste the token when asked

happier connect claude는 기본적으로 setup-token을 묻습니다. 토큰은 Happier 계정에 암호화되어 저장되고 내 기기에서만 복호화됩니다. Settings → Connected services에 표시되며, 어느 컴퓨터에서 Claude 세션을 시작할 때든 고를 수 있습니다. Anthropic API 키도 happier connect claude --api-key로 같은 방식으로 다룰 수 있습니다.

솔직한 한계: 서버는 여전히 켜져 있고 접근 가능해야 합니다. Happier는 꺼진 머신의 로그인을 유지하지 못하며, 토큰에 관한 공급자 자체의 규칙도 그대로 적용됩니다.

문제 해결

Claude Code 로그인에서 c를 눌러도 붙여 넣을 수 있는 것이 복사되지 않음

복사는 노트북이 아니라 서버에 됩니다. 터미널 자체의 선택 기능으로 URL을 선택하거나, 줄바꿈되지 않도록 창을 넓히거나, 다른 컴퓨터에서 claude setup-token을 쓰세요.

Claude 로그인 후 브라우저가 localhost에 닿지 못함

콜백이 노트북에 닿으려는 것입니다. 코드를 보여 주는 브라우저 탭으로 돌아가거나, 로그인을 다시 시작해 코드 단계를 찾으세요. SSH에서는 코드가 예상된 경로입니다.

SSH에서는 Claude Code가 되는데 서비스가 시작한 세션은 로그인을 요구함

서비스는 대화형 셸의 환경을 보지 못합니다. 서비스 환경에 CLAUDE_CODE_OAUTH_TOKEN을 설정하거나, 토큰을 연결된 서비스로 저장해 세션이 시작 시 받도록 하세요.

setup-token으로 Claude Code Remote Control이 시작되지 않음

Anthropic 문서에 따르면 setup-token은 모델 요청만 할 수 있으므로 Remote Control에는 방법 1의 일반 claude.ai 로그인이 필요합니다.

자주 묻는 질문

브라우저 없이 Claude Code에 로그인할 수 있나요?

어딘가에서 한 번은 브라우저가 필요합니다. 노트북이든 휴대폰이든 됩니다. claude setup-token과 코드 붙여넣기 로그인 모두 다른 기기의 브라우저를 씁니다. 브라우저를 완전히 건너뛰는 것은 API 키뿐입니다.

setup-token은 얼마나 유효한가요?

Anthropic 문서에 따르면 1년입니다. 한 번만 출력되고 어디에도 저장되지 않으므로 터미널을 닫기 전에 보관하세요.

Claude Pro나 Max가 필요한가요?

코드 붙여넣기 로그인과 setup-token에는 Claude 구독이 필요합니다(setup-token은 Pro, Max, Team, Enterprise 필요). API 키는 구독이 필요 없고 Console을 통해 과금됩니다.

노트북의 ~/.claude를 서버로 복사해도 되나요?

그렇게 하는 사람도 있지만 문서화된 로그인 방법이 아니며, 공급자가 자격 증명을 교체하면 복사한 것이 동작하지 않을 수 있습니다. 다른 컴퓨터에서 로그인을 재사용하는 문서화된 방법은 setup-token입니다.

Raspberry Pi나 VPS에서도 같나요?

네. 단계는 하드웨어와 무관하고, 머신에 브라우저가 없다는 점에만 좌우됩니다.

관련 가이드

claudesshlinuxheadlessself-host
마지막 업데이트: 2026-10-26