내 CLI 연결하기

이 사이트는 API 키를 하나도 갖고 있지 않습니다. 답은 내 컴퓨터에 이미 로그인해 둔 claude(Claude Max·Pro 구독)와 codex(ChatGPT Plus·Pro 구독)가 만듭니다.

어떻게 되는 건가

내 PC 가 Cloudflare 로 연결을 겁니다. 반대 방향이 아닙니다. 그래서 내 컴퓨터에 포트를 열 필요도, 공유기를 만질 필요도 없고, 폰이나 학교 PC 에서도 그대로 됩니다.

  폰 · 학교 PC · 어디서든
        │ HTTPS + Cloudflare Access 로그인
        ▼
  이 사이트  ◀──── WSS ──── 내 PC (에이전트 실행 중)
                             ├─ claude   (구독)
                             └─ codex    (구독)

에이전트를 끄면 지난 문서와 회로도는 그대로 보입니다. 필요한 건 새로 물어볼 때뿐입니다.

명령어 3개

git clone https://github.com/DeveloperDE/circuit.git
cd circuit
npm install

npm run setup      # ← 나머지를 전부 안내합니다

npm run setup 이 하는 일:

중간에 끊어도 됩니다. 다시 실행하면 이미 된 건 건너뜁니다.

직접 하셔야 하는 것 두 가지

자동화가 불가능한 부분입니다.

1. CLI 로그인 — claude 와 codex 를 각각 한 번 실행해서 로그인. setup 이 안 된 걸 찾아서 어떤 명령어를 치라고 알려줍니다.
   • npm i -g @anthropic-ai/claude-code → claude 실행 후 로그인
   • npm i -g @openai/codex → codex 실행 후 Sign in with ChatGPT

   ChatGPT 는 "Codex CLI" 라는 프로그램으로 연결합니다. 프로그램 이름만 Codex 이고 로그인하는 건 본인 ChatGPT 계정이며, 사용량도 ChatGPT 요금제에서 나갑니다 — API 과금이 아닙니다.

2. Cloudflare 대시보드에서 Access 켜기 — 클릭 몇 번. setup 이 화면에 순서를 띄워 주고, AUD 태그를 붙여넣으면 나머지 설정은 자동으로 들어갑니다.

⚠️ Access 를 켜기 전까지 이 주소는 보호되지 않습니다.
설정이 비어 있으면 Worker 가 인증 없이 서빙하는 대신 503 을 돌려줍니다 — 깜빡한 채 열려 있는 것보다 안 되는 게 낫기 때문입니다.

setup 마지막에 주소를 직접 찔러보고 로그인 화면으로 넘어가는지 확인합니다. "켰다고 생각한다"와 "실제로 켜졌다"는 다르고, 이건 후자만 통과시킵니다.

에이전트용 서비스 토큰

Access 를 켜면 에이전트도 그 벽에 막힙니다. 브라우저가 없으니 로그인을 끝낼 수가 없습니다. 서비스 토큰이 Cloudflare 가 마련해 둔 기계 대 기계 통로라서, 에이전트는 로그인 대신 이것을 제시합니다.

1. Zero Trust → Access → Service Auth → Service Tokens → Create
2. 이름은 아무거나 (예: circuit-agent)
3. Client ID 와 Client Secret 을 지금 복사 — 다시 못 봅니다
4. 애플리케이션 정책에 Action: Service Auth 정책을 하나 더 추가하고 Include 에 이 토큰을 지정

setup 이 이 두 값을 물어보고 config/local.json 에 저장합니다. 이 파일은 .gitignore 에 있어 커밋되지 않습니다.

토큰이 계속 막힐 때 — 그 경로만 열기

서비스 토큰은 정책을 만드는 것과 그 정책을 애플리케이션에 붙이는 것이 따로라서 자주 어긋납니다. 계속 로그인 화면으로 튕기면 토큰을 포기하고 에이전트가 쓰는 경로 하나만 여는 쪽이 간단합니다. Access 는 경로가 더 자세한 애플리케이션을 먼저 적용합니다.

1. Access → Applications → Add an application → Self-hosted
2. 도메인은 같은 *.workers.dev 주소, 경로에 agent/connect
3. 정책 하나: Action: Bypass, Include Everyone

이 경로가 열려도 안전합니다. Worker 가 AGENT_SECRET 헤더를 직접 확인해서 맞지 않으면 업그레이드 자체를 401 로 끊습니다. 문서와 /api/ 는 원래 앱의 Access 뒤에 그대로 남습니다.

물어본 것을 Obsidian 에 남기기 (선택)

setup 마지막 단계에서 볼트 폴더를 고르면, 물어본 것과 답이 문서마다 한 파일로 쌓입니다.

<볼트>/_질문/분압기와 분류기 — 질문.md

노트 본문이 아니라 옆에 두는 이유가 있습니다. 노트는 다시 만들어지면 통째로 덮이지만 이 파일은 몇 번을 다시 만들어도 남고, Obsidian 에서는 위키링크로 둘이 나란히 보입니다. 둘 다로 물으면 두 답이 한 항목 안에 들어가서 어디서 갈렸는지 바로 보이고, 워크벤치에서 물었다면 그때 보던 회로도 함께 남습니다.

Google Drive 폴더 안에 두면 자동으로 올라갑니다 — API 는 쓰지 않습니다.그냥 동기화 폴더에 파일을 쓸 뿐입니다. Drive 데스크톱은 스트리밍이 아니라 "파일 미러링" 으로 두세요. 지정하지 않으면 이 기능은 그냥 꺼집니다.

그 다음

npm run agent      # 켜둔 채로 두세요

  ✓ 내 CLI 가 온라인이 되었습니다

  브라우저를 엽니다 …

이 창의 표시가 초록으로 바뀌고, 모든 문서 페이지의 오른쪽 AI 패널이 살아납니다. 폰이든 어디든 이 주소로 들어가면 그대로 씁니다.

안전에 대해

• 내 PC 로 들어오는 연결이 하나도 없습니다. 내가 바깥으로 걸기만 합니다.
• 사이트 전체가 Cloudflare Access 뒤에 있고, 허용된 이메일만 들어옵니다.
• Worker 는 Access 가 준 토큰의 서명을 직접 검증합니다 — 헤더가 있다는 것만 믿지 않습니다.
• AGENT_SECRET 을 아는 컴퓨터만 에이전트로 붙을 수 있습니다.
• claude 는 도구를 전부 막고 실행합니다 — 글만 씁니다.
• codex 는 읽기 전용 샌드박스로 실행합니다.
• 프롬프트는 stdin 으로 보냅니다 — 윈도우 8191자 한도와 명령 주입이 함께 사라집니다.

윈도우에서 주의할 점

PowerShell 을 관리자 권한으로 열지 마세요. 이 프로그램은 관리자 권한이 전혀 필요 없고, 관리자 창은 C:\Windows\System32 에서 시작하기 때문에 거기에 저장소가 만들어집니다. 시작 메뉴에서 PowerShell 을 그냥 클릭하면 C:\Users\<이름> 에서 시작합니다. (혹시 이미 그렇게 하셨다면 setup 이 감지해서 정리 방법을 알려줍니다.)

잘 안 될 때

무엇이 왜 실패하는지부터 보세요. 이 명령은 고치지 않고 보여 주기만 합니다 — 실행한 명령줄, 종료 코드, 출력 전문을 그대로 찍습니다. 시크릿은 찍지 않으니 출력을 그대로 복사해 물어보셔도 됩니다.

npm run doctor

{ "cliPaths": { "claude": "C:\...\claude.cmd" } }