AI Key와 Credential 관리

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

provider credential, webhook signing secret, 환경 변수의 경계는 Secret과 민감한 값 다루기를 참고하세요.

누가 무엇을 할 수 있나요?

목록 조회, 생성, 교체, 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	API key. setup token은 저장할 수 있어도 Agent binding에는 쓰지 않습니다.
OpenAI	OpenAI API keys	Project API key
Google Gemini	Google AI Studio API keys	Gemini API key
OpenRouter	OpenRouter API 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 공식 인증 안내를 참고하세요.
• 연결 대기·확인 중: 완료 표시를 기다립니다. 로그인에 실패한 상태를 저장 완료로 간주하지 않습니다.
• 기존 연결 만료·재로그인 필요: 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 로그인 방식을 이용하거나 공식 저장 방식 안내를 확인하세요.

수동 입력에는 최상위 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 기능으로 확인되지 않았으므로 이 문서에서는 운영 절차로 안내하지 않습니다.