---
title: AI Key와 Credential 관리
description: AI Key Management에서 provider credential을 등록·연결·교체·회수하는 안전한 방법입니다.
---

# AI Key와 Credential 관리

**AI Key Management**의 Credential profile은 Agent가 model provider 또는 local LLM에 연결할 때 쓰는 민감한 값입니다. 이 기능은 개인 비밀번호 보관함이나 범용 secret store가 아닙니다. Portal에서 관리하더라도 비밀값을 Chat, playbook, 문서, 로그에 복사하지 마세요.

provider credential, webhook signing secret, 환경 변수의 경계는 [Secret과 민감한 값 다루기](./handle-secrets.mdx)를 참고하세요.

## 누가 무엇을 할 수 있나요?

목록 조회, 생성, 교체, Agent에 적용, 삭제에는 각각 다른 권한이 필요할 수 있습니다. 테넌트 관리자와 플랫폼 최고 관리자에는 역할 기반 우회가 적용될 수 있으며, 그 밖의 사용자는 필요한 Credential·Agent action을 모두 받아야 합니다. 화면이 보여도 모든 버튼을 쓸 수 있는 것은 아닙니다.

플랫폼 최고 관리자는 tenant별 profile을 필터링해 볼 수 있습니다. tenant를 바꿀 때는 같은 이름의 key가 아닌 **tenant, provider, fingerprint, 연결된 Agent 수**를 함께 확인하세요.

## 등록하기

1. **관리자 → 연동 → AI 키 관리 → 키 추가**를 엽니다.
2. provider와 credential type을 선택합니다.
3. 이름을 입력하고 선택한 방식에 따라 비밀값을 등록하거나 아래의 **ChatGPT 로그인**을 완료한 뒤 저장합니다.
4. 목록의 provider, type, fingerprint, version, 연결된 Agent 수를 확인합니다.

현재 선택지에는 Claude API key 또는 setup token, OpenAI API key, OpenAI Codex ChatGPT 로그인 또는 `auth.json`, Google Gemini API key, OpenRouter API key, Ollama server, OpenAI-compatible local LLM server가 포함됩니다. 실제 선택지는 release와 권한에 따라 달라질 수 있습니다.

Ollama는 server 주소와 사용할 model을 설정하며 API key를 받지 않습니다. OpenAI-compatible local LLM server는 필요 시 API key를 함께 설정할 수 있습니다. 연결 테스트 성공은 Agent runtime에서도 사용할 수 있다는 보장은 아니므로, 비민감 test prompt로 Agent 호출을 한 번 더 확인하세요.

## Provider API key 발급하기

API key는 ClawPod가 발급하지 않습니다. 사용할 provider의 계정 또는 프로젝트에서 직접 만들고, 한 번 표시된 값은 조직의 비밀값 보관 절차에 따라 보관한 뒤 ClawPod에는 Credential 입력란으로만 전달합니다.

| Provider | 실제 발급 위치 | ClawPod에 넣을 값 |
| --- | --- | --- |
| Anthropic Claude | [Anthropic Console API keys](https://console.anthropic.com/settings/keys) | API key. setup token은 저장할 수 있어도 Agent binding에는 쓰지 않습니다. |
| OpenAI | [OpenAI API keys](https://platform.openai.com/api-keys) | Project API key |
| Google Gemini | [Google AI Studio API keys](https://aistudio.google.com/apikey) | Gemini API key |
| OpenRouter | [OpenRouter API keys](https://openrouter.ai/settings/keys) | OpenRouter API key |

각 콘솔에서 해당 조직 또는 프로젝트를 선택하고 새 key를 만든 뒤, 필요한 최소 권한·예산·결제 설정을 provider 쪽에서 정합니다. 화면의 **Official console** 링크도 같은 발급 페이지로 이동합니다. provider의 key 생성 메뉴와 과금 조건은 provider가 바꾸므로, 이 문서는 고정된 버튼 이름을 재현하지 않습니다.

발급한 값은 전체를 다시 볼 수 없을 수 있습니다. Chat, task, workspace 파일, 스크린샷, 지원 요청에 붙여 넣지 마세요. 노출이 의심되면 ClawPod에서 값을 교체하는 것과 별도로 provider 콘솔에서 이전 key를 폐기해야 합니다.

## OpenAI Codex 로그인으로 연결하기

OpenAI Codex는 **ChatGPT로 로그인하기(추천)**와 **auth.json 직접 등록** 중 선택할 수 있습니다. 일반 OpenAI API key를 등록하려면 AI 서비스를 **OpenAI**로 선택하세요. ClawPod 계정 로그인과 Agent가 사용할 ChatGPT 계정 연결은 별도입니다.

### ChatGPT로 로그인하기 — 추천

1. 상단 **관리자 → 연동 → AI 키 관리 → 키 추가**를 엽니다.
2. **AI 서비스**에서 **OpenAI Codex**를 선택하고 **키 이름**을 입력합니다.
3. **ChatGPT로 로그인하기**를 선택한 상태에서 **ChatGPT로 계속**을 누릅니다.
4. 표시된 **디바이스 코드**를 확인하고 **ChatGPT 로그인 페이지 열기**를 선택합니다. 공식 페이지에서 사용할 ChatGPT 계정으로 로그인한 뒤 코드를 입력합니다.
5. ClawPod의 연결 창을 열어 둡니다. 기다리는 중에 창을 닫으면 연결이 취소됩니다.
6. **ChatGPT 계정이 연결되었습니다. 저장을 눌러 완료하세요.**가 표시되면 **키 추가**를 눌러 저장합니다. 로그인 완료만으로 등록이 끝난 것은 아닙니다.
7. AI 키 목록에서 저장된 이름·OpenAI Codex·**Codex 로그인** 유형과 상태를 확인합니다.
8. 대상 Agent의 **AI 리소스 설정**에서 저장한 Credential을 선택하고 적용 결과를 확인합니다. 마지막으로 작은 요청을 보내 실제 모델 호출이 되는지 확인합니다.

이 방식에서는 로컬 `auth.json`을 찾아 복사할 필요가 없습니다. 로그인은 본인 또는 조직에서 사용을 허용한 계정으로 완료하고, 비밀번호·디바이스 코드·인증정보를 가이드나 채팅에 붙여 넣지 마세요.

### 로그인이 되지 않을 때

- **디바이스 코드 만료**: 다시 시도해 새 코드로 로그인합니다.
- **디바이스 코드 로그인이 허용되지 않음**: ChatGPT 보안 설정 또는 워크스페이스 관리자의 허용 여부를 확인합니다. 조직 정책을 우회하지 마세요. [OpenAI 공식 인증 안내](https://learn.chatgpt.com/docs/auth#preferred-device-code-authentication-beta)를 참고하세요.
- **연결 대기·확인 중**: 완료 표시를 기다립니다. 로그인에 실패한 상태를 저장 완료로 간주하지 않습니다.
- **기존 연결 만료·재로그인 필요**: AI 키 목록의 해당 항목에서 **업데이트**를 열고 ChatGPT 로그인 절차를 다시 진행한 뒤 저장합니다. 연결된 Agent의 적용 결과도 확인합니다.

### 대안: auth.json 직접 등록

이미 신뢰할 수 있는 기기에서 Codex CLI로 로그인했다면 **auth.json 직접 등록**도 사용할 수 있습니다.

1. 해당 기기에서 `codex login`으로 본인 계정의 로그인을 완료합니다.
2. 파일 저장 방식을 사용하는 경우 `~/.codex/auth.json`의 **전체 JSON**을 ClawPod의 **auth.json 직접 등록** 입력란에 넣습니다. `CODEX_HOME`을 바꿨다면 그 위치를 사용합니다.
3. 화면의 형식 확인·저장 절차를 완료하고 대상 Agent에 연결합니다.

OS 자격 증명 저장소를 사용하는 Codex에서는 파일이 없을 수 있습니다. 이 경우 파일이 반드시 생성된다고 가정하지 말고 위의 Portal 로그인 방식을 이용하거나 [공식 저장 방식 안내](https://learn.chatgpt.com/docs/auth#credential-storage)를 확인하세요.

수동 입력에는 최상위 `tokens` 객체가 포함된 유효한 JSON이 필요합니다. 일반 API key로 대체하지 마세요. **수동 auth.json 등록은 ChatGPT 연결 상태를 자동 확인하지 않으므로**, 저장 성공과 Agent의 실제 호출 성공을 구분합니다. 만료되면 새 로그인 정보로 업데이트합니다. 인증 파일은 저장소·공유 문서·이슈·채팅에 올리지 않습니다.

## Agent에 연결하기

1. 대상 Agent 설정에서 사용할 Credential을 선택합니다.
2. Agent와 Credential의 tenant가 같은지 확인합니다.
3. 같은 runtime slot에 충돌하는 다른 credential이 없는지 확인합니다.
4. 적용 결과가 updated, pending, failed 중 무엇인지 확인합니다.
5. pending 또는 runtime 적용 경고가 있으면 Agent 상태와 재시작 필요 여부를 확인한 뒤 작은 요청으로 검증합니다.

Claude setup token은 저장할 수 있어도 Agent binding에는 API key만 허용됩니다. provider나 type을 바꾸고 싶다면 기존 profile의 값만 덮어쓴다고 가정하지 말고, 새 profile을 만든 뒤 대상 Agent에서 연결을 검토하세요.

## 안전하게 교체하기

1. provider 콘솔에서 새 secret을 발급합니다.
2. 목록에서 fingerprint와 **Used by** Agent 목록을 확인합니다.
3. 해당 profile을 열고 새 값을 입력합니다. provider와 credential type, profile 이름은 교체 화면에서 바꿀 수 없습니다.
4. 적용 결과와 연결된 Agent 수를 확인하고, 영향을 받는 Agent에서 작은 요청을 실행합니다.
5. 새 연결이 정상 동작한 뒤 provider에서 기존 secret을 폐기합니다.

Portal은 저장된 raw secret을 다시 표시하지 않습니다. 목록에는 식별용 fingerprint와 현재 version만 표시됩니다. 값을 잃어버렸다면 조회를 시도하지 말고 provider에서 새 값을 발급해 교체하세요.

## 연결 해제와 삭제

삭제하려면 먼저 profile을 사용하는 Agent가 없어야 합니다. **Used by**에서 연결된 Agent를 확인하고, 각 Agent의 credential binding을 다른 profile로 바꾸거나 해제한 뒤 삭제하세요. 삭제 요청이 거절되면 사용 중인 Agent가 남아 있다는 뜻으로 보고, 삭제를 반복하지 말고 binding을 먼저 정리합니다.

profile 삭제는 목록에서 제거하는 회수 작업입니다. provider 쪽 API key 자체를 폐기하지 않으므로, 노출 또는 퇴직·계약 종료 상황에서는 provider 콘솔에서의 revoke도 별도로 수행하세요.

## 문제 해결

- Agent가 provider를 호출하지 못하면 Credential 연결, Agent 설정, 재시작 여부, provider의 계정·quota·네트워크 상태를 순서대로 확인합니다.
- 수정 후에도 실패하면 안전한 테스트 Room에서 오류 메시지와 Agent logs를 확인합니다.
- secret 노출이 의심되면 즉시 교체하고 영향받는 Agent를 재시작합니다.

Credential 생성·교체 권한은 조직 정책에 따라 제한됩니다. 다른 구성원의 secret을 요청하거나 공유하지 마세요. encryption key의 생성·rotation·복구는 고객 Portal의 self-service 기능으로 확인되지 않았으므로 이 문서에서는 운영 절차로 안내하지 않습니다.