7.4. API 키·토큰
개요
AI 에이전트는 AI 모델이나 외부 서비스에 접속할 때 키와 토큰을 씁니다. 「API 키·토큰」 화면은 이 키와 토큰이 어느 프로파일(작업공간 안의 AI 에이전트 한 명의 설정 묶음, 4.2. 프로파일 개요와 모델)에 어떤 상태로 들어 있는지 보여 줍니다. 키가 곧 끝나는지, 값이 비어 있는지 확인할 때 씁니다. 값이 필요한 서비스를 연결하기 전에 이미 들어 있는지 볼 때도 씁니다.
권한: 화면은 모든 사용자가 봅니다. 값을 넣고 바꾸는 일은 AI 에이전트 작업공간의 주인, 팀 관리자, 관리자가 합니다. 「관리 기록」의 상태, 담당, 메모는 관리자만 적습니다.
용어는 다음과 같습니다. 전체 낱말은 A.1. 용어 사전에 있습니다.
| 용어 | 뜻 |
|---|---|
| API 키 | 서비스가 사용자를 알아보도록 발급하는 비밀 문자열입니다. |
| 토큰(접속) | 접속 권한을 담은 비밀 문자열입니다. 만료일이 있는 것이 많습니다. AI 가 읽고 쓴 글의 양을 세는 토큰(7.1. 사용량)과 다릅니다. |
| LLM | AI 가 글을 읽고 쓰는 데 쓰는 대규모 언어 모델(Large Language Model)입니다. |
| MCP | 외부 프로그램의 기능을 AI 에이전트에 붙이는 연결 방식(Model Context Protocol)입니다. 4.5. 외부 도구(MCP) 연결을 봅니다. |
주의: 이 화면은 키와 토큰의 값을 보여 주지 않습니다. 이름, 위치, 채워져 있는지, 만료일, 같은 값이 여러 곳에 있는지만 보여 줍니다.
화면 열기
왼쪽 메뉴의 「설정 › API 키·토큰」을 엽니다. 메뉴 옆에 숫자가 붙으면 만료되었거나 곧 만료되는 키가 있다는 뜻입니다.
그림 7.4-1. 「API 키 · 토큰」 화면
화면 머리의 「프로파일」 선택에서 보고 싶은 프로파일을 고릅니다. 「전체 프로파일」을 고르면 모든 프로파일의 행이 나옵니다.
AAS 가 모든 프로파일에 기본으로 넣는 AI 모델 연결 키는 표에서 빠집니다. 빠진 개수는 표 아래 안내에 나옵니다. 모델 연결은 프로파일의 설정에서 봅니다.
카드로 확인할 것 고르기
화면 위의 카드에는 확인할 항목의 수가 나옵니다. 「만료·만료 임박」, 「빈 값」, 「백업·임시 파일」 카드를 누르면 그 조건의 행만 보입니다.
| 카드 | 뜻 |
|---|---|
| 만료·만료 임박 | 이미 만료되었거나 14일 안에 만료되는 키 |
| 빈 값 | 이름만 있고 값이 비어 있는 키 |
| 백업·임시 파일 | 백업이나 임시 파일로 보이는 항목. 정리해도 되는지 확인합니다. |
| 복사된 값 | 같은 값이 여러 곳에 복사된 키. 바꿀 때 모두 함께 바꿔야 합니다. |
「확인할 것」 보기에는 위 문제가 있는 행만 모입니다.
표 읽기
표의 행은 키나 토큰 하나입니다. 행을 누르면 서랍이 열립니다.
| 칸 | 내용 |
|---|---|
| 이름 | 키나 토큰의 이름 |
| 범위 | 모든 프로파일이 함께 쓰는 「전역」인지, 어느 프로파일의 것인지 |
| 인터페이스 | 접속하는 대상. 예: LLM(AI 모델), MCP(외부 도구) |
| 저장 위치 | .env, config.yaml, secrets 폴더 같은 위치 |
| 값 | 「채워져 있음」 또는 「비어 있음」 |
| 만료 | 만료일. 값에 만료 정보가 있을 때만 나옵니다. |
서랍의 「쓰는 곳」에서 이 키를 어느 서비스나 도구가 쓰는지 봅니다. 「같은 값이 N곳에」 표시가 있으면 같은 값이 복사된 곳이 나옵니다.
값 넣거나 바꾸기
서랍의 「값 바꾸기」 구역에서 키를 바꿉니다. 먼저 서랍과 표의 「저장 위치」 칸에 나온 이름을 보고, 아래 표에서 같은 줄의 방법을 고릅니다.
| 저장 위치 | 바꾸는 방법 |
|---|---|
.env | 서랍의 「값 바꾸기」 구역에서 값을 넣거나 바꿉니다. 「{프로파일} 프로파일의 비밀값에서 바꾸기」 링크로 비밀값 탭도 열 수 있습니다. |
config.yaml | 「{프로파일} 프로파일의 설정에서 바꾸기」 링크로 설정 탭에서 바꿉니다. |
secrets 폴더, auth.json | 이 화면에서 바꿀 수 없습니다. 서랍의 안내 문구를 관리자에게 전달합니다. |
화면 위의 「새 비밀값」으로 새 키를 넣을 수도 있습니다. 프로파일을 고르고, 이름을 영문 대문자·숫자·밑줄로 적고, 값을 넣습니다. 이름은 영문 대문자로 시작해 2자에서 64자까지입니다. 예: TELEGRAM_BOT_TOKEN 이름이 규칙에 맞지 않으면 「이름은 영문 대문자로 시작하고 영문 대문자·숫자·_ 로 2~64자여야 합니다」가 나오고 저장되지 않습니다. 규칙에 맞게 고쳐 다시 넣습니다.
권한이 없으면 값을 넣는 버튼이 보이지 않습니다. 이때는 주인이나 관리자에게 요청합니다. 안전한 연결(https)이 아닌 주소에서는 비밀값을 넣을 수 없습니다. 그때는 https 주소로 접속합니다.
바꾼 값은 화면에 다시 나오지 않습니다. 바꾼 값은 다음 대화부터 적용됩니다. 메신저용 값은 게이트웨이(AI 에이전트가 메신저와 예약 작업을 받는 통로)를 다시 시작해야 적용되므로, 바꾼 뒤 관리자에게 게이트웨이를 다시 시작해 달라고 요청합니다. 새로 넣은 키의 「쓰는 곳」이 0 인 것은 정상입니다. 아직 어떤 도구도 그 키를 쓰기 전이기 때문입니다.
성공하면 표의 「값」 칸이 「채워져 있음」으로 바뀝니다. 「새 비밀값」은 「○○ 을(를) ○○ 프로파일에 저장했습니다」 알림도 나옵니다. 「값」 칸이 계속 「비어 있음」이면 이름이 맞는지, 권한이 있는지 확인하고, 그래도 같으면 관리자에게 알립니다.
값 넣기와 인증 파일 올리기를 자세히 알려면 4.4. 비밀값과 인증 파일을 봅니다.
만료 확인하기
- 왼쪽 메뉴의 「API 키·토큰」 옆 숫자를 봅니다.
- 화 면에서 「만료·만료 임박」 카드를 누릅니다.
- 행을 눌러 만료일과 쓰는 곳을 확인합니다.
- 키를 발급한 서비스에서 새 키를 받은 뒤, 「값 바꾸기」에서 새 값을 넣습니다. 새 키는 관리자나 해당 서비스 담당자에게 받습니다.
AAS 에 접속하는 Claude Code 토큰의 만료는 이 화면이 아니라 「설정 › Claude Code 연결」에서 봅니다. 자세한 내용은 7.5. Claude Code 연결을 봅니다.
관리 기록
「확인할 것」 옆의 「등록됨」 보기에는 관리자가 담당과 용도를 적어 둔 항목이 나옵니다. 일반 사용자는 읽기만 합니다.