🔑 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로 요청을 보냅니다("이 기기에서 나간 데이터" 패널에 표시됨).
- 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호출이 허용된 IAM 액세스 키. - AMBA에서 설정 → 모델 → 공급자 추가 → AWS Bedrock을 열고 키와 리전을 입력한 뒤 (Claude in Amazon Bedrock) 표시가 있는 모델을 선택합니다.
이 모델들은 Anthropic 키로 쓰는 Claude와 똑같이 동작합니다(사고 요약, effort, 프롬프트 캐싱, 네이티브 도구 호출). Bedrock에서 제공되지 않는 두 기능, 즉 거절된 요청을 다른 모델로 서버 측에서 재시도하는 기능과 strict 도구 스키마는 AMBA도 사용하지 않습니다. us.anthropic.claude-sonnet-4-5-20250929-v1:0 같은 기존 Bedrock 모델 ID와 Claude가 아닌 Bedrock 모델은 이전처럼 Bedrock Converse API를 사용합니다. 실행이 "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를 클릭하여 신규 키를 발급받습니다.
4. OpenRouter
최적 용도: 단일 계정으로 수백 개의 최첨단 상용 모델 및 오픈소스 모델 통합 접근.
- OpenRouter에 접속합니다.
- Keys 메뉴에서 새 API 키(
sk-or-...)를 발급받습니다.
5. TypeSafe AI (Jev — System 1 Decision Engine)
최적 용도: 1초 미만 초고속 의도 판별 및 사고 모드(Research, Plan, Agent) 자동 라우팅.
- TypeSafe AI에 접속합니다.
- Jev 의사결정 엔진 전용 API 키를 발급받습니다.
⚙️ AMBA에 키를 등록하는 방법
- 컴퓨터에서 AMBA 애플리케이션을 실행합니다.
- 좌측 메뉴에서 **⚙️ Settings > Model Settings (모델 설정)**을 클릭합니다.
- 3단계 안내에 따라 설정합니다:
- 1단계: 주요 모델 (Primary Model): 메인 전략 추론 모델(예: Claude Opus 5.5 또는 GPT-4o)을 선택하고 API 키를 입력합니다.
- 2단계: 대체 모델 (Fallback): 속도 제한(Rate limit)이나 네트워크 장애 발생 시 대처할 보조 모델을 지정합니다.
- 3단계: 고급 및 실험적 라우팅 (Advanced & Experimental Routing): OpenRouter 또는 TypeSafe AI (Jev) 키를 등록하여 초고속 사고 모드 자동 라우팅을 활성화합니다.
- Save Key를 누릅니다. 입력란에 키가 키체인에 저장되었음이 표시됩니다. 키체인이 보관할 수 없으면 이유를 설명하는 오류가 표시되고 키는 저장되지 않습니다.
🧭 어떤 모델이 작업하나요
설정 → AI 모델 → 2단계에서 고른 모델이 모든 것의 기본값입니다. 직접 고른 모델이 이보다 우선하며, 순서는 다음과 같습니다.
- 에이전트 — 에이전트 채팅에서 고른 모델. 그 에이전트(첫 번째 "Bot 1" 포함)에 저장되고 프로젝트 모델은 바뀌지 않습니다. 에이전트는 채팅, 프로세스 단계, 단계 테스트에서 이 모델을 씁니다. 목록 맨 위의 기본값 따르기 (…) 는 에이전트 자체 선택을 해제합니다.
- 프로젝트 — 프로젝트 설정 → 일반 → AI 모델에서 고른 모델. 새 프로젝트는 기본값 따르기 (…) 로 시작합니다.
- 기본값 — 설정 → AI 모델 → 2단계. 여기서 바꾸면 자체 선택이 없는 모든 프로젝트와 에이전트가 따라 바뀝니다.
아무것도 정하지 않았다면 키가 설정된 첫 번째 모델을 씁니다. "한 문장으로 만들기"와 에이전트에게 요청 단계에는 모델과 그 이유가 표시됩니다: Opus 5.5 (Amazon Bedrock) · 기본값, · 프로젝트, · 에이전트.
이전 버전의 프로젝트와 에이전트는 기존 모델을 유지합니다. 한 번에 모두 기본값으로 되돌리려면 2단계의 모든 프로젝트에서 기본 모델 사용을 쓰세요. 바뀔 프로젝트와 에이전트 수를 먼저 알려 주고 확인을 받습니다.