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

# 로컬 커넥터

> zapbip의 connect, listen, channel 명령: 플래그, 환경 변수, 웨이크 격리, 로그.

보통 AI는 이미 작업 중일 때만 WhatsApp을 읽어요. AI가 쉬고 있을 때 쓰면 메시지는 기다려요.

zapbip 커넥터가 이를 해결해요. 내 컴퓨터에서 계속 켜 두는 작은 프로그램이에요. WhatsApp에서 쓰면, 이미 쓰던 AI 세션을 깨우고, 내 메시지를 전달해서 답하게 해요. Claude Code는 약 7초, Codex는 약 6초가 걸려요.

Claude Code와 Codex에서 작동해요. 컴퓨터가 켜져 있고 깨어 있어야 하며, 커넥터가 실행 중이어야 해요.

## 명령

| 명령 | 하는 일 |
| - | - |
| `connect` | 내가 쓰면 닫힌 세션을 깨워요. `--client`, `--cwd`, `--session`을 받아요. |
| `listen` | 메시지마다 JSON 한 줄을 출력해요. 백그라운드 명령을 지켜보는 에이전트용이에요. |
| `channel` | 로컬 MCP 채널을 실행해 각 메시지를 열려 있는 Claude Code 세션에 넣어요. |

`ZAPBIP_CONNECTION_URL`에 연결 링크가 들어 있어요. `connect`와 `listen`은 설정되지 않았으면 링크를 물어봐요.

## 필요한 것

* 이미 zapbip에 연결된 Claude Code 또는 Codex.
* AI가 작업하게 할 폴더에 이전 세션이 하나 이상 있어야 해요.
* Node 24 이상.
* 연결 링크. AI가 zapbip과 이야기할 때 쓰는 것과 같은 `https://.../c/<secret>/mcp` 링크예요. 비밀번호처럼 다루세요.

## 시작하기

AI를 쓰는 폴더에서 터미널을 열고 다음 중 하나를 실행하세요.

```bash theme={null}
export ZAPBIP_CONNECTION_URL='https://<host>/c/<secret>/mcp'
npx zapbip@0.1.0 connect --client claude-code
```

```bash theme={null}
export ZAPBIP_CONNECTION_URL='https://<host>/c/<secret>/mcp'
npx zapbip@0.1.0 connect --client codex
```

`ZAPBIP_CONNECTION_URL`을 설정하지 않으면 커넥터가 링크를 물어봐요. 링크를 인자로 받지는 않아요. 인자는 셸 기록과 프로세스 목록에 남기 때문이에요.

터미널은 열어 두세요. 커넥터는 이벤트마다 한 줄을 출력하고 `Ctrl+C`를 누르면 멈춰요. 터미널 없이 계속 실행하려면 [백그라운드에서 실행하기](https://docs.zapbip.com/ko/developers/background-running.md)를 보세요.

## 내가 쓰면 일어나는 일

1. WhatsApp에서 AI에게 써요.
2. 커넥터가 메시지를 받고 폴더에서 가장 최근의 세션을 깨워요.
3. AI가 메시지를 읽고 WhatsApp으로 답해요.
4. 여러 메시지가 한꺼번에 도착하면 순서대로 하나씩 처리돼요.

오프라인이었거나 커넥터가 멈춰 있었어도 메시지는 사라지지 않아요. 다시 연결되면 답하지 못한 메시지를 모두 가져와요.

## 세션 고르기

기본적으로 커넥터는 폴더에서 가장 최근의 세션을 사용해요. 같은 폴더를 다른 창에서 열어 두었다면 웨이크가 그 대화에 이어 붙을 수 있어요. 이를 피하려면 세션을 고정하세요.

```bash theme={null}
npx zapbip@0.1.0 connect --client claude-code --session <session-id>
```

| 옵션 | 하는 일 |
| - | - |
| `--client` | `claude-code` 또는 `codex`. 필수예요. |
| `--cwd` | 작업할 폴더. 기본값은 명령을 실행한 폴더예요. |
| `--session` | 가장 최근 세션 대신 항상 다시 시작할 세션 id(UUID). |

## AI가 깨어났을 때 할 수 있는 일

한 가지뿐이에요. 나에게 메시지를 돌려보내는 것이에요. 커넥터는 AI에게 zapbip만 담은 전용 설정을 주므로, 내 다른 MCP 서버의 도구는 사용할 수 없어요. Claude Code는 내 설정 파일 없이, 모든 내장 도구를 끈 채 실행돼요. Codex는 읽기 전용 샌드박스에서 실행되며, Codex 설정 파일에서 찾은 다른 MCP 서버는 꺼져요. 그 파일 중 하나를 읽을 수 없으면 Codex를 깨우지 않고 메시지를 읽지 않은 상태로 둬요. 또한 관리되는 Codex 파일이 무해한 키의 짧은 목록 밖의 키를 설정하거나, 프로필이 샌드박스, 승인, 도구, 기능(또는 그 목록 밖의 키)을 설정하거나, 파일이 웹 검색 스위치를 켜거나, `zapbip`이 Codex 홈의 `config.toml` 외의 곳에 정의되어 있으면 거부해요. Codex의 웹 검색은 꺼져요. Codex에 남는 것은 `send_message`와 읽기 전용 셸이에요. Codex 계정의 앱과 커넥터는 꺼지지 않으며, macOS 관리 환경설정 `com.openai.codex`와 Claude Code의 관리 정책 설정도 계속 적용돼요. 내 메시지는 검증됨으로 표시된, 나에게서 온 메시지로 전달돼요. 다른 사람에게서 전달받은 메시지는 검증되지 않음과 전달됨 라벨이 붙어 도착하며, AI는 그것을 내 지시로 취급하지 않아요.

Codex 앱이 이미 그 대화를 열어 두었다면 Codex는 다시 시작하기를 거부해요. 그러면 커넥터가 같은 폴더에서 새 세션 하나를 시작하며, 이 세션은 이전 대화 없이 시작되고 그 뒤로는 이 세션을 사용해요.

## 열려 있는 세션이 계속 듣게 하기

`connect`는 닫힌 세션을 깨워요. 지금 열어 둔 세션에는 Claude Code가 웨이크도 대기도 없이 바로 내 말을 들을 수 있어요. 방법은 두 가지이고, 첫 번째가 더 좋아요.

채널이 첫 번째 선택이에요. Claude Code가 다른 도구와 같은 방식으로 직접 시작하는 작은 프로그램이에요. WhatsApp에서 쓴 메시지를 하나씩, 검증됨으로 표시된 나의 메시지로서 열려 있는 세션에 바로 넣어 줘요(전달된 메시지는 검증되지 않음으로 표시돼요). Claude Code가 실행되는 환경에 `ZAPBIP_CONNECTION_URL`을 설정하면 Claude Code가 다음으로 시작해요.

```bash theme={null}
npx zapbip@0.1.0 channel
```

채널은 링크를 물어볼 수 없으므로 `ZAPBIP_CONNECTION_URL`에서만 읽어요. 인자도 받지 않아요.

작업하는 폴더의 `.mcp.json`에 두 서버를 모두 선언하세요. 채널이 내 메시지를 가져오고, 다른 키 아래의 zapbip HTTP 서버가 세션에 답장용 `send_message` 도구를 줘요.

```json theme={null}
{
  "mcpServers": {
    "zapbip-channel": {
      "command": "npx",
      "args": ["zapbip@0.1.0", "channel"],
      "env": { "ZAPBIP_CONNECTION_URL": "https://<host>/c/<secret>/mcp" }
    },
    "zapbip": {
      "type": "http",
      "url": "https://<host>/c/<secret>/mcp"
    }
  }
}
```

세션은 `zapbip`을 통해 답해요. 이것이 없으면 세션은 내 말을 듣지만 답할 방법이 없어요. 그런 다음 Claude Code를 다음으로 시작하세요.

```bash theme={null}
claude --dangerously-load-development-channels server:zapbip-channel
```

`zapbip`은 `.mcp.json`에 있는 채널 서버의 키예요. 시작 줄에 `Channels (experimental)`이 표시돼요. Claude Code가 개발 채널과 프로젝트 MCP 서버를 수락할지 물으면 둘 다 수락하세요.

리스너는 예비 수단이에요. 내가 WhatsApp에서 쓴 메시지마다 한 줄을 출력하고, Claude Code가 Monitor 도구로 그 줄을 지켜봐요. 각 줄이 열려 있는 세션을 깨우며, 내가 조용한 동안에는 아무것도 소모되지 않아요.

```bash theme={null}
export ZAPBIP_CONNECTION_URL='https://<host>/c/<secret>/mcp'
npx zapbip@0.1.0 listen
```

각 줄은 메시지 id, 종류, `"sender":"owner"`, `"verified"`(내 메시지는 `true`, 전달된 메시지는 `false`), `"forwarded"`, 텍스트를 담은 JSON이에요. Monitor 감시는 최대 30분 동안 이어지므로, 감시가 끝날 때마다 AI가 감시를 다시 시작해요. OpenClaw와 Hermes처럼 백그라운드 명령을 계속 실행하고 그 출력에 반응할 수 있는 다른 에이전트도 `npx zapbip@0.1.0 listen`을 같은 방식으로 쓸 수 있어요.

두 프로그램 모두 계속 열려 있고, `connect`처럼 스스로 다시 연결해요. 둘 다 메시지를 넘겨준 뒤에야 처리됨으로 표시하므로, 메시지는 사라지지도 두 번 보이지도 않아요. 로그는 오류 출력으로 가며 내 메시지나 링크가 담기지 않아요.

정리하면 세 방법이 함께 맞물려요. 열린 세션에는 채널, 그 예비로 `listen`, 닫힌 세션에는 `connect`이에요.

## 연결 하나에 커넥터 하나

같은 연결에 두 번째 커넥터를 시작하면 첫 번째 커넥터는 실행 중인 웨이크를 마치고 멈춰요. 한 번에 한 대의 컴퓨터에서만 실행하세요. 전환하는 순간에 메시지가 도착하면 두 커넥터가 같은 메시지로 AI를 한 번씩 깨울 수 있어요. zapbip은 최소 한 번 전달하며, 0번 전달하는 일은 없어요.

커넥터가 연결되어 있는 동안 zapbip은 그것을 통해 AI를 깨워요. 커넥터가 닫히면 zapbip은 이전 설정으로 되돌아가요.

## 출력되는 내용

각 줄은 시간과 `wake_started`, `wake_finished` 같은 이벤트를 담은 JSON이에요. 줄에는 id, 종류, 결과, 소요 시간이 담겨요. 내 메시지, AI의 답장, 연결 링크는 절대 담기지 않아요.

## 작동하지 않을 때

| 보이는 것 | 의미 |
| - | - |
| 커넥터가 바로 종료됨 | 링크를 알 수 없거나 해제되었어요. 새 링크를 요청하세요. |
| 메시지에 답이 없음 | 폴더에 아직 세션이 없거나, 커넥터가 실행되는 곳에 `claude` 또는 `codex`가 설치되어 있지 않아요. 그 폴더에서 AI를 한 번 여세요. |
| 계속 다시 연결함 | 네트워크가 끊겼어요. 대기 시간을 늘리며 최대 30초까지 다시 시도하고, 중단된 곳에서 이어서 가져와요. |
| 스스로 멈춤 | 같은 연결에 다른 커넥터를 시작했어요. |


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