Skip to content
푸땡로그
Go back

Hermes Agent 시작하기: 맥에 설치하고 ChatGPT OAuth로 GPT 모델 연결하기

Hermes Agent ↗는 Nous Research가 MIT 라이선스로 공개한 터미널 AI 에이전트입니다. 작업 경험에서 스킬을 만들고, 세션 사이에 메모리를 유지하며, 지난 대화를 검색합니다. 에이전트가 쓸 언어 모델은 사용자가 따로 연결합니다.

ChatGPT 구독이 있다면 OpenAI API 키 없이 ChatGPT 계정으로 로그인해 GPT 모델을 쓸 수 있습니다. 순서는 설치, hermes model에서 OpenAI ▸ ChatGPT or Codex Subscription 선택, 브라우저에서 디바이스 코드 승인, 연결 확인입니다. Apple Silicon 맥과 디바이스 코드 로그인이 허용된 ChatGPT 계정을 기준으로 설명합니다.

기준: 2026년 10월 24일 · Hermes Agent v0.22.5(stable, 2026-10-23 릴리스). 근거는 Hermes Agent 공식 문서 ↗와 GitHub 릴리스 ↗입니다.


설치 전에 준비할 것

맥 종류, 기본 도구, ChatGPT 계정 설정 세 가지를 먼저 확인합니다.

항목조건근거
맥Apple Silicon은 1순위 지원 대상입니다. Intel 맥도 명령줄 버전은 설치할 수 있습니다.Platform Support ↗
기본 도구Git, curl, tar, SHA-256 도구가 필요합니다. macOS에는 SHA-256 도구인 shasum이 있습니다.Installation ↗
ChatGPT디바이스 코드 로그인이 허용된 계정이어야 합니다.OpenAI Codex Authentication ↗
Codex CLI설치하지 않아도 됩니다.Providers ↗

Command Line Tools를 설치하지 않은 맥에서는 /usr/bin/git이 실행되지 않는 빈 명령입니다. 이 경우 설치 스크립트가 Homebrew로 Git을 설치하거나 Apple의 설치 창을 엽니다.

디바이스 코드 로그인은 터미널에 표시된 코드를 브라우저에 입력해 로그인을 승인하는 방식입니다. Hermes는 Codex CLI와 같은 OpenAI 디바이스 코드 로그인 경로를 씁니다. OpenAI 문서 ↗는 이 방식을 베타로 표시합니다. 개인 계정은 ChatGPT 보안 설정에서 디바이스 코드 로그인을 켭니다. 워크스페이스 계정은 관리자가 워크스페이스 권한에서 허용해야 합니다. 허용할 수 없는 환경이면 아래의 브라우저 로그인을 씁니다.


1단계: 설치하고 hermes 명령 확인하기

공식 설치 문서 ↗의 한 줄 설치 명령을 실행합니다.

Bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

설치 스크립트는 최신 stable 릴리스를 ~/.hermes/hermes-agent에 내려받습니다. 이어서 Hermes의 패키지 관리자(PM)가 Python 3.14, Node.js, npm, ripgrep, FFmpeg를 고정된 버전으로 준비합니다. 브라우저 자동화 도구(agent-browser와 Chromium)와 컴퓨터 제어 드라이버(cua-driver)도 기본으로 설치합니다. 마지막으로 ~/.local/bin/hermes 실행 파일을 만들고 ~/.zshrc와 ~/.zprofile에 PATH 설정 줄을 추가합니다.

터미널에서 실행하면 설치 끝에 hermes setup 마법사와 게이트웨이 설정이 이어서 열립니다. 모델 연결을 다음 단계에서 따로 하려면 입력이 필요한 단계를 건너뛰는 --non-interactive를 붙입니다. 브라우저 도구가 당장 필요 없으면 --skip-browser, 컴퓨터 제어 드라이버가 필요 없으면 --skip-computer-use를 함께 붙일 수 있습니다.

Bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive

설치가 끝나면 셸 설정을 다시 읽고 버전을 확인합니다.

Bash
source ~/.zshrc
hermes --version
Text
Hermes Agent v0.22.5 (2026.9.24) · stable · local <커밋>
Install directory: /Users/<사용자>/.hermes/hermes-agent
Install method: git
Python: 3.14.9

첫 줄의 v0.22.5가 설치된 버전이고 stable은 업데이트 채널입니다. hermes: command not found가 나오면 새 터미널을 열거나 source ~/.zshrc를 다시 실행합니다.

터미널 대신 데스크톱 앱을 쓰려면 Hermes 사이트 ↗의 DMG로 Hermes.app을 설치할 수 있습니다. stable 릴리스의 맥용 데스크톱 앱 패키지는 기본으로 Apple Silicon용만 빌드됩니다. 이 글은 터미널 명령을 기준으로 진행합니다.


2단계: hermes model에서 ChatGPT OAuth 선택하기

provider와 모델은 hermes model로 연결합니다. provider는 Hermes가 모델을 호출하는 경로이고, ChatGPT 계정 경로의 provider id는 openai-codex입니다. 이 명령은 셸에서 실행합니다. Hermes 대화 안의 /model은 이미 연결한 provider 사이에서만 전환하며 OAuth 로그인을 시작하지 못합니다(CLI 명령 문서 ↗).

Bash
hermes model

provider 목록에서 OpenAI ▸ (ChatGPT/Codex subscription or direct OpenAI API)를 고르면 하위 메뉴가 열립니다.

Text
Select OpenAI provider:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel  ← previous
 → (●) ChatGPT or Codex Subscription
   (○) OpenAI API

ChatGPT or Codex Subscription이 ChatGPT 계정으로 로그인하는 항목입니다. OpenAI API는 API 키로 연결하는 항목입니다. 2026년 5월 말의 v0.15.2에서는 이 항목이 최상위 목록의 OpenAI Codex였습니다. 지금은 OpenAI ▸ 아래로 묶여 있습니다.

선택한 뒤의 흐름은 저장된 로그인이 있는지에 따라 갈립니다.

flowchart TD
    A["hermes model 실행"] --> B["OpenAI ▸ → ChatGPT or Codex Subscription"]
    B --> C{"Hermes에 저장된 Codex 로그인이 있나?"}
    C -->|있음| D["Use existing credentials 선택"]
    C -->|없음| E["터미널에 URL과 코드 표시"]
    E --> F["브라우저에서 ChatGPT 로그인 후 코드 입력·승인"]
    F --> G["~/.hermes/auth.json에 토큰 저장"]
    G --> H["Codex 모델 목록에서 기본 모델 선택"]
    D --> H
    H --> I["~/.hermes/config.yaml에 provider·model 저장"]

저장된 로그인이 있으면 Use existing credentials, Reauthenticate (new OAuth login), Cancel 중 하나를 고릅니다. 다른 ChatGPT 계정으로 바꾸려면 Reauthenticate를 고릅니다.

Codex CLI로 로그인한 적이 있어 ~/.codex/auth.json이 있으면 Hermes가 그 자격 증명을 가져올지 묻습니다. 질문은 Import these credentials? (a separate login is recommended) [y/N]이고 기본값은 N입니다. 두 프로그램이 같은 토큰을 나눠 쓰면 한쪽의 토큰 갱신이 다른 쪽 로그인을 끊을 수 있습니다. 그래서 N을 눌러 Hermes 전용 로그인을 새로 만듭니다. 이유는 토큰 절에서 설명합니다.


3단계: 브라우저에서 디바이스 코드 승인하기

새 로그인을 시작하면 터미널에 아래 안내가 나옵니다. Hermes v0.22.5 소스 ↗가 출력하는 문구이며 코드는 로그인할 때마다 달라집니다.

Text
Signing in to OpenAI Codex...
(Hermes creates its own session — won't affect Codex CLI or VS Code)

To continue, follow these steps:

  1. Open this URL in your browser:
     https://auth.openai.com/codex/device

  2. Enter this code:
     <표시된 코드>

Waiting for sign-in... (press Ctrl+C to cancel)

브라우저에서 https://auth.openai.com/codex/device를 엽니다. ChatGPT 계정으로 로그인한 뒤 터미널의 코드를 입력하고 접근을 승인합니다. 그동안 터미널은 승인 여부를 계속 확인합니다. 15분 안에 승인하지 않으면 Login timed out after 15 minutes.로 끝나므로 hermes model을 다시 실행합니다.

승인이 끝나면 터미널에 다음 결과가 나옵니다(같은 소스 기준).

Text
Login successful!
  Auth state: ~/.hermes/auth.json
  Config updated: /Users/<사용자>/.hermes/config.yaml (model.provider=openai-codex)

이어서 모델 선택 목록이 열립니다. 목록은 ChatGPT 계정의 Codex 백엔드에서 받아 오므로 요금제에 따라 다를 수 있습니다. 이름 끝에 -900k가 붙은 항목은 큰 컨텍스트 창을 쓰는 선택지입니다. 붙지 않은 기본 항목은 대부분 272K 컨텍스트로 동작합니다(Providers ↗). 모델을 고르면 Default model set to: <모델> (via OpenAI Codex)가 출력됩니다.

이 과정에서 ~/.hermes/config.yaml의 model 항목이 다음처럼 바뀝니다.

YAML
# ~/.hermes/config.yaml (해당 부분)
model:
  default: <선택한 모델>
  provider: openai-codex
  base_url: https://chatgpt.com/backend-api/codex

디바이스 코드가 막혀 있으면: 브라우저 로그인

조직 정책으로 디바이스 코드 로그인을 쓸 수 없으면 브라우저 인증 방식(authorization code + PKCE)으로 로그인합니다(Providers의 Codex Note ↗).

Bash
hermes auth add openai-codex --browser

Hermes가 브라우저로 OpenAI 로그인 페이지를 열고 http://localhost:1455/auth/callback에서 결과를 받습니다. 1455 포트는 OpenAI가 Codex 클라이언트용으로 등록한 주소라 바꿀 수 없습니다. Codex CLI 로그인이 진행 중이라 포트가 사용 중이면 Hermes가 그 사실을 알리고 디바이스 코드 방식으로 돌아갑니다.

로그인이 끝나면 hermes model에서 같은 항목을 고르고 Use existing credentials로 모델을 정합니다. 앞으로 모든 Codex 로그인을 브라우저 방식으로 하려면 config.yaml에 다음을 넣습니다. 이 설정은 hermes model의 로그인에도 적용됩니다.

YAML
# ~/.hermes/config.yaml
auth:
  codex_login_flow: browser

토큰은 어디에 저장되고 언제 만료되나

Hermes는 ChatGPT 로그인 토큰을 ~/.hermes/auth.json에 저장합니다. Codex CLI의 ~/.codex/auth.json에는 쓰지 않습니다. 파일 권한은 소유자만 읽고 쓰는 600이고 상위 폴더는 700입니다. 토큰이 평문 JSON으로 들어 있으므로 비밀번호처럼 다룹니다.

auth.json의 위치내용
providers.openai-codex.tokens.access_token모델 요청에 붙이는 토큰입니다. 만료 시각(exp)이 들어 있습니다.
providers.openai-codex.tokens.refresh_token새 access token을 받을 때 쓰는 토큰입니다. 한 번 쓰면 새 값으로 바뀝니다.
providers.openai-codex.last_refresh마지막 로그인 또는 갱신 시각입니다.
credential_pool.openai-codex계정 목록입니다. hermes auth add로 계정을 여러 개 추가할 수 있습니다.
active_provider현재 쓰는 provider입니다. 로그인 후 openai-codex가 됩니다.

access token은 만료 시각이 있습니다. Hermes는 요청 전에 만료 시각을 확인하고 2분 이내로 남았으면 refresh token으로 새 토큰을 받습니다(인증 상수 ↗). 그래서 평소에는 다시 로그인하지 않아도 됩니다. access token의 정확한 수명은 Hermes와 OpenAI 문서 모두 밝히지 않습니다.

refresh token은 일회용이고 갱신할 때마다 새 값으로 바뀝니다. 두 프로그램이 같은 토큰 계열을 갖고 있으면 먼저 갱신한 쪽이 다른 쪽의 사본을 무효로 만듭니다. Hermes나 Codex CLI 한쪽이 계속 인증에 실패하면 이 충돌을 의심합니다(Borrowed CLI logins ↗). Hermes 전용 로그인을 따로 만들면 피할 수 있습니다.

Hermes에는 자기 로그인을 쓸 수 없을 때 Codex CLI의 로그인을 자동으로 빌려 오는 기능도 있고, 기본으로 켜져 있습니다. Codex CLI를 함께 쓴다면 이 기능을 끕니다. 끄더라도 hermes auth add openai-codex는 Codex CLI 로그인을 가져올지 먼저 묻습니다.

YAML
# ~/.hermes/config.yaml
auth:
  adopt_external_logins: false

갱신이 invalid_grant, 취소된 권한, 기타 HTTP 4xx 오류로 실패하면 Hermes는 그 refresh token을 더는 쓰지 않습니다. 다음 요청에서 다시 로그인하라는 안내가 나옵니다. hermes auth add openai-codex나 hermes model로 새로 로그인하면 풀립니다.


연결이 됐는지 확인하는 명령

아래 네 명령으로 로그인 상태, 기본 provider, 계정 한도, 실제 응답을 차례로 확인합니다. hermes status와 hermes auth status는 토큰을 갱신하지 않고 저장된 상태만 읽습니다.

명령로그인 전연결 성공 후
hermes auth status openai-codexopenai-codex: logged out (No Codex credentials stored. …)openai-codex: logged in
hermes statusProvider: Auto, Providers: none connectedModel:에 고른 모델, Provider: ChatGPT or Codex Subscription
hermes usage --provider openai-codex종료 코드 1과 No account usage available … 안내요금제(plan)와 5시간·주간 사용 비율, 초기화 시각
hermes -z "Reply with OK" --provider openai-codex종료 코드 2와 No Codex credentials stored … 안내모델의 답(예: OK)과 종료 코드 0

로그인 전 열은 v0.22.5를 새로 설치한 상태의 출력입니다. 성공 후 열은 CLI 명령 문서 ↗와 Hermes 소스의 출력 문구를 따릅니다.

hermes -z는 질문 하나를 보내고 최종 답만 출력하는 한 번 실행 모드입니다. --provider openai-codex를 붙이면 이번 실행만 ChatGPT 연결로 보냅니다. 종료 코드 0은 답을 받았다는 뜻이고, 2는 실패하거나 중간에 멈췄다는 뜻입니다. 출력이 비었는지가 아니라 종료 코드로 판단합니다.

Bash
hermes -z "Reply with OK" --provider openai-codex
echo $?

hermes usage는 대화를 시작하지 않고 계정 한도만 조회합니다. --json을 붙이면 스크립트에서 읽을 수 있는 JSON으로 출력합니다.

마지막으로 hermes나 hermes --tui로 대화를 엽니다. 시작 배너에 고른 모델과 provider가 보이고 두 번 이상 주고받아도 오류가 없으면 연결이 끝난 것입니다(Quickstart ↗).


실패할 때 흔한 원인과 해결

증상원인해결
hermes: command not found셸이 PATH를 다시 읽지 않았습니다.새 터미널을 열거나 source ~/.zshrc를 실행합니다.
브라우저에서 디바이스 코드 로그인을 진행할 수 없습니다.계정이나 워크스페이스에서 디바이스 코드 로그인이 꺼져 있습니다.ChatGPT 보안 설정에서 켜거나 관리자에게 요청합니다. 안 되면 hermes auth add openai-codex --browser를 씁니다.
Port 1455 is already in use …Codex CLI 로그인이 같은 포트를 쓰고 있습니다.Codex CLI 로그인을 끝낸 뒤 다시 실행합니다. 그대로 두면 디바이스 코드 방식으로 진행됩니다.
Login timed out after 15 minutes.15분 안에 브라우저에서 승인하지 않았습니다.hermes model을 다시 실행합니다.
OpenAI is rate-limiting Codex login requests (HTTP 429)짧은 시간에 로그인을 여러 번 시도했습니다.안내된 시간만큼 기다렸다가 다시 시도합니다. 자격 증명 문제는 아닙니다.
로그인 중 [SSL: UNEXPECTED_EOF_WHILE_READING] 또는 TLS 핸드셰이크 시간 초과중간 네트워크 장비가 OpenSSL 3.5+의 양자 내성 키 교환 그룹(X25519MLKEM768 등)을 거부합니다.아래 OPENSSL_CONF 설정으로 키 교환 그룹을 제한하고 hermes model을 다시 실행합니다.
로그인 후에도 Hermes나 Codex CLI 한쪽이 계속 인증에 실패합니다.두 프로그램이 같은 refresh token을 나눠 썼습니다.hermes auth add openai-codex로 Hermes 전용 로그인을 만들고 auth.adopt_external_logins: false를 넣습니다.
No Codex credentials stored.로 시작하는 안내로그인이 끝나지 않았거나 다른 프로필에서 실행했습니다.hermes model을 다시 실행합니다. 이름 있는 프로필은 hermes -p <프로필> auth add openai-codex로 로그인합니다.
The '<model>' model is not supported when using Codex with a ChatGPT account. (HTTP 400)ChatGPT 계정의 Codex 백엔드가 그 모델을 제공하지 않습니다.hermes model 목록에 있는 모델을 고릅니다.
사용량 한도 도달 안내요금제의 Codex 사용 한도를 다 썼습니다.hermes usage --provider openai-codex로 초기화 시각을 확인합니다.
대화 안의 /model에 ChatGPT 항목이 없습니다./model은 새 provider를 추가하지 못합니다.대화를 끝내고 셸에서 hermes model을 실행합니다.

TLS 오류는 Providers 문서 ↗가 안내하는 OpenSSL 설정으로 우회합니다. 아래 내용을 파일로 저장하고 OPENSSL_CONF 환경 변수에 그 경로를 지정한 뒤 hermes model을 실행합니다.

ini
openssl_conf = openssl_init

[openssl_init]
ssl_conf = ssl_sect

[ssl_sect]
system_default = system_default_sect

[system_default_sect]
Groups = x25519:secp256r1:secp384r1:x448

일시적인 연결 끊김은 오류로 끝나지 않습니다. Hermes는 승인을 기다리는 동안 전송 오류가 여섯 번 연속으로 나야 로그인을 중단합니다.


API 키 경로(openai-api)와 무엇이 다른가

같은 OpenAI ▸ 메뉴의 OpenAI API는 OpenAI API 키로 연결하는 별도 provider입니다. 두 경로는 인증, 호출 주소, 비용 구조가 다릅니다.

구분ChatGPT or Codex Subscription (openai-codex)OpenAI API (openai-api)
인증ChatGPT 계정 디바이스 코드 또는 브라우저 로그인~/.hermes/.env의 OPENAI_API_KEY
호출 주소https://chatgpt.com/backend-api/codexapi.openai.com, 또는 OPENAI_BASE_URL로 지정
모델ChatGPT 계정의 Codex 백엔드가 허용하는 모델OpenAI API가 제공하는 모델
비용ChatGPT 요금제의 사용 한도API 토큰 사용량 과금
자격 증명~/.hermes/auth.json~/.hermes/.env

어떤 ChatGPT 요금제에서 이 경로를 쓸 수 있는지는 Hermes 문서에 아직 없습니다. Hermes 사용량이 요금제 한도에서 어떻게 차감되는지도 설명하지 않습니다(Providers의 구독 요금제 절 ↗). 한도가 신경 쓰이면 hermes usage로 직접 확인합니다.

이미지 해석, 웹 요약 같은 보조 작업도 기본으로는 hermes model에서 고른 모델을 씁니다. 보조 작업을 다른 모델로 돌리려면 Auxiliary Models ↗ 설정을 바꿉니다. 어떤 경로든 모델의 컨텍스트 창은 64,000 토큰 이상이어야 합니다. 이보다 작은 모델은 시작 단계에서 거부됩니다(Quickstart ↗).


OpenClaw를 쓰고 있었다면

OpenClaw ↗는 MIT 라이선스의 셀프 호스팅 도구입니다. 자기 컴퓨터에서 돌리는 Gateway가 WhatsApp, Slack, Discord, Telegram 같은 채팅 앱을 AI 에이전트에 연결합니다. Hermes도 자체 메시징 게이트웨이 ↗로 Telegram, Discord, Slack, WhatsApp, Signal 등을 연결합니다. 두 도구의 사용 장면이 겹치므로 OpenClaw 설정을 Hermes로 옮기는 기능이 있습니다.

처음 설치한 Hermes에서 hermes setup을 실행하면 ~/.openclaw를 찾아 설정을 가져올지 묻습니다. 위에서 --non-interactive로 설치했거나 이미 설정을 마쳤다면 가져오기 플러그인을 설치하고 직접 실행합니다.

Bash
hermes plugins install agent-importers
hermes import-agent openclaw --dry-run

--dry-run은 무엇을 옮길지 미리 보여 주기만 합니다. API 키는 --migrate-secrets를 붙여야 옮기며, 그때도 허용 목록에 있는 키만 옮깁니다(CLI 명령 문서 ↗). OpenClaw 쪽의 최근 변화는 OpenClaw 2.0 정리 글에 있습니다.


기록해 둘 내용


관련 글


참고 자료

2026년 10월 24일 수정: 제목이 약속한 ChatGPT OAuth 연결 과정을 v0.22.5 기준으로 다시 썼습니다. 메뉴 위치(OpenAI ▸), 디바이스 코드 승인, 토큰 저장·갱신, 연결 확인 명령, 실패 해결을 추가했고 OpenClaw 비교는 현재 기능에 맞게 고쳤습니다.


Share this post on:

Previous Post
스크린 리더가 읽는 버튼 이름의 계산 규칙 등 W3C 접근성 초안 4종 갱신 — A11Y 주간 다이제스트 2026.05.25 ~ 05.31
Next Post
Claude Opus 4.8 출시: 더 똑똑한 모델보다 협업 능력이 중요한 이유