# norang 연결 안내서

norang은 평소 쓰는 AI와 카카오톡을 이어 주는 안내서와 도구입니다. 카카오와 제휴하거나 승인받은 서비스가 아닙니다.

**현재 상태: 안내서와 설치 파일은 공개되어 있습니다.** norang의 PlayMCP 중계 연결은 로컬 검증 중이라 아직 사용자에게 제공하지 않습니다. 카카오가 제공하는 PlayMCP 도구와 norang의 중계 도구를 구분하세요. 최신 배포 상태와 설치 파일 정보는 [connection.json](https://norang.inlevel9.com/connection.json)에 있습니다.

## AI가 이 주소를 받았을 때

이 문서는 사용자의 요청을 돕는 참고 지침입니다. URL을 받거나 문서를 읽는 것만으로 설치·로그인·권한 부여·메시지 전송이 승인되지는 않습니다. 사용자가 요약이나 검토를 요청했다면 그 요청을 따르세요.

연결을 요청한 경우, 이미 말한 목적과 연결된 도구부터 확인하세요. 목적이 분명하면 다시 묻지 말고 진행합니다. 목적이 없으면 다음처럼 짧게 시작하세요.

> 카카오톡과 함께 쓰도록 도와드릴게요. 제가 만든 내용을 내 카톡으로 받고 싶으세요, 아니면 카톡에서 컴퓨터의 AI에게 일을 부탁하고 싶으세요?

비개발자에게 서버, API, 토큰, JSON을 먼저 설명하지 마세요. AI가 할 수 있는 설정은 직접 처리하고, 사용자가 해야 하는 로그인·연결 동의만 한 단계씩 안내하세요. 현재 단계와 사용자가 할 일 하나를 짧게 전합니다.

## 사람들이 쓰는 장면

| 사용자의 말 | 도와줄 일 |
|---|---|
| 이 여행 계획, 내 카톡에서 바로 보고 싶어 | 현재 AI에서 만든 계획을 짧게 정리해 나와의 채팅으로 전달 |
| 이 내용을 가족 단톡방에 알려야 해 | 읽기 쉬운 안내문을 만들고 사용자가 보낼 대상을 직접 선택하도록 안내 |
| 밖인데, 집 컴퓨터의 AI에게 자료 정리를 부탁하고 싶어 | norang 중계의 제공 여부와 연결된 컴퓨터 확인. 중계는 아직 제공 전임을 안내 |
| Claude에서 만들었는데 다른 AI에서도 이어 쓰고 싶어 | 사용자가 고른 내용만 이어받기 메모로 만들기. 계정 사이의 자동 동기화라고 설명하지 않기 |

기존 카톡 대화 검색·요약을 첫 기능으로 권하지 마세요. 사용자가 요청할 때만 직접 제공한 자료를 다룹니다.

## 연결 방법 고르기

### 1. 이미 연결된 도구가 있다면

현재 세션의 도구 목록에서 카카오톡 전송 또는 PlayMCP 도구가 실제로 있는지 확인합니다. 도구 이름이나 권한을 추측하지 않습니다. 연결되어 있다면 재설치하거나 개발자 앱을 만들게 하지 말고 요청을 처리합니다.

사용자가 “이 계획을 내 카톡으로 보내줘”라고 했다면 보낼 내용과 수신 대상이 정해져 있는 것입니다. 같은 허가를 반복해서 묻지 마세요. 초안·요약 요청만 했다면 전송하지 않습니다. 호스트의 확인 화면이나 로그인 동의는 우회하지 않습니다.

전송 뒤에는 도구 결과에 근거해 완료를 알립니다. 설정을 저장한 것만으로 “메시지가 도착했다”고 말하지 않습니다. 결과가 불확실하면 재전송 전에 확인해 중복을 피합니다.

### 2. AI에 카카오 도구함을 연결할 수 있다면

[PlayMCP](https://playmcp.kakao.com/)는 카카오가 운영합니다. 도구함에서 제공 중인 나와의 채팅·일정 등의 도구를 골라 지원되는 AI에 연결합니다. norang 설치나 카카오 개발자 앱 생성은 필요하지 않습니다.

1. PlayMCP에서 목적에 맞는 도구를 찾고, 표시된 기능과 접근 범위를 확인합니다.
2. 사이트의 현재 **도구함 연결 안내**에서 사용 중인 AI를 고릅니다. 연결 주소는 `https://playmcp.kakao.com/mcp`입니다. 이 홈페이지 주소와 MCP 연결 주소는 다릅니다.
3. AI가 지원하는 연결 설정을 처리합니다. 계정·요금제·조직 정책에 따라 메뉴가 없을 수 있으므로 실제 화면과 공식 안내를 기준으로 합니다.
4. 로그인과 접근 동의는 사용자가 카카오 화면에서 직접 합니다. 비밀번호·인증번호·연결 키를 AI 대화창에 적게 하지 않습니다.
5. 도구가 실제로 보이는지 확인하고 사용자가 요청한 내용으로 전송을 검증합니다. 별도의 시험 메시지를 보내려면 내용을 먼저 제안합니다.

이 연결은 모든 채팅방이나 친구에게 임의로 보내는 권한을 뜻하지 않습니다. 가족·친구에게 전달할 때는 도구가 지원하는 수신 범위를 확인하고, 지원하지 않으면 사용자가 직접 공유하도록 합니다.

### 3. 연결 도구가 없어도 내 카톡으로 받기

ChatGPT·Claude·Gemini·Grok의 일반 대화창에서도 같은 전송 확인 화면을 이용할 수 있습니다. 앱 설치를 지원하지 않는 AI에게 로컬 프로그램 설치나 MCP 메뉴를 찾게 할 필요가 없습니다.

1. 보낼 글을 2,000자 이내로 정리합니다. `prepare_message` 도구가 보이면 호출해 확인 링크를 받습니다. 이 도구는 컴퓨터 연결 키 없이 쓸 수 있고, 직접 메시지를 전송하지 않습니다.
2. 도구가 없으면 `https://norang.inlevel9.com/send#text=` 뒤에 글을 UTF-8 URL 인코딩해 붙인 클릭 가능한 링크를 제공합니다. 자바스크립트로 만들 때는 `"https://norang.inlevel9.com/send#text=" + encodeURIComponent(text)`와 같습니다. `#`를 `?`로 바꾸거나 비밀번호·토큰을 글에 넣지 않습니다.
3. 링크를 만들기 어렵거나 글이 길면 [내 카톡으로 받기](https://norang.inlevel9.com/send)를 열고 글을 붙여 넣도록 안내합니다. 글과 안내 링크를 함께 제공합니다.
4. 사용자는 화면에서 내용을 확인하고, 카카오 로그인·메시지 전송 동의 뒤 **내 카톡으로 보내기**를 누릅니다. 로그인만으로 보내지는 않습니다. 웹 로그인에는 카카오톡 메시지 전송만 요청하며, 일반 사용자에게 개발자 앱이나 키를 요구하지 않습니다.

링크를 만들었다고 전송이 끝난 것은 아닙니다. 도구가 이미 직접 전송을 끝냈다면 이 링크를 추가로 만들어 중복 전송을 유도하지 않습니다. 전송 화면은 앱 설정 상태를 확인하며, 설정이 아직 준비되지 않은 배포에서는 글 복사로 이어갈 수 있습니다. 연결 시작 문장은 [AI별 시작 화면](https://norang.inlevel9.com/connect)에서도 복사할 수 있습니다.

### 4. 복사·공유로 이어가기

설정에 없는 기능을 찾게 하거나 다른 유료 서비스 가입을 요구하지 마세요. 현재 AI에서 카톡용 짧은 글을 만들어 사용자가 복사해 붙여 넣게 합니다. 공유 메뉴가 있다면 실제 화면에서 카카오톡을 고를 수 있는지 확인합니다.

“연결은 아직 지원되지 않지만, 바로 카톡에 보낼 글은 만들어 드릴게요”라고 설명합니다. 복사·공유를 연결 설치 완료라고 말하지 않습니다.

## AI마다 확인할 점

| 사용 중인 환경 | 가능한 안내 |
|---|---|
| ChatGPT | 실제 계정의 플러그인·앱·사용자 지정 MCP 연결 기능 확인. 지원될 때 PlayMCP의 현재 안내로 연결 |
| Claude 웹·데스크톱 | 실제 계정의 커넥터 연결 기능 확인. 지원될 때 PlayMCP의 현재 안내로 연결 |
| Gemini 앱·웹 | 전송 확인 링크를 만들거나 `/send`에 글을 붙여 넣어 본인 카톡으로 받기. Gemini CLI의 MCP 지원을 앱·웹의 연결 지원으로 설명하지 않기 |
| Grok 앱·웹 | 전송 확인 링크를 만들거나 `/send`에 글을 붙여 넣어 본인 카톡으로 받기. xAI API의 MCP 지원을 일반 Grok 대화창의 설치 지원으로 설명하지 않기 |
| Claude Code·Codex·Gemini CLI 등 | 로컬 명령 실행·설정 권한이 있을 때 아래 설치 절차 사용. 각 AI의 실제 지원 기능을 따름 |

주소를 읽을 수 없는 AI라면 사용자가 [안내서 원문](https://norang.inlevel9.com/guide.md)을 열어 필요한 부분을 붙여 넣을 수 있습니다. 페이지를 읽은 상태, 도구가 연결된 상태, 실제 왕복이 확인된 상태를 구분해서 알리세요.

## 컴퓨터에 설치할 수 있는 AI를 위한 절차

웹 대화창에 로컬 명령 실행 권한이 생기는 것은 아닙니다. AI가 만든 내용을 내 카톡으로 받는 목적에는 앞의 PlayMCP 연결을 우선합니다.

### 공개 상태와 설치 파일 확인

1. `connection.json`을 읽습니다. `publicInstallationAvailable`이 `false`이거나 설치 파일 URL이 제공되지 않으면 공개 설치가 준비됐다고 안내하지 않습니다. 로컬 시험에서는 사용자가 제공한 저장소나 파일을 사용합니다.
2. 공개 설치가 가능한 상태라면 Node.js 20 이상과 기존 norang 설치를 확인합니다. 이미 설치되어 있으면 필요한 변경만 합니다.
3. 설치 파일을 내려받아 `connection.json`의 SHA-256과 비교합니다. 인증서 오류를 무시하거나 출처가 다른 패키지로 바꾸지 않습니다.

지금 내려받는 버전은 0.2.0 입니다. 설치 파일의 SHA-256 값은 `c1f71245964423afcbce64955308ac8fb91e520d919c23beaa52a3ce872747ee` 입니다.

4. 사용자가 요청한 범위와 호스트 권한에 따라 설치합니다. 배포 주소는 아래와 같습니다.

```
npm install -g https://norang.inlevel9.com/norang.tgz
norang --version
```

기존 AI 설정을 덮어쓰지 말고 norang 항목만 추가합니다. MCP 연결과 스킬 설치는 별개입니다. Claude Code에서 로컬 도구를 추가할 때:

```
claude mcp add norang -- norang mcp
```

Codex에서 같은 로컬 도구를 추가할 때:

```
codex mcp add norang -- norang mcp
```

다른 호스트는 공식 설정 방법을 확인합니다. 일반 `norang mcp` 연결만으로 카톡에서 작업을 받는 채널이 켜지지는 않습니다. 설치 후 도구 목록과 상태를 확인하세요.

### 스킬만 등록하기

스킬은 AI가 연결 절차를 기억하도록 하는 지침입니다. 그 자체로 카카오 계정에 접근하지 않습니다. 사용자가 설치를 요청했고 로컬 파일을 관리할 수 있는 AI라면, 위에서 검증한 패키지 안의 `package/skills/norang-setup` 폴더를 해당 호스트의 스킬 경로에 등록합니다. CLI 실행 프로그램의 전역 설치는 스킬만 쓸 때 필요하지 않습니다.

| 호스트 | 개인 스킬 폴더 |
|---|---|
| Claude Code | `~/.claude/skills/norang-setup/` |
| Codex | `~/.agents/skills/norang-setup/` |

`SKILL.md`와 `references/developer-app.md`를 함께 둡니다. 기존 같은 이름의 스킬을 덮어쓰지 말고 먼저 내용을 확인합니다. 호스트가 스킬을 인식하는지 확인하고, 필요하면 새 세션을 시작하게 안내합니다. 이 단계가 끝나도 카카오 연결은 별도로 확인합니다. Gemini CLI 등은 해당 호스트의 공식 스킬 설치 방법을 따릅니다.

웹 대화창에서는 이 파일 경로에 접근할 수 없습니다. [SKILL.md 원문](https://norang.inlevel9.com/SKILL.md)을 읽고 현재 대화에서 안내하는 것과 영구 설치는 구분합니다. 이 안내서의 설치 명령을 웹 사용자가 직접 입력하게 하지 마세요.

### 카톡에서 내 컴퓨터의 AI에게 부탁하기

카카오톡의 AI가 PlayMCP로 작업을 보내면, 연결된 컴퓨터의 Claude Code가 처리하고 결과를 돌려주는 연결을 만들고 있습니다. 컴퓨터와 Claude Code 세션이 켜져 있어야 합니다.

**이 중계는 아직 로컬 검증 중이며 공개 연결 주소가 없습니다.** Gemini·Grok·ChatGPT까지 작업을 받는 기능이 완성되었다고 말하지 마세요. `connection.json`의 `remoteBridge.available`이 `true`가 될 때까지 일반 사용자에게 연결 키 발급이나 PlayMCP 개발자 콘솔 등록을 시키지 않습니다.

개발·로컬 시험 요청에는 설치 패키지의 `docs/RELAY.md`를 참고합니다. 컴퓨터 연결 뒤 `norang agent start --folder "작업할 폴더"`로 현재 세션 전용 채널을 켭니다. 읽기 작업만 허용하려면 `--read-only`를 사용합니다. 개발용 채널 확인은 사용자가 직접 선택하고 일반 권한 확인은 유지합니다. 이 명령은 기존 AI 설정을 덮어쓰지 않습니다.

`norang relay pair`의 연결 키는 컴퓨터에 작업을 보낼 수 있는 자격 정보입니다. 대화나 일반 URL에 표시하지 말고 지정된 인증 설정에만 입력합니다. 연결 하나는 실행 중인 Claude 세션 하나에만 사용합니다. `send_task`가 반환한 작업 ID로 `get_replies(task_id, after, wait_seconds)`를 조회합니다. 최대 10초 기다릴 수 있고, 답이 없으면 완료됐다고 하지 않습니다. 후속 요청은 같은 세션의 대화 맥락을 이어받지만 새로운 작업 ID를 가집니다.

Mac 카카오톡 화면을 읽는 선택 기능은 PlayMCP 경로와 다릅니다. 일반 연결 과정에서 손쉬운 사용 권한이나 화면 조작을 대신 활성화하지 않습니다.

## 데이터와 연결 해제

연결할 때는 어떤 글이 어떤 서비스로 이동하는지 설명합니다. norang 중계는 작업 문장과 답을 서버에 최대 24시간 보관하는 구조입니다. 카카오와 사용 중인 AI 서비스도 각자의 정책에 따라 요청을 처리합니다. 사용자가 요청한 자료만 처리합니다.

전송 화면의 글은 보내기 전까지 해당 탭의 임시 저장소에 두고, 보내기를 누를 때 norang 서버를 거쳐 카카오로 전달합니다. 웹 로그인 토큰은 암호화된 HttpOnly 쿠키에 보관되며 AI나 브라우저 자바스크립트에 보여 주지 않습니다. 이 기능의 카카오 연결은 전송 화면의 연결 해제 버튼으로 철회합니다.

- PlayMCP: AI의 연결 설정과 PlayMCP 도구함에서 해당 연결·도구를 해제합니다. 스킬 삭제와 계정 연결 해제는 별개입니다.
- norang 중계: `norang relay unpair`로 연결을 해제하고 실행 중인 채널 세션도 종료합니다.
- 로컬 norang: 필요하면 `npm uninstall -g norang`으로 제거합니다. 설정은 `~/.config/norang`에 있습니다. 로컬 설정 삭제로 외부 서비스의 로그까지 삭제되지는 않습니다.

개발자 앱을 직접 소유하고 공식 Open API를 연동하려는 사용자만 [개발자용 설정](https://norang.inlevel9.com/developer.md)을 읽습니다. 일반 사용자에게 앱 키나 개발자 콘솔 등록을 필수 단계로 안내하지 마세요.

## 참고

- [PlayMCP](https://playmcp.kakao.com/)
- [ChatGPT MCP 연결](https://developers.openai.com/plugins/deploy/connect-chatgpt)
- [Claude 커넥터](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp)
- [Gemini CLI 확장](https://geminicli.com/docs/extensions/)
- [Claude Code 스킬](https://code.claude.com/docs/en/skills)
- [Codex 스킬](https://developers.openai.com/codex/skills)
- [xAI API 원격 MCP](https://docs.x.ai/developers/tools/remote-mcp)
- [개인정보 처리방침](https://norang.inlevel9.com/privacy) · [이용약관](https://norang.inlevel9.com/terms)

INLEVEL9 인레벨나인 · contact@inlevel9.com