만약 당신이 실제 API와 함께 작업하기 위해 Claude Code, Codex 또는 Cursor를 사용한다면, 문제는 매우 빠르게 발생합니다. 에이전트(agent)는 로그인 정보가 필요하지만, 당신의 비밀번호 관리자(password manager)는 이를 노출하지 않도록 설계되어 있기 때문입니다. 채팅창에 API key를 붙여넣으면 그것은 모델의 컨텍스트(context) 안에 남게 됩니다. .env 파일에 secret을 설정하면 에이전트의 bash 도구가 이를 cat으로 읽어 전송할 수도 있습니다. 더 올바른 방법은 secret을 범위(scope)에 따라 런타임(runtime)에 제공하고, LLM의 컨텍스트에 넣지 않는 것입니다. Bitwarden의 새로운 오픈 소스 프로젝트인 Agent Access는 이 문제에 대한 진지한 접근 방식입니다. 이는 로그인 정보를 공유하는 프로토콜, CLI (aac), 그리고 비밀번호 관리자와 원격 프로세스(AI 에이전트, CI runner 또는 스크립트) 사이에 암호화된 터널을 생성하기 위한 Rust + Python SDK로 구성됩니다. 핵심 아이디어는 에이전트가 도메인(domain) 또는 vault item ID에 따라 사용에 필요한 정확한 자격 증명(credential)만 받는다는 것입니다. 에이전트는 전체 vault를 볼 수 없고, .env를 읽을 필요도 없으며, 당신이 프롬프트(prompt)에 secret을 붙여넣을 필요도 없습니다. 이 글은 Agent Access를 설치하고, aac connect를 사용하며, aac run을 사용하고, 이를 Claude Code, Codex, Cursor 워크플로우에 통합하며 Apidog를 사용하여 API를 테스트하는 방법을 안내합니다. AI 에이전트의 API 자격 증명 위생(hygiene)에 대한 더 넓은 맥락이 필요하다면, 'AI 에이전트의 API 자격 증명 보안 방법'을 더 참조하십시오. Agent Access란 무엇인가? Agent Access는 Bitwarden이 구축한 참조 구현을 포함한 개방형 프로토콜입니다. 목표는 어떤 비밀번호 관리자라도 프로바이더(provider) 역할을 할 수 있도록 하는 것입니다. CLI aac는 Noise 프로토콜을 사용하여 종단 간(end-to-end) 암호화 터널을 생성합니다. 모델은 두 측면으로 구성됩니다: Provider: 요청을 수신하고 어떤 자격 증명을 반환할지 결정합니다. Consumer: 작업을 실행하기 위해 자격 증명이 필요한 에이전트, 스크립트 또는 CI job입니다. Consumer는 다음과 같이 자격 증명을 요청할 수 있습니다: 도메인(예: github.com), vault item ID. Consumer는 전체 vault를 나열할 수 없습니다. Provider 또한 자격 증명을 제공한 후 consumer가 그것으로 무엇을 하는지 알 수 없습니다. 감사 로그(Audit log)는 양측 모두에 존재합니다. 현재 Agent Access는 초기 프리뷰(preview) 단계에 있습니다.

프로젝트의 README는 API와 프로토콜이 변경될 수 있음을 경고합니다. Bitwarden 또한 민감한 자격 증명(credential)을 LLM이나 AI agent에 직접 입력해서는 안 된다고 명시하고 있습니다. 따라서 권장되는 패턴은 다음과 같습니다: aac run을 통해 런타임(runtime) 시점에 secret을 가져오고, 이를 환경 변수(environment variable) 형태로 자식 프로세스(child process)에 주입하며, secret이 agent의 프롬프트(prompt)나 로그(log)에 나타나지 않도록 하는 것입니다.

이것이 왜 중요할까요? AI 코딩 agent는 더 이상 단순히 파일만 수정하지 않습니다. Claude Code, Codex, Cursor 및 유사한 도구들은 다음과 같은 작업을 수행할 수 있습니다:

• 리포지토리(repository) 읽기
• 테스트 실행
• API 호출
• 풀 리퀘스트(pull request) 생성
• 배포 스크립트 실행
• CI와 상호작용

이러한 단계들은 대개 자격 증명(credential)을 필요로 합니다. 만약 자격 증명이 .env, 쉘 히스토리(shell history), 로그 또는 LLM의 컨텍스트(context)에 포함되어 있다면, 리스크는 급격히 증가합니다. Postman의 API 키 유출 사고는 인간이 조작할 때조차 자격 증명 관리(credential management)가 얼마나 어려운지를 보여줍니다. 자동화된 agent를 워크플로(workflow)에 추가할 때는 더욱 엄격한 접근 방식이 필요합니다.

적용해야 할 원칙:

• agent를 과도하게 신뢰하지 마십시오.
• agent에게 더 적은 민감 데이터를 제공하십시오.

Agent Access는 프로토콜 수준에서 이 작업을 수행합니다:

• 자격 증명의 범위(scope) 제한
• 데이터 암호화
• 런타임(runtime) 시점에 secret 가져오기
• 프로세스 종료 시 secret 소멸
• agent가 실제 값을 볼 필요가 없음

전통적인 키 관리(key management) 도구들도 여전히 중요합니다. API 키 관리 도구에 대해 더 알아보세요. Agent Access의 차별점은 agent 및 스크립트 런타임(script runtime) 유스케이스(use case)를 위해 직접 설계되었다는 점입니다.

aac 설치
사용 중인 운영체제에 맞는 버전을 선택하세요.

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
최신 릴리스(release) 페이지에서 aac-windows-x86_64.zip을 다운로드한 후, PATH에 포함된 폴더에 압축을 해제하세요.

설치 확인: aac --help

Bitwarden CLI (bw)가 PATH에 포함되어 있다면, aac는 이를 기본 자격 증명 제공자 (credential provider)로 사용합니다. 아직 Bitwarden CLI를 사용하지 않는다면, 데모 제공자 (demo provider)로 빠르게 테스트해 볼 수 있습니다: aac --provider example --help

퀵스타트 (Quickstart): 페어링 및 자격 증명 가져오기

Vault가 있는 컴퓨터 또는 제공자 (provider)에서 리스너 (listener)를 실행하세요. 보통은 사용자의 노트북입니다: aac listen

이 명령은 페어링 토큰 (pairing token)을 출력합니다. 소비자 (consumer) 측에서 — 원격 컴퓨터, CI 러너 (CI runner), 또는 동일한 컴퓨터의 다른 터미널일 수 있습니다 — 토큰을 사용하여 연결하고 도메인별로 자격 증명을 요청합니다: 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을 파싱하여 필요한 필드를 사용할 수 있습니다.

도메인 대신 Vault 아이템 ID (vault item ID)로 자격 증명을 가져오고 싶다면: aac connect --id <vault-item-id> --output json

주의: 아이템에 TOTP 설정이 있는 경우 --id와 --domain은 서로 배타적이며, TOTP 코드는 동일한 페이로드 (payload) 내에 포함됩니다. 비밀 정보 (secret)가 포함될 수 있으므로 이 출력을 CI 로그에 인쇄하지 마세요.

권장 패턴: aac run

aac connect는 JSON을 직접 처리할 때 유용합니다. 하지만 AI 에이전트 (AI agent) 및 CI의 경우, 더 안전한 패턴은 보통 aac run입니다. aac run은 자격 증명을 가져온 후, 필요한 필드들을 환경 변수 (environment variables) 형태로 주입하여 하위 프로세스 (child process)를 실행합니다. 비밀 정보는 stdout으로 출력될 필요가 없고, 디스크에 기록될 필요도 없으며, 에이전트의 프롬프트 (prompt)에 나타날 필요도 없습니다.

특정 필드 주입하기

예를 들어 psql 명령에 비밀번호와 사용자 이름을 주입하는 경우:
aac run \
--domain example.com \
--env DB_PASSWORD=password \
--env DB_USER=username \
-- psql

psql 프로세스 내에서 다음과 같이 읽을 수 있습니다: $DB_PASSWORD, $DB_USER

기본 접두사 (prefix)와 함께 모든 필드 주입하기:
aac run --domain example.com --env-all -- ./deploy.sh
환경 변수에는 AAC_ 접두사가 붙게 됩니다.

--env-all과 변수 이름 재정의(override)를 결합하면 다음과 같습니다:

aac run \
--domain example.com \
--env-all \
--env CUSTOM_PW=password \
-- ./deploy.sh

매핑 가능한 필드는 다음과 같습니다: username, password, totp, uri, notes, domain, credential_id

이것이 Bitwarden이 AI agent를 위해 권장하는 모델입니다. LLM의 컨텍스트(context)에 secret을 직접 넣는 대신, agent가 스크립트를 실행하도록만 지시합니다:

aac run --domain api.stripe.com --env-all -- ./deploy.sh

Agent는 명령어를 볼 수 있지만, secret의 실제 값은 볼 수 없습니다. Secret은 오직 하위 프로세스인 deploy.sh 내에서만 존재합니다. 이는 'AI 에이전트의 API 자격 증명 보안 방법'에서 언급된 격리(isolation) 원칙을 구체적인 도구를 통해 구현한 것입니다.

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 구현체를 사용합니다. 실제 애플리케이션에서는 데모 예시처럼 print()로 password를 출력하는 것을 피하십시오. 자격 증명(credential)을 사용하는 클라이언트나 프로세스에 직접 전달해야 합니다.

Rust SDK

Rust는 라이브러리 수준에서 RemoteClient 인터페이스를 제공합니다. 참조 예제는 examples/rust-remote/에 있습니다.

다음과 같은 경우에 Rust SDK를 사용하십시오:

• 내부 CLI를 작성할 때
• 빌드 러너(build runner) 서비스를 만들 때
• 컴파일된 바이너리가 필요한 경우
• 제한된 환경에서 실행되는 컨슈머(consumer)를 만들 때

이미 엔터프라이즈급 secret 시스템을 갖춘 팀의 경우, Agent Access는 HashiCorp Vault 또는 Azure Key Vault와 같은 통합을 보완할 수 있습니다. 이는 기업용 Vault를 완전히 대체하는 것이 아니라, 개발자 노트북, 로컬 스크립트 및 CI 러너(runner)에 적합합니다.

AI coding agent인 Claude Code와 통합하기

Claude Code가 직접 deploy를 호출하는 대신, 래퍼 스크립트(wrapper script)를 만들어 호출하도록 설정하십시오.

deploy.sh

#!/usr/bin/env bash
set -euo pipefail
aac run --domain prod.example.com --env-all -- ./run-deploy.sh

실행 권한 부여:
chmod +x deploy.sh

그 다음 Claude Code의 워크플로우를 다음과 같이 설정하십시오:
./deploy.sh

Claude Code는 스크립트와 aac run 명령어만 볼 수 있습니다. 실제 자격 증명 (Credential)은 하위 프로세스인 run-deploy.sh 내에서만 나타납니다.

GitHub Actions를 사용하는 Claude Code의 경우, 유사한 패턴을 CI로 확장할 수 있습니다: 러너 (runner)에 aac를 설치하고, 러너를 테스트나 배포를 실행하는 프로바이더 (provider)와 연결하여 aac run을 통해 실행함으로써 리포지토리나 OpenAI Codex 프롬프트에 API 키를 저장하지 않도록 합니다.

Codex CLI를 사용할 때도 모델이 비밀 정보 (secret)가 필요한 도구를 직접 호출하는 대신 래퍼 스크립트 (wrapper script)를 호출하도록 해야 합니다. 예시:

test-api.sh

#!/usr/bin/env bash
set -euo pipefail
aac run --domain staging.example.com --env API_TOKEN=password -- ./run-api-tests.sh

Codex는 ./test-api.sh를 실행할 수 있지만, API_TOKEN이 무엇인지는 알 필요가 없습니다. 휴대폰에서 작성된 Codex 관련 글은 Codex의 더 넓은 사용 범위를 다룹니다. Agent Access는 해당 워크플로우 내의 자격 증명 (credential) 문제를 해결합니다.

Cursor

Cursor의 경우, 실제 패턴은 터미널 명령어나 Composer 워크플로우를 aac run으로 감싸는 것입니다. 예시:

local-contract-test.sh

#!/usr/bin/env bash
set -euo pipefail
aac run --domain api.example.com --env-all -- npm run test :contract

Cursor는 주로 로컬에서 실행되므로, 리스너 (listener)를 동일한 머신에서 실행할 수 있습니다: aac listen.
그 후 테스트나 배포 스크립트는 평소처럼 실행되지만, 비밀 정보 (secret)는 .env 파일에 존재하지 않습니다.

OpenClaw

Agent Access는 처음부터 리포지토리 내의 SKILL.md 파일 형태로 OpenClaw의 공식 스킬 (SKILL)을 갖추고 있습니다. 팀이 OpenClaw 방식의 워크플로우를 사용한다면, 이것이 현재 가장 좋은 내장 통합 방식입니다. 이 스킬은 다음과 같은 방법을 알고 있습니다: 프로토콜에 따라 연결하기, 자격 증명 (credential) 가져오기, 다운스트림 도구 (downstream tool)에 자격 증명 전달하기.

Agent Access를 더 넓은 자격 증명 관리 (credential management) 맥락에서 이해하려면 OpenClaw API 키 가이드를 참조하십시오.

Agent Access 보안 모델은 세 가지 주요 보호 지점을 제공합니다.

2. Noise Protocol Framework을 통해 Consumer와 Provider 간의 Noise Traffic으로 이루어지는 종단간 암호화 (End-to-End Encryption)가 적용됩니다. 이는 WireGuard 및 Signal과 같은 시스템에서 사용되는 프로토콜 계층입니다. 2. Credential의 범위가 제한됩니다. Consumer는 자신이 요청한 credential, 즉 하나의 도메인(domain) 또는 하나의 vault item ID만 수신합니다. 전체 vault를 탐색하거나 나열할 수 없습니다. 3. Secret을 디스크에 기록할 필요가 없습니다. aac run을 사용하면 secret이 환경 변수 (environment variable)를 통해 하위 프로세스로 전달됩니다. 다음 작업이 필요하지 않습니다: .env 기록, stdout 출력, shell history 저장, LLM 프롬프트에 붙여넣기.

Agent Access가 해결하지 못하는 문제
Agent Access는 절대적인 보호 계층이 아닙니다. 다음의 한계점을 반드시 이해해야 합니다.

Consumer가 침해된 경우: 만약 에이전트(agent)나 하위 프로세스가 악의적이라면, 이미 부여된 credential이 유출될 수 있습니다. 여기서의 방어 전략은 credential의 범위를 최소화하는 것이지, Consumer의 안전을 항상 보장하는 것이 아닙니다.

Provider가 침해된 경우: Bitwarden vault 또는 귀하의 Provider가 침해(compromise)된 경우, Agent Access는 원본 secret을 보호할 수 없습니다.

Secret을 LLM에 붙여넣는 경우: 만약 credential을 채팅창에 복사한다면, 그 뒤의 모든 프로토콜 계층은 무의미해집니다. 프로젝트의 README에는 다음과 같이 명시되어 있습니다: 민감한 credential을 LLM이나 AI agent에 직접 입력하지 마십시오. secret을 붙여넣는 대신 aac run을 사용하십시오.

일반적인 워크플로우: 에이전트가 코드를 작성하고, Apidog가 API를 검증합니다.
에이전트 기반의 API 변경을 위한 테스트 파이프라인을 구축 중이라면, API 팀을 위한 실제적인 워크플로우는 다음과 같을 수 있습니다:

1. 에이전트가 코드 작성: Claude Code, Codex 또는 Cursor가 엔드포인트(endpoint)를 수정하고 풀 리퀘스트(pull request)를 생성합니다.
2. CI에서 테스트 실행: 테스트 러너(test runner)가 aac run을 호출하여 범위가 제한된 API key를 가져온 뒤, 스테이징(staging) 환경에서 테스트를 실행합니다.
3. Apidog가 컨트랙트(contract) 검증: Apidog가 별도의 CI 단계로서 OpenAPI 컨트랙트 검사를 실행하며, 이 역시 aac run을 통해 수행됩니다.

CI 스크립트 예시:

#!/usr/bin/env bash
set -euo pipefail

aac run \
  --domain staging.example.com \
  --env API_TOKEN=password \
  -- npm run test :contract

결과:

• 에이전트가 코드를 배포합니다.
• API 컨트랙트가 검증됩니다.
• secret이 리포지토리(repo)에 포함되지 않습니다.
• secret이 프롬프트(prompt)에 나타나지 않습니다.
• secret을 .env에 저장할 필요가 없습니다.

더 보기
에이전트 주도형(agent-driven) API 변경을 위한 테스트 파이프라인을 구축 중이라면, 귀하의 AI 에이전트가 API를 호출하는 방식을 확인하는 방법을 참조하십시오.

알아야 할 제한 사항

여전히 Preview API 단계이며 프로토콜이 변경될 수 있습니다. 유지보수 예산이 충분하지 않다면 v0 버전에 프로덕션 워크플로우 (production workflow)를 고정하지 마십시오.

Bitwarden CLI Provider는 기본적으로 bw를 사용해야 합니다. Bitwarden CLI를 먼저 설치하거나, 테스트를 위해 --provider example을 사용하십시오.

안정적인 설정 파일이 아직 없음
현재 Agent Access는 주로 플래그 (flag)에 의해 제어됩니다. 반복되는 워크플로우는 스크립트 (script)로 패키징해야 합니다.

기본적인 위생 (hygiene) 수칙을 대체할 수 없음
여전히 키를 로테이트 (rotate)하고, 최소한의 스코프 (scope)를 사용하며, 시크릿 (secret)을 로그에 남기지 말고, 프롬프트 (prompt)에 시크릿을 넣지 말아야 합니다.

FAQ

Agent Access는 무료인가요?
네. CLI, SDK 및 프로토콜은 Bitwarden의 GitHub organization 내에서 오픈 소스로 제공됩니다. Bitwarden을 Vault로 사용하는 경우, Bitwarden 비용은 귀하가 사용 중인 요금제에 따라 달라집니다.

Bitwarden 이외의 다른 비밀번호 관리자와도 작동하나요?
프로토콜은 특정 공급업체에 의존하지 않도록 설계되었습니다. 현재 참조 구현 (reference implementation)은 Bitwarden과 예시 프로바이더 (example provider)를 지원합니다. 다른 프로바이더들도 향후 이 프로토콜에 따라 구현될 수 있습니다.

비밀번호 관리자 없이도 사용할 수 있나요?
네, 테스트를 위해...