매트릭스

anchor alias

매트릭스 설정

Hermes 에이전트는 오픈 소스 연합 메시징 프로토콜인 매트릭스와 통합됩니다. 매트릭스를 통해 자체 홈서버를 운영하거나 matrix.org와 같은 공용 서버를 사용할 수 있으며, 어느 쪽이든 커뮤니케이션을 스스로 제어할 수 있습니다. 봇은 mautrix Python SDK를 통해 연결되며, Hermes 에이전트 파이프라인(도구 사용, 메모리, 추론 포함)을 통해 메시지를 처리하고 실시간으로 응답합니다. 텍스트, 파일 첨부, 이미지, 오디오, 비디오 및 선택적 종단 간 암호화()를 지원합니다.

Hermes는 모든 매트릭스 홈서버와 호환됩니다 — Synapse, Conduit, Dendrite 또는 matrix.org.

설치 전에, 대부분의 사람들이 알고 싶어하는 부분은 다음과 같습니다: Hermes가 연결된 후 어떻게 작동하는지.

헤르메스의 행동 방식

문맥	행동
다이렉트 메시지(디엠)	Hermes는 모든 메시지에 응답합니다. `@mention`가 필요하지 않습니다. 각 DM에는 자체 세션이 있습니다. 봇이 DM에서 `@mentioned`일 때 스레드를 시작하려면 `MATRIX_DM_MENTION_THREADS=true`을 설정하세요.
객실	기본적으로 Hermes는 응답하기 위해 `@mention`이 필요합니다. 무료 응답 방의 경우 `MATRIX_REQUIRE_MENTION=false`을 설정하거나 `MATRIX_FREE_RESPONSE_ROOMS`에 방 ID를 추가하세요. 방 초대는 자동으로 수락됩니다.
쓰레드	Hermes는 Matrix 스레드(MSC3440)를 지원합니다. 스레드에 답장하면 Hermes는 메인 룸 타임라인과 스레드 컨텍스트를 분리하여 유지합니다. 봇이 이미 참여한 스레드에서는 언급이 필요하지 않습니다.
자동 스레딩	기본적으로, Hermes는 방에서 응답하는 각 메시지에 대해 자동으로 스레드를 생성합니다. 이는 대화를 분리된 상태로 유지합니다. 비활성화하려면 `MATRIX_AUTO_THREAD=false`을 설정하세요.
다중 사용자가 이용하는 공유 방	기본적으로 Hermes는 방 안에서 사용자별로 세션 기록을 분리합니다. 같은 방에서 대화하는 두 사람은 명시적으로 이를 비활성화하지 않는 한 하나의 기록을 공유하지 않습니다.

팁

봇은 초대받으면 자동으로 방에 참여합니다. 봇의 Matrix 사용자를 아무 방에나 초대하면 참여하여 응답을 시작합니다.

매트릭스의 세션 모델

기본적으로:

각 DM은 자체 세션을 갖습니다
각 스레드는 자체 세션 네임스페이스를 갖습니다
공유 방의 각 사용자는 해당 방 안에서 자신만의 세션을 갖습니다

이것은 config.yaml에 의해 제어됩니다:

group_sessions_per_user: true

전체 방에 대해 하나의 공유된 대화를 명시적으로 원할 경우에만 false으로 설정하세요:

group_sessions_per_user: false

공유 세션은 협업용 방에서 유용할 수 있지만, 동시에 다음을 의미하기도 합니다:

사용자들은 컨텍스트 성장과 토큰 비용을 공유합니다
한 사람의 길고 도구 중심적인 작업이 다른 사람들의 상황을 부풀릴 수 있다
한 사람의 비행 중 실행이 같은 방에서 다른 사람의 후속 작업을 방해할 수 있습니다

언급 및 스레딩 구성

환경 변수 또는 config.yaml를 통해 멘션 및 자동 스레딩 동작을 구성할 수 있습니다:

matrix:
  require_mention: true           # Require @mention in rooms (default: true)
  free_response_rooms:            # Rooms exempt from mention requirement
    - "!abc123:matrix.org"
  auto_thread: true               # Auto-create threads for responses (default: true)
  dm_mention_threads: false       # Create thread when @mentioned in DM (default: false)

또는 환경 변수를 통해:

MATRIX_REQUIRE_MENTION=true
MATRIX_FREE_RESPONSE_ROOMS=!abc123:matrix.org,!def456:matrix.org
MATRIX_AUTO_THREAD=true
MATRIX_DM_MENTION_THREADS=false
MATRIX_REACTIONS=true          # default: true — emoji reactions during processing

Disabling reactions

MATRIX_REACTIONS=false는 봇이 수신된 메시지에 게시하는 처리-라이프사이클 이모지 반응(👀/✅/❌)을 끕니다. 반응 이벤트가 시끄럽거나 모든 참여 클라이언트에서 지원되지 않는 채팅방에서 유용합니다.

노트

만약 이전 버전에서 MATRIX_REQUIRE_MENTION가 없었던 버전에서 업그레이드하는 경우, 봇은 이전에는 방의 모든 메시지에 응답했습니다. 해당 동작을 유지하려면 MATRIX_REQUIRE_MENTION=false을 설정하세요.

이 가이드는 봇 계정을 만드는 것부터 첫 번째 메시지를 보내는 것까지 전체 설정 과정을 안내합니다.

1단계: 봇 계정 만들기

봇을 사용하려면 Matrix 사용자 계정이 필요합니다. 이를 위한 여러 가지 방법이 있습니다:

옵션 A: 홈서버에 등록하기 (권장)

자신의 홈서버(Synapse, Conduit, Dendrite)를 운영하는 경우:

새 사용자를 만들려면 관리자 API 또는 등록 도구를 사용하세요:

# Synapse example
register_new_matrix_user -c /etc/synapse/homeserver.yaml http://localhost:8008

hermes 같은 사용자 이름을 선택하세요 — 전체 사용자 ID는 @hermes:your-server.org 입니다.

옵션 B: matrix.org 또는 다른 공개 홈서버 사용

Element Web로 이동하여 새 계정을 만드세요.
봇의 사용자 이름을 선택하세요 (예: hermes-bot)

옵션 C: 자신의 계정 사용

Hermes를 자신의 사용자로 실행할 수도 있습니다. 이는 봇이 당신으로서 게시한다는 것을 의미하며, 개인 비서용으로 유용합니다.

2단계: 액세스 토큰 받기

Hermes는 홈서버에 인증하기 위해 액세스 토큰이 필요합니다. 두 가지 옵션이 있습니다:

옵션 A: 액세스 토큰 (권장)

토큰을 얻는 가장 신뢰할 수 있는 방법:

비아 요소:

봇 계정으로 Element에 로그인하세요.
설정→도움말 및 정보로 이동하세요.
아래로 스크롤하고 고급을 확장하세요 — 액세스 토큰이 그곳에 표시됩니다.
즉시 복사하세요.

API를 통해:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '{
    "type": "m.login.password",
    "user": "@hermes:your-server.org",
    "password": "your-password"
  }'

응답에는 access_token 필드가 포함되어 있습니다 — 그것을 복사하세요.

Keep your access token safe

액세스 토큰은 봇의 Matrix 계정에 대한 전체 액세스를 제공합니다. 절대 공개적으로 공유하거나 Git에 커밋하지 마세요. 토큰이 유출된 경우, 해당 사용자의 모든 세션에서 로그아웃하여 토큰을 취소하세요.

액세스 토큰을 제공하는 대신, Hermes에 봇의 사용자 ID와 비밀번호를 줄 수 있습니다. Hermes는 시작 시 자동으로 로그인합니다. 이것이 더 간단하지만, 비밀번호가 .env 파일에 저장된다는 것을 의미합니다.

MATRIX_USER_ID=@hermes:your-server.org
MATRIX_PASSWORD=your-password

3단계: 매트릭스 사용자 ID 찾기

Hermes 에이전트는 Matrix 사용자 ID를 사용하여 누가 봇과 상호작용할 수 있는지 제어합니다. Matrix 사용자 ID는 @username:server 형식을 따릅니다.

당신의 것을 찾으려면:

Element (또는 선호하는 Matrix 클라이언트)를 엽니다.
아바타를 클릭 → 설정.
사용자 ID는 프로필 상단에 표시됩니다(예: @alice:matrix.org).

팁

Matrix 사용자 ID는 항상 @로 시작하며 서버 이름이 뒤따르는 :을 포함합니다. 예를 들어: @alice:matrix.org, @bob:your-server.com.

단계 4: Hermes 에이전트 구성

옵션 A: 인터랙티브 설정 (권장)

안내 설정 명령을 실행하세요:

hermes gateway setup

프롬프트가 표시되면 Matrix를 선택한 후, 요구 시 홈서버 URL, 액세스 토큰(또는 사용자 ID + 비밀번호), 허용된 사용자 ID를 입력하세요.

옵션 B: 수동 설정

다음 내용을 ~/.hermes/.env 파일에 추가하세요:

액세스 토큰 사용:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_ACCESS_TOKEN=***

# Optional: user ID (auto-detected from token if omitted)
# MATRIX_USER_ID=@hermes:matrix.example.org

# Security: restrict who can interact with the bot
MATRIX_ALLOWED_USERS=@alice:matrix.example.org

# Multiple allowed users (comma-separated)
# MATRIX_ALLOWED_USERS=@alice:matrix.example.org,@bob:matrix.example.org

비밀번호 로그인 사용:

# Required
MATRIX_HOMESERVER=https://matrix.example.org
MATRIX_USER_ID=@hermes:matrix.example.org
MATRIX_PASSWORD=***

# Security
MATRIX_ALLOWED_USERS=@alice:matrix.example.org
``~/.hermes/config.yaml`의 선택적 동작 설정:

```yaml
group_sessions_per_user: true

group_sessions_per_user: true는 각 참가자의 컨텍스트를 공유 방 안에서 격리시킵니다.

게이트웨이를 시작하세요

설정이 완료되면, 매트릭스 게이트웨이를 시작하세요:

hermes gateway

봇은 여러분의 홈서버에 연결되어 몇 초 내에 동기화를 시작해야 합니다. 테스트를 위해 메시지를 보내세요 — DM이든 봇이 참여한 방이든 상관없습니다.

팁

지속적인 운영을 위해 hermes gateway을 백그라운드에서 또는 systemd 서비스로 실행할 수 있습니다. 자세한 내용은 배포 문서를 참조하세요.

종단 간 암호화 ()

Hermes는 Matrix 종단간 암호화를 지원하므로 암호화된 방에서 봇과 채팅할 수 있습니다.

요구 사항

는 암호화 확장 기능이 있는 mautrix 라이브러리와 libolm C 라이브러리를 필요로 합니다:

# Install mautrix with  support
pip install 'mautrix[encryption]'

# Or install with hermes extras
pip install 'hermes-agent[matrix]'

시스템에 libolm도 설치되어 있어야 합니다:

# Debian/Ubuntu
sudo apt install libolm-dev

# macOS
brew install libolm

# Fedora
sudo dnf install libolm-devel

활성화

당신의 ~/.hermes/.env에 추가:

MATRIX_ENCRYPTION=true

가 활성화되면, Hermes:

암호화 키를 ~/.hermes/platforms/matrix/store/에 저장합니다(이전 설치: ~/.hermes/matrix/store/)
첫 연결 시 장치 키를 업로드합니다
들어오는 메시지를 자동으로 해독하고 나가는 메시지를 암호화합니다
초대받으면 암호화된 방에 자동으로 참여함

교차 서명 확인 (권장)

Matrix 계정에 교차 서명이 활성화되어 있는 경우(기본적으로 Element에서 활성화됨), 봇이 시작할 때 자신의 장치를 자체 서명할 수 있도록 복구 키를 설정하세요. 이를 설정하지 않으면, 장치 키가 교체된 후 다른 Matrix 클라이언트가 봇과 암호화 세션을 공유하지 않을 수 있습니다.

MATRIX_RECOVERY_KEY=EsT... your recovery key here

찾는 위치: Element에서 설정 → 보안 및 개인정보 → 암호화 → 복구 키(“보안 키”라고도 함)로 이동하세요. 이것이 바로 크로스-사인 설정을 처음 했을 때 저장하라고 요청받았던 키입니다.

매번 시작 시, MATRIX_RECOVERY_KEY가 설정되어 있으면, Hermes는 홈서버의 안전한 비밀 저장소에서 교차 서명 키를 가져와 현재 장치를 서명합니다. 이는 멱등이며 영구적으로 활성화된 상태로 두어도 안전합니다.

Deleting the crypto store

만약 ~/.hermes/platforms/matrix/store/crypto.db를 삭제하면, 봇은 자신의 암호화 신원(identity)을 잃게 됩니다. 동일한 장치 ID로 단순히 재시작하는 것만으로는 완전히 복구되지 않습니다 — 홈서버는 여전히 이전 신원 키로 서명된 일회용 키를 보유하고 있으며, 피어들은 새로운 Olm 세션을 설정할 수 없습니다.

Hermes는 시작 시 이 조건을 감지하고 활성화를 거부하며 다음과 같이 기록합니다: device XXXX has stale one-time keys on the server signed with a previous identity key.

가장 쉬운 복구: 새로운 액세스 토큰 생성 (이때 이전 키 기록이 없는 새로운 장치 ID가 발급됩니다). 아래의 '를 사용한 이전 버전에서 업그레이드' 섹션을 참조하세요. 이것이 가장 신뢰할 수 있는 방법이며 홈서버 데이터베이스를 건드리지 않습니다.

수동 복구 (고급 — 동일한 장치 ID 유지):

Synapse를 중지하고 구형 장치를 데이터베이스에서 삭제하세요:

sudo systemctl stop matrix-synapse
sudo sqlite3 /var/lib/matrix-synapse/homeserver.db "
  DELETE FROM e2e_device_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
  DELETE FROM e2e_one_time_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
  DELETE FROM e2e_fallback_keys_json WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
  DELETE FROM devices WHERE device_id = 'DEVICE_ID' AND user_id = '@hermes:your-server';
"
sudo systemctl start matrix-synapse

또는 Synapse 관리자 API를 통해서도 가능합니다(URL로 인코딩된 사용자 ID에 주의하세요):

curl -X DELETE -H "Authorization: Bearer ADMIN_TOKEN" \
  'https://your-server/_synapse/admin/v2/users/%40hermes%3Ayour-server/devices/DEVICE_ID'

참고: 관리 API를 통해 장치를 삭제하면 관련 액세스 토큰도 무효화될 수 있습니다. 이후에 새 토큰을 생성해야 할 수도 있습니다.

로컬 암호 저장소를 삭제하고 Hermes를 재시작하세요:
```
rm -f ~/.hermes/platforms/matrix/store/crypto.db*
# restart hermes
```

다른 Matrix 클라이언트(Element, matrix-commander)는 이전 장치 키를 캐시할 수 있습니다. 복구 후, Element에서 /discardsession를 입력하여 봇과 새로운 암호화 세션을 강제로 시작하세요.

정보

만약 mautrix[encryption]가 설치되어 있지 않거나 libolm이 없으면, 봇은 자동으로 일반(암호화되지 않은) 클라이언트로 돌아갑니다. 로그에서 경고를 보게 될 것입니다.

홈룸

봇이 사전 알림 메시지(예: 크론 작업 출력, 알림 및 공지)를 보내는 '홈 룸'을 지정할 수 있습니다. 설정하는 방법은 두 가지가 있습니다:

슬래시 명령어 사용하기

봇이 있는 어떤 Matrix 방에서든 /sethome를 입력하세요. 그 방이 홈 룸이 됩니다.

수동 설정

이것을 당신의 ~/.hermes/.env에 추가하세요:

MATRIX_HOME_ROOM=!abc123def456:matrix.example.org

팁

룸 ID를 찾으려면: Element에서 해당 방으로 이동 → 설정 → 고급 → 내부 룸 ID가 거기에 표시됩니다 (_!으로 시작).

문제 해결

봇이 메시지에 응답하지 않습니다

원인: 봇이 방에 참여하지 않았거나 MATRIX_ALLOWED_USERS에 사용자의 ID가 포함되어 있지 않습니다.

수정: 봇을 방에 초대하세요 — 초대하면 자동으로 참여합니다. 사용자 ID가 MATRIX_ALLOWED_USERS에 있는지 확인하세요 (@user:server 형식을 전체로 사용). 게이트웨이를 재시작하세요.

시작 시 '인증 실패' / 'whoami 실패'

원인: 액세스 토큰 또는 홈서버 URL이 올바르지 않습니다.

수정: MATRIX_HOMESERVER이 홈서버를 가리키는지 확인하세요 (https:// 포함, 마지막에 슬래시 없음). MATRIX_ACCESS_TOKEN가 유효한지 확인 — curl로 시도해보세요:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-server/_matrix/client/v3/account/whoami

이것이 사용자 정보를 반환하면 토큰이 유효한 것입니다. 오류가 반환되면 새 토큰을 생성하세요.

"mautrix가 설치되지 않음" 오류

원인: mautrix Python 패키지가 설치되어 있지 않습니다.

수정: 설치하세요:

pip install 'mautrix[encryption]'

또는 Hermes 추가 기능과 함께:

pip install 'hermes-agent[matrix]'

암호화 오류 / '이벤트를 복호화할 수 없음'

원인: 암호화 키 누락, libolm 미설치, 또는 봇의 기기가 신뢰되지 않음.

수정:

시스템에 libolm가 설치되어 있는지 확인하세요(위의 섹션 참조).
.env에서 MATRIX_ENCRYPTION=true가 설정되어 있는지 확인하세요.
Matrix 클라이언트(Element)에서 봇의 프로필 -> 세션 -> 봇의 기기를 확인/신뢰하세요.
만약 봇이 방금 암호화된 방에 참여했다면, 봇은 참여 이후에 보내진 메시지만 해독할 수 있습니다. 이전 메시지는 접근할 수 없습니다.

이전 버전에서 와 함께 업그레이드하기

팁

만약 당신이 crypto.db를 수동으로 삭제했다면, 위의 섹션에 있는 '암호화 저장소 삭제' 경고를 참고하세요 — 홈서버에서 오래된 일회용 키를 제거하기 위한 추가 단계가 있습니다.

이전에 MATRIX_ENCRYPTION=true와 함께 Hermes를 사용했고 업그레이드하려는 경우 새로운 SQLite 기반 암호화 저장소를 사용하는 버전, 봇의 암호화 신원이 변경되었습니다. 사용 중인 Matrix 클라이언트(Element)가 이전 장치 키를 캐시하고 있을 수 있습니다. 그리고 암호화 세션을 봇과 공유하는 것을 거부하십시오.

증상: 봇이 연결되며 로그에 ' 활성화'가 표시되지만, 모든 메시지에 '이벤트를 복호화할 수 없음'이 표시되고 봇이 전혀 응답하지 않습니다.

무슨 일이 일어나고 있는지: 이전 matrix-nio 또는에서의 이전 암호화 상태 직렬화 기반 mautrix 백엔드는 새로운 SQLite 암호화와 호환되지 않습니다 상점. 봇은 새로운 암호화 ID를 생성하지만, 당신의 매트릭스 클라이언트는 여전히 이전 키가 캐시되어 있으며 방의 암호화 세션을 공유하지 않습니다. 키가 바뀐 장치입니다. 이것은 매트릭스 보안 기능입니다 -- 클라이언트는 같은 장치에 대해 신원 키가 의심스럽게 변경되었습니다.

수정 (일회성 이전):

새 액세스 토큰 생성하여 새로운 기기 ID를 얻으세요. 가장 간단한 방법:

curl -X POST https://your-server/_matrix/client/v3/login \
  -H "Content-Type: application/json" \
  -d '&#123;
    "type": "m.login.password",
    "identifier": &#123;"type": "m.id.user", "user": "@hermes:your-server.org"&#125;,
    "password": "***",
    "initial_device_display_name": "Hermes Agent"
  &#125;'

새로운 access_token을 복사하고 ~/.hermes/.env에서 MATRIX_ACCESS_TOKEN을 업데이트하세요.

이전 암호화 상태 삭제:

rm -f ~/.hermes/platforms/matrix/store/crypto.db
rm -f ~/.hermes/platforms/matrix/store/crypto_store.*

복구 키 설정 (크로스사인을 사용하는 경우 — 대부분의 Element 사용자가 해당). ~/.hermes/.env에 추가:
```
MATRIX_RECOVERY_KEY=EsT... your recovery key here
```

이는 봇이 시작 시 크로스 사인 키로 스스로 서명할 수 있게 하여 Element가 새 장치를 즉시 신뢰하게 합니다. 이것이 없으면 Element는 새 장치를 검증되지 않은 것으로 보고 암호화 세션 공유를 거부할 수 있습니다. Element에서 설정 → 보안 및 개인 정보 → 암호화에서 복구 키를 찾으세요.

Matrix 클라이언트가 암호화 세션을 강제로 회전하도록 하세요. Element에서, 봇과 DM 방을 열고 /discardsession을 입력하세요. 이것은 Element를 강제로 실행합니다 새 암호화 세션을 생성하고 이를 봇의 새 장치와 공유합니다.

게이트웨이 재시작:

hermes gateway run
``MATRIX_RECOVERY_KEY`이 설정되어 있으면 로그에서 `Matrix: cross-signing verified via recovery key`을 볼 수 있어야 합니다.

새 메시지 보내기. 봇은 평소처럼 해독하고 응답해야 합니다.

노트

업그레이드 이전에 보낸 메시지는 마이그레이션 후에 복호화할 수 없습니다 -- 이전 암호화 키가 사라졌습니다. 이것은 전환에만 영향을 미치며 새로운 메시지는 작동합니다. 보통.

팁

새로운 설치에는 영향을 미치지 않습니다. 이 마이그레이션은 이전에 설치한 경우에만 필요합니다. 이전 버전의 Hermes로 작동하는 설정을 가지고 있으며 업그레이드 중입니다.

왜 새 액세스 토큰이 필요한가요? 각 매트릭스 액세스 토큰은 특정 기기에 연결되어 있습니다 ID. 새로운 암호화 키로 동일한 장치 ID를 재사용하면 다른 매트릭스가 발생합니다 클라이언트가 장치를 신뢰하지 않게 함(그들은 변경된 신원 키를 잠재적인 것으로 봄) 보안 침해). 새로운 액세스 토큰은 오래된 키 없이 새로운 장치 ID를 받습니다 역사가 있어 다른 고객들이 즉시 신뢰합니다.

프록시 모드 (macOS에서 )

Matrix 는 macOS ARM64(Apple Silicon)에서 컴파일되지 않는 libolm를 필요로 합니다. hermes-agent[matrix] 추가 기능은 Linux에서만 사용 가능합니다. macOS를 사용하는 경우, 프록시 모드를 이용하면 실제 에이전트는 macOS에서 로컬 파일, 메모리, 스킬에 완전히 접근하면서 실행되는 동안 Docker 컨테이너 내 Linux VM에서 를 실행할 수 있습니다.

작동 원리

macOS (Host):
  └─ hermes gateway
       ├─ api_server adapter ← listens on 0.0.0.0:8642
       ├─ AIAgent ← single source of truth
       ├─ Sessions, memory, skills
       └─ Local file access (Obsidian, projects, etc.)

Linux VM (Docker):
  └─ hermes gateway (proxy mode)
       ├─ Matrix adapter ←  decryption/encryption
       └─ HTTP forward → macOS:8642/v1/chat/completions
           (no LLM API keys, no agent, no inference)

Docker 컨테이너는 Matrix 프로토콜과 만 처리합니다. 메시지가 도착하면 이를 복호화하고 표준 HTTP 요청을 통해 호스트로 텍스트를 전달합니다. 호스트는 에이전트를 실행하고, 도구를 호출하며, 응답을 생성하고 이를 스트리밍 방식으로 다시 보냅니다. 컨테이너는 응답을 암호화하여 Matrix로 전송합니다. 모든 세션은 통합되어 있으며 — CLI, Matrix, Telegram, 그리고 다른 어떤 플랫폼도 동일한 메모리와 대화 기록을 공유합니다.

1단계: 호스트(macOS) 구성

API 서버를 활성화하여 호스트가 Docker 컨테이너로부터 들어오는 요청을 수락하도록 합니다.

~/.hermes/.env에 추가:

API_SERVER_ENABLED=true
API_SERVER_KEY=your-secret-key-here
API_SERVER_HOST=0.0.0.0

API_SERVER_HOST=0.0.0.0는 모든 인터페이스에 바인딩되어 Docker 컨테이너가 그것에 접근할 수 있습니다.
API_SERVER_KEY는 비-루프백 바인딩에 필요합니다. 강력한 임의 문자열을 선택하세요.
API 서버는 기본적으로 포트 8642에서 실행됩니다(필요하면 API_SERVER_PORT으로 변경).

게이트웨이를 시작하세요:

hermes gateway

설정한 다른 플랫폼과 함께 API 서버가 시작되는 것을 확인해야 합니다. VM에서 접근 가능한지 확인하세요:

# From the Linux VM
curl http://<mac-ip>:8642/health

단계 2: Docker 컨테이너(Linux VM) 구성

컨테이너에는 Matrix 자격 증명과 프록시 URL이 필요합니다. LLM API 키는 필요하지 않습니다.

docker-compose.yml:

services:
  hermes-matrix:
    build:.
    environment:
      # Matrix credentials
      MATRIX_HOMESERVER: "https://matrix.example.org"
      MATRIX_ACCESS_TOKEN: "syt_..."
      MATRIX_ALLOWED_USERS: "@you:matrix.example.org"
      MATRIX_ENCRYPTION: "true"
      MATRIX_DEVICE_ID: "HERMES_BOT"

      # Proxy mode — forward to host agent
      GATEWAY_PROXY_URL: "http://192.168.1.100:8642"
      GATEWAY_PROXY_KEY: "your-secret-key-here"
    volumes:
      -./matrix-store:/root/.hermes/platforms/matrix/store

Dockerfile:

FROM python:3.11-slim

RUN apt-get update && apt-get install -y libolm-dev && rm -rf /var/lib/apt/lists/*
RUN pip install 'hermes-agent[matrix]'

CMD ["hermes", "gateway"]

그것이 전체 컨테이너입니다. OpenRouter, Anthropic 또는 어떤 추론 제공업체의 API 키도 없습니다.

3단계: 둘 다 시작

먼저 호스트 게이트웨이를 시작하세요:
```
hermes gateway
```
Docker 컨테이너를 시작하세요:
```
docker compose up -d
```
암호화된 Matrix 방에 메시지를 보내세요. 컨테이너가 이를 복호화하고 호스트로 전달한 다음, 응답을 다시 스트리밍합니다.

구성 참조

프록시 모드는 컨테이너 측(thin 게이트웨이)에서 구성됩니다:

설정	설명
`GATEWAY_PROXY_URL`	원격 Hermes API 서버의 URL (예: `http://192.168.1.100:8642`)
`GATEWAY_PROXY_KEY`	인증을 위한 베어러 토큰 (호스트의 `API_SERVER_KEY`와 일치해야 함)
`gateway.proxy_url`	`GATEWAY_PROXY_URL`와 동일하지만 `config.yaml`에서

호스트 측에서는 필요합니다:

설정	설명
`API_SERVER_ENABLED`	`true`로 설정
`API_SERVER_KEY`	컨테이너와 공유되는 베어러 토큰
`API_SERVER_HOST`	네트워크 접근을 위해 `0.0.0.0`로 설정
`API_SERVER_PORT`	포트 번호 (기본값: `8642`)

모든 플랫폼에서 작동

프록시 모드는 매트릭스에 국한되지 않습니다. 어떤 플랫폼 어댑터도 이를 사용할 수 있습니다 — 어떤 게이트웨이 인스턴스에서든 GATEWAY_PROXY_URL를 설정하면 로컬에서 실행하는 대신 원격 에이전트로 전달됩니다. 이는 플랫폼 어댑터가 에이전트와 다른 환경에서 실행되어야 하는 배포(네트워크 격리, 종단 간 암호화 요구 사항, 자원 제약)에 유용합니다.

팁

세션 연속성은 X-Hermes-Session-Id 헤더를 통해 유지됩니다. 호스트의 API 서버는 이 ID로 세션을 추적하므로, 대화는 로컬 에이전트와 마찬가지로 메시지 간에 지속됩니다.

노트

제한 사항 (v1): 원격 에이전트의 도구 진행 메시지는 전달되지 않으며 — 사용자는 개별 도구 호출이 아니라 스트리밍된 최종 응답만 보게 됩니다. 위험한 명령 승인 프롬프트는 Matrix 사용자에게 전달되지 않고 호스트 측에서 처리됩니다. 이는 향후 업데이트에서 해결될 수 있습니다.

동기화 문제 / 봇 지연

원인: 장시간 실행되는 도구 때문에 동기화 루프가 지연되거나, 홈 서버가 느릴 수 있습니다.

수정: 동기화 루프는 오류 발생 시 5초마다 자동으로 재시도합니다. 동기화 관련 경고는 Hermes 로그를 확인하세요. 봇이 지속적으로 뒤처지는 경우, 홈서버에 충분한 리소스가 있는지 확인하세요.

봇이 오프라인입니다

원인: Hermes 게이트웨이가 실행되지 않거나 연결에 실패했습니다.

수정: hermes gateway이 실행 중인지 확인하세요. 터미널 출력에서 오류 메시지를 확인하세요. 일반적인 문제: 잘못된 홈서버 URL, 만료된 액세스 토큰, 홈서버에 접근 불가.

"사용자 허용 안 됨" / 봇이 무시함

원인: 사용자의 ID가 MATRIX_ALLOWED_USERS에 없습니다.

수정: ~/.hermes/.env에서 MATRIX_ALLOWED_USERS에 사용자 ID를 추가하고 게이트웨이를 재시작하세요. 전체 @user:server 형식을 사용하세요.

보안

{#failed-to-authenticate--whoami-failed-on-startup}

항상 MATRIX_ALLOWED_USERS를 설정하여 누가 봇과 상호작용할 수 있는지 제한하세요. 이를 설정하지 않으면, 안전 조치로 게이트웨이는 기본적으로 모든 사용자를 거부합니다. 신뢰하는 사람들의 사용자 ID만 추가하세요 — 인증된 사용자는 도구 사용 및 시스템 접근을 포함한 에이전트의 모든 기능에 완전히 접근할 수 있습니다.

Hermes 에이전트 배포 보안을 위한 자세한 내용은 보안 가이드를 참조하세요.

노트

모든 홈서버: Synapse, Conduit, Dendrite, matrix.org 또는 사양을 준수하는 모든 Matrix 홈서버와 작동합니다. 특정 홈서버 소프트웨어가 필요하지 않습니다.
연합: 연합 홈서버를 사용 중인 경우, 봇이 다른 서버의 사용자와 소통할 수 있습니다 — 단지 그들의 전체 @user:server ID를 MATRIX_ALLOWED_USERS에 추가하면 됩니다.
자동 참여: 봇이 방 초대를 자동으로 수락하고 참여합니다. 참여 후 즉시 응답하기 시작합니다.
미디어 지원: Hermes는 이미지, 오디오, 비디오, 파일 첨부를 보내고 받을 수 있습니다. 미디어는 Matrix 콘텐츠 저장소 API를 사용하여 사용자의 홈서버에 업로드됩니다.
네이티브 음성 메시지 (MSC3245): 매트릭스 어댑터는 발신 음성 메시지에 org.matrix.msc3245.voice 플래그를 자동으로 태그합니다. 이는 TTS 응답과 음성 오디오가, 일반적인 오디오 파일 첨부가 아니라, Element 및 MSC3245를 지원하는 다른 클라이언트에서 네이티브 음성 버블로 렌더링됨을 의미합니다. MSC3245 플래그가 붙은 수신 음성 메시지도 올바르게 식별되어 음성-텍스트 전사로 라우팅됩니다. 설정은 필요 없으며, 이 기능은 자동으로 작동합니다.

anchor alias​

매트릭스 설정

헤르메스의 행동 방식​

매트릭스의 세션 모델​

언급 및 스레딩 구성​

1단계: 봇 계정 만들기​

옵션 A: 홈서버에 등록하기 (권장)​

옵션 B: matrix.org 또는 다른 공개 홈서버 사용​

옵션 C: 자신의 계정 사용​

2단계: 액세스 토큰 받기​

옵션 A: 액세스 토큰 (권장)​

옵션 B: 비밀번호 로그인​

3단계: 매트릭스 사용자 ID 찾기​

단계 4: Hermes 에이전트 구성​

옵션 A: 인터랙티브 설정 (권장)​

옵션 B: 수동 설정​

게이트웨이를 시작하세요​

종단 간 암호화 ()​

요구 사항​

활성화​

교차 서명 확인 (권장)​

홈룸​

슬래시 명령어 사용하기​

수동 설정​

문제 해결​

봇이 메시지에 응답하지 않습니다​

시작 시 '인증 실패' / 'whoami 실패'​

"mautrix가 설치되지 않음" 오류​

암호화 오류 / '이벤트를 복호화할 수 없음'​

이전 버전에서 와 함께 업그레이드하기​

프록시 모드 (macOS에서 )​

작동 원리​

1단계: 호스트(macOS) 구성​

단계 2: Docker 컨테이너(Linux VM) 구성​

3단계: 둘 다 시작​

구성 참조​

모든 플랫폼에서 작동​

동기화 문제 / 봇 지연​

봇이 오프라인입니다​

"사용자 허용 안 됨" / 봇이 무시함​

보안​

노트​