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

터미널에서 쓰는 AI 에이전트는 이제 종류가 꽤 많아졌습니다. 그중 Nous Research ↗가 만든 Hermes Agent는 경험에서 스킬을 만들고, 메모리를 영속화하며, 자신의 과거 대화를 검색하는 self-improving 에이전트를 표방합니다.

이 글에서는 Hermes Agent를 맥에 설치하고, ChatGPT 구독을 OAuth로 연동해 Codex 모델을 연결하는 흐름을 정리합니다. 마지막에는 자주 함께 언급되는 OpenClaw와 무엇이 다른지도 짚습니다.

배경 / 왜 필요한가?

Hermes Agent는 Nous Research가 공개한 AI 에이전트 플랫폼이자 CLI입니다. License는 MIT이고 Python으로 작성되었으며, GitHub releases ↗ 기준 최신 버전은 v2026.5.29.2(2026-05-29 릴리스)입니다. 날짜 기반(date-based) 버저닝을 사용하는, 빠르게 움직이는 프로젝트입니다.

터미널 중심 에이전트라는 점에서, 모바일에서 에이전트를 운영하는 흐름을 다룬 OpenAI Codex 모바일 앱 통합이나 맥에서 로컬 LLM을 돌리는 Ollama + EXAONE 3.5 설치 가이드와 같은 결의 주제입니다. 이 글은 그 위에 Hermes Agent 설치와 ChatGPT OAuth 연동이라는 구체적인 경로를 더합니다.

맥에 설치하기

설치는 한 줄짜리 스크립트로 끝납니다. macOS / Linux / WSL2에서 동일하게 동작합니다. 공식 설치 문서 ↗에 따른 방법입니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

이 installer는 uv, Python 3.11, Node.js, ripgrep, ffmpeg를 자동으로 처리합니다. 사용자가 미리 준비해야 하는 것은 Git 하나뿐입니다.

설치가 끝나면 셸 설정을 다시 불러온 뒤 실행합니다.

source ~/.zshrc
hermes

설정과 자격 증명 위치

Hermes Agent는 홈 디렉터리의 ~/.hermes/에 설정과 자격 증명을 보관합니다. 주요 파일은 다음과 같습니다.

OpenAI 연동: 두 가지 경로

이 글의 핵심입니다. Hermes Agent에서 OpenAI를 쓰는 방법은 providers 문서 ↗ 기준 두 갈래로 나뉩니다. 둘은 인증 방식도, 사용하는 모델도, 과금 방식도 다릅니다.

flowchart TD
    Start[OpenAI를 Hermes에 연결] --> Choice{인증 방식}
    Choice -->|OAuth| Run[hermes model 실행]
    Run --> Device[ChatGPT OAuth 디바이스 코드 로그인]
    Device --> Codex[provider: openai-codex<br/>ChatGPT 구독 · Codex 모델]
    Choice -->|API key| Env[~/.hermes/.env 에<br/>OPENAI_API_KEY 설정]
    Env --> Api[provider: openai-api<br/>pay-per-token · gpt-4o 등]

경로 1 — OAuth (openai-codex)

ChatGPT 구독을 그대로 활용하는 경로입니다. provider id는 openai-codex이며, hermes model로 ChatGPT OAuth 디바이스 코드 로그인을 트리거합니다.

hermes model

로그인한 자격 증명은 ~/.hermes/auth.json에 저장됩니다. 또한 ~/.codex/auth.json 파일이 있으면 Hermes가 그 안의 기존 Codex CLI 자격 증명을 그대로 import합니다. 이 OAuth 로그인 자체에는 Codex CLI 설치가 필요하지 않습니다.

이 경로는 ChatGPT 구독을 통해 Codex 모델을 사용합니다. 즉 “ChatGPT 로그인으로 Codex 모델을 쓴다”는 것이지, OAuth만으로 임의의 gpt-4o나 gpt-5에 접근하는 것은 아닙니다. 이 구분을 분명히 해두는 게 중요합니다.

경로 2 — API key (openai-api)

토큰 단위 과금(pay-per-token)으로 gpt-4o 같은 모델을 직접 쓰는 경로입니다. provider id는 openai-api입니다.

먼저 ~/.hermes/.env에 API 키를 넣습니다.

# ~/.hermes/.env
OPENAI_API_KEY=sk-...

그다음 실행 시 provider를 지정하거나,

hermes chat --provider openai-api

~/.hermes/config.yaml에 기본값으로 설정합니다. (configuration 문서 ↗ 참조)

# ~/.hermes/config.yaml
model:
  provider: "openai-api"
  default: "gpt-4o"

OpenAI 호환 엔드포인트를 쓴다면 OPENAI_BASE_URL을 추가로 지정할 수 있습니다.

두 경로 비교

설정을 더 쉽게: setup 헬퍼

provider와 model을 그때그때 바꾸려면 hermes model을 쓰고, 전체 설정을 한 번에 잡으려면 hermes setup을 사용합니다.

hermes setup

OpenClaw와는 무엇이 다른가?

Hermes Agent를 찾다 보면 OpenClaw ↗가 자주 함께 등장합니다. 그런데 둘은 경쟁 제품이라기보다 레이어가 다른 도구입니다.

OpenClaw는 WhatsApp, Slack, Discord, iMessage, Telegram, Signal 등 20개 이상의 채팅 플랫폼을 자기 머신의 AI 에이전트에 연결하는 self-hosted 메시징 게이트웨이입니다(License MIT, repo ↗). 멘탈 모델은 “어떤 채팅 앱에서든 개인 비서에게 메시지를 보낸다”에 가깝습니다. 항상 켜져 있는 Gateway 데몬으로 동작하며(openclaw onboard --install-daemon), 선택적으로 macOS 메뉴바와 iOS/Android 컴패니언 노드를 둘 수 있습니다.

정리하면 이렇습니다.

• Hermes Agent = 실제로 일을 하는 에이전트. CLI 우선이며 세션 단위로 호출합니다(선택적 chat frontend도 있음).
• OpenClaw = 메시징 앱을 에이전트에 연결하는 게이트웨이/라우터 레이어. 개인 비서·운영 지향이며 항상 켜져 있습니다.

즉 둘은 경쟁이 아니라 대체로 상호 보완적(orthogonal)입니다. 상호작용 표면(터미널 중심 에이전트 vs 어디서든 메시지를 보내는 게이트웨이)과 주된 목적(코딩/작업 수행 vs 라우팅 및 도달 가능성)이 다릅니다.

마무리

Hermes Agent는 한 줄짜리 스크립트로 맥에 설치되고, uv·Python·Node 같은 의존성을 알아서 처리합니다. OpenAI 연동은 OAuth(openai-codex, ChatGPT 구독 + Codex 모델)와 API key(openai-api, pay-per-token + gpt-4o 등)의 두 경로로 나뉘며, 이 구분만 정확히 잡으면 나머지는 단순합니다.

빠르게 바뀌는 제품인 만큼, 실제 적용 전에는 공식 문서로 커맨드와 모델 라인업을 한 번 더 확인하길 권합니다.

관련 내부 포스트:

• OpenAI Codex 모바일 앱 통합 — 폰에서 에이전트를 운영하는 흐름. 이 글은 터미널에서 Hermes로 같은 Codex 계열을 OAuth 연결합니다.
• Mac에서 Ollama + EXAONE 3.5 설치 가이드 — 맥에서 로컬 LLM을 돌리는 경로. 이 글은 반대로 클라우드 모델(ChatGPT/OpenAI)을 에이전트에 붙입니다.
• Claude Code Auto Mode — 또 다른 CLI 코딩 에이전트의 자율 실행 권한 모드. 에이전트 운용 관점을 비교하기 좋습니다.

참고 자료

• Hermes Agent 설치 문서 ↗ — 설치 스크립트와 사전 준비
• Providers 문서 ↗ — openai-codex / openai-api 연동과 64K 컨텍스트 하한
• GitHub repo ↗ — 정체성·License·릴리스
• OpenClaw 문서 ↗ — 메시징 게이트웨이 비교 근거