AI 키 교체를 끝내는 기준: 저장, 실제 호출, 이전 키 폐기

AI 키를 교체하는 조직 운영 담당자를 위한 글입니다. 읽고 나면 새 키 발급, ClawPod Cloud 연결 변경, 실제 호출 확인, 이전 키 폐기를 서로 다른 완료 조건으로 나눌 수 있습니다. 제공자 계정의 발급·폐기 권한과 대상 조직의 Credential·Agent 변경 권한이 필요합니다. 여기서는 공개 Guide가 설명하는 API 키의 계획 교체를 다루며, 실제 관리 화면의 배치나 무중단 전환을 보장하지 않습니다.

먼저 기억할 세 가지

• API 키는 모델 제공자가 발급합니다. ClawPod Cloud에 새 값을 저장해도 제공자에 남아 있는 이전 키가 자동으로 폐기되지는 않습니다.
• 저장 성공, Agent 적용 결과, 실제 모델 호출 성공은 서로 다른 확인입니다. 연결된 Agent마다 확인해야 합니다.
• 계획 교체와 노출 사고를 구분하세요. 의심되는 키를 복구용이라는 이유만으로 계속 유지하는 절차는 만들지 않습니다.

키 발급과 연결 관리는 서로 다른 책임입니다

Credential profile은 Agent가 모델 제공자 또는 로컬 언어 모델에 연결할 때 쓰는 인증 정보를 등록·연결하는 단위입니다. 공개 Guide는 이를 ClawPod Cloud의 Portal에서 관리하는 기능으로 설명합니다. Agent Control UI나 실행 환경의 내부 설정을 바꾸는 절차와 같은 것으로 취급하지 마세요. 이 글은 현재 Portal을 직접 확인한 화면 안내가 아니라 문서에 근거한 운영 안내입니다.

API 키는 사용할 제공자의 계정 또는 프로젝트에서 만듭니다. 최소 권한, 예산, 결제 조건도 제공자 쪽에서 정합니다. 그다음 조직에서 허용한 Credential 입력 경로로 등록하고 대상 Agent에 연결합니다. 비밀값을 채팅, 문서, 작업 댓글, 로그, 스크린샷에 복사하지 마세요.

Guide는 저장된 원본 비밀값을 Portal이 다시 표시하지 않는다고 설명합니다. 식별용 fingerprint와 현재 version 같은 메타데이터로 대상을 확인하며, 값을 잃어버렸다면 조회를 시도하는 대신 제공자에서 새 값을 발급해 교체합니다. fingerprint는 키를 구별하기 위한 정보이고 비밀값 자체가 아닙니다. version을 정확한 교체 횟수나 복구 가능한 이력으로 해석하지 마세요. Guide는 그런 보장을 하지 않습니다.

모델 연결용 Credential profile은 개인 비밀번호 보관함이나 범용 비밀값 저장소가 아닙니다. 업무용 서비스 비밀번호·접근 토큰은 사용 가능한 Agent 시크릿 스토어와 조직의 승인된 전달 절차를 따릅니다. URL·프로젝트 ID 같은 비민감 환경 변수와도 구분합니다. 추가 환경 변수를 비밀값 보관 장소로 사용하지 않습니다.

바꾸기 전에 대상, 담당자, 사건을 적으세요

목록 조회, 생성, 교체, Agent 적용, 삭제에는 각각 다른 권한이 필요할 수 있습니다. 화면에 접근할 수 있다는 사실만으로 모든 변경 권한이 있다고 판단하지 마세요. 제공자 계정 담당자와 ClawPod Cloud 변경 담당자가 다르다면 검증 결과를 누가 전달하고 이전 키를 누가 폐기할지도 정합니다.

다음 표는 제품의 자동 정책이 아니라 조직이 채울 운영 기록입니다.

결정할 항목	기록할 내용	빠졌을 때 생기는 문제
대상	조직, 제공자, profile, fingerprint, 연결된 Agent 목록·수	같은 이름의 다른 키를 바꿀 수 있습니다
담당	발급·적용·검증·폐기 담당자와 대리자	새 키 저장 뒤 폐기가 누락됩니다
시작 조건	계획 교체, 담당자 변경, 계약 종료, 노출 의심	날짜만 정하면 사건에 대한 대응이 빠집니다
중단·복구 조건	허용된 변경 시간, 멈출 업무, 실패 시 판단권자	적용 결과가 불명확한데 변경을 반복합니다

tenant는 조직별 관리 경계입니다. Guide는 Agent와 Credential의 tenant가 같아야 한다고 설명합니다. 여러 조직을 다룰 때는 profile 이름만 보지 말고 조직, 제공자, fingerprint, 연결된 Agent를 함께 확인합니다. 중앙 담당자에게 권한을 모을지 팀별 담당자를 둘지는 조직의 선택입니다. 어느 쪽이든 부재 시 대리자와 폐기 책임자는 명시하세요.

계획 교체는 발급 → 적용 → 검증 → 폐기로 진행합니다

노출 정황이 없는 계획 교체에서는 Guide의 다음 순서를 사용합니다.

1. 새 키를 발급합니다. 올바른 제공자 계정·프로젝트인지와 권한·예산 조건을 확인합니다. 키의 값은 승인된 비밀값 전달 경로에만 넣습니다.
2. 영향 범위를 확인합니다. 교체할 profile의 fingerprint와 연결된 Agent 목록을 확인합니다. Agent 수만 같다고 같은 대상이라고 판단하지 않습니다.
3. 같은 profile의 값을 교체합니다. Guide에 따르면 이 교체에서 제공자, 인증 유형, profile 이름은 바꿀 수 없습니다. 제공자나 유형을 바꾸려면 새 profile을 만들고 대상 Agent의 연결을 별도로 검토합니다.
4. 적용 결과와 실제 호출을 확인합니다. updated, pending, failed를 구분하고 각 Agent에 비민감한 작은 요청을 보냅니다. pending이나 실행 환경 적용 경고가 있으면 Agent 상태와 재시작 필요 여부를 먼저 확인합니다.
5. 정상 연결을 확인한 뒤 이전 키를 폐기합니다. 제공자 쪽 폐기는 별도 작업입니다. 누가 어떤 대상의 폐기를 확인했는지 비밀값 없이 기록합니다.

연결 테스트가 성공해도 Agent의 실행 환경에서 호출할 수 있다는 보장은 아닙니다. 반대로 답변 하나를 받았다는 사실만으로 새 키가 사용됐다고 단정해서도 안 됩니다. 의도한 profile 연결, 적용 결과, 영향받는 Agent별 요청 결과를 함께 확인하세요. 대체 제공자나 다른 인증 경로가 성공 응답을 만든 것인지 구분할 수 없다면 새 키 전환은 아직 확인되지 않은 상태입니다.

재시작은 항상 필요한 것도, 항상 불필요한 것도 아닙니다. 해당 변경의 안내와 Agent 상태에 따라 판단합니다. Guide는 중지·재시작이 실행 중인 작업이나 대화에 영향을 줄 수 있다고 설명합니다. 계획 변경에서는 담당자가 작업 종료 여부와 공지·변경 시간을 확인해야 합니다. 기존 대화가 그대로 유지된다거나 모든 Agent가 동시에 전환된다고 가정하지 마세요.

가상 사례: 두 Agent 중 하나가 아직 대기 상태라면

가상 예시입니다. 다음 요청과 결과는 운영 기록의 표본이며 실제 실행 결과, 제품 화면, 자동화 기능이 아닙니다. 키 값이나 실제 식별자는 포함하지 않습니다.

담당자가 변경 기록 작성을 요청합니다.

문서 요약 Agent A·B가 사용하는 summary-model의 계획 교체 기록을 정리해 주세요. 승인된 변경 대상과 각 Agent의 적용·시험 결과, 이전 키 폐기 여부를 구분해 주세요. 비밀값을 요청하거나 출력하지 말고, 이 요청만으로 키 발급·교체·재시작·폐기를 실행하지 마세요.

승인된 절차로 변경을 수행한 담당자가 전달한 결과를 다음처럼 정리할 수 있습니다.

확인 대상	채워진 결과 표본	판단
범위	예시 조직의 summary-model, Agent A·B 총 2대	이름만 아니라 조직과 대상 목록을 대조했습니다
profile	새 fingerprint 메타데이터와 현재 version 확인, 비밀값 미기록	저장 확인이며 전체 전환 완료는 아닙니다
Agent A	적용 updated, 비민감 시험 문서 요약 성공, 의도한 연결 확인	A 검증 완료
Agent B	적용 pending, 새 연결 시험 미완료	B 검증 미완료
이전 키	아직 폐기하지 않음; 노출 정황 없는 계획 교체	전체 완료로 보고하지 않습니다

담당자는 표의 A·B가 실제 영향 대상과 일치하는지 확인하고, B의 상태·적용 경고·재시작 필요 여부를 점검합니다. 재시작이 필요하면 승인된 변경 시간에 처리하고, 같은 비민감 시험 문서로 B의 응답과 의도한 연결을 확인합니다. B도 검증된 뒤 제공자 담당자가 이전 키 폐기를 확인하면 최종 기록은 “A·B 적용 및 호출 확인, 이전 키 폐기 확인, 담당자와 시각 기록”으로 바뀝니다. 답변 내용에 비밀값이 없어야 하는 것도 성공 조건입니다.

B의 호출이 실패하면 Credential 연결, Agent 설정, 재시작 여부, 제공자의 계정·사용량 한도·네트워크 상태를 순서대로 확인합니다. 안전한 테스트 Room의 오류와 로그를 점검하되 민감값을 공유 기록에 옮기지 않습니다. 결과를 알 수 없는 상태에서 교체나 재시작을 반복하지 마세요.

이전 키를 아직 폐기하지 않았다는 사실은 자동 복구 버튼이 있다는 뜻이 아닙니다. 원래 연결로 돌아갈 수 있는지, 이전 값이 조직의 승인된 방식으로 보관됐고 여전히 유효한지, 누가 복구를 승인할지 먼저 확인해야 합니다. 복구가 불가능하면 업무를 멈추고 정상 인증 경로를 다시 마련합니다. 폐기된 키의 복원이나 Portal에서 원본 값을 되읽는 방법은 전제로 두지 않습니다.

노출 의심은 계획 교체의 대기 규칙을 그대로 쓰지 않습니다

Guide는 비밀값 노출이 의심되면 즉시 교체하고 영향받는 Agent를 재시작하며, 제공자에서 이전 키도 별도로 폐기하라고 안내합니다. 이 상황에서 “모든 시험이 끝날 때까지 이전 키 유지”를 무조건 적용하면 의심되는 접근을 계속 허용할 수 있습니다. 조직의 사고 대응 담당자가 차단과 업무 중단의 우선순위를 정하고 대응하도록 하세요. 앞의 가상 사례는 노출 사고의 대기 지침이 아닙니다.

퇴직·계약 종료처럼 접근을 끝내야 하는 경우에도 제공자 쪽 폐기 확인을 별도 완료 조건으로 둡니다. 교체 주기만 적는 것보다 사건의 판단권자와 폐기 담당자를 함께 정하는 편이 누락을 찾기 쉽습니다.

profile 삭제와 제공자 키 폐기를 따로 확인하세요

Guide에 따르면 profile을 삭제하기 전에 이를 사용하는 Agent가 없어야 합니다. 각 Agent의 연결을 다른 profile로 바꾸거나 해제한 뒤 삭제합니다. 사용 중이라는 이유로 삭제가 거절되면 삭제 요청을 반복하지 말고 남은 연결을 정리합니다.

profile 삭제는 제공자 API 키 폐기가 아닙니다. 목록에서 사라졌다는 사실과 제공자에서 더 이상 인증에 사용할 수 없다는 사실을 별도로 확인하세요. 새 profile로 옮겼다면 대상 Agent의 새 연결과 실제 호출도 다시 검증해야 합니다.

이 글의 계획 교체는 API 키에 한정됩니다. Codex 로그인 재인증, 로컬 모델 서버 설정, 저장소 암호화 키의 교체는 같은 절차로 취급하지 않습니다. Guide는 Claude setup token을 저장할 수 있어도 Agent 연결에는 API 키만 허용한다고 설명하며, 고객 Portal의 암호화 키 생성·교체·복구를 셀프서비스 기능으로 확인하지 않습니다.

다음 변경 전에 한 profile을 골라 영향받는 Agent 목록, Agent별 검증 담당자, 제공자 폐기 담당자부터 채워 보세요. 세 항목을 채울 수 없다면 키 값을 바꾸기 전에 운영 책임부터 정할 차례입니다.

Sources

• ClawPod Guide — AI Key와 Credential 관리: 발급, 권한, 적용 결과, 교체, 삭제와 제공자 폐기의 구분.
• ClawPod Guide — Secret과 민감한 값 다루기: 모델 인증 정보, 업무용 시크릿, 환경 변수의 경계.
• ClawPod Guide — Agent 상태와 설정 관리하기: 변경 후 검증과 재시작의 작업·대화 영향.