AI 에이전트 직접 설치하는 법 — 우분투 서버에 AI 직원을 올리는 순서
«챗GPT 창에 매번 붙여 넣는 대신, 우리 회사 일을 알아서 나눠 받는 AI 직원을 서버에 두고 싶다.» 요즘 이런 문의가 많아요. AI 에이전트는 생각보다 단순한 구조라서 서버 한 대, AI 모델 API 키, 지시를 받을 창구(디스코드 같은 메신저) 세 가지만 있으면 직접 올릴 수 있어요. 이 글은 저희가 실제로 운영하는 AI 직원 시스템(AICO)을 고객 서버에 설치하는 순서를 그대로 옮긴 것이에요. 어디서 막히는지도 함께 적었어요.
우분투 22.04 또는 24.04 서버(sudo 권한, 메모리 4GB 이상 권장)에 실행 환경(Python, Node.js)을 깔고, API 키와 봇 토큰을 서버 안 비밀 파일 한 곳에만 넣은 뒤 서비스로 등록하면 돼요. 가장 많이 막히는 곳은 디스코드 개발자 포털의 Message Content Intent를 켜지 않은 경우예요. 비용은 서버 이용료와 API 사용료가 따로 들고, API 사용료는 쓰는 양에 따라 달라져요.
AI 에이전트는 무엇으로 이뤄져 있나
«AI 에이전트»라고 하면 거창해 보이지만, 설치 관점에서 보면 세 덩어리예요.
| 구성 | 하는 일 | 준비할 것 |
|---|---|---|
| 두뇌(AI 모델) | 지시를 읽고 계획을 세우고 글·코드를 써요 | Anthropic API 키(sk-ant-로 시작) |
| 몸(실행 서버) | 파일을 만들고, 브라우저를 열고, 명령을 실행해요 | 우분투 서버 1대(클라우드 VM도 돼요) |
| 입(대화 창구) | 사람의 지시를 받고 결과와 승인 요청을 올려요 | 디스코드 서버와 봇 토큰 |
AI 직원이 여러 명인 구조라면 여기에 «누가 무엇을 맡는지»를 정하는 조직도와, 밖으로 나가는 일(메일·게시·결제)을 막아 두는 승인 장치가 더해져요. 승인 장치는 설치할 때 기본으로 켜 두는 것을 권해요.
준비물 체크리스트
- 서버 — Ubuntu 22.04 또는 24.04 LTS, sudo 권한, 인터넷 연결. 브라우저 도구까지 쓰려면 메모리 4GB 이상이 편해요. 두 버전 모두 장기 지원(LTS) 버전이에요.
- Anthropic API 키 — Claude 콘솔(platform.claude.com)의 API Keys에서 만들어요. 결제 수단이나 크레딧이 없으면 키가 있어도 호출이 막혀요.
- 디스코드 서버 — 내가 관리자인 서버 하나. 기존 커뮤니티 서버보다 AI 직원 전용으로 새로 만드는 쪽이 채널이 섞이지 않아요.
- 디스코드 봇 — 아래 3장에서 만들어요.
- 내 디스코드 사용자 ID — 지시와 승인을 할 수 있는 사람을 이 ID로 묶어요.
디스코드 봇 만들기 — 여기서 가장 많이 막혀요
- 디스코드 개발자 포털(discord.com/developers/applications)에서 New Application을 눌러 이름을 정해요.
- Bot 메뉴에서 Reset Token으로 토큰을 복사해요. 토큰은 비밀번호와 같아서 채팅창이나 메일에 붙여 넣지 않아요.
- 같은 화면의 Privileged Gateway Intents에서 Server Members Intent와 Message Content Intent를 켜요. 메시지 내용을 읽어야 지시를 알아들을 수 있는데, 이 권한은 디스코드가 «특권 인텐트»로 따로 묶어 두었어요. 꺼져 있으면 봇이 접속하자마자
PrivilegedIntentsRequired오류로 멈춰요. - OAuth2 → URL Generator에서 Scopes는
bot,applications.commands를 고르고, 채널 관리·메시지 보내기·스레드·파일 첨부·기록 읽기 권한을 골라요. - 만들어진 초대 주소를 열어 봇을 내 서버에 넣어요.
- 디스코드 설정 → 고급 → 개발자 모드를 켜고, 서버 아이콘과 내 프로필을 우클릭해 서버 ID와 사용자 ID를 복사해요.
저희가 쓰는 AI 직원 시스템을 고객님 우분투 서버에 설치하고, 디스코드 연결과 첫 지시까지 화면 공유로 함께 해요. 키와 토큰은 고객님이 직접 입력해요. AICO 살펴보기 →
설치 순서 — 서버에서 하는 일
저희 설치 스크립트가 하는 일을 순서대로 적으면 이래요. 다른 에이전트 프로그램을 직접 올릴 때도 순서는 거의 같아요.
| 단계 | 하는 일 | 확인할 것 |
|---|---|---|
| 1 | 운영체제 버전 확인 | 22.04/24.04가 아니면 패키지 이름이 달라 실패할 수 있어요 |
| 2 | 의존성 설치(python3, venv, Node.js, sqlite3) | Node.js는 배포판 기본 버전이 낮을 수 있어 공식 저장소로 받아요 |
| 3 | 회사 이름·도메인·대표 메일, API 키, 봇 토큰, 서버 ID 입력 | 키는 화면에 보이지 않게 입력받아요 |
| 4 | 프로그램을 /opt 아래로 복사, 가상환경과 패키지 설치 | 전용 사용자 계정으로 실행되게 해요 |
| 5 | 설정 파일(config.yaml)과 회사 지식 파일 생성 | 회사 정보는 설정 파일에, 비밀값은 다음 단계 파일에만 |
| 6 | 키를 /etc 아래 비밀 파일에 저장(관리자만 읽기) | 파일 권한 600, 깃 저장소에 들어가지 않는 위치 |
| 7 | 브라우저 도구(playwright, chromium) 설치 | 실패해도 나머지는 동작하니 나중에 다시 시도해요 |
| 8 | systemd 서비스 등록, 자가 점검, 첫 기동 | API 키와 봇 토큰을 실제로 호출해 확인해요 |
설치가 끝나면 디스코드에 지휘·부서 채널이 생기고, 보고 채널에 «출근했다»는 첫 메시지가 올라와요. 비서 채널에 «자기소개 한 줄 부탁해요»라고 써서 답이 오면 정상이에요.
키와 토큰은 어디에 두나
- 설정 파일과 비밀 파일을 나눠요. 회사 이름·채널 이름 같은 값은 config.yaml에, API 키·봇 토큰은 별도 비밀 파일(예: /etc/aico/secrets.env, 권한 600)에만 둬요. 설정 파일은 백업하거나 남에게 보여 줘도 되게 만드는 것이 목적이에요.
- 설치를 맡길 때도 키는 내가 입력해요. 대행업체에 키를 메신저로 보내지 말고, 화면 공유 상태에서 직접 입력하는 방식을 요구하세요. 저희 설치 대행도 이렇게 진행하고 키를 보관하지 않아요.
- 키를 바꾸면 서비스를 다시 시작해요. 토큰이 새어 나갔다고 의심되면 개발자 포털에서 Reset Token, 콘솔에서 키 폐기 후 다시 넣어요.
자주 막히는 오류와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
| API 확인 실패 HTTP 401 | 키 복사 오류, 폐기된 키 | 키를 다시 만들어 입력, 콘솔에서 결제 수단·크레딧 확인 |
| 디스코드 토큰 확인 실패 HTTP 401 | 토큰을 Reset한 뒤 예전 값을 넣음 | 새 토큰을 다시 복사해 입력 |
| 로그에 PrivilegedIntentsRequired | 특권 인텐트 꺼짐 | Server Members·Message Content Intent 켜기 |
| 슬래시 명령이 안 보임 | 초대할 때 applications.commands 빠짐 | 그 범위를 넣은 주소로 다시 초대 |
| 내 글에 반응이 없음 | 설치 때 넣은 대표 사용자 ID가 다름 | 사용자 ID를 다시 복사해 재설정 |
| API 429 오류 | 요청 한도(rate limit) 초과 | 동시에 일하는 AI 직원 수를 줄이고 자동 회의를 꺼 둠 |
비용은 어떻게 나오나
직접 설치하면 프로그램 비용과 별개로 두 가지가 계속 들어요.
- 서버 이용료 — 쓰는 클라우드와 사양에 따라 달라요. 사무실에 있는 리눅스 PC로도 시험은 할 수 있어요.
- AI API 사용료 — 모델과 쓰는 양(토큰)에 따라 달라지고 Anthropic 계정으로 청구돼요. 모델별 단가는 공식 가격 문서에서 확인해요. AI 직원이 많고 자동 회의를 많이 켤수록 사용량이 늘어나요. 처음에는 자동 반복을 꺼 둔 채 직접 지시하며 사용량을 보고, 콘솔에서 월 사용 한도를 걸어 두는 것을 권해요.
AICO 설치 대행은 사전 점검, 설치·기동, 디스코드 연결, 화상 사용 교육 1회까지 490,000원(부가세 포함)이에요. API 키와 토큰은 고객님이 직접 입력하고 고객님 서버에만 저장돼요. 설치 뒤에는 필요할 때만 월 관리(99,000원, 자동결제 아님)를 이용하시면 돼요.
AICO 설치 대행 알아보기팀플럿(주) · 서버 이용료와 AI API 사용료는 고객님이 각 회사에 직접 내요자주 묻는 질문
AI 에이전트를 설치하려면 서버가 꼭 있어야 하나요?
네, 24시간 지시를 받으려면 계속 켜져 있는 우분투 서버가 필요해요. 클라우드 VM이나 사무실 리눅스 PC 모두 돼요. 우분투 22.04 또는 24.04, sudo 권한, 메모리 4GB 이상을 권해요.
디스코드 봇이 메시지를 못 읽어요. 왜 그런가요?
개발자 포털의 Bot 메뉴에서 Message Content Intent가 꺼져 있을 가능성이 커요. 디스코드는 메시지 내용 읽기를 특권 인텐트로 따로 관리해서, 켜지 않으면 봇이 접속하지 못하거나 내용을 받지 못해요.
설치 업체에 API 키를 보내야 하나요?
보내지 않는 쪽이 안전해요. 화면 공유를 켠 상태에서 본인이 직접 입력하고, 키는 서버 안 비밀 파일에만 저장되게 하세요. AICO 설치 대행도 이 방식으로만 진행해요.
AI API 사용료는 한 달에 얼마나 나오나요?
쓰는 모델과 양에 따라 달라서 미리 정해진 금액은 없어요. 처음에는 자동 반복 기능을 꺼 두고, Anthropic 콘솔에서 사용 한도를 걸어 둔 채 일주일쯤 실제 사용량을 보고 판단하는 것을 권해요.
참고 문서
- Anthropic Claude API 개요 — API 키 발급과 호출 방식
- Anthropic 모델 가격 — 모델별 토큰 단가
- Anthropic API 요청 한도(rate limits) — 429 오류와 한도
- Claude Code 개요 — 에이전트 실행 도구
- Discord Gateway — Privileged Intents — Message Content·Server Members Intent
- Discord OAuth2 — 봇 초대 범위 — bot · applications.commands
- Ubuntu 릴리스 주기 — 22.04·24.04 LTS 지원 기간
이 글은 2026년 10월 11일 기준 공식 문서와 저희 설치 스크립트 실제 동작으로 썼어요. 각 서비스의 화면 이름과 정책은 바뀔 수 있어요.