환경 & 로그인
응급 트러블슈팅 매뉴얼
"구독 결제를 마쳤는데 왜 API 과금이 되는가", "새 PC로 교체한 뒤 실행이 안 된다", "다른 사람이 쓰던 PC에서 설정이 꼬였다" — 이 모든 문제는 원인 불명의 오류가 아니라 5개의 명확한 레이어 중 하나에 속합니다. 체계적인 5계층 진단법, 2대 도구 증상별 응급 처치표, 3대 시나리오별 처방전, 단계별 만능 리셋 절차를 제공합니다.
증상별 빠른 진단 + 장애 분류 맵
env | cut -d= -f1 | grep -iE 'anthropic|openai'로 세션을 가로채고 있는 환경 변수를 찾아 unset 처리;② 깔끔한 재로그인:
/logout 후 /login (Codex: codex logout && codex login);③ 자격 증명 확인:
/status 또는 codex login status로 정상 계정과 로그인 방식인지 확인.4대 근본 원인 맵
| 근본 원인 | 전형적인 증상 | 발생 이유 |
|---|---|---|
| ① 복수 설치 경로 충돌 | 버전이 제멋대로 바뀌거나 업데이트가 반영되지 않음 | 공식 네이티브 설치, npm 글로벌, Homebrew, IDE 내장 바이너리가 공존하며 PATH 우선순위 충돌 |
| ② 자격 증명 소스 충돌 | "로그인했는데 Invalid API key가 뜸", 구독 계정인데 API 종량 과금됨 | 환경 변수에 설정된 API Key가 브라우저 OAuth 구독 자격 증명보다 우선순위가 높기 때문 |
| ③ 설정 계층 오버라이드 | "설정을 바꿨는데 적용이 안 됨", 회사 PC에서 설정이 잠김 | Enterprise 정책 > CLI 인자 > 프로젝트 로컬 > 프로젝트 공유 > 사용자 전역 순으로 덮어씀 |
| ④ 네트워크 및 시스템 환경 | 로그인 콜백 멈춤, TLS/인증서 오류, 다운로드 403 | 기업 프록시, 사설 CA, 방화벽이 로컬 콜백 포트(Codex는 1455) 차단 |
다섯 가지 진단 계층
실행 파일과 버전, 환경변수 이름, 인증, 설정 계층과 실제 연결 주소를 확인합니다. 여러 설치나 프록시 변수가 곧 오류는 아닙니다. 키 파일과 환경변수 값을 출력하지 않으며 Claude 출처는 /status로 확인하고 검증하지 않은 Codex /debug-config에 의존하지 않습니다.
codex --version
claude --version
# Variable names only (macOS / Linux / WSL)
env | cut -d= -f1 | sort | grep -iE 'anthropic|claude|codex|openai|proxy' || trueClaude Code · 인증
관리 설정, --settings, 프로젝트 local, 공유 프로젝트, 사용자 순입니다. 환경변수 우선순위는 키별로 다릅니다. 구독, Console, API, 클라우드와 기업 게이트웨이를 구분합니다.
Claude Code · 설정
관리 설정, --settings, 프로젝트 local, 공유 프로젝트, 사용자 순입니다. 환경변수 우선순위는 키별로 다릅니다. 구독, Console, API, 클라우드와 기업 게이트웨이를 구분합니다.
Claude Code · 진단
관리 설정, --settings, 프로젝트 local, 공유 프로젝트, 사용자 순입니다. 환경변수 우선순위는 키별로 다릅니다. 구독, Console, API, 클라우드와 기업 게이트웨이를 구분합니다.
Codex · 인증
제공자 ID, 인증, URL, 필수 조건, 상호 배타 설정과 마이그레이션은 전용 장을 봅니다. ChatGPT, API와 게이트웨이 자격 증명은 서로 다른 경로입니다.
Codex · 설정
제공자 ID, 인증, URL, 필수 조건, 상호 배타 설정과 마이그레이션은 전용 장을 봅니다. ChatGPT, API와 게이트웨이 자격 증명은 서로 다른 경로입니다.
Codex · 진단
제공자 ID, 인증, URL, 필수 조건, 상호 배타 설정과 마이그레이션은 전용 장을 봅니다. ChatGPT, API와 게이트웨이 자격 증명은 서로 다른 경로입니다.
시나리오 B · PC 교체 / 멀티 머신 동기화
기본 원칙은 명쾌합니다: "설정은 가져가고, 인증 정보는 머신마다 새로 로그인하며, 히스토리는 그 자리에 둔다". '무엇을 가져가고, 무엇을 가져가지 말아야 하는지'만 명확히 구분하면 새 PC 세팅은 10분 만에 끝납니다.
가져갈 것과 가져가지 말아야 할 것 (2대 도구 비교 대조)
| 자산 | Claude Code | Codex | 마이그레이션 방침 |
|---|---|---|---|
| 핵심 설정 | settings.json, 글로벌 CLAUDE.md, skills/, agents/ | config.toml, profiles, 글로벌 AGENTS.md | ✅ dotfiles 저장소로 관리하고 새 PC에서 clone |
| 프로젝트 설정 | .claude/, .mcp.json, 프로젝트 CLAUDE.md | .codex/, 저장소 AGENTS.md | ✅ 프로젝트 git 저장소에 이미 존재 |
| 자격 증명 | 키체인 / .credentials.json | auth.json / 키체인 | ❌ 복사 금지: 새 PC에서 1회 재로그인(30초)하는 것이 훨씬 안전하고 깔끔함 |
| 세션 히스토리 | projects/, history.jsonl (평문!) | 세션 데이터 디렉터리 | ❌ 로컬 기록은 이전 불필요; 머신 간 연속 작업은 Claude의 --teleport/클라우드 세션, Codex의 클라우드 태스크 활용 |
| 캐시 / 플러그인 | plugins/, shell-snapshots/ 등 | 로그 디렉터리 | ➖ 백업 불필요. 새 머신에서 자동 재생성됨 |
새 PC 10분 표준 셋업 프로세스
# 1. 설치 (공식 네이티브 채널 사용, npm과 혼용 금지)
curl -fsSL https://claude.ai/install.sh | bash # Claude Code
npm install -g @openai/codex # Codex (또는 brew install codex)
# 2. 설정 복원 (dotfiles 방식)
git clone git@github.com:yourname/dotfiles.git ~/dotfiles
ln -s ~/dotfiles/claude ~/.claude # 또는 export CLAUDE_CONFIG_DIR=~/dotfiles/claude
ln -s ~/dotfiles/codex ~/.codex # 또는 export CODEX_HOME=~/dotfiles/codex
# 3. 각 도구별 1회 로그인 (자격 증명 파일은 절대 복사하지 말 것)
claude # 브라우저 OAuth → /status로 계정과 Login method 검증
codex login # 브라우저 OAuth → codex login status로 검증
# 4. 진단 스크립트로 최종 검증
claude doctor && bash ai-env-check.shCLAUDE_CONFIG_DIR / CODEX_HOME을 클라우드 동기화 폴더(iCloud/Dropbox 등)로 지정하는 방법도 있습니다 (주의: 인증 정보나 projects/ 히스토리가 동기화되지 않도록 .gitignore 등으로 확실히 제외할 것).참고: 공식 ~/.claude 디렉터리 완전 해설 · anthropics/claude-code#36693 (멀티 머신 동기화 논의)
SSH / Docker / CI 헤드리스 환경 인증
브라우저가 없는 원격 서버에서는 SSH 포트 포워딩을 이용하거나 터미널 출력 URL을 로컬 브라우저에서 열어 인증 코드를 붙여넣습니다:
# Codex 로컬 포트 포워딩 (콜백 수신용)
ssh -L 1455:localhost:1455 user@remote-server
# Claude Code 헤드리스 인증
claude login --no-browser # 표시된 URL을 로컬에서 열고 코드를 터미널에 입력실전 사례 분석: 증상에서 근본 원인까지
실제 현장에서 가장 자주 발생하는 4가지 고빈도 시나리오를 통해 5계층 진단법의 실제 적용 흐름을 확인해 봅니다. 이 4가지 구조를 이해하면 대부분의 "원인 불명의 오류"를 스스로 해결할 수 있습니다 — 특히 에러 메시지 텍스트와 실제 근본 원인이 얼마나 동떨어져 있는지에 주목하세요.
사례 1 · "Max 회원인데 조직이 비활성화되었다는 오류가 발생합니다"
| 현장 상황 | 동료에게 인수인계받은 PC에 Claude Code를 새로 설치하고 유료 구독 계정으로 정상 로그인했으나, 프롬프트를 입력하자마자 API Error: 400 "This organization has been disabled" 오류가 발생함. 프로그램을 두 차례 재설치했으나 전혀 개선되지 않음. |
| 진단 과정 | L1 정상 (단일 설치, 최신 버전); L2에서 원인 발견 — env | cut -d= -f1 | grep -i anthropic을 실행하자 ANTHROPIC_API_KEY=sk-ant-…가 검출됨. 확인 결과 ~/.zshrc 파일 내에 이전 사용자가 남겨둔 API 키였으며, 해당 키의 Console 조직은 이미 폐기된 상태였음. |
| 조치 단계 | 변수를 unset 처리하고 rc 파일에서 export 구문 삭제 → 터미널 재시작 → /status에서 Login method가 구독 계정으로 복귀했음을 확인. 소요 시간 3분, 재설치는 전혀 불필요했음. |
| 교훈 | 에러 메시지는 '조직'을 말했고 사용자는 '구독'을 의심했으나, 진짜 원인은 '환경 변수'에 있었습니다 — 에러 메시지는 결과 현상만을 기술할 뿐 근본 원인이 아닙니다. 이것이 L2 문제를 해결할 때 재설치(L1 조치)가 영원히 먹히지 않는 이유입니다. |
사례 2 · "VS Code 확장에서만 Invalid API key가 뜨고 터미널은 멀쩡합니다"
| 현장 상황 | 터미널의 claude는 완벽히 정상 작동하지만, VS Code 확장 프로그램에서는 Invalid API key · Please run /login 팝업이 반복해서 뜨고, 로그인에 성공해도 화면이 검은색으로 멈춤 (anthropics/claude-code#12204에 기록된 전형적 사례). |
| 진단 과정 | L3 자격 증명 계층 문제로 보이지만 근본 원인은 L2: 머신에 3개의 서로 다른 자격 증명 소스가 동시에 공존하고 있었음 (OAuth 로그인, 수동 설정 API 키, Shell 환경 변수). 터미널이 rc 파일에서 로드한 환경과 VS Code가 GUI로 실행되며 상속받은 환경이 서로 달랐으며, 두 프로세스가 서로 다른 자격 증명을 로드하여 한쪽은 유효하고 한쪽은 무효화됨. |
| 조치 단계 | 자격 증명 소스를 단일화: 모든 ANTHROPIC_* 환경 변수와 수동 API 키를 정리 → CLI와 확장 프로그램 양쪽에서 클린 재로그인 → 양쪽의 /status에서 동일한 구독 계정이 인식되는지 확인. |
| 교훈 | "터미널은 정상인데 IDE만 이상하다"는 현상은 십중팔구 두 프로세스가 바라보는 환경 변수의 불일치 때문입니다. 자격 증명이 혼재되어 있으면 어떤 프로세스가 어떤 키를 쥐게 될지 예측할 수 없습니다 — 자격 증명 소스는 반드시 단 하나로 단일화하세요. |
사례 3 · "아침에 일어나 맥북을 열었더니 모든 세션이 일제히 재로그인을 요구합니다"
| 현장 상황 | 전날 밤 3개의 병렬 Claude Code 세션을 열어둔 채 노트북을 닫고 취침. 다음 날 아침 절전 모드에서 복귀하자 3개 세션이 일제히 로그인 화면을 띄웠고, 하나를 다시 로그인하면 다른 세션이 튕기는 현상이 반복됨. |
| 진단 과정 | L2/L3는 깨끗했고, 직관과 달리 L1 버전 계층이 원인이었음: 공식 changelog를 확인한 결과 v2.1.211 이전에 알려진 버그가 있었음 — 절전 복귀 시 여러 세션이 동일 토큰에 대해 동시에 갱신을 시도하며 서로의 인증을 무효화시키는 레이스 컨디션 발생. |
| 조치 단계 | v2.1.211 이상으로 업데이트 (갱신 로직이 단일 프로세스 조율 방식으로 개선됨), 1회 재로그인한 뒤 완전히 재발하지 않음. |
| 교훈 | 전체적이고 비정상적인 시점에 발생하는 문제는 개인 설정을 의심하기 전에 도구 버전과 릴리스 노트를 확인하세요. 공식 개발팀이 이미 패치한 버그는 로컬 환경을 아무리 조사해도 원인을 찾을 수 없습니다. |
사례 4 · "Codex가 CI에서 일주일간 잘 돌다가 갑자기 전체 파이프라인에서 401 에러를 냅니다"
| 현장 상황 | ChatGPT 구독 플랜으로 CI를 구성: 로컬의 auth.json을 CI Secret에 등록하고 작업 실행마다 복원하여 사용. 일주일 후 모든 파이프라인에서 일제히 401 오류가 발생하기 시작했고, 로컬에서 파일을 다시 복사해 넣으면 며칠간 정상 작동하다가 다시 깨지는 악순환 반복. |
| 진단 과정 | L3 자격 증명 계층의 특성: Codex 토큰은 약 8일간 미사용 시 stale 상태가 됩니다. 작업 실행 중 자동 갱신되어 auth.json에 새로 쓰여졌음에도 불구하고, CI 파이프라인이 매 실행 시 Secret의 '최초의 오래된 파일'로 덮어쓰며 복원했기 때문에 자동 갱신 결과가 버려지고 갱신 체인이 끊겨 만료됨. |
| 조치 단계 | 공식 권장 CI 패턴으로 순환 루프 구축: 복원 → 실행 → 갱신된 auth.json을 Secret에 다시 저장; 병렬 작업 간 동일 자격 증명을 공유하지 않도록 격리. 자체 호스팅 러너의 경우 영구 볼륨에 CODEX_HOME을 마운트하여 완전 자동화. |
| 교훈 | 자격 증명은 정적 설정 파일이 아니라 생명주기(상태)를 갖는 동적 개체입니다. "N일 주기로 주기적으로 고장 나는" 문제는 만료되는 리소스의 갱신 체인이 끊어지지 않았는지 확인하세요. |
사례 근거: 공식 troubleshoot-install / authentication 문서, anthropics/claude-code#12204, Codex CI/CD auth 공식 가이드 (2026-07 검증 완료). 상황 설명은 이해를 돕기 위해 재구성되었으나 진단 경로와 근본 원인은 실제 시스템 메커니즘을 기반으로 합니다.
복구 가능한 진단과 초기화
오류, 버전, 적용 설정, 민감 정보를 가린 로그를 보존하세요. 자격 증명이 원인일 때만 재로그인하세요. 일부 백업으로 모든 기록을 복구할 수 없으므로 설정 전체를 지우지 마세요.
격리가 필요하면 실제 경로를 확인하고 전체를 타임스탬프와 함께 복사하여 읽을 수 있는지 확인하세요. 원본을 보존하고 확인된 항목 하나씩 변경하거나 복원하세요.
2대 도구 비교 대조표 & 리소스
| 항목 | Claude Code | Codex |
|---|---|---|
| 설정 디렉토리 | ~/.claude/ | ~/.codex/ |
| 설정 파일 | settings.json | config.toml |
| 자격 증명 파일 | 키체인 또는 .credentials.json | auth.json |
| 로그인 명령어 | claude (자동 프롬프트) 또는 /login | codex login |
| 로그아웃 명령어 | /logout | codex logout |