AI 에이전트 보안을 위한 비밀 관리 게이트웨이, OneCLI 기술 정리

이 글에서는 AI 에이전트 환경에서 API 키와 같은 민감한 인증 정보를 안전하게 관리하기 위해 등장한 오픈소스 게이트웨이인 **OneCLI**를 소개합니다.
OneCLI가 왜 필요하게 되었는지, 어떤 구조로 동작하는지, 그리고 실제로 어떻게 사용할 수 있는지를 기술적인 관점에서 정리해, AI 에이전트 기반 시스템을 설계·운영하는 분들이 전체 흐름을 쉽게 이해할 수 있도록 설명합니다.

반응형

---

AI 에이전트 환경에서의 보안 문제

AI 에이전트는 외부 서비스와의 연동을 전제로 동작합니다.
LLM 기반 에이전트가 데이터베이스, 결제 API, SaaS 도구 등 수십 개의 API를 호출하는 환경은 이제 흔합니다.

하지만 이 구조에는 치명적인 문제가 있습니다.

• 각 에이전트에 API 키를 직접 포함해야 함
• 키 유출 시 피해 범위가 큼
• 키 교체·권한 관리가 어려움
• 어떤 에이전트가 어떤 API를 호출했는지 추적하기 어려움

OneCLI는 바로 이 지점에서 출발한 솔루션입니다.

---

OneCLI란 무엇인가

OneCLI는 AI 에이전트와 외부 API 사이에 위치하는 보안 게이트웨이입니다.
에이전트는 실제 API 키를 전혀 알지 못한 채, 평범한 HTTP 요청만 전송합니다.

핵심 개념은 다음과 같습니다.

• API 키는 OneCLI에 한 번만 저장
• 에이전트에는 **가짜 키(placeholder)**만 제공
• 게이트웨이가 요청을 가로채 실제 키를 주입
• 에이전트는 끝까지 비밀 정보를 보지 않음

즉, 인증과 비밀 관리를 중앙 집중화하는 구조입니다.

---

OneCLI가 만들어진 배경

OneCLI는 다음과 같은 현실적인 문제를 해결하기 위해 설계되었습니다.

• AI 에이전트 수가 늘어날수록 보안 관리 복잡도 증가
• 에이전트 코드에 키를 넣는 방식은 근본적으로 위험
• 키 회전, 접근 제어, 감사 로그를 한 곳에서 관리할 필요성

이 문제를 해결하기 위해 OneCLI는 단일 게이트웨이 기반 인증 처리라는 접근 방식을 선택했습니다.

---

OneCLI 동작 방식 정리

OneCLI의 요청 흐름은 다음과 같습니다.

1. 사용자는 실제 API 키를 OneCLI에 저장
2. 에이전트에는 FAKE_KEY와 같은 가짜 키를 전달
3. 에이전트가 HTTP 요청을 게이트웨이를 통해 전송
4. 게이트웨이가 요청의 호스트·경로 패턴을 분석
5. 일치하는 실제 키를 복호화하여 요청 헤더에 주입
6. 외부 API로 정상 요청 전송

중요한 점은 실제 키는 요청 시점에만 복호화되며, 에이전트 메모리나 로그에 남지 않는다는 것입니다.

---

OneCLI 아키텍처 구성

OneCLI는 다음과 같은 구성 요소로 이루어져 있습니다.

Rust Gateway

• 고성능 HTTP 게이트웨이
• HTTPS MITM 방식으로 요청 가로채기
• Proxy-Authorization 헤더를 통한 에이전트 인증
• 메모리 안전성을 보장하는 Rust 기반 구현

Web Dashboard

• Next.js 기반 웹 애플리케이션
• 에이전트, 시크릿, 권한 관리 UI 제공
• 게이트웨이가 사용하는 내부 API 제공

Secret Store

• AES-256-GCM 방식으로 암호화된 시크릿 저장소
• 요청 시점에만 복호화
• 호스트·경로 패턴 기반 시크릿 매칭

---

주요 기능 정리

OneCLI가 제공하는 핵심 기능은 다음과 같습니다.

• 에이전트 코드 수정 없는 투명한 인증 처리
• AES-256-GCM 기반 암호화된 시크릿 저장
• 호스트 및 경로 패턴 매칭을 통한 정밀한 키 주입
• 멀티 에이전트 지원 및 권한 스코프 분리
• Docker Compose 기반의 간단한 초기 실행
• 로컬 단일 사용자 모드 및 Google OAuth 팀 모드
• Bitwarden 등 외부 Vault 연동 지원

---

빠르게 시작하는 방법

로컬 환경에서 OneCLI를 실행하는 가장 빠른 방법은 Docker Compose입니다.

git clone https://github.com/onecli/onecli.git
cd onecli
docker compose -f docker/docker-compose.yml up

실행 후:

• 대시보드: http://localhost:10254
• 게이트웨이: http://localhost:10255

대시보드에서 에이전트를 생성하고 시크릿을 등록한 뒤,
에이전트의 HTTP 프록시를 localhost:10255로 설정하면 바로 사용이 가능합니다.

---

로컬 개발 환경 구성 개요

OneCLI는 다음과 같은 개발 환경을 전제로 합니다.

• Node.js / pnpm (mise로 관리)
• Rust (게이트웨이)
• Docker (PostgreSQL)

개발 모드에서는 웹 앱과 게이트웨이를 동시에 실행하며,
Prisma ORM을 통해 데이터베이스 스키마와 마이그레이션을 관리합니다.

---

728x90

OneCLI가 가지는 의미

OneCLI는 단순한 비밀 저장소가 아니라,
AI 에이전트 시대에 맞는 인증 아키텍처의 방향성을 제시하는 도구입니다.

• 에이전트는 더 단순해지고
• 보안은 중앙에서 통제되며
• 키 유출 위험은 구조적으로 차단됩니다.

AI 에이전트를 실제 서비스 환경에 적용하려는 팀이라면,
OneCLI는 보안과 운영 복잡도를 동시에 낮출 수 있는 실질적인 선택지가 될 수 있습니다.

300x250

https://github.com/onecli/onecli

GitHub - onecli/onecli: Open-source credential vault, give your AI agents access to services without exposing keys.