Linux 서버에 Claude Code와 ChatGPT Codex 설치하기: 단계별 가이드

이 가이드는 갓 설치한 Debian 또는 Ubuntu 서버에서 출발해, 로그를 분석하고 설정을 점검하며 유지보수 작업을 수행하는 AI 에이전트를 실제로 쓸 수 있는 상태로 만드는 과정을 안내합니다. Claude Code(Anthropic)와 Codex CLI(OpenAI, ChatGPT 계열의 명령줄 도구)를 설정하되 둘 다 권한이 제한된 전용 사용자로 실행하고, 세 번째 선택지로 Gemini CLI(Google)도 소개합니다. 모든 명령은 Debian 13과 Ubuntu 24.04가 설치된 KernelHost KVM 루트 서버에서 직접 실행해 확인했습니다. AI 관리형 서버가 무엇인지, 어떤 구조가 있는지는 AI 관리형 서버: AI 에이전트를 안전하게 연결하기 글에서 설명합니다.

2026년 9월 기준입니다. 도구가 빠르게 발전하고 있으니, 확실하지 않을 때는 각각 claude --help, codex --help, gemini --help로 옵션을 확인하세요.

사전 요구 사항

• Debian 12 또는 13, 혹은 Ubuntu 22.04 또는 24.04가 설치되어 있고 SSH로 root 접근이 가능한 루트 서버. AlmaLinux와 Rocky Linux에서도 단계는 같으며, 패키지 명령으로 dnf를 apt 대신 쓴다는 점만 다릅니다.
• 기본 보안 강화 완료: 키 기반 SSH 로그인, 방화벽, 자동 보안 업데이트. 새 루트 서버 체크리스트에서 이 내용을 다룹니다.
• Anthropic 계정(Claude Pro, Max 또는 Team)이나 API 키, ChatGPT 계정(Plus, Pro 또는 Team)이나 OpenAI API 키. 도구를 하나만 설정하려면 그중 하나만 있으면 됩니다.
• api.anthropic.com과 api.openai.com으로 나가는 HTTPS 연결. KernelHost 서버에서는 기본으로 허용되어 있으며, 제한적인 자체 방화벽을 쓰고 있다면 이 연결을 허용해야 합니다.

AI 에이전트에는 어떤 서버면 충분할까요?

언어 모델은 제공업체 쪽에서 실행되므로, AI 에이전트를 위해 서버에 특별한 하드웨어나 GPU를 갖출 필요는 없습니다. 서버에서는 명령줄 도구와 Node.js만 실행되며, 둘을 합쳐도 세션 중에 보통 수백 메가바이트의 메모리를 쓰는 정도입니다. 다른 작업이 거의 없는 서버라면 2 vCPU와 4 GB RAM이면 충분합니다. 서버에서 웹사이트, 데이터베이스, 게임 서버도 함께 운영한다면 에이전트용으로 1 GB 정도의 메모리 여유를 잡아 두세요. KernelHost의 KVM 루트 서버는 약 30초 만에 준비되고, 최소 약정 기간 없이 PrePaid 방식으로 요금이 청구되므로 에이전트를 먼저 시험해 보는 테스트 시스템으로도 적합합니다.

1단계: 전용 사용자 만들기와 sudo 제한

에이전트는 절대 root로 실행하지 않습니다. 대신 전용 계정을 주고, sudo 허용 목록을 통해 꼭 필요한 명령만 실행할 수 있게 합니다. 읽기 전용 명령 몇 개로 시작하고, 작업에 정말 필요할 때만 목록을 넓히세요.

sudo adduser --disabled-password --gecos "KI-Agent" aiagent
sudo tee /etc/sudoers.d/aiagent >/dev/null <<'EOF'
aiagent ALL=(root) NOPASSWD: /usr/bin/journalctl *, /usr/bin/systemctl status *, /usr/bin/systemctl restart nginx, /usr/bin/apt-get update, /usr/bin/apt-get upgrade -y, /usr/bin/tail *, /usr/bin/df *, /usr/bin/ss *
EOF
sudo chmod 440 /etc/sudoers.d/aiagent
sudo visudo -cf /etc/sudoers.d/aiagent

마지막 줄은 문법을 검사합니다. sudoers 파일에 오류가 하나라도 있으면 모든 사용자의 sudo가 막힐 수 있으므로 이 검사는 항상 거쳐야 합니다. --disabled-password는 누구도 비밀번호로 aiagent 계정에 로그인할 수 없게 합니다. 이 계정으로는 나중에 sudo -iu aiagent로 전환합니다. sudo 사용자의 기본 원리는 리눅스에서 sudo 사용자 만들기 글에서 설명합니다.

sudo 편집기 대신 필요한 쓰기 권한만 부여하기

에이전트가 /etc의 파일을 수정해야 한다면 nano를 sudo로 허용하지 마세요(그러면 /etc/sudoers를 포함해 어떤 파일이든 편집할 수 있게 됩니다). 대신 그룹과 대상을 정한 쓰기 권한을 사용하세요. 예를 들면 setfacl -m u:aiagent:rw /etc/nginx/sites-available/meine-seite.conf와 같은 방식입니다. 처음에는 에이전트가 변경을 제안하고 여러분이 직접 반영하는 것으로 충분합니다.

허용 목록에 와일드카드가 들어간 명령도 마찬가지입니다. /usr/bin/tail *는 root가 접근할 수 있는 모든 파일을 에이전트가 읽을 수 있게 하며, 여기에는 인증 정보가 담긴 파일도 포함됩니다. 이를 원하지 않는다면 /usr/bin/tail -n 200 /var/log/nginx/error.log처럼 허용할 경로를 명시해 두세요.

2단계: Node.js 22 설치

두 도구 모두 Node.js로 실행됩니다. Claude Code는 최소 18 버전, Codex CLI는 최소 22 버전이 필요하므로 22 LTS를 설치합니다. Debian 12의 패키지 저장소는 너무 오래된 버전을 제공하고, NodeSource는 최신 버전을 제공합니다.

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
node --version
npm --version

root 권한이 필요 없는 대안: nvm

인터넷에서 받은 스크립트를 root 권한으로 실행하고 싶지 않다면 에이전트 사용자의 홈 디렉터리에서 nvm을 사용하세요. 이 방법은 처음부터 끝까지 root 권한 없이 진행할 수 있습니다. nvm 설치 명령은 프로젝트의 README에서 가져오고, 그다음에는 세 줄이면 충분합니다.

nvm install 22
nvm alias default 22
node --version

자세한 내용과 다른 설치 방법은 Debian에 Node.js 설치하기 가이드에 정리되어 있습니다.

3단계: Claude Code 설치와 로그인

여기서부터는 에이전트 계정에서 작업합니다.

sudo -iu aiagent
curl -fsSL https://claude.ai/install.sh | bash
claude --version

네이티브 설치 프로그램은 Claude Code를 ~/.local/bin에 설치하고 스스로 최신 상태를 유지합니다. 대신 npm으로 npm install -g @anthropic-ai/claude-code를 실행해 설치할 수도 있습니다. 이때 EACCES 오류로 실패한다면 아래의 문제 해결 섹션을 참고하세요.

브라우저가 없는 서버에서 로그인하기

claude를 처음 실행하면 로그인을 요청합니다. Claude 계정을 쓰면 보통 브라우저가 열리지만, 브라우저가 없는 서버에서는 주소와 코드가 표시되므로 노트북이나 스마트폰에서 확인하면 됩니다. 이후 로그인은 로그아웃할 때까지 이 서버의 해당 사용자에게 계속 유지됩니다.

스크립트와 cron 작업용 API 키

스크립트와 cron 작업에는 API 키가 더 나은 선택입니다.

echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.bashrc
chmod 600 ~/.bashrc
source ~/.bashrc
claude -p "OK라고만 답해 줘" 

이렇게 하면 키는 다른 사용자가 읽을 수 없는 에이전트 사용자의 홈 디렉터리에만 저장됩니다. Anthropic 콘솔에서 키를 만들 때 월 지출 한도를 설정해 두면, 통제를 벗어난 세션이 생겨도 큰 비용으로 이어지지 않습니다. 키 자체는 에이전트에게 주는 작업 지시에도, 에이전트가 출력해야 하는 파일에도 절대 적지 마세요.

4단계: 서버용 Claude Code 설정

규칙 파일 CLAUDE.md

Claude Code는 시작할 때 현재 디렉터리에 있는 CLAUDE.md 파일을 읽습니다. 이 파일에는 모든 세션에 적용되는 규칙을 적습니다. 에이전트의 홈 디렉터리에 작업 디렉터리를 만들고 이 파일을 넣으세요.

mkdir -p ~/server && cd ~/server
cat > CLAUDE.md <<'EOF'
# 이 서버의 규칙
- 이 서버는 운영 서버(Debian 13, nginx, PHP-FPM, MariaDB)입니다.
- 읽기 전용 명령(journalctl, systemctl status, tail, df, ss)은 언제든 실행해도 됩니다.
- 쓰기 명령을 실행하기 전에는 무엇이 바뀌는지 짧게 설명하고 승인을 기다리세요.
- 패키지 제거, /var/lib 아래 파일 삭제, 사용자 생성과 삭제는 절대 하지 마세요.
- 비밀번호, 키, 고객 데이터는 출력에 절대 다시 적지 마세요.
- 작업이 끝날 때마다 세 문장으로 요약해 주세요.
EOF

이 파일은 운영하면서 함께 늘어납니다. 에이전트가 원하시는 것과 다르게 작업할 때마다 그 교정 내용을 새 규칙으로 추가하세요. 몇 주가 지나면 이 파일에 여러분 서버의 작업 방식이 꽤 정확하게 담깁니다.

settings.json의 허용 목록

여기에 도구 허용 목록을 더해, Claude Code가 읽기 전용 명령은 묻지 않고 실행하고 나머지는 모두 승인을 요청하게 합니다. ~/.claude/settings.json 파일은 이 사용자에게 적용됩니다.

mkdir -p ~/.claude
cat > ~/.claude/settings.json <<'EOF'
{
  "permissions": {
    "allow": [
      "Bash(sudo journalctl:*)",
      "Bash(sudo systemctl status:*)",
      "Bash(sudo tail:*)",
      "Bash(df:*)",
      "Bash(free:*)",
      "Bash(ss:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo rm:*)",
      "Bash(dd:*)",
      "Bash(mkfs:*)"
    ]
  }
}
EOF

거부 목록은 추가 안전망이지 벽이 아닙니다. 같은 명령도 얼마든지 다른 방식으로 쓸 수 있습니다. 실제 경계를 긋는 것은 1단계의 sudo 허용 목록입니다. 사용자가 할 수 없는 일은 에이전트도 할 수 없기 때문입니다.

대화형으로 실행하는 첫 작업

이제 첫 작업을 대화형으로 실행합니다.

cd ~/server && claude
> 지난 24시간 동안 journalctl에 기록된 오류를 요약하고, 가장 흔한 원인 세 가지를 알려 줘.

cron 작업으로 무인 실행하기

같은 작업을 무인으로 실행할 수도 있습니다. 예를 들어 매일 오전 7시에 cron 작업으로 실행하고 결과를 이메일로 받는 방식입니다.

0 7 * * * cd /home/aiagent/server && /home/aiagent/.local/bin/claude -p "지난 24시간 동안 journalctl에 기록된 오류와 경고를 요약해 줘. 서비스, 시각, 추정 원인을 알려 줘." --allowedTools "Bash(sudo journalctl:*)" 2>&1 | mail -s "서버 일일 보고서" admin@example.com

-p 옵션은 대화형 세션 없이 Claude Code를 시작하고, --allowedTools는 이 실행에 꼭 필요한 도구만 쓰도록 제한합니다. 쓰기 작업은 무인 실행에 넣지 않습니다. cron 작업을 설정하는 기본 방법은 리눅스에서 cron 작업 설정하기 글에서 설명합니다.

5단계: Codex CLI(ChatGPT) 설치와 로그인

설치와 로그인

Codex CLI는 ChatGPT의 기반 모델을 명령줄로 가져오는 OpenAI의 도구입니다. 같은 사용자 계정에서 설치합니다.

npm install -g @openai/codex
codex --version

로그인은 ChatGPT 계정(Plus, Pro 또는 Team)으로 합니다. codex를 실행하고 “Sign in with ChatGPT”를 선택한 뒤, 표시된 주소를 브라우저가 있는 기기에서 여세요. 스크립트용으로는 그 대신 OpenAI 플랫폼에서 발급한 API 키를 설정합니다.

echo 'export OPENAI_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

config.toml의 샌드박스와 승인 모드

Codex에는 자체 샌드박스와 승인 모드가 있습니다. 둘 다 ~/.codex/config.toml에서 지정하며, 운영 서버에는 다음 조합이 적절합니다.

mkdir -p ~/.codex
cat > ~/.codex/config.toml <<'EOF'
approval_policy = "on-request"
sandbox_mode = "workspace-write"
EOF

workspace-write는 현재 작업 디렉터리에서만 쓰기를 허용하고, on-request는 그 밖의 모든 작업에 대해 에이전트가 허가를 요청하게 합니다. danger-full-access 단계는 이 두 제한을 모두 해제하므로 운영 시스템에는 맞지 않습니다.

AGENTS.md의 규칙

Codex는 CLAUDE.md와 같은 규칙을 작업 디렉터리의 AGENTS.md 파일에서 읽습니다. 같은 내용을 그대로 써도 됩니다.

cp ~/server/CLAUDE.md ~/server/AGENTS.md
cd ~/server && codex "활성화된 systemd 서비스가 모두 실행 중인지 확인하고, 실패한 서비스를 마지막 오류 메시지와 함께 나열해 줘."

무인 실행에는 codex exec "Aufgabe"를 씁니다. claude -p에 해당하는 명령입니다.

6단계: 세 번째 선택지, Gemini CLI

Gemini CLI는 Google의 명령줄 도구이며 같은 원리로 작동합니다. 이 도구도 Node.js로 실행되며 같은 사용자 계정에 설치합니다.

npm install -g @google/gemini-cli
gemini --version

gemini를 처음 실행할 때 Google 계정으로 로그인하고, 스크립트용으로는 환경 변수 GEMINI_API_KEY에 API 키를 설정합니다. Gemini CLI는 작업 디렉터리의 GEMINI.md 파일에서 규칙을 읽으며, 여기에도 CLAUDE.md의 내용을 그대로 가져와 쓸 수 있습니다. 무인 실행은 gemini -p "Aufgabe"로 시작합니다. 세 도구 중 어느 것을 쓸지는 주로 이미 가지고 계신 계정에 달려 있습니다. 서버에서 일하는 방식은 세 도구 모두 같고, 여러 도구를 나란히 운영할 수도 있습니다.

대안: 에이전트가 내 컴퓨터에서 실행되며 SSH로 작업하는 방식

서버에 아무것도 설치하고 싶지 않다면 노트북에서 Claude Code나 Codex를 실행하고, 에이전트가 SSH로 명령을 보내게 하면 됩니다. 이를 위해 서버에는 에이전트 사용자의 전용 SSH 키를 등록하고, CLAUDE.md에는 모든 서버 명령 앞에 ssh aiagent@server를 붙인다는 규칙을 적어 둡니다. 가끔 하는 유지보수에는 이 방식이 잘 맞지만, 긴 작업과 cron 작업은 서버에서 직접 실행하는 편이 낫습니다. 전용 키, 호스트 별칭, 승인 절차를 갖춘 SSH 연결이 구체적으로 어떤 모습인지, 그리고 에이전트가 어떤 절차에 따라 운영 시스템에 배포하는지는 실무 사례 AI를 서버에 연결하기에서 보실 수 있습니다.

7단계: 보안 조치와 한계 설정

• 세션 전 스냅샷 또는 백업: 무언가를 변경할 세션이라면 매번 먼저 만들어 둡니다. 서버 백업 전략에서 이를 자동으로 실행하는 방법을 보여 줍니다.
• 승인 모드는 켜 둡니다. Claude Code의 --dangerously-skip-permissions와 Codex의 danger-full-access는 일회용 VM을 위한 것입니다.
• 비밀 정보는 접근할 수 없는 곳에 둡니다. 에이전트 사용자는 .env 파일, 데이터베이스 비밀번호, 고객 데이터를 읽을 수 없어야 합니다. 에이전트가 읽는 내용은 제공업체로 전송됩니다.
• 비용 한도는 제공업체 콘솔에서 API 키마다 설정합니다.
• 추적 가능성: etckeeper를 설치해 /etc 아래의 모든 변경이 Git에 기록되게 하고, 에이전트의 요약은 보관해 둡니다.
• 인바운드 쪽은 바뀌는 것이 없습니다. 두 도구 모두 아웃바운드 HTTPS만 필요합니다. 방화벽, Fail2ban, 호스팅 업체의 DDoS 방어는 그대로 유지됩니다.

처음 맡길 작업: 유용한 작업 다섯 가지

처음 맡기기에 가장 좋은 작업은 읽을 것은 많고 위험은 없는 작업입니다. 이런 작업은 에이전트가 얼마나 꼼꼼하게 일하는지 금방 보여 주고, 곧바로 쓸모 있는 결과를 냅니다.

• 로그 보고서: “지난 24시간의 오류와 경고를 서비스별로 묶어서 추정 원인과 함께 요약해 줘.”
• 서비스 점검: “실패한 systemd 서비스를 모두 마지막 오류 메시지와 함께 나열하고, 각각 무엇을 해야 할지 설명해 줘. 아무것도 변경하지 마.”
• 디스크 공간: “어떤 디렉터리가 공간을 가장 많이 차지하는지 보여 주고, 안전하게 정리할 수 있는 것을 제안해 줘.” 배경 설명은 리눅스에서 디스크가 가득 찼을 때 글에 있습니다.
• 업데이트: “보안 업데이트가 대기 중인 패키지는 무엇이고, 업데이트 후에 재시작해야 하는 서비스는 무엇이야?”
• 웹 서버: “nginx 설정에 오류나 오래된 설정이 있는지 점검하고, 찾은 항목을 하나하나 설명해 줘.”

이런 분석 결과가 정확할 때 비로소 에이전트에게 쓰기 작업을 맡길 만하며, 그때도 테스트 시스템에서 먼저 시작하세요.

흔한 오류와 해결 방법

도구를 최신 상태로 유지하기

네이티브 설치 프로그램으로 설치한 Claude Code는 스스로 업데이트됩니다. npm으로 설치한 도구는 명령 하나로 최신 버전으로 올릴 수 있습니다.

npm update -g @openai/codex @google/gemini-cli
codex --version
gemini --version

새 버전에서는 옵션이나 기본 설정이 바뀌기도 합니다. 업데이트 후에는 무인 실행을 계속 돌리기 전에 변경 내역을 간단히 읽어 보고, 다음 일일 보고서에 이상한 점이 없는지 확인하세요.

결론

서버의 AI 에이전트는 한 시간이면 설정할 수 있습니다. 사용자, sudo 허용 목록, Node.js, 도구, 규칙이 전부입니다. 정작 중요한 일은 한계를 정하는 것이며, 이 가이드에서는 그 한계를 일부러 좁게 잡았습니다. 작업이 요구할 때 한 단계씩 넓히고, 절대 한꺼번에 풀지 마세요. KernelHost 루트 서버나 전용 서버에서는 이를 위해 따로 활성화할 것이 없습니다. root 접근, 배포판 자유 선택, 아웃바운드 연결이 기본으로 제공됩니다.

그다음 에이전트가 백업, 롤백 경로, 승인 절차를 갖추고 운영 시스템에 배포하는 방법은 실무 사례 AI를 서버에 연결하기에서 설명합니다.

핵심 요약

• Claude Code, Codex CLI, Gemini CLI는 Node.js 22가 설치된 모든 리눅스 서버에서 실행되며, GPU는 필요 없습니다.
• 에이전트에게는 sudo 허용 목록이 적용된 전용 사용자를 주고, root로는 절대 실행하지 않습니다.
• 규칙은 CLAUDE.md, AGENTS.md 또는 GEMINI.md에 적고, 읽기 전용 명령은 허용 목록에 넣으며, 나머지는 모두 승인을 거칩니다.
• cron 작업과 스크립트에는 지출 한도를 설정한 API 키가 깔끔한 방법이며, 무인 실행은 읽기 작업만 합니다.
• 세션 전에는 백업하고, 비밀 정보는 접근할 수 없는 곳에 두며, 승인 모드는 켜 둡니다.
• KernelHost 서버에서는 root 접근, 배포판 자유 선택, 아웃바운드 연결이 기본으로 제공됩니다.