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

이 가이드는 갓 설치한 Debian 또는 Ubuntu 서버에서 출발해, 로그를 분석하고 설정을 점검하고 유지보수 작업을 수행하는 작동 가능한 AI 에이전트까지 안내합니다. Claude Code(Anthropic)와 Codex CLI(OpenAI, ChatGPT 뒤에 있는 명령줄 도구)를 설정하며, 둘 다 권한이 제한된 전용 사용자 아래에서 실행합니다. 모든 명령은 Debian 13과 Ubuntu 24.04가 설치된 KernelHost KVM 루트 서버에서 테스트했습니다. AI 관리형 서버가 무엇이고 어떤 구조가 있는지는 AI 관리형 서버: AI 에이전트를 안전하게 연결하기 글에서 설명합니다.

2026년 9월 기준입니다. 도구는 빠르게 발전하므로 확실하지 않으면 claude --help 또는 codex --help로 옵션을 확인하세요.

사전 요구사항

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

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

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

sudo adduser --disabled-password --gecos "AI 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로 이 계정으로 전환합니다.

에이전트가 /etc의 파일을 수정해야 한다면 sudo로 nano를 주지 마세요(그러면 /etc/sudoers를 포함해 모든 파일을 편집할 수 있게 됩니다). 대신 그룹과 정밀한 쓰기 권한을 사용하세요. 예를 들어 setfacl -m u:aiagent:rw /etc/nginx/sites-available/my-site.conf입니다. 처음에는 에이전트가 변경을 제안하고 여러분이 실행하는 것으로 충분합니다.

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 권한이 전혀 필요 없습니다. 자세한 내용과 대안은 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 키가 더 나은 선택입니다.

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

이렇게 하면 키는 다른 사용자가 읽을 수 없는 에이전트 사용자의 홈 디렉터리에만 있습니다. Anthropic 콘솔에서 월 지출 한도를 걸어 만들면, 통제를 벗어난 세션이 비싸질 수 없습니다.

4단계: 서버용 Claude Code 설정

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

여기에 도구 허용 목록을 더해, 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

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

cd ~/server && claude
> 지난 24시간 journalctl의 오류를 요약하고 가장 흔한 원인 세 가지를 말해줘.

같은 작업을 무인으로, 예를 들어 매일 아침 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는 도구를 이 실행에 필요한 것으로만 제한합니다. 쓰기 작업은 무인 실행에 넣지 않습니다.

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

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 수준은 둘 다 해제하며 운영 시스템에는 맞지 않습니다. CLAUDE.md와 같은 규칙을 Codex는 작업 디렉터리의 AGENTS.md 파일에서 읽습니다. 같은 내용을 쓰면 됩니다.

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

무인 실행에는 claude -p에 해당하는 codex exec "작업"이 있습니다.

대안: 에이전트가 내 컴퓨터에서 실행되고 SSH로 작업한다

서버에 아무것도 설치하고 싶지 않다면 노트북에서 Claude Code나 Codex를 실행하고 에이전트가 SSH로 명령을 보내게 합니다. 이를 위해 서버에는 에이전트 사용자용 별도 SSH 키를 두고, CLAUDE.md에는 모든 서버 명령을 ssh aiagent@server로 시작한다는 규칙을 적습니다. 가끔 하는 유지보수에는 잘 맞지만, 긴 작업과 cron 작업은 서버에서 직접 실행하는 편이 낫습니다.

6단계: 보호와 한도 설정

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

흔한 오류와 해결책

결론

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