터미널 AI Agent 시나리오를 위한 환경 설치, 모델 설정 및 문제 해결 방법입니다.

적용 시나리오: Hermes Agent는 Nous Research가 오픈 소스로 공개한 터미널 AI Agent입니다. 로컬 명령줄, 파일 읽기 및 쓰기, 웹/이미지/음성 도구, 영구 메모리 및 메시지 게이트웨이가 필요한 사용자에게 적합합니다. 이 문서에서는 ‘환경 설치 → Hermes 설치 → Guishu Token 모델 설정 → 채팅 / 게이트웨이 실행 → 문제 해결’ 순서로 안내합니다.

설정 항목	권장 입력값	설명
Provider	More Provider / Custom / OpenAI Compatible	버전에 따라 이름이 조금씩 다릅니다. 사용자 지정 URL을 입력할 수 있는 메뉴를 선택합니다.
Base URL	`https://api.llm-token.cn/v1`	`/v1`이 포함된 루트 경로를 우선 사용하고, 연결되지 않으면 `https://api.llm-token.cn`을 사용해 보십시오.
API Key	`sk-xxxxxxxx`	붙여 넣을 때 터미널에 일반 텍스트가 표시되지 않는 것은 정상입니다.
권장 모델	`claude-sonnet-4-6`	응답이 빠르고 Agent, 이미지 인식 및 대규모 컨텍스트를 지원합니다. 모델 목록에서 다른 모델을 선택해도 됩니다.

1. Hermes란?

Hermes Agent는 터미널에서 대화하고 명령을 실행하며, 파일을 읽고 쓰고 검색하고, 웹 및 멀티모달 도구를 호출할 수 있습니다. 영구 메모리를 통해 장기적인 기본 설정도 저장합니다. 로컬 또는 서버에서 지속적으로 작업할 수 있는 AI Agent라고 이해하면 됩니다.

초보자 권장 사항: 먼저 명령줄 채팅 설정을 완료한 뒤 Telegram, Discord, WeChat 등의 메시지 채널을 설정하십시오. 최소 연결 경로부터 정상화하면 이후 문제 해결이 훨씬 쉬워집니다.

2. 설치 방법 선택

시스템	권장 방법	명령 / 설명
Windows / macOS 일반 사용자	Hermes Desktop	가장 간편한 데스크톱 설치 프로그램을 우선 다운로드합니다.
Linux / macOS / WSL2 / Termux	공식 원클릭 스크립트	`curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| bash`
Windows 네이티브 PowerShell	공식 PowerShell 스크립트	`iex (irm https://hermes-agent.nousresearch.com/install.ps1)`
안정적인 Windows 방법	WSL2 + Ubuntu	네이티브 Windows 설치가 원활하지 않으면 WSL2를 사용합니다.

3. Windows에서 WSL2 설치

PowerShell을 관리자 권한으로 엽니다.
WSL 설치 명령을 실행합니다.

wsl --install

설치가 0%에서 멈추면 다음 명령을 사용할 수 있습니다.

wsl --install --web-download -d Ubuntu

안내에 따라 컴퓨터를 재시작합니다.
Ubuntu를 처음 열 때 Linux 사용자 이름과 비밀번호를 설정합니다.
Win 키를 눌러 WSL 또는 Ubuntu를 검색하고 메뉴가 표시되는지 확인합니다.

Windows Subsystem for Linux(WSL) 시스템 아이콘입니다. 빨간색 배경 왼쪽 위에 파란색 펭귄이 있고 오른쪽…

WSL이 정상적으로 설치되었는지 검증합니다.

wsl --version

4. Git 및 Hermes 설치

WSL2 / Ubuntu 터미널에서 다음을 실행합니다.

sudo apt update
sudo apt install git -y
git --version

그런 다음 Hermes를 설치합니다.

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

설치가 완료되면 터미널 설정을 다시 로드하고 검증합니다.

source ~/.bashrc
hermes version
hermes doctor

WSL2/Ubuntu 터미널에서 hermes --version 명령을 실행한 결과입니다. Hermes Agent 버전 v0.8.0…

주의: 기존 문서의 hermes updata는 오타입니다. 올바른 업데이트 명령은 hermes update입니다.

5. Guishu Token 모델 설정

Hermes를 설치한 터미널에서 다음을 실행합니다.

hermes setup

Hermes를 설치한 터미널에서 명령을 실행한 화면입니다. ‘hermes setup’을 실행한 뒤 ‘omen@LAPTOP-VMJ1…

빠른 설정 또는 모델 설정을 선택합니다.
More Provider / 사용자 지정 제공자를 선택합니다.
OpenAI Compatible 또는 사용자 지정 URL을 입력할 수 있는 프로토콜을 선택합니다.

Hermes 설정 터미널 화면으로 어두운 배경 위쪽에는 현재 hermes-chat 터미널 환경이 표시됩니다. 첫 줄에는 Teleg…

Hermes를 설치한 터미널의 제공자 선택 화면입니다. 위쪽에는 ‘Select provider:’가 표시되고 아래에는 Nous P…

Hermes를 설치한 터미널의 제공자 선택 화면입니다. 위쪽에는 ‘Select provider:’가 표시되고 아래에는 GitHub…

URL 입력 시 다음 주소를 우선 사용합니다.

https://api.llm-token.cn/v1

현재 버전에서 검증에 실패하면 다음 주소를 사용해 보십시오.

https://api.llm-token.cn

Hermes에서 Guishu Token 모델을 설정할 때의 사용자 지정 OpenAI 호환 인터페이스 화면입니다. 핵심 문구는 ‘C…

API Key를 붙여 넣습니다. 터미널에 일반 텍스트가 표시되지 않는 것은 정상이며, 붙여 넣은 뒤 바로 Enter를 누릅니다.
테스트용 모델로 먼저 claude-sonnet-4-6을 선택하는 것이 좋습니다.
컨텍스트 길이를 묻는 경우 claude-sonnet-4-6 사용 시 대규모 컨텍스트 값을 입력할 수 있습니다. 클라이언트 제한이 엄격하면 먼저 32000으로 정상화한 뒤 점차 늘리십시오.
첫 설정에서는 채팅 채널을 건너뛰고 터미널 채팅이 정상적으로 동작한 뒤 게이트웨이를 설정할 수 있습니다.

Hermes에 Guishu Token 모델을 설정한 뒤의 터미널 화면입니다. 위쪽에는 API base URL https://api…

Hermes 설정 완료 후 채팅으로 들어갈 때의 화면입니다. ‘Connect a messaging platform? (Telegr…

6. 채팅 및 게이트웨이 실행

설정이 완료되면 바로 채팅으로 들어갈 수 있습니다. 채팅을 시작할지 묻는 화면이 나타나면 Y를 입력합니다.

Hermes 배포 완료 후의 터미널 안내 화면입니다. 위쪽에는 ‘Ready to go!’가 표시되고 아래에는 채팅 시작용 ‘her…

메시지 채널을 설정했지만 반응하지 않으면 gateway를 실행하거나 상태를 확인합니다.

hermes gateway
hermes gateway status

7. 자주 사용하는 명령

명령	용도
`hermes`	채팅을 시작합니다.
`hermes setup`	전체 설정 마법사를 다시 엽니다.
`hermes model`	모델 또는 제공자를 전환합니다.
`hermes doctor`	종속성, 설정 및 서비스 상태를 진단합니다.
`hermes update`	Hermes를 업데이트합니다.
`hermes --continue`	이전 세션을 복원합니다.

8. 자주 발생하는 문제

문제	처리 방법
`hermes: command not found`	`source ~/.bashrc`를 실행하거나 터미널을 다시 엽니다. 그래도 해결되지 않으면 PATH를 확인하십시오.
모델 검증 실패	URL, API Key 및 모델 ID를 확인하고 `https://api.llm-token.cn/v1`을 우선 사용하십시오.
응답이 중단되거나 컨텍스트가 너무 작음	`hermes setup` 또는 설정 파일에서 context length를 조정하십시오. 먼저 정상적으로 실행한 뒤 컨텍스트를 늘립니다.
WSL2에서 Windows 로컬 서비스에 접근할 수 없음	Windows 11에서는 WSL mirrored networking을 사용해 보고, Windows 10에서는 localhost 대신 WSL 기본 게이트웨이 IP를 사용할 수 있습니다.
업데이트 후 설정이 사라짐	`hermes config check` 및 `hermes config migrate`를 실행합니다.

[wsl2]
networkingMode=mirrored

wsl --shutdown

Your privacy choices

Hermes 배포 가이드