AI/ChatGPT(Codex)

free-code 설치 및 사용 방법 : OpenAI Codex를 Claude Code 터미널 감각으로 붙이는 법

안녕하세요! 갓대희 입니다.

Claude Code의 터미널 감각은 마음에 드는데, 모델/provider는 좀 더 자유롭게 바꿔 써보고 싶은 경우가 있다. 특히 Codex 계열 모델을 같은 CLI 습관으로 붙여 쓰고 싶은 사람에게는 이런 포크가 눈에 들어온다.

이번 글에서 다룰 free-code는 바로 그 지점을 건드린다.

이 프로젝트는 공개된 Claude Code 스냅샷을 바탕으로 만든 포크이며, OpenAI Codex · AWS Bedrock · Google Vertex AI 등 멀티 provider 확장과 experimental feature unlock을 전면에 내세운다.

지금 실제로 어떻게 설치하고, 어떻게 로그인하고, 어떻게 Codex 모델로 실행하는지, provider별 환경변수 설정과 OAuth 경로까지 정리해보려 한다.

free-code는 Claude Code의 터미널 하네스를 유지하면서 provider와 실험 기능을 훨씬 더 거칠게 열어둔 포크다.

one-liner로 설치하고 나서 어떤 provider를 쓸지 고르는 게 이 도구의 실제 진입점이다.

free-code가 무엇인가
왜 이 도구를 보나
설치 방법 — README one-liner
현재 설치 주의사항
수동 설치/빌드 방법
로그인/인증 방법
실제 사용법
소스코드 핵심 분석
장점과 단점
트러블슈팅 Q&A + 결론

1. free-code가 무엇인가 — Claude Code 포크를 왜 보는가

free-code README는 이 도구를 "Anthropic Claude Code CLI의 clean, buildable fork"라고 소개한다.

소개 문구도 꽤 공격적이다. telemetry 제거, prompt guardrails 제거, experimental feature unlock을 전면에 내세운다.

Claude Code 스타일의 터미널 코딩 에이전트를 공식 배포판보다 느슨한 제약과 더 많은 실험 기능으로 돌려보는 포크다.

공식 대체재가 아니라 "더 많이 열어둔 실험 환경"이라는 표현이 더 정확하다.

항목	값
생성 시점	2026-03-31 11:11:49Z
Stars	7,715 (2026-04-12 기준)
Forks	1,686
Open Issues	12

스타 7천 개가 넘는다는 건 그냥 화제성이 아니다.

Claude Code 하네스는 그대로 쓰되 provider를 바꾸고 싶다는 수요가 실제로 있다는 얘기다.

2. 왜 이 도구를 보나 — Codex 모델을 Claude Code 감각으로 붙일 수 있다

README의 Model Providers 섹션은 Anthropic 기본값 외에 4개의 provider를 추가로 지원한다.

OpenAI Codex만이 아니라 AWS Bedrock, Google Vertex AI, Anthropic Foundry까지 포함한다.

Provider	환경변수	주요 모델 / 인증 방식
Anthropic (기본)	—	claude-opus-4-6, claude-sonnet-4-6, claude-haiku-4-5 / API 키 또는 OAuth
OpenAI Codex	`CLAUDE_CODE_USE_OPENAI=1`	gpt-5.3-codex (권장), gpt-5.4, gpt-5.4-mini / OpenAI OAuth
AWS Bedrock	`CLAUDE_CODE_USE_BEDROCK=1`	AWS 자격증명
Google Vertex AI	`CLAUDE_CODE_USE_VERTEX=1`	gcloud ADC
Anthropic Foundry	`CLAUDE_CODE_USE_FOUNDRY=1`	전용 API 키

즉 free-code는 Claude 모델만 쓰는 포크가 아니다.

터미널 UX는 Claude Code 계열이지만, 환경변수 하나로 provider를 전환할 수 있어 멀티-provider 실험용 CLI로 쓸 수 있는 포크다.

3. 설치 방법 — README one-liner 실제 실행 흐름

README가 제시하는 기본 설치는 다음 one-liner다. (직접 실행 검증: 2026-04-12, Darwin arm64)

curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh | bash

보안 참고사항 (curl | bash 패턴)

이 패턴은 스크립트 내용을 실행 전 검토할 수 없다. 실행 전 내용을 먼저 확인하고 싶다면 아래 방식을 쓴다.

curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh -o install.sh
cat install.sh   # 내용 확인
bash install.sh  # 이상 없으면 실행

ex) curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh | bash

3.1 실제 설치 흐름 (직접 실행 기준)

install.sh를 직접 실행하면 다음 5단계가 자동으로 처리된다.

단계	내용	실제 결과
① OS/환경 체크	OS, git, bun 버전 확인	Darwin arm64, git 2.52.0 확인
② Bun 자동 업그레이드	1.3.11+ 미충족 시 자동 업그레이드	v1.3.5 → v1.3.12 자동 업그레이드
③ 저장소 clone	`~/free-code`로 clone	정상 clone 완료
④ 의존성 설치 + 빌드	`bun install` → `build:dev:full`	564 packages, 5689 modules, ~5초 빌드
⑤ PATH 심링크	`~/.local/bin/free-code`	심링크 자동 생성 완료

포인트: Bun 버전을 미리 맞출 필요가 없다. 스크립트가 1.3.11+ 미충족 시 자동으로 업그레이드한다. 기존 bun이 없어도 신규 설치해준다.

3.2 실제 설치 로그 (2026-04-12, Darwin arm64)

[*] Starting installation...
[+] OS: Darwin arm64
[+] git: git version 2.52.0
[!] bun v1.3.5 found but v1.3.11+ required. Upgrading...
    → bun was installed successfully to ~/.bun/bin/bun
[+] bun: v1.3.12 (just installed)

[*] Cloning repository...
    Cloning into '/Users/gdh/free-code'...
[+] Source: /Users/gdh/free-code

[*] Installing dependencies...
    564 packages installed [5.65s]
[+] Dependencies installed

[*] Building free-code (all experimental features enabled)...
    $ bun run ./scripts/build.ts --dev --feature-set=dev-full
    [288ms]  minify  -33.28 MB (estimate)
    [4.513s]  bundle  5689 modules
    [434ms]  compile ./cli-dev
    Built ./cli-dev
[+] Binary built: /Users/gdh/free-code/cli-dev
[+] Symlinked: /Users/gdh/.local/bin/free-code

  Installation complete!

  Run it:
    free-code                          # interactive REPL
    free-code -p "your prompt"         # one-shot mode

  Set your API key:
    export ANTHROPIC_API_KEY="sk-ant-..."

  Or log in with Claude.ai:
    free-code /login

  Source: /Users/gdh/free-code
  Binary: /Users/gdh/free-code/cli-dev
  Link:   ~/.local/bin/free-code

3.3 설치 후 진입점

설치가 끝나면 다음 두 경로 중 하나로 시작한다. 어떤 provider를 쓸지 결정하는 단계가 이후 로그인 방식과 모델 선택을 좌우한다.

Anthropic 기본 경로 — export ANTHROPIC_API_KEY="sk-ant-..." 후 free-code
Claude.ai OAuth 경로 — free-code /login으로 브라우저 OAuth 진행
멀티 provider 경로 — 환경변수로 provider 지정 후 실행 (6절 참조)

혹시 정상 설치가 되었다면, 4~5번ㅇ느 넘어 가도 좋다. 예전 초창기에 오류 때문에 4~5번의 섹션을 추가 해 두었다.

4. 설치 실패시 알아두면 좋은 것들( 나의 경우 에러 상황이 많아 기록 )

현재(2026-04-12 기준) GitHub API 기준 disabled: false로 저장소는 정상 접근 가능하다. one-liner를 그대로 실행하면 된다.

참고 (과거 이슈): 2026-04-02 시점에는 git clone이 403 disabled로 실패하는 상황이 있었다. 현재는 복구됐지만, 이 저장소는 외부 압력에 따라 접근이 제한될 가능성을 배제하기 어렵다. 중요한 실험 환경에 쓸 예정이라면 clone 직후 로컬 백업을 해두는 편이 안전하다.

README는 GitHub 외에 IPFS mirror도 함께 제공한다. Filecoin을 통해 영구 보관된 스냅샷이다. GitHub clone이 다시 막히는 상황을 대비한 fallback으로 볼 수 있지만, 이 mirror가 buildable full repo인지는 별도로 확인이 필요하다.

4.1 macOS 26 (Tahoe)에서 컴파일 바이너리가 즉시 종료되는 문제

증상: free-code /login 실행 시 [1] killed로 즉시 종료 (exit code 137 = SIGKILL)

환경: macOS 26.1 (Tahoe, Darwin 25.1.0) — 2026-04-12 직접 확인

install.sh가 생성하는 cli-dev는 Bun의 컴파일 바이너리(180MB 단일 실행파일)다.
macOS 26에서 이 바이너리는 --version조차 실행되지 않고 SIGKILL로 종료된다. 리빌드해도 동일하다. Bun 컴파일 바이너리와 macOS 26의 호환성 문제로 보인다.

해결책: 컴파일 바이너리 대신 bun source 모드 wrapper로 교체한다. 아래 명령으로 심링크를 wrapper 스크립트로 대체하면 된다.

cat > ~/.local/bin/free-code << 'EOF'
#!/bin/zsh
cd ~/free-code && exec bun run ./src/entrypoints/cli.tsx "$@"
EOF
chmod +x ~/.local/bin/free-code

적용 후 동작 확인:

free-code --version
# → 2.1.87-dev (Claude Code)

방식	macOS 26	비고
컴파일 바이너리 (`cli-dev`)	(exit 137)	install.sh 기본 결과물
bun source 모드 wrapper	정상 동작	위 스크립트로 교체 후

5. 수동 설치/빌드 방법 — one-liner 대신 직접 빌드하려면

5.1 Bun 준비

install.sh 기준 최소 요구사항은 Bun 1.3.11 이상이다.

curl -fsSL https://bun.sh/install | bash

5.2 소스 확보

현재는 정상적으로 clone 가능하다.

git clone https://github.com/paoloanzn/free-code.git
cd free-code

이 저장소는 IPFS mirror(w3s.link gateway)도 함께 제공한다. Filecoin을 통해 영구 보관된 스냅샷으로, GitHub 접근이 막힐 경우의 fallback이다. 다만 이 mirror가 곧바로 빌드 가능한 full repo인지는 별도로 확인이 필요하다. 가장 확실한 방법은 지금 clone 후 로컬에 백업해 두는 것이다.

README가 IPFS mirror를 숨겨둔 링크가 아니라 문서에 명시해뒀다는 점 자체가, 저장소 접근 제한 가능성을 프로젝트가 어느 정도 예상하고 있다는 신호로 읽힌다. 이 도구를 중요한 환경에서 쓸 계획이라면 clone 직후 백업을 권장한다.

5.3 빌드

bun install
bun run build:dev:full

빌드 완료 후 아래 명령으로 파일이 생성됐는지 먼저 확인한다. 이 파일이 없으면 build:dev:full이 완료되지 않은 것이다.

ls -l ./cli-dev

이 빌드는 ./cli-dev를 만들고, working experimental features bundle 전체를 켠다.

5.4 링크

링크 예시는 두 경로를 분리해서 보는 편이 안전하다. install.sh가 성공한 경우 소스 디렉터리는 ~/free-code일 가능성이 높다. 반면 수동 clone 빌드인 경우에는 현재 작업 디렉터리의 ./cli-dev를 가리키는 편이 덜 헷갈린다.

수동 빌드 기준으로는 다음처럼 잡는 편이 안전하다.

mkdir -p ~/.local/bin
ln -sf "$(pwd)/cli-dev" ~/.local/bin/free-code
export PATH="$HOME/.local/bin:$PATH"

export는 현재 세션에만 적용된다. 터미널을 새로 열어도 유지하려면 셸 설정 파일에 추가한다.

# zsh 사용 시
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# bash 사용 시
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

5.5 첫 실행 전에 확인할 것

확인 항목	왜 보나
`free-code`가 PATH에서 잡히는가	`command -v free-code`로 확인한다. 링크가 안 잡히면 이후 단계가 모두 꼬인다
`cli-dev`가 실제 생성됐는가	`ls -l ./cli-dev`로 확인한다. build:dev:full이 끝났는지 보는 가장 빠른 방법이다
지금 Anthropic 경로로 갈지, Codex 경로로 갈지	이후 로그인 방식이 달라진다

설치 자체보다 provider 선택이 먼저다. 환경변수 하나로 인증 흐름이 완전히 달라진다.

6. 로그인/인증 방법 — Codex 경로 기준으로 보면 이렇게 간다

README는 로그인 예시로 ./cli /login을 제시한다.

그런데 여기서 중요한 건 provider마다 인증 흐름이 다르다는 점이다.

6.1 OpenAI Codex 경로

Codex provider는 CLAUDE_CODE_USE_OPENAI=1을 켠 상태에서 로그인하는 구조다.

export CLAUDE_CODE_USE_OPENAI=1
./cli-dev /login

ex)

> export CLAUDE_CODE_USE_OPENAI=1
> free-code /login

- Codex account 를 사용해보자.

- 브라우저를 통한 인증 완료

- cli에서도 인증 성공확인

이미 free-code 심볼릭 링크를 잡아둔 상태라면 free-code /login으로 같은 작업을 할 수 있다. 중요한 건 로그인과 REPL 진입 순서를 한 번 정해두고 계속 같은 방식으로 쓰는 것이다.

코드 기준으로는 OpenAI 브라우저 로그인 → localhost:1455 콜백 → PKCE token exchange의 흐름이다. auth handler는 이 토큰을 Anthropic API key로 바꾸지 않고, Codex 전용 슬롯에 따로 저장한다.

Codex 경로는 Claude API key를 대신 꽂는 꼼수가 아니다. 완전히 별도 OAuth/provider 경로로 설계돼 있다.

기존 Anthropic 인증과 충돌하지 않는다.

7. 실제 사용법 — REPL, one-shot, provider 전환, 모델 선택

목적	명령
대화형 REPL	`free-code` 또는 `./cli-dev`
one-shot 실행	`free-code -p "what files are in this directory?"`
모델 지정	`free-code --model gpt-5.3-codex`
로그인	`free-code /login` 또는 `./cli-dev /login`

Codex provider를 붙여 쓰고 싶다면 실전 흐름은 보통 이렇다.

export CLAUDE_CODE_USE_OPENAI=1
free-code /login
free-code

중요: 새 터미널/새 세션에서는 다시 환경변수를 먼저 설정해야 한다

export CLAUDE_CODE_USE_OPENAI=1은 현재 셸 세션에만 적용된다. 즉 새 터미널을 열었거나 새 세션으로 다시 시작했다면, free-code를 실행하기 전에 이 값을 다시 export해야 한다. 이 단계가 빠지면 provider가 기본값(Anthropic)으로 잡혀 /model에서 GPT-5.4, gpt-5.3-codex, gpt-5.4-mini가 보이지 않을 수 있다.

그 다음 모델을 직접 고를 수 있다. README와 model config 기준으로 현재 문서에서 직접 확인되는 후보는 세 가지다.

모델	문서에서 확인되는 정보
`gpt-5.3-codex`	README에서 `(recommended)` 표기
`gpt-5.4`	OpenAI Codex provider 모델 ID
`gpt-5.4-mini`	OpenAI Codex provider 모델 ID

ex) /model

7.1 처음 시작하는 방법 정리

free-code로 REPL에 들어간다
OpenAI Codex를 쓸 경우 CLAUDE_CODE_USE_OPENAI=1 상태에서 free-code /login 또는 ./cli-dev /login을 먼저 수행한다
로그인 뒤 free-code -p "ping"처럼 아주 짧은 one-shot 프롬프트로 CLI가 정상 응답하는지 확인한다
그 다음에야 긴 리팩터링이나 멀티파일 작업으로 넘어간다

설치 직후 모델 품질 얘기는 나중에 해도 된다. 먼저 로그인 상태, provider 선택, binary 링크가 제대로 맞물렸는지 확인하는 게 우선이다. 여기서 꼬이면 이후 단계가 전부 헷갈린다.

8. 소스코드 핵심 분석 — 왜 이 포크가 "도구"로서 설득력이 있는가

튜토리얼 글이라도 코드 구조는 짚어야 한다.

코드를 열어보면 README 약속이 실제로 구현돼 있다. src/utils/model/configs.ts에는 Claude 계열과 GPT 계열 config가 같이 등록돼 있고, OpenAI 쪽은 auth.openai.com 기반 PKCE client를 별도로 갖고 있다.

build:dev:full 하나로 experimental bundle 전체를 켤 수 있는 것도 확인된다.

안정성보다 provider 확장성과 실험 기능 접근성을 우선한 개발자용 포크다. 공식 배포판이 줄 수 없는 걸 원한다면 여기서 찾을 수 있다.

9. 장점과 단점 — 공식 Claude Code와 비교하면

항목	free-code 장점	free-code 단점
provider 선택	5개 provider 지원 (Anthropic, Codex, Bedrock, Vertex AI, Foundry)	공식 지원 안정성은 기대하기 어렵다. 포크 특성상 각 provider 연동의 품질은 직접 테스트로 확인해야 한다
인증	OpenAI OAuth 경로가 실제 코드로 존재하고, 다른 provider는 환경변수로 전환	provider별 로그인 상태를 직접 이해해야 한다
기능 접근	36개 working experimental feature 활성화 가능	bundle-clean이 runtime-safe를 뜻하지는 않는다
설치	스크립트와 구조가 단순하다. 현재 정상 clone 가능	외부 압력에 따라 저장소 접근이 다시 제한될 가능성을 완전히 배제하기 어렵다

free-code를 공식 Claude Code 대체재로 보면 실망한다.

더 실험적이고 더 거칠지만 더 많이 열어둔 포크다. 팀 표준 툴이 아니라 개인 실험 환경으로 보는 게 맞다.

선택 기준은 단순하다. Bedrock · Vertex AI · Codex 중 하나를 Claude Code 감각으로 붙여보고 싶다면 free-code가 맞다. 안정성과 지원이 최우선이라면 공식판이 맞다.

10. 트러블슈팅 Q&A + 결론

10.1 Q&A

Q. install.sh를 그대로 실행하면 되나?

현재(2026-04-12)는 정상 동작한다. 과거(2026-04-02)에는 git clone 403 disabled로 막히는 상황이 있었으나 현재는 복구됐다. 단, 이 저장소 특성상 향후 접근이 다시 제한될 가능성을 고려해 clone 직후 로컬 백업을 권장한다.

Q. GitHub clone이 막히면 대안이 있나?

README가 IPFS mirror(CID: bafybeiegvef3dt24n2znnnmzcud2vxat7y7rl5ikz7y7oglxappim54bm)를 함께 제공한다. Filecoin을 통해 영구 보관된 스냅샷이다. 다만 이 mirror가 곧바로 빌드 가능한 full repo인지는 별도 확인이 필요하다. 가장 확실한 대안은 지금 시점에 clone해서 로컬 백업을 만들어 두는 것이다.

Q. Codex provider를 쓰려면 OpenAI API 키가 꼭 필요한가?

이 저장소가 전제하는 기본 경로는 OpenAI OAuth다. 다만 모든 상황에서 API 키가 필요 없다고 일반화해서 쓰면 안 된다. 이 글은 README와 코드에 확인된 OAuth 경로만 다룬다.

10.2 "누가 써볼 만한가 / 누가 그냥 공식판을 쓰는 게 나은가" 결정 매트릭스

상황	권장	이유
Claude Code 스타일 UX로 Codex 모델을 붙여 보고 싶은 경우	free-code를 써볼 만하다	OpenAI provider와 OAuth 경로가 실제로 구현돼 있다
안정성과 공식 지원이 최우선일 때	공식 Claude Code가 낫다	free-code는 포크이고 experimental bundle 성격이 강하다
설치가 한 번에 끝나야 하는 팀 환경	공식 Claude Code가 낫다	저장소 접근 안정성이 보장되지 않는 실험적 포크다. 팀 표준 툴로는 공식판이 더 적합하다
experimental feature를 만져보고 싶은 경우	free-code가 더 재미있다	build:dev:full이 working feature bundle 전체를 켠다

free-code는 팀 표준 툴보다 개인 실험, 연구, provider 비교 용도에 더 맞는 도구다.

10.3 오늘 바로 따라할 체크리스트

Bun 1.3.11+ 설치 여부를 먼저 확인한다
one-liner(curl -fsSL https://raw.githubusercontent.com/paoloanzn/free-code/main/install.sh | bash)로 설치한다
ls -l ./cli-dev로 빌드 완료를 확인한다
~/.local/bin/free-code 링크를 잡고 PATH를 추가한다
사용할 provider의 환경변수를 설정한다 — Codex: CLAUDE_CODE_USE_OPENAI=1 / Bedrock: CLAUDE_CODE_USE_BEDROCK=1 / Vertex: CLAUDE_CODE_USE_VERTEX=1
환경변수 설정 후 free-code /login으로 로그인한다

10.4 결론

free-code는 Claude Code의 터미널 하네스를 유지하면서, provider와 실험 기능을 더 거칠게 열어둔 포크다. 이게 전부다.

설치와 사용법 자체는 어렵지 않다. one-liner로 설치하고, 쓸 provider를 고르고, 환경변수를 설정한 뒤 로그인하면 된다. 그래서 이 도구는 공식판 대체재로 보기보다, Codex · Bedrock · Vertex AI 등 멀티-provider CLI를 Claude Code 감각으로 실험해보고 싶은 개발자에게 더 잘 맞는다.

지금 시점에서 가장 실무적인 조언은 이것이다. 어떤 provider를 쓸지 먼저 결정하고 → 해당 환경변수를 설정한 뒤 → 로그인 경로를 확인해라. 그래야 provider별 인증 흐름 차이에서 헤매지 않는다. 그리고 포크 특성상 GitHub 접근이 다시 제한될 가능성을 고려해 clone 직후 로컬 백업을 만들어 두는 편이 안전하다.

참고 자료

저작자표시 비영리 변경금지 (새창열림)

'AI > ChatGPT(Codex)' 카테고리의 다른 글

GPT Image2 이미지 잘 만드는 법 : GPT Image2로 한글 썸네일과 인포그래픽까지 끝내기(이미지 프롬프트 패턴, 예시 모음) (8)	2026.04.29
OpenAI GPT-5.5 리뷰 : 에이전틱 AI의 새 기준인가, 가격 2배 인상의 정당화인가 - 벤치마크부터 환각률까지 (1)	2026.04.24
OpenAI Codex 서브에이전트 - awesome-codex-subagents : 136개 Codex SubAgents 모음( TOML 에이전트 컬렉션 ) (1)	2026.03.28
GPT-5.4 출시 리뷰 - 신규 기능, 벤치마크, 시장 반응, Pro 5.4 vs Thinking 5.4, 실제로 얼마나 다를까? 비교 분석 (5)	2026.03.08
gpt5.3codex 출시 리뷰 - 신규 기능, 벤치마크, 시장 반응, 개발자 후기 등 (vs Opus 4.6: AI 코딩 전쟁) (2)	2026.02.06

Contents

새소식