일반 연결 안내는 https://norang.inlevel9.com/guide.md 를 따른다. 아래는 개발자용 선택 경로다.

# 개발자 앱을 직접 연동하는 경우

사용자가 직접 해야 하는 단계와 에이전트가 대신 할 수 있는 단계를 구분해 안내한다. 카카오 디벨로퍼스 콘솔 조작과 카카오 로그인은 사용자 본인이 한다. 앱 키나 비밀번호를 대화창에 붙여 넣으라고 요청하지 않는다.

먼저 `auth_status`(또는 `norang doctor`)로 현재 상태를 확인하고, 이미 끝난 단계는 건너뛴다.

## 1. 본인 앱 만들기 (사용자)

이 절차는 카카오 개발자 앱을 직접 관리하는 사용자를 위한 선택 경로다. 일반 사용자에게 앱을 만들게 할 필요는 없다. 앱 키·토큰 공유 금지 규정만으로 모든 사용자가 각자 앱을 만들어야 한다고 해석하지 않는다.

1. https://developers.kakao.com 에 카카오계정으로 로그인하고 앱을 하나 만든다.
2. 앱의 **REST API 키**를 확인한다.
3. **카카오 로그인**을 사용하도록 켠다.
4. **앱 > 플랫폼 키 > REST API 키**를 열어 "카카오 로그인 리다이렉트 URI"에 `http://localhost:8791/callback` 을 등록한다. 포트를 바꿨다면 `auth_status`가 보여 주는 값을 그대로 쓴다. 같은 화면의 클라이언트 시크릿은 새 키에서 기본으로 켜져 있으므로, 켜 둔 채 쓰려면 그 코드를 2단계에서 함께 등록해야 한다.
5. **카카오 로그인 > 동의항목**의 접근권한에서 "카카오톡 메시지 전송"(`talk_message`)은 선택 동의로, "톡캘린더 및 일정 생성, 조회, 편집/삭제"(`talk_calendar`)는 이용 중 동의로 설정한다. 톡캘린더의 선택 동의는 API 검수를 받은 앱만 고를 수 있다. 각 항목에 동의 목적을 실제 용도대로 적어야 한다.
6. 나에게 보내기 메시지의 링크를 쓰려면 **앱 > 제품 링크 관리**의 웹 도메인에 그 사이트 도메인을 등록한다.

콘솔 메뉴 이름은 바뀔 수 있다. 위치를 못 찾으면 공식 문서를 안내한다.

- 카카오 로그인 설정: https://developers.kakao.com/docs/ko/kakaologin/prerequisite
- 카카오톡 메시지: https://developers.kakao.com/docs/ko/kakaotalk-message/common
- 톡캘린더: https://developers.kakao.com/docs/ko/talkcalendar/common

톡캘린더 API는 사용 권한을 받지 않은 앱에서는 앱 멤버만 호출할 수 있다. 본인이 만든 앱에 본인 계정으로 로그인하면 그대로 쓸 수 있다.

## 2. 키 등록 (사용자)

둘 중 하나로 한다.

- **플러그인 설정**: 플러그인 설정 화면의 "카카오 REST API 키" 칸에 입력한다. 클라이언트 시크릿을 사용하는 앱이면 그 칸도 채운다.
- **터미널**: `norang init` 을 실행해 물음에 답한다.

## 3. 로그인

1. `auth_login` 을 호출해 받은 `loginUrl` 을 사용자에게 보여 준다. 터미널이라면 `norang login` 이 브라우저를 직접 연다.
2. 사용자가 브라우저에서 로그인하고 동의한다. 주소는 5분 동안 유효하다.
3. `auth_status` 로 `loggedIn: true` 와 두 동의항목의 `agreed: true` 를 확인한다.

리다이렉트 URI 오류(KOE006)가 나면 4번 단계의 주소가 한 글자도 다르지 않게 등록됐는지 확인하게 한다.

## 4. 대화 파일 등록 (선택, 사용자)

과거 대화를 검색·요약하고 싶을 때만 한다.

1. 카카오톡에서 해당 채팅방을 열고 메뉴의 **대화 내용 내보내기**로 텍스트(.txt 또는 .csv) 파일을 저장한다.
2. 터미널에서 `norang archive add <저장한 파일 경로>` 를 실행한다.

등록은 일부러 터미널 명령으로만 받는다. 어떤 대화를 AI가 볼 수 있게 할지는 사용자가 직접 정해야 하기 때문이다. 파일은 복사되지 않고 원래 위치에서 읽힌다. 내보낸 뒤의 새 메시지는 다시 내보내야 반영된다.

## 5. 확인

`memo_send` 를 `dry_run: true` 로 한 번 호출해 구성이 맞는지 보고, 사용자가 원하면 실제로 "norang 연결 완료" 같은 짧은 메모를 보내 확인한다.

## 연결 끊기

`norang logout --unlink` 는 토큰을 지우고 앱 연결을 끊어 동의를 철회한다. 로컬 설정과 토큰은 `~/.config/norang/` 에 있다. 이 폴더를 삭제해도 카카오 연결 동의나 외부 서비스의 로그까지 삭제되지는 않는다.