> ## Documentation Index
> Fetch the complete documentation index at: https://docs.archetype.ing/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> 앱이나 CLI가 호스트에 닿지 않을 때, 로그인이 만료됐을 때, MCP 서버가 실패할 때, 플러그인이 꺼져 있거나 알림이 오지 않을 때.

먼저 이것부터 봅니다.

```bash theme={null}
archetype --doctor          # 설정, 모델, 키, 기록을 모델 호출 없이 점검
archetype daemon status     # 폴더마다 백그라운드 서비스가 도는지
archetype --version
```

## 앱이 호스트에 닿지 않을 때

데스크톱 앱은 자기 호스트를 띄웁니다. 준비된 뒤에 호스트가 멈추면 앱이 5분에 세 번까지 다시 띄웁니다. 시작하다가 멈추면 이유와 함께 **다시 시도**와 **로그 보기**가 나옵니다.

* 직접 다시 띄우려면 **파일 → Archetype 다시 시작**을 누릅니다.
* \*\*호스트가 다시 시작됐어요. Archetype을 다시 열면 연결돼요.\*\*가 보이면 앱을 닫았다가 다시 엽니다.
* **서버의 호스트:** 앱은 시스템의 `ssh`로 연결하므로, 터미널에서 비밀번호를 묻지 않고 `ssh`가 되어야 합니다. **다시 연결**(**파일**, 또는 **관리 → 설정 → 서버**)을 누릅니다. 서버가 더 오래된 버전이면 **업데이트 후 다시 연결**이 나옵니다. 그래도 안 되면 **이 컴퓨터 쓰기**로 이 컴퓨터의 호스트를 엽니다.
* **휴대폰:** 컴퓨터에 **연결할 수 없어요**라고 나오면 컴퓨터가 켜져 있고 앱이나 호스트가 도는지 확인합니다. 포트가 이미 쓰이고 있다고 나오면 설정 파일의 `phones.port`를 다른 값으로 바꿉니다. [기기](https://docs.archetype.ing/ko/use/devices.md) 참고.

## 채팅, 예약, 트리거에 답이 없을 때

이것들은 앱을 닫아도 백그라운드 서비스가 돌립니다.

```bash theme={null}
archetype daemon status                # 돌고 있을 때만 0으로 끝남
archetype daemon logs -n 100 --follow  # 서비스 로그
archetype daemon restart               # 지금 설정으로 다시 시작
archetype daemon install               # 없으면 다시 설치
```

앱에 \*\*백그라운드 서비스가 설치됐지만 실행 중이 아니라서 채팅에 답하지 않아요.\*\*가 보이면 **다시 시작**을 누릅니다.

서비스는 셸의 환경 변수를 받지 못합니다. 키와 토큰은 `~/.config/archetype/env`에 한 줄에 하나씩 `NAME=value`로 두고, 나만 읽게 합니다(`chmod 600`). 다른 사람이 읽을 수 있으면 서비스가 시작을 거부합니다.

## 로그인이 만료됐을 때

| 어디 | 보이는 것 | 할 일 |
| - | - | - |
| 모델이나 엔진 | **로그인 시간이 지났어요. 다시 로그인해 주세요.** | 안내하는 곳에서 다시 로그인합니다. [엔진](https://docs.archetype.ing/ko/use/engines.md) 참고. |
| 팀 | **열려면 …에 로그인해 주세요** | 사이드바에서 그 회사에 로그인합니다. |
| 앱(Gmail, Notion, Linear…) | **다시 연결 필요** | **관리 → 연결 → 앱**에서 다시 연결합니다. |
| 메신저 계정 | **다시 연결** | 그 계정에서 누릅니다. [계정](https://docs.archetype.ing/ko/use/accounts.md) 참고. |

## MCP 서버가 실패할 때

```bash theme={null}
archetype mcp list          # 서버 목록, 플러그인의 서버 포함
archetype mcp check NAME    # 띄워 보고 도구 목록 보기
archetype mcp login NAME    # 로그인이 필요한 서버에 로그인
```

어느 턴에서 닿지 않는 서버는 그 턴에서만 빠지고 나머지는 계속합니다. `"disabled": true`인 서버는 돌지 않습니다. [MCP 서버](https://docs.archetype.ing/ko/extend/mcp.md) 참고.

## 플러그인이 꺼져 있거나 보이지 않을 때

* **관리 → 플러그인**을 확인합니다. **보낼 것**과 **식사**는 직접 켜기 전에는 꺼져 있습니다.
* `~/.config/archetype/config.json`에서 끈 플러그인(`"plugins": { "이름": false }`)은 꺼진 채로 있습니다.
* 회사 호스트에서는 관리자가 어느 역할이 플러그인을 보고 도구를 쓸지 정합니다. 내 역할에 없으면 관리자에게 묻습니다. [회사 호스팅](https://docs.archetype.ing/ko/teams/hosting.md) 참고.
* **음악**은 Mac에서만 동작하고, macOS가 Archetype의 앱 조작을 허용해야 합니다. [음악](https://docs.archetype.ing/ko/plugins/music.md) 참고.

## 알림이 오지 않을 때

* **관리 → 내 설정 → 알림 설정**을 엽니다. 기기마다 알림을 받는지 보이고, **시스템 설정에서 꺼짐**, **이 브라우저에서 꺼짐**, **브라우저가 막음**, **닿지 않음**이 이유를 알려 줍니다.
* 시스템 설정에서 Archetype의 알림을 켠 뒤 다시 확인합니다.
* **방해 금지 시간**에는 알림을 미루고, **알림 끈 세션**은 알리지 않습니다.
* 그 대화가 앞에 있는 창에 열려 있으면 알림을 띄우지 않습니다.
* 팀의 멘션, 답글, 결정 알림은 그 팀의 설정을 따릅니다.

## 로그 위치

| 무엇 | 어디 |
| - | - |
| 데스크톱 앱의 호스트 | **도움말 → 로그 보기**, 또는 **도움말 → 로그 폴더 보기** |
| 백그라운드 서비스 | `archetype daemon logs`, 또는 폴더 기록의 `daemon/daemon.log` |
| 직접 운영하는 회사 호스트 | `docker compose logs -f archetype` |

로그에는 접속 토큰이 빠져 있습니다. 보내기 전에 개인적인 내용이 없는지 한 번 봅니다.

## 문제 알리기

[help@archetype.ing](mailto:help@archetype.ing)로 다음을 보냅니다.

* 무엇을 했고, 무엇을 기대했고, 무슨 일이 있었는지
* 컴퓨터와 시스템, `archetype --version`
* `archetype --doctor` 출력, 그리고 문제 앞뒤의 로그 줄
* 연결한 앱이나 플러그인이라면 그 이름


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.