4.4. 비밀값과 인증 파일
개요
주의: 채팅 창에 비밀번호나 키를 붙여 넣지 않습니다. 채팅에 적은 값은 대화 기록에 남습니다. 키는 이 장의 「비밀값(.env)」 탭에만 넣습니다.
이 장에서 말하는 값은 다음과 같습니다.
- API 키: 외부 서비스가 발급해 주는 긴 글자열입니다. AI 에이전트가 그 서비스에 대신 접속할 때 쓰는 열쇠입니다. 서비스 담당자에게 받거나 그 서비스의 설정 화면에서 만듭 니다.
- 토큰: API 키와 같은 용도의 글자열입니다. 서비스에 따라 이름만 다릅니다.
- 비밀값: API 키, 토큰, 비밀번호를 묶어 부르는 AAS 의 말입니다.
- 인증 파일: 같은 목적으로 쓰는 JSON 형식의 파일입니다. 필요한 사람은 일부입니다(뒤쪽의 「인증 파일(고급)」).
내 개인 계정의 비밀번호는 넣지 않습니다. 어떤 값을 넣어야 할지 모르겠으면 스킬 설명서나 그 서비스 담당자에게 묻습니다. 스킬이나 MCP 서버가 키를 요구할 때, 키가 만료되거나 바뀌어 새 값을 넣어야 할 때 이 장의 방법을 씁니다. 이 장은 비밀값 넣기, 바꾸기, 지우기와 인증 파일 올리기를 설명합니다.
권한: 관리자와 그 AI 에이전트 작업공간의 주인만 값을 넣을 수 있습니다. 접근 권한만 받은 사용자는 「관리자만 바꿀 수 있습니다」를 보게 됩니다. 이때는 관리자에게 「<프로파일 이름> 에 <이름> 키를 넣어야 합니다」라고 요청합니다.
비밀값을 넣을 때 지킬 점
- 채팅 창에 붙여 넣지 않습니다. 키와 비밀번호는 이 화면의 비밀값 탭에만 넣습니다. 스킬이 채팅에서 안내하는 로그인 절차(예: Google 로그인)는 그 안내를 따릅니다.
- 넣은 값은 다시 볼 수 없습니다. 값을 바꾸려면 새 값을 넣습니다.
- 이 AI 에이전트가 이 값을 읽고 쓸 수 있습니다. 다른 일에도 쓰는 개인 비밀번호는 넣지 않고, 이 용도로 발급한 키를 넣습니다.
바꾼 값은 다음 대화부터 적용됩니다. 메신저용 값은 게이트웨이(AI 에이전트가 메신저와 예약 작업을 받는 통로)를 다시 시작해야 적용되며, 이 일은 관리자에게 요청합니다. 컨테이너 전체에 적용되는 환경변수는 이 화면에서 바꿀 수 없습니다.
비밀값 탭 열기
- 왼쪽 메뉴의 「내 AI 에이전트 › 프로파일」을 누릅니다.
- 내 주 프로파일 행을 눌러 상세 서랍을 엽니다.
- 「비밀값(.env)」 탭을 엽니다.
그림 4.4-1. 「비밀값(.env)」 탭
이미 넣은 값은 이름과 「값 있음」 표시만 보입니다. 「값이 있는 것 n개」가 목록 위에 나옵니다. 값이 하나도 없으면 「값이 있는 비밀값이 없습니다」가 나옵니다.
잠긴 항목
모델 제공자 키와 동작 변수는 잠긴 항목입니다. 잠긴 항목은 주인이 바꿀 수 없으며, 「잠긴 변수도 보기」를 켜면 「잠금」 표시와 함께 보입니다.
주의: 브라우저 주소 표시줄의 주소가
https로 시작하지 않으면(암호화되지 않은 주소) 값을 넣는 칸이 나오지 않고 「암호화되지 않은 주소(http, 사내 IP)에서는 값을 넣을 수 없습니다」가 나옵니다. 이때는 관리자에게 알립니다.
새 비밀값 넣기
이름은 스킬 설명서나 MCP 서버 안내가 정한 이름을 그대로 적습니다. 정한 이름이 없으면 영문자로 시작하고 영문 대문자, 숫자, _ 로만 적습니다. 소문자로 적으면 대문자로 바뀝니다.
- 「새로 넣기」 구역의 「새 이름」 칸에 이름을 적습니다. 예: MY_API_KEY
- 「새 비밀값 넣기」를 누릅니다.
- 값을 붙여 넣고 저장합니다.
그림 4.4-2. 「새로 넣기」 구역
성공하면 목록에 그 이름이 「값 있음」으로 나옵니다. 저장되지 않으면 화면의 오류 문장을 읽고, 이름 규칙이나 주소(https)를 확인합니다.
이미 있는 값 찾기와 바꾸기
비밀값 목록은 기본으로 값이 있는 항목만 보여 줍니다. 목록에 없는 항목을 찾을 때는 「Hermes 가 아는 변수 모두 보기」를 켭니다. Hermes 는 AAS 안에서 AI 에이전트를 실제로 실행하는 프로그램입니다.
「이름 검색」 칸에 이름 일부를 적어 찾을 수 있습니다. 검색 칸으로는 / 키로 이동합니다.
값을 바꾸려면 항목의 「값 바꾸기」를 누르고 「새 값」을 넣어 저장합니다. 값이 없던 항목은 「값 넣기」를 누릅니다. 바꾸기 전 확인 창에 「지금 값은 다시 볼 수 없어 되돌릴 수 없습니다」가 나옵니다. 이전 값을 따로 보관해 두지 않았다면 되돌릴 수 없습니다. 이전 값을 모르면 그 서비스에서 키를 새로 발급해 넣습니다.
비밀값 지우기
- 항목의 「지우기」를 누릅니다.
- 확인을 위해 비밀값 이름을 입력합니다.
- 지우기를 확정합니다.
지운 값은 되돌릴 수 없습니다. 그 값을 쓰던 스킬이나 MCP 서버는 실패할 수 있습니다. 되돌리려면 그 서비스에서 키를 다시 확인하거나 새로 발급해 같은 이름으로 다시 넣습니다.
인증 파일(고급)
Google 서비스를 연결하거나 안내를 받았을 때만 읽습니다. 해당하지 않 으면 건너뜁니다.
「비밀값(.env)」 탭 아래의 「인증 파일(JSON)」 구역에서 JSON 형식의 자격 파일을 다룹니다. 파일 내용은 화면에 나오지 않고 내려받을 수도 없습니다. AI 에이전트는 이 파일을 읽을 수 있습니다.
| 파일 | 설명 |
|---|---|
google_client_secret.json | Google Cloud 콘솔에서 받은 client_secret_*.json 을 올립니다. |
google_token.json | Google 로그인 토큰입니다. 채팅에서 google-workspace 로그인을 하면 만들어집니다. |
secrets/<이름>.json | 설정이나 스킬이 경로로 가리키는 JSON 파일입니다. 「새 JSON 파일」로 만듭니다. |
각 줄에는 파일이 있는지, 마지막으로 바꾼 시각, 바꾼 사람이 나옵니다.
파일 올리기와 바꾸기
- 줄의 「파일 올리기」(이미 있으면 「파일 바꾸기」)를 누릅니다.
.json파일을 고릅니다.- 「선택: <파일 이름> · <크기>」를 확인하고 「저장」을 누릅니다.
「저장했습니다」가 나오면 끝납니다. google_client_secret.json 을 저장한 뒤에는 「다음: 채팅에서 Google 로그인」 안내를 따릅니다.
파일은 64KB 이하의 JSON 파일이어야 합니다. JSON 은 서비스가 내려 주는 설정용 텍스트 파일 형식입니다. 칸에 맞지 않는 JSON 이면 「이 칸에 맞는 JSON 이 아닙니다. 파일을 확인하세요」가 나옵니다.
붙여 넣기 칸은 없습니다. 비밀 내용이 화면에 나오지 않게 파일 고르기만 지원합니다.
새 JSON 파일 만들기
- 「새 JSON 파일」을 누르고 파일 이름을 적습니다. 예: omdm
- 「만들 파일: secrets/omdm.json」으로 경로를 확인합니다.
.json파일을 골라 저장합니다.
이름은 영문 소문자, 숫자, _, - 로 63자까지 적습니다. 확장자 .json 은 자동으로 붙습니다.
파일 지우기
줄의 「지우기」를 누르고 확인 칸에 파일 경로를 입력합니다. 지우면 되살릴 수 없습니다. 바꾸기 전 파일도 되살릴 수 없습니다.
이 구역을 쓸 수 없는 경우
- 쿠버네티스에 설치한 환경에서만 쓸 수 있습니다. 한 컴퓨터용 시험 설치에서는 쓸 수 없습니다.
- 이름이 없는 기본 프로파일(default)에서는 쓸 수 없습니다. 주 프로파일(main) 같은 이름 있는 프로파일을 고릅니다.
https주소에서만 쓸 수 있습 니다.- 접근 권한만 받은 사용자는 인증 파일을 바꿀 수 없습니다.
- 「PC 가져오기가 끝난 뒤 다시 하세요」가 나오면 가져오기가 끝나기를 기다립니다.
- 「오퍼레이터 갱신이 필요합니다」 같은 안내는 서버 업데이트가 필요하다는 뜻입니다. 관리자에게 그 문장을 그대로 전달합니다.
키 만료 확인
프로파일 개요 탭의 「API 키·토큰」 줄에 개수와 만료가 가까운 개수가 나옵니다. 키와 토큰이 어디에 있는지 한눈에 보려면 7.4. API 키·토큰을 봅니다.