Codex CLI를 Proxmox, Home Assistant, Synology NAS, OpenCloud LXC에 설치해 쓰는 방법

Codex CLI를 Proxmox, Home Assistant, Synology NAS, OpenCloud LXC에 설치해 쓰는 방법

OpenAI의 Codex CLI는 터미널 안에서 코드 읽기, 수정, 명령 실행까지 이어지는 로컬 코딩 에이전트다. 직접 써보면 단순 챗봇보다 훨씬 실무적이고, 특히 홈랩이나 서버 운영 환경에서 진가가 나온다.

이번 글은 Proxmox, Home Assistant, Synology NAS, OpenCloud LXC 네 가지 환경에서 Codex CLI를 안정적으로 굴리는 방법을 정리한 것이다. 특히 많이 헷갈리는 부분인 AGENTS.md vs AGENT.md, Home Assistant에서 재부팅 후 설정이 날아가는 문제, Synology에서 Docker로 배포하면서 SSH 키를 안전하게 넣는 방법까지 같이 다룬다.

먼저 결론부터:

• 공식 설치 기본값은 npm i -g @openai/codex 이다.
• 파일명은 AGENT.md가 아니라 AGENTS.md 가 맞다.
• Home Assistant의 Terminal & SSH 애드온에서는 /config 아래만 영속 경로로 생각하는 게 안전하다.
• Synology는 직접 설치보다 Docker/Container Manager 컨테이너로 분리하는 편이 관리가 훨씬 낫다.

이번 수정본은 명령어와 설정 예시를 복붙하기 쉬운 코드 스니펫 형태로 다시 정리했다. 설명은 짧게, 코드는 바로 실행 가능한 형태로 최대한 유지했다.

OpenAI Codex CLI terminal screenshot

공식 기준으로 확인한 핵심 포인트

• OpenAI 공식 문서는 Codex CLI 설치 방법으로 npm i -g @openai/codex 를 안내한다.
• GitHub 저장소에는 npm 설치 외에도 플랫폼별 바이너리 릴리스 사용법이 있다.
• 커스텀 지시 파일 이름은 AGENTS.md 이며, Codex는 전역 ~/.codex/AGENTS.md 와 프로젝트별 AGENTS.md 를 읽는다.
• Home Assistant 공식 Terminal & SSH 문서에는 설정 디렉터리가 /config 라고 명시되어 있다.

AGENT.md 말고 AGENTS.md가 맞는 이유

이 부분은 헷갈리기 쉬운데, 현재 Codex 공식 문서와 저장소 기준으로는 AGENTS.md 가 맞다. Codex는 작업 시작 전에 이 파일을 읽고, 전역 지침과 프로젝트별 지침을 계층적으로 합친다.

즉 아래처럼 두는 게 정석이다.

파일 경로

~/.codex/AGENTS.md
/path/to/project/AGENTS.md

예를 들어 홈랩용 공통 규칙은 전역에, 특정 리포지토리 전용 빌드/배포 규칙은 프로젝트 루트의 AGENTS.md 에 넣으면 된다.

공통 준비물

• 인터넷 연결
• OpenAI API 키 또는 ChatGPT 로그인 가능한 계정
• 작업용 디렉터리 하나, 예: ~/workspace
• SSH 키 한 쌍(원격 Git, 서버 접근용)
• 지속 설정용 AGENTS.md

추천 디렉터리 구조는 다음 정도면 충분하다.

디렉터리 구조 예시

~/workspace/
  AGENTS.md
  project-a/
  project-b/
~/.codex/
  AGENTS.md
  config.toml

1. Proxmox LXC에 Codex CLI 설치하기

Proxmox에서는 Ubuntu 24.04 또는 Debian 12 기반 LXC 에 설치하는 구성이 가장 단순하다. Codex CLI 자체는 무겁지 않아서, 별도 VM 없이 LXC로도 충분하다.

Proxmox VE dashboard

권장 컨테이너 조건

• OS: Ubuntu 24.04 LTS 또는 Debian 12
• vCPU: 2개 이상
• RAM: 2GB 이상
• Storage: 8GB 이상
• SSH 접속 가능 상태

1-1. 기본 패키지 설치

bash

sudo apt update
sudo apt install -y curl git ca-certificates build-essential unzip

1-2. Node.js 22 계열 설치

Codex CLI는 공식적으로 npm 설치를 안내하므로, LXC에서는 Node.js를 먼저 안정적으로 넣는 게 좋다.

bash

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

1-3. Codex CLI 설치

bash

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

1-4. 전역 지침 파일 만들기

bash

mkdir -p ~/.codex
cat > ~/.codex/AGENTS.md <<'EOF'
# Global AGENTS.md

- Explain risky commands before running them.
- Prefer small, reviewable diffs.
- For homelab services, show rollback steps.
- Use Korean unless the repository already uses English docs.
EOF

1-5. 프로젝트 지침 파일 만들기

bash

mkdir -p ~/workspace/homelab
cat > ~/workspace/homelab/AGENTS.md <<'EOF'
# Homelab repo rules

- Always confirm systemctl unit names before editing.
- When editing docker compose files, validate indentation carefully.
- For reverse proxy changes, summarize exposed ports and domains.
EOF

1-6. 실행

bash

cd ~/workspace/homelab
codex

첫 실행에서는 로그인 또는 API 키 설정을 안내한다. 이 방식은 일반적인 Proxmox LXC에서 가장 무난하고, 업데이트도 단순하다.

2. Home Assistant Terminal & SSH에서 설치할 때, 왜 매번 초기화될까?

핵심은 간단하다. 애드온 컨테이너 내부 파일시스템은 휘발성으로 봐야 하고, /config만 영속 저장소로 취급해야 한다.

즉, 아래 경로에 뭔가를 설치하면 재시작/업데이트 때 사라질 수 있다.

휘발 가능 경로

/root
/usr/local
/tmp
/app
~

반대로 아래처럼 /config 아래에 Codex 관련 파일을 몰아두면 살아남는다.

영속 경로

/config/codex/bin
/config/codex/home
/config/codex/workspace
/config/.ssh

Home Assistant Terminal SSH addon interface

중요: Home Assistant에서는 npm 설치보다 바이너리 설치가 더 현실적일 때가 많다

공식 Terminal & SSH 애드온은 일반 리눅스 셸처럼 마음대로 패키지를 넣는 용도에 최적화되어 있지 않다. 그래서 Codex CLI 바이너리를 /config 아래에 저장하는 방식이 더 안정적이다.

2-1. 영속 디렉터리 준비

bash

mkdir -p /config/codex/bin
mkdir -p /config/codex/home
mkdir -p /config/codex/workspace
mkdir -p /config/.ssh

2-2. Codex CLI 바이너리 설치

Home Assistant 애드온은 Alpine 기반인 경우가 많아서, Linux musl 바이너리를 쓰는 쪽이 맞다.

bash

cd /config/codex/bin
curl -L -o codex.tar.gz \
  https://github.com/openai/codex/releases/latest/download/codex-x86_64-unknown-linux-musl.tar.gz

tar -xzf codex.tar.gz
mv codex-x86_64-unknown-linux-musl codex
chmod +x codex

2-3. 환경 변수 스크립트 만들기

bash

cat > /config/codex/env.sh <<'EOF'
export PATH="/config/codex/bin:$PATH"
export CODEX_HOME="/config/codex/home"
export WORKSPACE="/config/codex/workspace"
EOF

2-4. 세션마다 불러오기

bash

source /config/codex/env.sh
cd /config/codex/workspace
codex

2-5. Home Assistant에서 꼭 기억할 영속 경로

• Codex 홈: /config/codex/home
• 작업 디렉터리: /config/codex/workspace
• SSH 키: /config/.ssh
• 공통 지침 파일: /config/codex/home/AGENTS.md

즉, 용상님이 원하신 “재부팅 후 설정이 초기화되지 않게 하는 올바른 path”는 /config 아래 다.

2-6. Home Assistant용 AGENTS.md 예시

bash

cat > /config/codex/home/AGENTS.md <<'EOF'
# Home Assistant Codex rules

- Never modify YAML automations without showing the entity_ids involved.
- Prefer creating backups before bulk edits.
- For add-on troubleshooting, separate host issues from container issues.
- Keep examples compatible with Home Assistant OS paths under /config.
EOF

2-7. 좀 더 편하게 쓰고 싶다면

Community의 Advanced SSH & Web Terminal 애드온은 패키지 설치, init commands, SSH 키/설정 유지 등에서 더 유연하다. 다만 그래도 실제 영속 데이터는 /config에 두는 습관이 가장 중요하다.

3. Synology NAS에서는 직접 설치보다 Docker 배포가 낫다

Synology는 DSM 환경 자체에 직접 의존성을 섞기보다, Container Manager(Docker) 로 분리하는 쪽이 관리와 복구가 훨씬 쉽다. 특히 Codex CLI처럼 업데이트가 자주 있을 수 있는 도구는 컨테이너 격리가 잘 맞는다.

Synology DSM Container Manager

권장 호스트 경로

디렉터리 구조 예시

/volume1/docker/codex/
  compose.yaml
  ssh/
  codex-home/
  workspace/

3-1. NAS에서 SSH 활성화

DSM에서 제어판 → 터미널 및 SNMP → SSH 서비스 활성화 를 켠 뒤 NAS에 접속한다.

3-2. SSH 키 준비

호스트 또는 별도 관리 PC에서 키를 만들고, 컨테이너에 읽기 전용으로 마운트한다.

bash

mkdir -p /volume1/docker/codex/ssh
ssh-keygen -t ed25519 -f /volume1/docker/codex/ssh/id_ed25519
chmod 700 /volume1/docker/codex/ssh
chmod 600 /volume1/docker/codex/ssh/id_ed25519
chmod 644 /volume1/docker/codex/ssh/id_ed25519.pub

GitHub를 쓴다면 공개키 내용을 GitHub 계정의 SSH Keys에 등록하면 된다.

3-3. AGENTS.md 파일 준비

여기서도 파일명은 AGENTS.md 다.

bash

mkdir -p /volume1/docker/codex/workspace
cat > /volume1/docker/codex/workspace/AGENTS.md <<'EOF'
# Synology homelab workspace rules

- Assume files are on mounted NAS volumes.
- Avoid commands that can recursively alter /volume1 without confirmation.
- When suggesting Docker changes, include volume and permission notes.
EOF

3-4. compose.yaml 작성

yaml

services:
  codex:
    image: node:22-bookworm-slim
    container_name: codex-cli
    working_dir: /workspace
    stdin_open: true
    tty: true
    environment:
      CODEX_HOME: /home/codex/.codex
    command: >
      bash -lc "npm install -g @openai/codex && exec bash"
    volumes:
      - /volume1/docker/codex/codex-home:/home/codex/.codex
      - /volume1/docker/codex/workspace:/workspace
      - /volume1/docker/codex/ssh:/home/codex/.ssh:ro
    restart: unless-stopped

bash

cat > /volume1/docker/codex/compose.yaml <<'EOF'
services:
  codex:
    image: node:22-bookworm-slim
    container_name: codex-cli
    working_dir: /workspace
    stdin_open: true
    tty: true
    environment:
      CODEX_HOME: /home/codex/.codex
    command: >
      bash -lc "npm install -g @openai/codex && exec bash"
    volumes:
      - /volume1/docker/codex/codex-home:/home/codex/.codex
      - /volume1/docker/codex/workspace:/workspace
      - /volume1/docker/codex/ssh:/home/codex/.ssh:ro
    restart: unless-stopped
EOF

3-5. 컨테이너 실행

bash

cd /volume1/docker/codex
docker compose up -d
docker exec -it codex-cli bash

3-6. 컨테이너 안에서 초기 확인

bash

codex --version
ls -la /workspace
ls -la /home/codex/.codex

3-7. SSH known_hosts 등록

원격 Git 서버에 처음 붙을 때는 호스트 키를 등록해 둬야 덜 귀찮다.

bash

ssh-keyscan github.com >> /volume1/docker/codex/ssh/known_hosts
chmod 644 /volume1/docker/codex/ssh/known_hosts

이 구조의 장점은 분명하다.

• Codex 설정은 /volume1/docker/codex/codex-home 에 남는다.
• 작업물은 /volume1/docker/codex/workspace 에 남는다.
• SSH 키는 마운트만 바꾸면 손쉽게 교체 가능하다.
• DSM 업데이트와 Codex 실행 환경을 분리할 수 있다.

4. OpenCloud LXC에서는 이렇게 잡으면 편하다

여기서는 Ubuntu/Debian 기반의 OpenCloud용 LXC 컨테이너 를 기준으로 설명한다. 사실 설치 자체는 Proxmox LXC와 거의 같고, 차이는 운영용 경로를 좀 더 명확하게 분리하는 데 있다.

Linux container terminal coding environment

권장 운영 경로

디렉터리 구조 예시

/opt/codex/bin
/opt/codex/home
/srv/codex/workspace

4-1. 시스템 패키지와 Node 설치

bash

sudo apt update
sudo apt install -y curl git ca-certificates build-essential
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs

4-2. 전용 사용자 만들기

bash

sudo useradd -m -s /bin/bash codex
sudo mkdir -p /opt/codex/home
sudo mkdir -p /srv/codex/workspace
sudo chown -R codex:codex /opt/codex /srv/codex

4-3. Codex CLI 설치

bash

sudo npm install -g @openai/codex

4-4. 프로필 스크립트 추가

bash

sudo tee /etc/profile.d/codex.sh > /dev/null <<'EOF'
export CODEX_HOME=/opt/codex/home
export PATH="$PATH:/usr/bin"
EOF

4-5. 작업 지침 파일 추가

bash

sudo -u codex bash -lc 'cat > /opt/codex/home/AGENTS.md <<"EOF"
# OpenCloud LXC rules

- Prefer explicit service names and bind mounts.
- Before changing reverse proxies, summarize ports and domains.
- Keep rollback commands with every deployment plan.
EOF'

4-6. 실행

bash

sudo -u codex -H bash -lc 'cd /srv/codex/workspace && codex'

이 구성은 여러 프로젝트를 장기간 유지할 때 특히 좋다. 사용자 홈과 서비스용 데이터 경로가 명확히 분리되기 때문이다.

환경별 추천 방식 한눈에 보기

환경	추천 설치 방식	영속 경로	비고
Proxmox LXC	Node + npm 글로벌 설치	~/.codex, ~/workspace	가장 단순함
Home Assistant	바이너리 설치 권장	/config/codex, /config/.ssh	/config 밖은 날아갈 수 있음
Synology NAS	Docker/Container Manager	/volume1/docker/codex	호스트와 격리 쉬움
OpenCloud LXC	Node + npm 글로벌 설치	/opt/codex, /srv/codex/workspace	운영 경로 분리 추천

실제로 써보면 좋은 AGENTS.md 예시

아래 예시는 홈서버/셀프호스팅 작업에 맞춘 최소 규칙 세트다.

markdown

# AGENTS.md

- Use Korean for explanations unless the repo uses English docs.
- Before changing infra config, summarize ports, domains, volumes, and rollback steps.
- Ask before destructive deletes.
- Prefer compose diffs or exact file patches over vague guidance.
- After changing service configs, propose a verification checklist.

이 정도만 넣어도 Codex가 꽤 덜 엇나간다.

자주 하는 실수

• AGENT.md 로 파일을 만들어 놓고 왜 안 읽냐고 하는 경우
• Home Assistant에서 /root 나 ~ 에 설치해 두고 재부팅 후 사라졌다고 느끼는 경우
• Synology 호스트에 직접 이것저것 설치해 DSM 업데이트와 충돌하는 경우
• SSH 키를 컨테이너에 복사만 해두고 권한을 안 맞춰서 접속이 실패하는 경우

마무리

정리하면, Codex CLI는 어디서나 돌아가지만 환경별로 “어디에 설치하고, 무엇을 영속 데이터로 볼 것인가” 를 먼저 정리해야 오래 편하게 쓸 수 있다.

• Proxmox LXC: 가장 표준적인 리눅스 방식
• Home Assistant: /config 아래로 몰아넣기
• Synology NAS: Docker로 분리, SSH 키는 볼륨 마운트
• OpenCloud LXC: 운영 경로를 명확히 분리

그리고 마지막으로 다시 한 번. 파일명은 AGENTS.md 다.

참고 링크

• OpenAI Codex CLI 공식 문서
• openai/codex GitHub 저장소
• AGENTS.md 공식 가이드
• Home Assistant OS common tasks
• Home Assistant Terminal & SSH 문서
• Advanced SSH & Web Terminal 문서