🔑 AI 모델 API 키 설정
AMBA는 사용자의 PC 내부 파일과 로컬 계산 능력을 세계 유수의 상용 AI가 제공하는 고도화된 전략 추론 능력과 결합합니다. AMBA를 활용하려면 지원되는 AI 공급자 중 최소 하나의 API 키가 필요합니다.
🔒 키 저장 위치: OS 키체인에만 저장
IMPORTANT
AMBA는 API 키를 운영체제 키체인에만 저장합니다:
- macOS: macOS Keychain
- Windows: Windows Credential Manager
- Linux: D-Bus를 통한 Secret Service(GNOME Keyring, KWallet 5.97 이상, 또는 Secret Service를 켠 KeePassXC)
평문이나 데이터베이스로 대체 저장하지 않습니다. 키는 로그에 기록되지 않으며 해당 키를 발급한 제공업체로만 전송됩니다. 저장 후 키를 다시 읽어 키체인이 실제로 보관한 경우에만 성공으로 표시합니다. 붙여 넣은 키는 앞뒤 공백이 제거되며, 줄바꿈·보이지 않는 문자·비ASCII 문자가 포함된 키는 거부됩니다.
키링이 실행 중이지 않은 Linux: 저장이 "시스템 키체인을 사용할 수 없습니다…"로 실패하고 설정 → 시스템 진단에 키체인 사용 불가로 표시됩니다. GNOME Keyring 또는 KWallet을 설치/활성화한 뒤 AMBA를 다시 시작하세요(자세히).
TIP
macOS에서 "AMBA wants to use your confidential information stored in … in your keychain"이 표시되나요? AMBA는 모든 키를 하나의 키체인 항목에 보관하며, 실행 중 이 항목을 최대 한 번만 읽습니다. 항상 허용(Always Allow) 을 선택하면 더 이상 묻지 않으며, 서명된 업데이트도 이 선택을 유지합니다. 직접 빌드한 개발 버전은 빌드할 때마다 서명이 바뀌므로 다시 빌드할 때마다 다시 묻습니다. 0.5.11 이하에서 저장한 키는 처음 사용될 때 이 하나의 항목으로 옮겨지므로, 이전 키마다 한 번씩만 물을 수 있습니다.
어떤 항목이며 왜 "허용"만으로는 부족한가요? 대화 상자에는 항목 이름 AMBA – saved API keys and connections(계정 amba-vault-v1)가 표시됩니다. 이전 버전에서 만든 항목은 다음에 키를 저장하거나 로그인할 때까지 amba로 표시됩니다. AMBA의 모든 키와 연결을 보관하는 단 하나의 항목입니다. 허용(Allow) 은 한 번만 허용하므로 다음 실행 시, 그리고 키를 저장하거나 Google에 로그인할 때 다시 묻습니다. 항상 허용(Always Allow) 을 선택하면 계속 허용됩니다. 실행 중인 AMBA는 키가 실제로 바뀌지 않는 한 키체인에 다시 접근하지 않습니다. Google Drive의 매시간 로그인 갱신은 메모리에서만 처리되며 더 이상 키체인에 다시 쓰지 않습니다.
WARNING
0.5.9에서 업데이트하는 경우: 0.5.9로 업데이트한 뒤 저장한 키는 보관되지 않았습니다. 설정 → AI 모델에서 다시 입력하세요. 0.5.8 이하에서 저장한 키는 첫 실행 시 자동으로 키체인으로 옮겨집니다.
📋 지원 AI 공급자 및 키 발급 방법
1. Anthropic Claude (강력 추천)
최적 용도: 전략 종합 분석, 다부서 업무 분해, 심층 논리 추론 및 최고경영진 보고서 작성.
권장 모델: Claude Opus 5.5(AMBA의 기본 Claude 모델), 빠른 일상 작업용 Claude Sonnet 5.5, 가볍고 양이 많은 작업용 Claude Haiku 5.5. 가장 어려운 작업에는 Claude Fable 5.1을 선택할 수 있습니다. Claude 3.x 모델은 레거시로 유지됩니다.
- Anthropic 콘솔에 접속합니다.
- 계정 생성 또는 로그인합니다.
- API Keys 메뉴로 이동하여 Create Key를 클릭합니다.
- 키 이름을
AMBA Desktop으로 지정하고 발급된 키(sk-ant-...)를 복사합니다.
Claude in Amazon Bedrock (AWS를 사용하는 기업에 권장)
이미 AWS를 사용 중이라면 Claude in Amazon Bedrock을 통해 Claude를 사용하세요. 사용 요금은 고객님의 AWS 계정으로 청구·관리되며, AMBA는 bedrock-mantle.<region>.api.aws로 요청을 보냅니다("이 기기에서 나간 데이터" 패널에 표시됨). 이 엔드포인트가 고객님의 계정에 Claude 모델을 제공하지 않으면 AMBA는 해당 모델에 bedrock-runtime.<region>.amazonaws.com(Bedrock 플레이그라운드와 같은 InvokeModel)을 사용합니다. 공급자의 Claude 호출 경로 설정으로 둘 중 하나로 고정할 수도 있습니다.
- AWS 콘솔에서 사용하는 리전(예:
us-east-1)의 Amazon Bedrock → Model access를 열고 사용할 Claude 모델(Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5)을 활성화합니다. - 자격 증명을 만듭니다: Bedrock API 키(Amazon Bedrock → API keys, 단기 키는 12시간 내 만료) 또는
bedrock-mantle:CreateInference(InvokeModel로 호출하는 모델에는bedrock:InvokeModel,bedrock:InvokeModelWithResponseStream도) 호출이 허용된 IAM 액세스 키. - AMBA에서 설정 → 모델 → 공급자 추가 → AWS Bedrock을 열고 키와 리전을 입력한 뒤 (Claude in Amazon Bedrock) 표시가 있는 모델을 선택합니다.
이 모델들은 Anthropic 키로 쓰는 Claude와 똑같이 동작합니다(사고 요약, effort, 프롬프트 캐싱, 네이티브 도구 호출). Bedrock에서 제공되지 않는 두 기능, 즉 거절된 요청을 다른 모델로 서버 측에서 재시도하는 기능과 strict 도구 스키마는 AMBA도 사용하지 않습니다. us.anthropic.claude-sonnet-4-5-20250929-v1:0 같은 기존 Claude 모델 ID는 이전처럼 Bedrock Converse API를 사용합니다. Claude가 아닌 Bedrock 모델(Nova, Llama, Mistral 등)은 더 이상 지원하지 않으며, 업데이트 후 처음 실행할 때 해당 프로필이 삭제됩니다. 실행이 "model access" 오류로 실패하면 Amazon Bedrock → Model access에서 해당 모델을 활성화한 뒤 다시 시도하세요.
2. OpenAI
최적 용도: 표준적인 비즈니스 업무 처리, 정형화된 문서 초안 작성.
- OpenAI 플랫폼에 접속합니다.
- Settings > API Keys로 이동합니다.
- Create new secret key를 클릭하여 키(
sk-proj-...)를 생성하고 복사합니다.
3. Google Gemini
최적 용도: 초고속 멀티모달 분석 및 대용량 문서 일괄 검토.
- Google AI Studio에 접속합니다.
- Get API key를 클릭하여 신규 키를 발급받습니다.
Google Cloud — Gemini Enterprise Agent Platform(이전 이름: Vertex AI)
Google Cloud로 Gemini 비용을 내는 회사를 위한 설정입니다. Google은 2026년 4월 Vertex AI의 이름을 Gemini Enterprise Agent Platform으로 바꿨으며, API 호스트는 그대로 aiplatform.googleapis.com입니다. AMBA는 서비스 계정 JSON 키로 인증하고 키는 OS 키체인에만 저장합니다.
- 결제가 사용 설정된 프로젝트를 선택하거나 만듭니다.
- Agent Platform API를 사용 설정합니다(
aiplatform.googleapis.com). - IAM 및 관리자 → 서비스 계정 → 서비스 계정 만들기로 이동해 역할 Agent Platform User(
roles/aiplatform.user)를 부여합니다. - 계정을 열고 키 → 키 추가 → 새 키 만들기 → JSON을 선택합니다. 파일은 한 번만 다운로드되니 안전하게 보관하세요.
- *"Key creation is not allowed on this service account"*가 나오면 조직이 키 생성을 막고 있는 것입니다(2024년 5월 이후 만든 조직의 기본값). 조직 관리자에게 이 프로젝트를 Disable service account key creation 정책에서 제외해 달라고 요청하세요(Google 안내).
- AMBA에서 설정 → 모델 → 공급자 추가 → Google Cloud를 엽니다. 대화상자에도 같은 단계가 있고, 단계마다 Console 페이지를 여는 버튼이 있습니다. JSON 파일 전체를 붙여넣으면 AMBA가 바로 확인하고(API 키, OAuth 클라이언트 JSON, 잘린 붙여넣기는 그렇다고 알려 줌) 프로젝트 ID를 채우며 서비스 계정을 보여 줍니다.
- 처리를 미국(
us), EU(eu) 또는 특정 리전 안에서 해야 하는 경우가 아니면 위치는 global로 둡니다. 연결 테스트를 누르면 AMBA가 토큰을 받고 짧은 요청을 보내며, API가 꺼져 있거나 역할·결제가 없거나 그 위치에서 모델을 제공하지 않으면 그렇게 알려 줍니다. - 저장한 뒤 제공업체 카드에서 가져오기를 눌러 현재 Gemini 모델(Gemini 4 Argon, 3.8 Flash, 3.5 Flash, 3.5 Flash-Lite, 3.1 Pro preview)을 표시합니다. 다른 모델 ID는 직접 추가할 수 있습니다.
⚙️ AMBA에 키를 등록하는 방법
Claude를 연결하는 가장 빠른 방법은 사이드바의 설정 마법사입니다. Anthropic API 또는 Amazon Bedrock을 고르고 키(Bedrock은 AWS 리전도)를 붙여넣으세요. 그러면 Claude Opus 5.5가 기본 모델이 됩니다. 다른 제공업체는 설정에서 추가합니다:
- 컴퓨터에서 AMBA 애플리케이션을 실행합니다.
- 좌측 메뉴에서 **⚙️ Settings > Model Settings (모델 설정)**을 클릭합니다.
- 다음 안내에 따라 설정합니다:
- 1단계: 주요 모델 (Primary Model): 메인 전략 추론 모델(예: Claude Opus 5.5 또는 GPT-4o)을 선택하고 API 키를 입력합니다.
- 2단계: 대체 모델 (Fallback): 속도 제한(Rate limit)이나 네트워크 장애 발생 시 대처할 보조 모델을 지정합니다.
- 웹 검색 (선택 사항): 웹 검색 섹션에 Tavily 또는 Brave Search 키를 입력하면 허용된 프로젝트에서 에이전트가 인터넷을 검색할 수 있습니다. AMBA 계정에서 웹 검색이 켜져 있다면(설정에서 확인) 키가 필요 없습니다. 검색은 계정을 통해 이루어집니다(검색 1회당 1크레딧, 24시간 및 30일 검색 횟수 한도 있음). 본인 키를 입력하면 항상 본인 키가 먼저 사용됩니다.
- Save Key를 누릅니다. 입력란에 키가 키체인에 저장되었음이 표시됩니다. 키체인이 보관할 수 없으면 이유를 설명하는 오류가 표시되고 키는 저장되지 않습니다.
🧭 어떤 모델이 작업하나요
설정 → AI 모델 → 2단계에서 고른 모델이 모든 것의 기본값입니다. 직접 고른 모델이 이보다 우선하며, 순서는 다음과 같습니다.
- 에이전트 — 에이전트 채팅에서 고른 모델. 그 에이전트(첫 번째 "Bot 1" 포함)에 저장되고 프로젝트 모델은 바뀌지 않습니다. 에이전트는 채팅, 프로세스 단계, 단계 테스트에서 이 모델을 씁니다. 목록 맨 위의 기본값 따르기 (…) 는 에이전트 자체 선택을 해제합니다.
- 프로젝트 — 프로젝트 설정 → 일반 → AI 모델에서 고른 모델. 새 프로젝트는 기본값 따르기 (…) 로 시작합니다.
- 기본값 — 설정 → AI 모델 → 2단계. 여기서 바꾸면 자체 선택이 없는 모든 프로젝트와 에이전트가 따라 바뀝니다.
아무것도 정하지 않았다면 키가 설정된 첫 번째 모델을 씁니다. "한 문장으로 만들기"와 에이전트에게 요청 단계에는 모델과 그 이유가 표시됩니다: Opus 5.5 (Amazon Bedrock) · 기본값, · 프로젝트, · 에이전트.
이전 버전의 프로젝트와 에이전트는 기존 모델을 유지합니다. 한 번에 모두 기본값으로 되돌리려면 2단계의 모든 프로젝트에서 기본 모델 사용을 쓰세요. 바뀔 프로젝트와 에이전트 수를 먼저 알려 주고 확인을 받습니다.