Secret과 민감한 값 다루기

AI 모델 연결은 Portal의 Credential 관리로 설정하고, 생성된 Agent가 업무에 사용할 비밀값은 해당 Agent의 시크릿 스토어에 등록하도록 요청할 수 있습니다. 시크릿 스토어 도구가 준비되어 있고 현재 요청 범위에서 사용 가능한지 먼저 확인하세요.

어떤 경로를 써야 하나요?

값의 종류	사용할 경로	중요한 경계
Anthropic, OpenAI, Codex 로그인 또는 auth.json, Gemini, OpenRouter, Local LLM credential	관리자 → 연동 → AI 키 관리 → 키 추가	tenant 단위 credential profile로 저장하고 같은 tenant의 Agent에 연결합니다. Credential 관리를 따르세요.
새 Agent 생성 중 직접 입력하는 provider credential	Agent 생성의 AI 모델 설정·서비스 인증	생성 과정에서 해당 Agent에 직접 입력하는 방식입니다. 공유·교체·회수가 필요한 값은 이 경로 대신 Credential profile을 사용하세요.
외부 서비스가 ClawPod Webhook에 요청할 때 검증하는 signing secret	Webhooks → Sources	생성·재생성·rotation 때만 평문으로 표시될 수 있습니다. Webhook 가이드를 따르세요.
Agent 업무에 필요한 서비스 비밀번호·API key·access token	생성 후 대상 Agent에게 시크릿 스토어 등록 요청	사용 권한이 있는 값만 등록합니다. 일반 메모리에는 값을 남기지 않고 참조 ID로 관리합니다.
ClawPod 계정 비밀번호·MFA 인증 코드·복구 코드	계정의 전용 보안·인증 화면	인증 코드는 해당 인증에 사용하고 복구 코드는 조직의 보관 절차를 따릅니다. Agent 업무용 시크릿 등록과 구분하세요.
URL, 프로젝트 ID, 비민감 feature flag	Agent 생성의 환경 변수	추가 환경 변수는 비밀값 보관을 위한 경로가 아닙니다. 환경 변수 설정을 따르세요.

생성 후 채팅으로 시크릿 등록하기

1. 사용할 Agent와의 전용 1:1 채팅방을 엽니다.
2. 다음처럼 시크릿 스토어 등록을 요청합니다. 값은 본인 또는 조직이 사용을 허용한 것만 전달합니다.

이 서비스 인증값을 내 Agent의 시크릿 스토어에 등록해 줘. 이름은 report-service, 용도는 보고서 조회야. 일반 메모리나 문서에 복사하지 말고, 답변에는 값 대신 등록 성공 여부와 참조 ID만 알려 줘.

3. Agent는 사용 가능한 memory_secret 도구로 등록합니다. 도구 결과의 ok: true와 pointer_id를 확인해야 등록 완료로 판단합니다. 도구가 없거나 비활성화된 경우에는 완료했다고 안내하지 않도록 요청하세요.
4. 다음 작업에서는 “report-service로 등록한 시크릿을 찾아 승인한 보고서 조회에 사용해 줘. 값은 출력하지 마”처럼 이름·용도·참조 ID로 요청합니다. 등록만으로 모든 도구에 인증이 자동 연결되는 것은 아닙니다.

채팅으로 실제 값을 전달하면 원래 메시지나 처리 기록에 남을 수 있습니다. 시크릿 스토어 등록이 기존 채팅 기록을 자동 삭제하거나 가린다는 의미는 아닙니다. 값 전달은 조직에서 허용하는 방식으로 하고, 공유방이나 반복 메시지에는 넣지 마세요.

등록한 항목은 memory_secret_search로 참조 정보를 찾고, memory_secret_get으로 가려진 정보를 확인할 수 있습니다. 수정·삭제 요청은 각각 memory_secret_update, memory_secret_delete 도구가 제공되는 환경에서 처리합니다. 저장소에서 삭제해도 외부 서비스의 원래 토큰이 폐기되는 것은 아닙니다.

Provider credential을 안전하게 연결하기

1. API key 방식이면 provider 공식 콘솔에서 credential을 발급합니다. Codex 로그인 방식은 Credential 관리의 로그인 절차를 따릅니다.
2. AI Key Management에서 provider와 credential type을 선택해 등록합니다.
3. 같은 tenant의 대상 Agent에만 연결하고, 작은 test Room으로 동작을 확인합니다.
4. 노출·퇴직·계약 종료가 발생하면 provider에서 새 값을 발급해 Credential을 교체한 뒤 이전 값을 폐기합니다.

Portal은 저장된 raw credential을 다시 표시하지 않습니다. 값을 잃어버렸다면 조회를 시도하지 말고 새 값을 발급해 교체하세요.

Webhook signing secret 회전하기

Webhook Source의 signing secret은 provider credential과 다릅니다. 외부 서비스가 보낸 요청이 해당 Source에서 왔는지 검증하는 값입니다.

1. Source를 만든 직후 표시된 secret을 조직의 비밀값 보관 절차에 따라 보관합니다.
2. 외부 서비스의 Webhook 설정에 같은 값을 넣습니다.
3. 노출이 의심되면 Source에서 rotate 또는 regenerate를 실행하고 외부 서비스 설정을 즉시 바꿉니다.
4. test event로 새 서명이 검증되고 event가 전달되는지 확인합니다.

금지 사항

• SOUL.md, AGENTS.md, TOOLS.md, MEMORY.md에 secret을 적지 않습니다.
• 시크릿 등록을 위한 승인된 전달과 일반 대화를 구분합니다. 공유 Chat, task comment, meeting transcript, Skill package, webhook payload에 secret을 복사하지 않습니다.
• custom 환경 변수에 API key나 access token을 넣지 않습니다.
• 다른 사용자의 auth.json, MFA recovery code, browser cookie를 받아 Agent에 등록하지 않습니다.
• 내부 설정이나 API를 비밀값 보관소로 사용하지 않습니다. 이 가이드의 용도별 입력 경로를 따릅니다.

참고: Agent 시크릿 스토어와 내부 경로

Agent의 시크릿 스토어는 소유 Agent 범위로 값을 보관하며, 도구 응답에는 평문 대신 참조 정보와 가려진 값이 반환됩니다. 구현상 저장 위치는 Agent workspace 아래 .openclaw/memory-secrets/memory-secrets.json입니다. 파일을 직접 편집하는 대신 등록·검색·수정·삭제 도구를 사용하세요.

Portal의 /agents/:id/secrets는 Agent 설정의 환경 변수를 관리하는 별도 내부 API입니다. 위 memory_secret 저장소와 같은 기능이 아니며, 채팅 등록을 위해 이 API를 호출할 필요가 없습니다.

등록된 값은 일반 메모리·문서·답변에 다시 출력하지 않고, 필요한 작업 결과와 성공·실패 상태만 확인하세요.

외부 서비스 연결 안내

Resend 이메일 발송은 Agent의 시크릿 스토어에 보관한 API 키를 사용합니다. Google Workspace는 브라우저에서 Google 계정 인증을 진행하는 별도 연결 절차를 따릅니다.