설치와 첫 실행

서명 경고 통과하기

설치 파일에 서명이 없어 세 플랫폼 모두 한 번씩 막습니다.

macOS

Gatekeeper가 더블클릭 실행을 거부합니다. 압축을 푼 뒤 둘 중 하나:

우클릭 → 열기, 나오는 대화상자에서 다시 「열기」. 한 번만 하면 됩니다.
또는 터미널에서 격리 속성 제거:
Terminal window
```
xattr -cr "OpenMMO Agent.app"
```

Windows

SmartScreen이 「PC를 보호했습니다」를 띄웁니다. 추가 정보 → 실행을 누르세요.

Linux

AppImage에 실행 권한을 직접 줘야 합니다:

chmod +x openmmo-agent-linux-x64.AppImage
./openmmo-agent-linux-x64.AppImage

첫 실행 흐름

화면 네 개를 순서대로 지나면 바로 게임입니다. 별도의 「플레이 시작」 버튼은 없습니다 — 캐릭터를 고르면 곧바로 입장합니다.

1. Server — 접속 프로필 선택

기본 제공되는 openmmo.to.nexus 프로필은 고정이며, 일반 플레이어는 이걸 그대로 쓰면 됩니다.

프로필 하나가 세 가지를 함께 묶습니다: 서버 주소, 지형 리소스 출처, Google client ID/secret. 서버마다 자기 허용 목록에 있는 client ID로 발급된 로그인 토큰만 받기 때문에 이 셋은 한 세트여야 합니다. 직접 운영하는 서버에 붙으려면 프로필을 새로 만들고, 사용 전에 연결 테스트를 할 수 있습니다.

버튼을 누르면 코드가 표시되고, 브라우저에서 입력하면 됩니다. 이전에 로그인한 적이 있으면 다음 단계로 바로 넘어갑니다.

3. Character — 캐릭터 선택 또는 생성

탭 두 개:

캐릭터 선택 — 계정당 최대 3개(서버 강제). 클릭하면 바로 입장, 삭제도 가능.
새 캐릭터 만들기 — 이름, 클래스, 성별. 최대치에 도달하면 이 탭은 숨겨집니다.

4. Game — 게임 시작

입장할 때 모드가 자동으로 결정됩니다: LLM 백엔드가 설정되어 있고 검증을 통과하면 자동 모드, 아니면 수동 모드. 자동 모드 시작에 실패해도 수동으로 넘어갑니다. 이후 헤더에서 언제든 전환할 수 있습니다.

두 가지 플레이 모드

서버는 캐릭터당 조종 세션을 하나만 허용하므로 두 모드의 구현이 다릅니다.

수동 모드는 직접 연결입니다 — 내장된 OpenMMO 웹 클라이언트가 당신의 Google 계정으로 로그인해 서버와 바로 통신합니다. 브라우저로 하는 것과 완전히 같습니다. 중계도, agent-client도 없습니다.

자동 모드는 agent-client를 띄우는데, 이쪽이 그 하나뿐인 세션을 독점합니다 — 그래서 「옆에서 지켜보기」를 또 하나의 접속으로 할 수 없습니다. 대신 로컬에 중계를 둡니다:

agent-client <--ws--> proxy (127.0.0.1) <--wss--> openmmo.to.nexus
                        |
                        +--> 관전 (/mirror)

서버는 에이전트 뒤에 뭔가 있다는 걸 전혀 알지 못합니다. 중간에 있으므로 서버 메시지를 하나하나 읽기 전용 관전 화면에 복제할 수 있습니다. 중계는 127.0.0.1에만 바인딩되므로 어떤 데이터도 당신의 PC를 떠나지 않습니다.

게임 화면

헤더에는 접속 상태, 체력과 상태, 관전 메모리 사용량, 3D 화면 새로고침 버튼, 수동/AI 모드 전환, 캐릭터·서버 변경 버튼이 있습니다. 실행 중에 설정을 바꾸면 Apply & restart 버튼이 추가로 나타납니다.

왼쪽 레일에서 서랍 여섯 개를 열 수 있습니다:

서랍	내용
Equipment	착용 중인 장비, 슬롯별 표시
Bag	소지품. 에이전트가 팔거나 버려도 되는 물건을 표시할 수 있음
Personality & Memory	이 캐릭터 전용 프롬프트(편집 가능)와 에이전트가 직접 쓴 기억(읽기 전용)
Coordinates	장소 북마크. 현재 위치를 바로 저장 가능
Dispatch Presets	자주 쓰는 지시를 버튼으로 저장
Activity	탭 두 개: Thoughts(주고받은 프롬프트)와 Log(에이전트 프로세스 출력)

서랍별 자세한 사용법은 패널 기능 상세를 보세요.

게임 화면 아래의 Dispatch는 실행 중인 에이전트에게 말을 거는 유일한 통로입니다. 한 줄 지시를 입력하면 캐릭터의 다음 턴에 참고됩니다 — 최선을 다할 뿐, 그대로 한다는 보장은 없습니다.

키는 어디에 저장되나

API 키와 접속 프로필의 비밀값은 운영체제 키체인으로 암호화되고 (Electron safeStorage, 실패 시 AES-GCM으로 대체), 환경 변수로 에이전트에 전달됩니다 — config.toml에 기록되지 않습니다. 그래서 설정 파일을 버그 리포트에 붙여넣어도 자격 증명이 새지 않습니다.

문제 해결

프로토콜 버전 불일치 표시 — 서버가 업데이트된 것입니다. 다운로드 페이지에서 새 버전을 받으세요.

설정을 바꿨는데 반영되지 않음 — 에이전트는 시작할 때 설정을 한 번만 읽습니다. 헤더의 Apply & restart를 누르세요.

VS Code 터미널에서 실행하면 뜨지 않음 — VS Code 자체가 Electron 앱이라 ELECTRON_RUN_AS_NODE=1이 새어 나가 클라이언트가 순수 Node로 시작됩니다:

env -u ELECTRON_RUN_AS_NODE npm start

관전 화면에 뭔가 없거나 멈춰 보임 — 자동 모드의 관전 화면은 스냅샷에서 시작하므로, 에이전트가 알고는 있지만 지금 추적하지 않는 것은 시야에 다시 들어올 때 나타납니다.