Local Tooling · Claude Code & Codex CLI · Zero API Key

API 키 없이,
AI 기능 만들기.

이미 컴퓨터에 설치된 claude CLI를 서버 코드에서 그대로 호출하면 됩니다. 발급도, 결제도, SDK도 필요 없이.

Read time 4 MIN Topic Claude Code · Local Tooling · Node/Bun Author CS

Background
WHY THIS WORKS

개인용 로컬 도구로 “포트 관리기”라는 앱을 만들면서, AI로 이름을 추천해주는 기능을 붙이려고 했습니다. 그런데 첫 관문에서 막혔습니다 — API 키를 발급받고, 결제를 등록하고, 사용량을 관리하는 게 개인 프로젝트치고는 너무 번거로웠습니다.

그런데 이미 컴퓨터에 Claude Code가 설치되어 있다면, 별도의 API 키 없이도 로컬 서버(Node.js, Bun, PHP 뭐든)에서 Claude를 그대로 호출할 수 있다는 걸 알게 됐습니다. 포트 관리기의 AI 이름 추천 기능은 지금 정확히 이 방식으로 동작합니다. 오늘은 그 원리를 그대로 뜯어서, 누구나 자기 프로젝트에 적용할 수 있게 쉽게 설명해보겠습니다.

명령 하나 실행하고,
출력만 파싱한다.

— claude CLI를 그냥 프로그램처럼 다루는 법

Part A

사람이 이해할 부분

왜 되는지, 언제 쓰고 언제 쓰면 안 되는지 — 코드를 치기 전에 필요한 판단

§ 01

핵심 아이디어`claude`는 그냥 커맨드라인 프로그램이다

추가 발급할
API 키

이미 인증된 로컬
CLI 세션을 재사용

구현
단계

경로 찾기 → 실행
→ 파싱, 이게 전부

권장
타임아웃

30s

서브프로세스 행
방지 안전장치

필요한
SDK

설치된 CLI를
그대로 호출

Claude Code를 터미널에 설치하면 claude라는 실행 파일이 생깁니다. 우리가 평소에 대화하듯 쓰는 그 도구인데, 사실 이건 일반 CLI 프로그램이라서 다른 프로그램에서도 그냥 실행시킬 수 있습니다.

Terminal · -p 옵션 한 줄 실행

# 대화형 모드 없이, 질문 하나 → 답변 하나 → 종료 claude -p “이 텍스트를 한 문장으로 요약해줘: …”

-p (또는 --print) 옵션을 주면, 대화형 모드로 들어가지 않고 프롬프트를 하나 던지고 → 답을 stdout으로 출력하고 → 바로 종료합니다. 즉, 서버 코드 입장에서는 “외부 프로그램 하나 실행해서 결과 텍스트 받기” 그 이상도 이하도 아닙니다.

Terminal · Codex CLI도 같은 패턴

# Codex CLI(OpenAI)도 이미 설치·인증돼 있다면 그대로 재사용 가능 codex exec “이 텍스트를 한 문장으로 요약해줘: …”

Claude Code만의 이야기가 아닙니다. Codex CLI도 로컬에 설치되어 로그인까지 끝나 있으면 똑같은 원리로 씁니다. 대화형 세션 대신 exec 서브커맨드(별칭 e)를 쓰면 -p와 같은 역할 — “프롬프트 하나 → 최종 응답 하나 → 종료”로 동작합니다.

처음엔 그냥 which claude로 경로를 찾았습니다. 터미널에서는 잘 됐죠. 그런데 포트 관리기를 GUI 앱으로 띄우고 나니 이 함수가 계속 null을 반환했습니다. GUI 앱은 보통 .zshrc를 안 읽는 non-login 셸 환경에서 뜨기 때문에, nvm/homebrew로 설치한 claude의 PATH가 비어 있었던 겁니다. 로그인 셸(zsh -l -c)로 감싸고 나서야 사용자가 평소 터미널에서 쓰는 PATH가 그대로 재현됐습니다 — Part B의 resolveClaudePath()가 굳이 zsh -l -c를 거치는 이유가 이겁니다. codex를 GUI 앱에서 호출할 때도 완전히 같은 문제가 나므로 같은 방식으로 경로를 찾아야 합니다.

§ 02

언제 쓰나장점과 주의할 점 — 쓰기 전에 판단할 것

기준	정식 Anthropic API	로컬 claude CLI 호출 (이 글의 방식)
발급 절차	API 키 발급 + 결제수단 등록 필요	없음 — 이미 인증된 CLI 세션 재사용
비용	토큰 사용량만큼 별도 과금	Claude Code 구독에 포함, 추가 과금 없음
배포 대상	웹에 배포해 불특정 다수가 쓰는 서비스	내 컴퓨터에서만 도는 개인용 로컬 도구

장점
WHEN TO USE

API 키 관리가 필요 없다 — 이미 로컬에 설치되어 인증된 claude CLI 세션을 그대로 재사용합니다.

비용 걱정이 없다 (개인 사용 기준) — Claude Code 구독/사용량에 포함되는 방식이라, 서버용 API 과금이 따로 붙지 않습니다.

로컬 전용 도구에 적합 — 배포된 다중 사용자 웹서비스가 아니라, 내 컴퓨터에서만 도는 개인 도구(포트 관리기 같은)에 딱 맞습니다.

주의
WHEN NOT TO

여러 사용자를 상대하는 프로덕션 서비스에는 맞지 않습니다. 이건 “내 컴퓨터에 설치된 CLI를 내 로컬 서버가 호출하는” 구조라서, 웹에 배포해 불특정 다수가 쓰는 서비스라면 정식 Anthropic API + API 키 발급이 맞는 선택입니다.

CLI가 없으면 실패합니다. resolveClaudePath()가 null을 반환하면 (Claude Code 미설치 등) 해당 기능은 503 에러를 내도록 처리해줘야 합니다.

타임아웃을 꼭 걸어주세요. 서브프로세스 호출은 응답이 안 올 수도 있으니, 강제 종료(proc.kill())하는 안전장치가 필요합니다.

Part B

AI에게 그대로 던질 부분

아래 프롬프트를 복사해서 Claude Code 같은 AI 코딩 어시스턴트에 붙여넣으면 구현됩니다

§ 03

구현 프롬프트복사해서 AI 어시스턴트에 붙여넣기

PROMPT · 그대로 복사

다음 사양대로 TypeScript(Bun 런타임) 유틸리티 두 개를 만들어줘: resolveClaudePath()와 callClaude().

1. resolveClaudePath(): string | null
   – zsh -l -c ‘which claude’ (로그인 셸)로 PATH를 조회해서 claude 실행 파일 경로를 찾는다.
   – 못 찾으면 아래 경로들을 순서대로 직접 확인한다:
     /opt/homebrew/bin/claude
     /usr/local/bin/claude
     ${HOME}/.npm-global/bin/claude
   – 그래도 없으면 null을 반환한다.

2. callClaude(prompt: string, model = ‘haiku’): Promise<any>
   – resolveClaudePath()가 null이면 즉시 503 에러를 던진다.
   – Bun.spawn으로 [claudePath, ‘–safe-mode’, ‘-p’, ‘–model’, model, prompt] 실행 (stdout/stderr ‘pipe’).
   – 30초 타임아웃: 응답이 없으면 proc.kill()로 강제 종료한다.
   – stdout을 문자열로 읽고, 정규식 /\{[\s\S]*\}/ 로 JSON 블록만 추출해서 JSON.parse한다.
   – JSON 블록을 못 찾으면 안전한 기본값(예: { name: null, category: null })을 반환한다.

제약 조건:
– –safe-mode를 반드시 포함해서 파일/명령 접근 없이 순수 텍스트 응답만 받는다.
– 이름·카테고리 추천처럼 가벼운 작업은 –model haiku로 고정한다.
– 여러 사용자를 상대하는 프로덕션 서버에는 이 패턴을 쓰지 않는다 (개인용 로컬 도구 전용).

이 프롬프트 안에 구현 순서, 폴백 경로, 타임아웃 값, 에러 처리까지 전부 들어 있습니다. 왜 이렇게 만들었는지가 궁금하면 위 Part A를 참고하세요.

§ 04

참고 구현AI가 생성할 결과물 예시 (Bun 기준)

경로 찾기

GUI·백그라운드 프로세스는 PATH가 비어있는 경우가 많아 로그인 셸로 다시 조회한다.

zsh -l -c ‘which claude’

서브프로세스 실행

프롬프트를 만들어 –safe-mode, -p, –model haiku 옵션으로 실행한다.

Bun.spawn([…])

타임아웃

응답이 안 올 수도 있으니 일정 시간 후 강제 종료하는 안전장치를 건다.

setTimeout(kill, 30_000)

응답 파싱

자연어 출력에서 정규식으로 JSON 블록만 뽑아낸다.

raw.match(/\{[\s\S]*\}/)

resolveClaudePath.ts

function resolveClaudePath(): string | null {
  // zsh 로그인 셸로 조회 — PATH, alias가 제대로 로드된 상태
  const r = Bun.spawnSync([‘zsh’, ‘-l’, ‘-c’, ‘which claude’]);
  const path = r.stdout.toString().trim();
  if (path && existsSync(path)) return path;

  // 못 찾으면 흔히 설치되는 위치들을 직접 확인
  for (const p of [
    ‘/opt/homebrew/bin/claude’,
    ‘/usr/local/bin/claude’,
    `${process.env.HOME}/.npm-global/bin/claude`,
  ]) {
    if (existsSync(p)) return p;
  }
  return null;
}

callClaude.ts

const prompt = `다음 프로젝트를 분석해서 JSON만 답해줘 (설명 없이):
파일 목록: ${files}
package.json 일부: ${pkgJson}

{“name”:”2~4단어 영문 별칭”,”category”:”한 단어 카테고리”}`;

const proc = Bun.spawn(
  [CLAUDE_PATH, ‘–safe-mode’, ‘-p’, ‘–model’, ‘haiku’, prompt],
  { stdout: ‘pipe’, stderr: ‘pipe’ }
);

const timeoutId = setTimeout(() => proc.kill(), 30_000); // 30초 타임아웃
await proc.exited;
clearTimeout(timeoutId);

const raw = (await new Response(proc.stdout).text()).trim();
const match = raw.match(/\{[\s\S]*\}/);
if (!match) return { name: null, category: null };
const parsed = JSON.parse(match[0]);

§ 05

옵션 3개프롬프트가 지키는 조합 — 안전하고 저렴한 이유

옵션	역할
-p	대화형 세션 대신 “질문 하나 → 답변 하나” 모드로 실행
–safe-mode	파일 읽기/쓰기, 명령 실행 등 도구 접근을 막고 순수 텍스트 응답만 받음 — 서버에서 신뢰 안 되는 입력을 다룰 때 안전
–model haiku	이름/카테고리 추천처럼 가벼운 작업엔 가장 빠르고 저렴한 모델로 충분

Codex CLI로 같은 걸 하고 싶다면 대응하는 옵션은 이렇습니다. 완전히 1:1은 아니라서 차이도 같이 적었습니다.

Codex 옵션	Claude 대응	역할 · 차이점
exec “…”	-p	대화형 세션 대신 “프롬프트 하나 → 최종 응답” 후 종료
–sandbox read-only	–safe-mode	파일 쓰기·명령 실행을 막음. 단 Codex는 읽기 접근은 여전히 허용하므로 `--safe-mode`만큼 완전 차단은 아닙니다 — 신뢰 안 되는 입력을 다룰 땐 이 차이를 감안하세요.
-o <file>	정규식으로 stdout 파싱	`--output-last-message`가 최종 응답을 파일에 바로 써줍니다 — 정규식으로 JSON 블록을 긁어낼 필요가 없어서 오히려 더 간단합니다.
-m <model>	–model haiku	가벼운 작업엔 저비용 모델을 지정. 정확한 모델 이름은 자주 바뀌므로 `codex --help`나 `~/.codex/config.toml`에서 확인하세요.

§ 06 · 정리

이미 있는 걸
다시 쓰면 된다.

API 키 발급도, 별도 SDK 설치도 필요 없이, 이미 여러분 컴퓨터에 있는 Claude Code를 그대로 “AI 엔진”으로 재활용하는 셈입니다. 개인용 로컬 도구를 만들 때 특히 유용한 패턴이니, 다음 사이드 프로젝트에 AI 기능을 붙이고 싶을 때 Part B의 프롬프트를 그대로 던져보세요.

새 API를 만드는 것보다, 이미 있는 인증을 재사용하는 게 더 빠르다.

API 키 없이,
AI 기능 만들기.

사람이 이해할 부분

핵심 아이디어`claude`는 그냥 커맨드라인 프로그램이다

언제 쓰나장점과 주의할 점 — 쓰기 전에 판단할 것

AI에게 그대로 던질 부분

구현 프롬프트복사해서 AI 어시스턴트에 붙여넣기

참고 구현AI가 생성할 결과물 예시 (Bun 기준)

옵션 3개프롬프트가 지키는 조합 — 안전하고 저렴한 이유

이미 있는 걸
다시 쓰면 된다.

답글 남기기 응답 취소

Hey!

Join the Club

Categories

Tags

Blogroll

사람이 이해할 부분

핵심 아이디어claude는 그냥 커맨드라인 프로그램이다

언제 쓰나장점과 주의할 점 — 쓰기 전에 판단할 것

AI에게 그대로 던질 부분

구현 프롬프트복사해서 AI 어시스턴트에 붙여넣기

참고 구현AI가 생성할 결과물 예시 (Bun 기준)

옵션 3개프롬프트가 지키는 조합 — 안전하고 저렴한 이유

이미 있는 걸다시 쓰면 된다.

이것이 좋아요:

Read Next:

답글 남기기 응답 취소

Hey!

Join the Club

Categories

Tags

Blogroll

핵심 아이디어`claude`는 그냥 커맨드라인 프로그램이다

이미 있는 걸
다시 쓰면 된다.