Claude Code에는 -p (비대화형 모드)를 위해 hooks, skills, plugins, MCP servers, auto memory, CLAUDE.md의 자동 발견을 모두 스킵하여 기동을 가속화하는 --bare 플래그가 있습니다. 공식 문서에는 "스크립트 실행·SDK 호출의 권장 모드로, 향후에는 -p의 기본값이 될 예정"이라고 명시되어 있는, 말하자면 "앞으로의 표준"인 기능입니다1.

필자는 Claude Code의 클라우드 실행 환경(OAuth 기반 인증으로 동작하는 환경)에서 claude --bare -p를 실제로 실행해 본 결과, 예상치 못한 **인증 에러 (Authentication error)**를 마주했습니다. 본 기사에서는 그 실측 로그와 원인, 회피책을 정리합니다.

• --bare 플래그가 구체적으로 무엇을 스킵하는가

• OAuth 인증 환경에서 --bare를 사용하면 어떤 일이 발생하는가 (실기 로그 포함)

• 회피책 (ANTHROPIC_API_KEY / apiKeyHelper)

• --bare가 CI·자동화 스크립트에서 권장되는 이유

• Claude Code: v2.1.198

• 실행 환경: Claude Cloud (OAuth 기반 인증, ANTHROPIC_API_KEY 미설정)

• --bare는 hooks, skills, plugins, MCP servers, auto memory, CLAUDE.md의 자동 발견을 스킵하는 경량 모드

• OAuth·keychain으로부터의 인증 정보 읽기도 동시에 스킵됨 (공식 문서에 명시)

• OAuth 로그인으로 동작하는 환경 (Claude Cloud의 스케줄 실행 등)에서 그대로 --bare를 사용하면 Authentication error가 발생함

• 회피를 위해서는 ANTHROPIC_API_KEY 환경 변수 또는 --settings를 통한 apiKeyHelper가 필요함

• Bedrock / Vertex / Foundry를 사용하는 경우에는 각 프로바이더의 통상적인 인증 정보가 그대로 사용됨

claude -p는 순수한 비대화형 모드라도 대화 세션과 동일한 컨텍스트 (작업 디렉토리의 .claude/나 ~/.claude 설정)를 읽어들입니다. 팀원의 ~/.claude에 놓인 hook나 프로젝트의 .mcp.json에 등록된 MCP 서버까지 함께 읽어들이기 때문에, 실행하는 머신에 따라 동작이 달라질 수 있습니다1.

--bare는 이를 피하기 위한 플래그로, 공식 문서에는 다음과 같이 명시되어 있습니다.

Bare mode is useful for CI and scripts where you need the same result on every machine. A hook in a teammate's ~/.claude or an MCP server in the project's .mcp.json won't run, because bare mode never reads them.1

먼저 실행 환경의 Claude Code 버전을 확인했습니다.

$ claude --version
2.1.198 (Claude Code)

--bare를 붙여 간단한 프롬프트를 비대화형으로 실행해 봅니다.

$ claude --bare -p "1+1은?"
Ignoring 2 permissions.allow entries from .claude/settings.json: this workspace has not been trusted...
Authentication error · This may be a temporary network issue, please try again

.claude/settings.json의 permissions가 무시된다는 메시지에 이어, **인증 에러 (Authentication error)**가 반환되었습니다. 이 실행 환경은 통상적인 claude -p (--bare 없음)에서는 OAuth 기반 인증으로 문제없이 동작하므로, --bare를 붙임으로써 인증 경로가 변경되었음을 알 수 있습니다.

공식 문서의 bare mode 항목을 확인해보니 원인이 명시되어 있었습니다.

Bare mode는 OAuth 및 keychain 읽기를 건너뜁니다. Anthropic 인증은 다음 중 하나를 통해 이루어져야 합니다:

ANTHROPIC_API_KEY

또는 --settings로 전달되는 JSON 내의

apiKeyHelper

Bedrock, Vertex, Foundry는 평소와 같은 프로바이더 자격 증명(provider credentials)을 사용합니다.1

즉, --bare는 hooks나 CLAUDE.md뿐만 아니라, OAuth 토큰이나 OS 키체인(keychain)으로부터의 인증 정보 읽기도 일절 건너뛰는 사양입니다. 이 실행 환경의 인증 변수를 확인해 보니 ANTHROPIC_API_KEY는 설정되어 있지 않았고, OAuth 로그인(Claude Cloud의 스케줄 실행)만으로 가동되고 있었습니다. --bare가 OAuth 읽기를 수행하지 않는 이상, 인증 정보를 찾지 못해 에러가 발생하는 것은 사양대로의 동작이었습니다.

가장 단순한 방법은 환경 변수로 직접 API 키를 전달하는 것입니다.

ANTHROPIC_API_KEY="sk-ant-..." claude --bare -p "1+1은?"

API 키를 하드코딩하고 싶지 않다면, 키를 가져오는 명령어를 반환하는 apiKeyHelper를 settings JSON에 지정합니다.

claude --bare -p "1+1은?" \
--settings '{"apiKeyHelper": "/path/to/get-api-key.sh"}'

get-api-key.sh는 표준 출력(standard output)으로 API 키를 반환하기만 하는 스크립트여도 상관없습니다. CI/CD에서 시크릿 매니저(secret manager)로부터 키를 가져와 전달하는 운영 방식과 궁합이 좋은 방법입니다.

Amazon Bedrock, Google Vertex AI, Microsoft Foundry를 통해 Claude를 이용하고 있는 경우에는 --bare에서도 이들 프로바이더의 통상적인 인증 정보(IAM 역할 등)가 그대로 사용되므로 추가 대응은 필요하지 않습니다1.

--bare는 "어떤 머신에서 실행해도 동일한 결과가 나오는 것"을 목적으로 하는 플래그입니다. OAuth 토큰이나 OS 키체인은 머신별, 사용자별로 상태가 다르기 때문에, 이것들을 읽어버리면 "내 로컬에서는 동작하지만 CI에서는 동작하지 않는다", "A의 환경에서는 동작하지만 B의 환경에서는 동작하지 않는다"와 같은 재현성 문제가 발생합니다. --bare가 인증도 건너뛰고 ANTHROPIC_API_KEY의 명시적 지정을 요구하는 것은, hooks나 CLAUDE.md의 자동 발견을 건너뛰는 것과 마찬가지로 "암묵적인 환경 의존성을 끊어내는" 설계 사상의 일부라고 생각됩니다.

공식 문서는 --bare를 "스크립트 및 SDK 호출 시 권장되는 모드이며, 향후에는 -p의 기본값이 될 것"이라고 명시하고 있습니다1. 현재 claude -p를 CI나 스케줄 실행에 포함하고 있는 경우, OAuth 인증 상태 그대로 --bare로 전환하면 동일한 인증 에러를 겪게 되므로, 전환 전에 ANTHROPIC_API_KEY를 준비해야 한다는 점을 기억해 두는 것이 좋습니다.

인증 외에도 --bare는 다음 항목들을 자동 발견하지 않습니다. 필요하다면 명시적으로 플래그를 통해 전달해야 합니다1.

읽어오고 싶은 것	전달할 플래그
시스템 프롬프트 추가	--append-system-prompt / --append-system-prompt-file
설정	--settings <file-or-json>
MCP 서버	--mcp-config <file-or-json>
커스텀 에이전트	--agents <json>
플러그인	--plugin-dir <path> / --plugin-url <url>

--bare 모드에서도 Bash, 파일 읽기, 파일 편집의 3가지 툴은 이용할 수 있습니다1.

실제로 시도해 보기 전까지는 "--bare

는 단순히 실행 속도가 빨라지는 경량 플래그(lightweight flag)라는 이해였으나, 실제 기기에서 인증 에러(authentication error)를 겪으면서 "hooks나 CLAUDE.md와 마찬가지로, OAuth 인증 또한 '암묵적으로 로드되는 환경 의존성 중 하나'로 취급된다"는 설계의 일관성을 깨달을 수 있었다. Claude Cloud의 스케줄 실행처럼 OAuth로 동작하는 운영 환경에서는, --bare 모드로의 이행은 "실행 속도가 빨라진다"는 장점뿐만 아니라 "API 키 관리를 어떻게 준비할 것인가"라는 비용까지 고려하여 판단할 필요가 있다.

• --bare 모드는 hooks, skills, plugins, MCP servers, auto memory, CLAUDE.md에 더해 OAuth/keychain 인증도 자동 발견(auto-discovery) 대상에서 제외됨

• OAuth 로그인 환경에서 그대로 사용하면 Authentication error가 발생함 (실제 기기에서 확인 완료)

• 회피를 위해서는 ANTHROPIC_API_KEY 또는 apiKeyHelper가 필요함 (Bedrock/Vertex/Foundry는 대상에서 제외)

• 향후 -p의 기본값(default)이 될 예정이므로, OAuth 기반 운영 스크립트는 조기에 API 키로의 전환을 검토할 가치가 있음