실제 API와 관련된 Claude Code, Codex 또는 Cursor를 사용하면 문제가 발생합니다. 에이전트가 자격 증명을 필요로 하고 비밀번호 관리자는 이를 안전하게 보관하기를 원합니다. 일반적인 해결책은 좋지 않습니다. API 키를 채팅에 붙여넣으면 모델의 컨텍스트 창에 영원히 남게 됩니다. 비밀을 .env 파일에 넣으면 에이전트의 bash 도구가 아무렇지 않게 이를 cat 하여 어딘가로 전송할 것입니다. 대부분의 팀은 그저 기준을 낮춥니다.
Bitwarden의 새로운 오픈 소스 프로젝트인 Agent Access는 이 문제를 해결하려는 첫 번째 진지한 시도입니다. 이는 자격 증명 공유 프로토콜이자 CLI(aac)이며, 비밀번호 관리자와 원격 프로세스(에이전트, CI 러너, 스크립트) 사이에 암호화된 터널을 구축하는 Rust + Python SDK입니다. 에이전트는 단일 도메인 또는 저장소 항목으로 범위가 지정된 필요한 비밀을 저장소를 전혀 보지 않고도 얻습니다.
이 가이드에서는 Agent Access가 제공하는 것, 설치 방법, aac connect 및 aac run 사용 방법, Claude Code, Codex 및 Cursor 워크플로에 어떻게 통합되는지, 그리고 AI 에이전트 API 자격 증명을 보호하는 방법에서 다루는 자격 증명 위생 패턴과 어떻게 연관되는지 설명합니다.
Agent Access란 무엇인가 (한 단락)
Agent Access는 Bitwarden이 구축했지만 모든 비밀번호 관리자가 채택할 수 있도록 설계된 오픈 프로토콜 및 참조 구현입니다. CLI(aac)는 Noise 프로토콜을 사용하여 종단간 암호화된 터널을 생성합니다. "제공자(provider)"는 연결 요청을 수신하고, "소비자(consumer)"(에이전트, 스크립트, CI 작업)는 제공자에 연결하여 도메인 또는 저장소 항목 ID로 자격 증명을 요청합니다. 제공자는 무엇을 다시 보낼지 결정합니다. 소비자는 전체 저장소를 결코 보지 않습니다. 제공자는 소비자가 자격 증명으로 무엇을 하는지 결코 보지 않습니다. 감사 추적은 양측에 존재합니다.
현재 초기 미리 보기 단계입니다. 프로젝트 README는 "API 및 프로토콜은 변경될 수 있다"고 경고하며 "민감한 자격 증명을 LLM 또는 AI 에이전트에 직접 입력하는 것을 권장하지 않는다"고 명시합니다. Bitwarden이 대신 권장하는 패턴은 이 가이드의 절반을 차지합니다: aac run을 통한 환경 주입으로, 에이전트의 컨텍스트 창에 노출하지 않고 비밀을 프로세스에 주입합니다.
2026년에 이것이 중요한 이유
AI 코딩 에이전트는 샌드박스를 넘어섰습니다. Claude Code, Codex, Cursor 및 기타 에이전트는 이제 저장소를 읽고, 테스트를 실행하고, API를 호출하며, 코드를 배포합니다. 이 모든 단계에서 자격 증명이 필요합니다. Postman API 키 노출 사건은 인간만 부주의할 때 자격 증명 위생이 얼마나 심각하게 확장되는지를 보여주었으며, 인간과 에이전트가 함께하면 더욱 나빠집니다.
올바른 해답은 "에이전트를 더 신뢰하라"가 아니라 "에이전트에 더 적게 제공하라"입니다. Agent Access는 프로토콜 수준에서 이를 수행합니다: 범위가 지정된 자격 증명, 전송 중 암호화, 런타임에 가져오기, 프로세스 종료 시 소멸. 현재 관행(API 키 관리 도구가 나머지 상황을 다룹니다)과 비교하면, Agent Access는 에이전트의 경우를 위해 특별히 구축된 첫 번째 솔루션입니다.
설치
플랫폼을 선택하세요.
macOS (Apple Silicon)
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-aarch64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
macOS (Intel)
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-macos-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Linux (x86_64)
curl -L https://github.com/bitwarden/agent-access/releases/latest/download/aac-linux-x86_64.tar.gz | tar xz
sudo mv aac /usr/local/bin/
Windows (x86_64)
최신 릴리스 페이지에서 `aac-windows-x86_64.zip`을 다운로드하여 PATH에 있는 아무 디렉토리에나 압축을 해제하세요.
`aac --help`를 사용하여 설치를 확인하세요. Bitwarden CLI(bw)도 PATH에 있으면 aac는 이를 기본 자격 증명 제공자로 사용하며, 그렇지 않은 경우 실험하는 동안 내장된 데모 제공자를 사용하려면 --provider example을 전달하세요.
빠른 시작: 자격 증명 페어링 및 가져오기
두 가지 명령입니다. 일반적으로 노트북과 같이 저장소를 가지고 있는 컴퓨터에서 aac listen을 실행하세요:
aac listen
리스너는 페어링 토큰을 출력합니다. 소비자 측(원격 컴퓨터, CI 러너, 또는 테스트하는 동안 동일 호스트의 다른 셸)에서 한 번의 호출로 페어링하고 가져오세요:
aac connect --token <pairing-token> --domain github.com --output json
다음과 같은 결과를 얻을 수 있습니다:
{
"credential": {
"notes": null,
"password": "alligator5",
"totp": null,
"uri": "https://github.com",
"username": "example"
},
"domain": "github.com",
"success": true
}
이 JSON 형식은 프로토콜의 안정적인 계약입니다. 스크립트는 원하는 방식으로 이를 파싱할 수 있습니다. 도메인 대신 저장소 항목 ID로 가져오려면:
aac connect --id <vault-item-id> --output json
--id와 --domain은 상호 배타적이므로 하나를 선택하세요. 저장소 항목에 TOTP 코드가 구성되어 있으면 동일한 페이로드를 통해 흐릅니다.
핵심 기능: 환경 주입을 위한 aac run
스크립트가 JSON을 처리하는 방법을 알고 있다면 aac connect도 좋습니다. 더 큰 패턴은 aac run입니다. 이는 자격 증명을 가져와서 비밀을 환경 변수로 주입하여 자식 프로세스를 실행합니다. 표준 출력으로 나가지 않고, 디스크에 기록되지 않으며, aac를 생성한 어떤 것에도 보이지 않습니다.
특정 필드를 주입합니다:
aac run --domain example.com --env DB_PASSWORD=password --env DB_USER=username -- psql
AAC_ 접두사가 붙은 모든 필드를 주입합니다:
aac run --domain example.com --env-all -- deploy.sh
기본값과 재정의를 결합합니다:
aac run --domain example.com --env-all --env CUSTOM_PW=password -- deploy.sh
사용 가능한 필드는 username, password, totp, uri, notes, domain, credential_id입니다.
이것은 Bitwarden이 AI 에이전트 사용에 적극적으로 권장하는 패턴입니다: Claude Code 또는 Codex를 aac run을 호출하는 스크립트로 지정하면, 비밀이 에이전트의 트랜스크립트에 나타나지 않습니다. 모델은 암호가 아닌 aac run --domain api.stripe.com --env-all -- ./deploy.sh 명령을 봅니다. 에이전트가 나중에 “$STRIPE_API_KEY의 값은 무엇입니까?”라고 물으면, deploy.sh 하위 프로세스에 한정되었기 때문에 “볼 수 없습니다”라고 대답합니다.
AI 에이전트 API 자격 증명을 보호하는 방법에서 다룬 동일한 격리 원칙을 실제 도구로 구체화한 것입니다.
Python 및 Rust SDK
CLI 호출만으로는 충분하지 않은 경우(예: Agent Access를 자체 애플리케이션에 임베드하는 경우) 일류 바인딩이 제공됩니다.
Python
from agent_access import RemoteClient
client = RemoteClient("python-remote")
client.connect(token="ABC-DEF-GHI")
cred = client.request_credential("example.com")
print(cred.username, cred.password)
client.close()
Python 모듈은 PyO3 기반이므로, 복잡한 작업은 Rust에서 이루어지며 내부적으로 동일한 Noise 프로토콜 구현을 사용합니다.
Rust
Rust SDK는 RemoteClient 인터페이스를 일류 라이브러리로 노출합니다. 참조 구현은 저장소의 examples/rust-remote/ 아래에 있습니다. 소비자를 Rust로 직접 작성할 때 사용하세요. CLI 도구, 빌드 러너, 컴파일된 바이너리 배포를 원하는 모든 서비스에서 흔히 사용됩니다.
이미 API 툴링을 제공하는 애플리케이션 팀의 경우, SDK 패턴은 HashiCorp Vault 또는 Azure Key Vault 통합과 깔끔하게 어울립니다. Agent Access는 엔터프라이즈 계층의 대체재는 아니지만, 개발자 노트북 및 CI 러너 사용 사례에 더 적합합니다.
AI 코딩 에이전트와 통합하기
Claude Code
Claude Code가 호출하는 스크립트에 aac run을 연결하세요. 배포 작업의 예시:
# deploy.sh
#!/usr/bin/env bash
aac run --domain prod.example.com --env-all -- ./run-deploy.sh
이 스크립트를 프로젝트에 추가하고 Claude Code 워크플로를 이 스크립트에 연결하면, 에이전트는 프롬프트에 자격 증명 없이 ./deploy.sh를 호출합니다. Claude Code GitHub Actions 통합은 동일한 패턴을 CI로 확장합니다: 러너에 aac를 설치하고, 제어 평면에서 실행되는 Bitwarden 저장소 제공자와 페어링하면, GitHub Actions는 작업 시점에 범위가 지정된 자격 증명을 상속받습니다.
OpenAI Codex
동일한 패턴이 Codex의 CLI에서도 작동합니다. Codex의 도구 호출 계층은 모델에 명령을 노출하고, 모델이 호출하는 스크립트는 aac run을 통해 비밀을 모델의 컨텍스트 외부로 유지합니다. 최근 휴대폰으로 Codex 사용하기 게시물은 Codex의 더 넓은 표면을 다루며, 이는 그와 짝을 이루는 자격 증명 관련 측면입니다.
Cursor
Cursor의 터미널 명령과 Composer 워크플로의 경우, 동일한 aac run으로 래핑된 스크립트가 수정 없이 작동합니다. Cursor의 강점은 로컬 편집이므로, 리스너는 일반적으로 동일한 컴퓨터에서 실행됩니다.
OpenClaw (Anthropic 생태계 스킬)
Agent Access는 기본적으로 공식 OpenClaw 스킬을 제공합니다 (SKILL.md 파일은 저장소에 있습니다). OpenClaw 스타일 스킬을 사용하는 팀에게 이것은 오늘날 가장 세련된 통합입니다: 이 스킬은 프로토콜 형태를 알고, 자격 증명을 가져와서 스킬이 노출하는 모든 다운스트림 도구에 전달합니다. OpenClaw API 키 가이드는 해당 생태계의 더 넓은 자격 증명 관리 스토리를 다룹니다.
간단히 설명하는 보안 모델
확인해 볼 만한 세 가지 주장:
- Noise를 통한 종단간 암호화. 소비자와 제공자 간의 트래픽은 WireGuard와 Signal이 사용하는 것과 동일한 핸드셰이크 계열인 Noise 프로토콜 프레임워크로 암호화됩니다. 전송 계층은 가장 약한 링크가 아닙니다.
- 범위가 지정된 자격 증명. 소비자는 요청한 것(하나의 도메인 또는 하나의 저장소 항목 ID)만 얻습니다. 저장소를 열거할 수 없습니다.
- 기본적으로 소비자 디스크에 비밀 없음.
aac run은 환경 변수를 통해 비밀을 자식 프로세스로 전달합니다. 파일에 아무것도 기록되지 않고, 표준 출력에 나타나지 않으며, 셸 히스토리에도 남지 않습니다.
Agent Access가 보호하지 않는 것:
- 손상된 소비자 프로세스. 에이전트가 악의적이거나 손상된 경우, 범위가 지정된 자격 증명도 유출될 수 있습니다. 방어는 프로토콜이 아닌 범위에 있습니다.
- 손상된 제공자. Bitwarden 저장소 자체가 손상된 경우, 이 계층은 아무런 도움이 되지 않습니다.
- LLM 컨텍스트 창에 직접 비밀 입력. README는 이에 대해 명확하게 명시합니다: “민감한 자격 증명을 LLM 또는 AI 에이전트에 직접 입력하는 것을 권장하지 않습니다.”
aac run이 해결책입니다.
일반적인 패턴: 에이전트가 API를 호출하고, Apidog가 테스트합니다
대부분의 팀이 정착하게 될 루프는 다음과 같습니다:
- 에이전트가 코드를 작성합니다. Claude Code, Codex 또는 Cursor는 엔드포인트와 관련된 PR을 엽니다.
- CI가 테스트를 실행합니다. 테스트 러너는
aac run을 호출하여 API 키를 가져오고, 스테이징 배포에 대해 테스트 스위트를 실행합니다. - Apidog가 계약을 확인합니다. Apidog는 별도의 CI 단계에서
aac run을 통해 OpenAPI 계약 테스트를 실행하며, 에이전트가 키를 보지 못하게 합니다.
결과: 에이전트는 코드를 배포하고, 계약은 유지되며, 비밀은 저장소를 벗어나지 않습니다. AI 기반 변경 사항 테스트에 대한 더 넓은 플레이북은 API를 호출하는 AI 에이전트를 테스트하는 방법에 있습니다.
제한 사항 및 경고
- 초기 미리 보기. API 및 프로토콜은 변경될 수 있습니다. 후속 재작성에 대한 예산 없이 프로덕션 워크플로를 v0 프로토콜에 고정하지 마세요.
- 기본적으로 Bitwarden CLI 필요. 기본 제공자는
bw입니다. 먼저 Bitwarden CLI를 설치하거나, 테스트하는 동안 데모 제공자를 사용하려면--provider example을 전달하세요. - 아직 설정 파일 없음. Agent Access는 현재 플래그 기반으로 작동합니다. 반복적인 호출에는 스크립팅이 필요합니다.
- LLM 프롬프트에 비밀을 붙여넣지 마세요. Agent Access가 설치되어 있더라도, 자격 증명을 채팅 창에 복사하면 어떤 프로토콜도 당신을 구할 수 없습니다.
자주 묻는 질문
Agent Access는 무료인가요?
네. CLI, SDK 및 프로토콜은 Bitwarden GitHub 조직에서 오픈 소스로 제공됩니다. Bitwarden을 저장소로 사용하는 경우 Bitwarden 비용은 여전히 지불해야 합니다.
Bitwarden 외 다른 비밀번호 관리자와도 작동하나요?
이 프로토콜은 벤더 중립적으로 설계되었습니다. 참조 구현에는 Bitwarden 지원과 예시 제공자가 함께 제공되며, 다른 벤더들도 시간이 지남에 따라 자체 제공자를 출시할 것으로 예상됩니다.
비밀번호 관리자 없이 사용할 수 있나요?
테스트를 위해서는 가능합니다. 내장된 데모 제공자를 사용하려면 --provider example을 전달하세요. 프로덕션 환경에서는 실제 제공자(현재 Bitwarden, 로드맵에 다른 제공자 있음)가 필요합니다.
소비자 프로세스에 네트워크 액세스가 필요한가요?
소비자는 제공자의 리스너에 도달하기 위해 네트워크 액세스가 필요합니다. 리스너와 소비자가 동일한 호스트에 있는 경우 로컬 전용 설정도 작동합니다.
이것은 .env 파일과 어떻게 다른가요?
.env 파일은 디스크에 저장되고, 실수로 리포지토리에 체크인되며, 에이전트가 실행할 수 있는 모든 것에 의해 읽힐 수 있습니다. aac run은 비밀을 프로세스 메모리에만 보관하며, 하위 프로세스에만 범위가 지정되고, 종료되면 사라집니다.
HashiCorp Vault 또는 AWS Secrets Manager를 대체하나요?
아니요. 엔터프라이즈 저장소는 대규모 서비스 간 비밀 관리를 위한 올바른 도구입니다. Agent Access는 전체 엔터프라이즈 저장소가 과도한 개발자 노트북 및 CI 러너의 격차를 메워줍니다.
Anthropic, OpenAI 또는 기타 에이전트 벤더들이 이를 직접 통합할 예정인가요?
아직 발표되지 않았습니다. 현재 통합 모델은 "스크립트를 aac run으로 래핑하는 것"입니다. 에이전트 벤더의 직접적인 일류 지원은 자연스러운 다음 단계이지만 아직 출시되지 않았습니다.
버그를 보고하거나 기여하려면 어떻게 해야 하나요?
GitHub 저장소에서 가능합니다. 이슈, PR 및 프로토콜 논의는 모두 그곳에서 이루어집니다.
지금 시도해 보세요
aac를 설치하고, 노트북에서 aac listen을 실행하고, 다른 터미널에서 aac connect --provider example --domain test.com --output json을 실행하세요. JSON이 반환되는지 확인하세요. 이것이 가장 작은 종단간 루프입니다. 그 다음, 예시 제공자를 bw로 바꾸고, 실제 스크립트를 aac run으로 래핑한 다음, AI 에이전트에 API 키를 붙여넣는 것을 멈추세요.
워크플로의 API 테스트 측면을 위해 Agent Access를 Apidog와 페어링하면 깔끔한 분리가 이루어집니다: 저장소는 비밀을 보관하고, Apidog는 계약을 테스트하며, 에이전트는 코드를 배포하고, 어떤 자격 증명도 평문으로 컴퓨터를 벗어나지 않습니다.