CLI-WeChat-Bridge

명령줄 도구(CLI)의 WeChat 브리지: 본 프로젝트는 WeChat 메시지와 로컬에서 실행 중인 Codex, Claude Code, OpenCode 또는 지속적인 powershell.exe 세션을 브리지(Bridge)하며, 로컬 출력, 승인 요청 및 실행 상태를 WeChat으로 동기화하는 데 사용됩니다.

현재 구현은 로컬 워크플로우를 중심으로 전개되며, 로컬 네이티브 터미널 경험을 유지하는 데 중점을 둡니다. 네이티브 사용 및 고급 파라미터 주입을 지원하며, 이를 기반으로 WeChat 측의 원격 입력, 결과 회류 및 상태 동기화 기능을 제공합니다.

본 프로젝트는 다음과 같은 사용 시나리오를 대상으로 합니다:

• 당신의 주 워크플로우가 여전히 로컬 터미널에서 진행될 때;
• 웹페이지나 호스팅된 봇으로 이동하는 대신, 네이티브 codex 또는 기타 CLI 도구를 계속 사용하고 싶을 때;
• 컴퓨터를 떠나 있을 때도 WeChat을 통해 로컬 세션에 요청을 보내고, 필요한 출력 및 상태 동기화를 받고 싶을 때.

현재 프로젝트는 WeChat을 새로운 주 작업 인터페이스로 만들려고 시도하지 않습니다. 대신, 다음과 같이 정의합니다:

• 로컬 CLI가 여전히 주 작업 인터페이스이며, 네이티브 사용 로직을 유지합니다;
• WeChat은 원격 접속을 허용하는 원격 엔트리(Entry)입니다;
• 세션 일관성, 스레드 상태 및 승인 흐름은 여전히 로컬 세션을 중심으로 합니다.

요구 사항:

• Node.js >= 24.0.0 (공식 홈페이지의 LTS 버전을 직접 설치하는 것을 권장)
• Bun >= 1.0.0 (개발자에게 필요하며, 일반 사용자는 설치할 필요 없음)
• 다음 중 최소 하나 이상의 로컬 CLI가 설치되어 있어야 함 (가급적 최신 버전으로 업데이트 권장):
  • Codex
  • Claude Code
  • OpenCode
  • powershell.exe

설치 방법:

정식 버전은 npm을 통해 직접 설치할 수 있습니다:

npm install -g @unlinearity/cli-wechat-bridge@latest

설치 후에는 임의의 프로젝트 디렉토리에서 wechat-codex-start, wechat-claude-start, wechat-opencode-start 등의 명령어를 직접 사용할 수 있습니다.

소스 코드로 실행하거나 개발에 참여하고 싶다면, 저장소를 클론(Clone)하고 의존성을 설치할 수 있습니다:

git clone https://github.com/UNLINEARITY/CLI-WeChat-Bridge
cd CLI-WeChat-Bridge
bun install

소스 저장소를 사용하는 경우, 현재 워크스페이스를 글로벌 명령어로 설치하려면 다음과 같이 입력합니다:

npm install -g .

개발 단계에서는 다음도 사용할 수 있습니다:

npm link

설명:

npm link는 글로벌 명령어가 현재 저장소의 소스 코드를 직접 가리키게 합니다. 반면 npm install -g .은 현재 저장소의 복사본을 설치합니다. 따라서 이후 코드가 업데이트되면 다시 실행해야 합니다.

현재 로컬 소스로 빌드된 패키지를 실제 글로벌 환경에 설치하고 임의의 디렉토리에서 수동으로 검증하고 싶다면, 다음을 직접 실행하십시오:

npm run smoke:global

이 스크립트는 먼저 현재 소스로 실제 npm tarball을 만든 다음, npm install -g <tarball>을 실행하여 실제 글로벌 환경에 설치합니다. 스크립트가 종료되면 저장소 디렉토리를 벗어나 wechat-codex-start 등의 명령어를 실행할 수 있습니다. 캐시를 먼저 정리하거나, 현재 글로벌 패키지를 제거하거나, 혹은 전체 품질 게이트(Quality Gate)를 함께 실행하고 싶다면 다음 파라미터를 추가할 수 있습니다:

npm run smoke:global -- --purge-global --clean-cache --full

• --clean-cache: 먼저 npm cache clean --force를 실행합니다.
• --purge-global: 먼저 현재의 실제 글로벌 패키지를 제거합니다.
• --full: 추가로 npm run quality를 실행합니다.
• --keep-tarball: 문제 해결을 용이하게 하기 위해 생성된 tarball을 유지합니다.

npm 글로벌 설치 후에는 바로 다음을 실행할 수 있습니다:

wechat-setup

클론한 저장소 디렉토리 내에 있다면 다음을 실행할 수도 있습니다:

bun run setup # WeChat ClawBot 바인딩

이 프로세스는 다음과 같이 진행됩니다:

• WeChat 로그인 QR 코드를 가져옵니다;
• 터미널에 QR 코드를 출력합니다;
• WeChat에서 QR 코드를 스캔하고 확인하기를 기다립니다;
• 봇(Bot) 인증 정보를 로컬 데이터 디렉토리에 기록합니다.

기본 인증 파일 경로:

~/.claude/channels/wechat/account.json

로그인에 성공하면 이전의 sync_buf.txt 및 context_tokens.json을 정리하여, 이전 세션 상태가 새로운 로그인 상태를 오염시키는 것을 방지합니다.

처음 설치하거나 WeChat 로그인이 만료된 경우, wechat-codex-start, wechat-claude-start, wechat-opencode-start 실행 시 프론트엔드에서 QR 코드 스캔 로그인을 안내합니다.

브리지(Bridge)를 시작한 후에는 먼저 WeChat에서 봇(Bot)에게 hello 또는 실행할 작업, 혹은 아무 문장이나 메시지를 보내는 것을 권장합니다. 이렇게 하면 브리지가 최신 WeChat 세션 context_token을 가져올 수 있습니다.

，그 이후에야 로컬 터미널의 입력, 최종 회신 및 승인 알림이 WeChat으로 안정적으로 동기화될 수 있습니다.

만약 콜드 스타트(Cold Start) 상태이거나 장시간 유휴 상태인 후 로컬 터미널에서 먼저 메시지를 보내면, bridge는 일반적으로 해당 로컬 입력을 캡처하여 Codex / Claude Code / OpenCode로 전달하지만, WeChat 측의 아웃바운드(Outbound) 전송은 오래된 context_token이 만료되어 실패할 수 있습니다. 이 경우 발생하는 현상은 다음과 같습니다: 로컬에는 이미 회신이 생성되었으나 WeChat으로는 일시적으로 전달되지 않습니다. 이후 WeChat에서 메시지를 먼저 한 번 보내고 나면, 이후의 양방향 동기화는 정상적으로 복구됩니다.

먼저 작업하려는 프로젝트 디렉토리로 이동합니다:

cd D:\work\your-project

단일 명령 엔트리 포인트를 직접 선택하는 것을 권장합니다:

사용하는 로컬 CLI	시작 명령
Codex	wechat-codex-start
...

세 가지 방식 모두 자동으로 다음 동작을 수행합니다:

• WeChat 로그인 자격 증명(Credentials) 검증 또는 갱신;
• 현재 디렉토리에서 이미 실행 중인 bridge를 재사용하거나, 현재 디렉토리에서 새로운 bridge를 시작;
• 만약 bridge가 다른 디렉토리에서 서비스 중이라면, 이전 bridge를 중지하고 현재 디렉토리로 전환;
• 현재 디렉토리에 해당하는 로컬 컴패니언 엔드포인트(Companion Endpoint)가 준비될 때까지 대기;
• 가시적인 로컬 CLI 세션 열기.

wechat-codex-start

/ wechat-claude-start

/ wechat-opencode-start

이제 단일 활성 워크스페이스 전환기(Single-active Workspace Switcher) 방식으로 작동합니다:

• 한 번에 하나의 프로젝트만 WeChat과 대화합니다;
• 현재 디렉토리에서 반복 실행하는 것은 멱등성(Idempotent)을 가집니다;
• 현재 디렉토리에 이미 가시적인 컴패니언(Companion) / 패널(Panel)이 실행 중이라면, 두 번째 창을 중복해서 열지 않습니다;
• 가시적인 엔드(End)가 존재하지만 워커(Worker) 상태가 비정상(예: stopped / error)인 경우, 자동으로 bridge를 재시작하고 가시적인 엔드를 다시 엽니다;
• 다른 디렉토리에서 실행하면 활성 워크스페이스가 명시적으로 전환됩니다.

bridge와 로컬 CLI 컴패니언(Companion)을 명확하게 관찰하고 싶다면, 두 개의 터미널로 나누어 실행할 수도 있습니다.

어댑터	터미널 A: bridge	터미널 B: 로컬 컴패니언
Codex	wechat-bridge-codex	wechat-codex
Claude Code	wechat-bridge-claude	wechat-claude
OpenCode	wechat-bridge-opencode	wechat-opencode

현재 로컬 파일을 WeChat으로 전송하는 기능을 지원합니다.

어댑터	현재 상태	설명
codex	연결됨	이중 터미널 모드; 로컬 컴패니언이 스레드 권한(Thread Authority)을 가짐; WeChat은 로컬 스레드를 따름
claude	연결됨	wechat-bridge-claude + wechat-claude의 이중 터미널 컴패니언 모드; 세션 전환, 최종 회신 및 승인 메타데이터가 Claude 세션 의미론(Semantics)에 따라 동기화됨
opencode	연결됨	wechat-bridge-opencode + wechat-opencode의 이중 터미널 컴패니언 모드; 로컬 세션 전환 추종을 지원하며, WeChat 측에서 /new / /new-session 지원
shell	사용 가능	지속적인 powershell.exe 세션; 고위험 명령에 대한 승인 지원

터미널 A:

wechat-bridge-codex

터미널 B:

wechat-codex

그 후 다음과 같은 작업이 가능합니다:

• WeChat에서 일반 텍스트 전송;
• 로컬 wechat-codex에서 네이티브 상호작용 계속 수행;
• 로컬에서 /resume을 실행하여 스레드 전환;
• WeChat이 현재 로컬 스레드를 자동으로 따르도록 설정.

Claude Code는 WeChat을 통해 원격 승인 확인을 수행할 수 있습니다.

OpenCode 모드에서는 WeChat 측에서 /new 또는 /new-session을 사용하여 새 세션을 생성할 수 있습니다. 로컬 OpenCode CLI에서 새 세션을 생성하면 WeChat 메시지도 새 세션을 따라갑니다.

유형	명령
로그인 및 업데이트	wechat-setup , wechat-check-update
...

bun run setup
bun run bridge:codex
bun run codex:panel
...

적용 대상:

wechat-bridge

wechat-bridge-codex

wechat-bridge-claude

wechat-bridge-opencode

wechat-bridge-shell

예시:

wechat-bridge --adapter codex --cwd D:\work\my-project
wechat-bridge-codex --cwd D:\work\my-project
wechat-bridge-claude --profile work
...

지원하는 파라미터:

--adapter <codex|claude|opencode|shell>

: 범용 엔트리(Entry)인 wechat-bridge 사용 시 어댑터(Adapter)를 명시적으로 지정해야 합니다. ; --cwd <path>

: 작업 디렉터리(Working Directory) 지정; --cmd <executable>

: 기본 명령어를 덮어쓰기; --profile <name-or-path>

: 어댑터에 프로필(Profile) 전달; --lifecycle <persistent|companion_bound>

: 브릿지(Bridge) 생명주기(Lifecycle) 지정; wechat-*-start는 companion_bound를 사용합니다.

예시:

wechat-codex-start --cwd D:\work\my-project
wechat-claude-start --profile work
wechat-opencode-start --cwd D:\work\my-project

지원하는 파라미터:

--cwd <path>

: 브릿지(Bridge) / 컴패니언(Companion)에 대응하는 작업 디렉터리를 명시적으로 지정; --profile <name-or-path>

: 백그라운드에서 실행되는 wechat-bridge-codex / wechat-bridge-claude / wechat-bridge-opencode로 전달; --timeout-ms <ms>

: 현재 디렉터리 엔드포인트(Endpoint)를 기다리는 최대 시간, 기본값은 15000입니다.

고급 사용법: 상기 스타터(Starter) 파라미터 외에, 알려지지 않은 파라미터는 가시적인 하위 CLI(Command Line Interface)로 계속 전달(Pass-through)됩니다. 이를 통해 위챗(WeChat) 로그인, 워크스페이스(Workspace) 전환 및 브릿지 생명주기 관리를 유지하면서, Codex / Claude Code 자체의 고급 실행 모드를 활성화할 수 있습니다.

wechat-codex-start --yolo
wech

- 그것들은 **단일 활성 워크스페이스 스위처 (Single-active workspace switcher)** 입니다.
- 현재 디렉토리에서 반복 실행하는 것은 멱등성 (Idempotent)을 가집니다.
- 다른 디렉토리에서 반복 실행하면 병렬로 여러 개를 여는 대신 워크스페이스 전환을 트리거합니다.

기본 데이터 디렉토리:

~/.claude/channels/wechat

주요 파일은 다음과 같습니다:

| 경로 | 역할 |
|---|---|
| `account.json` | WeChat 자격 증명 |
| `sync_buf.txt` | iLink 증분 동기화 커서 (Incremental sync cursor) |
| `context_tokens.json` | WeChat 컨텍스트 (Context) 토큰 캐시 |
| `bridge.log` | bridge 실행 로그 |
| `bridge.lock.json` | bridge 실행 잠금 (Lock) |
| `workspaces/<workspace-key>/bridge-state.json` | 현재 워크스페이스 상태 |
| `workspaces/<workspace-key>/codex-panel-endpoint.json` | 현재 워크스페이스 컴패니언 엔드포인트 (Companion endpoint); 파일명은 이전 버전과의 호환성을 유지함 |

| 변수명 | 설명 |
|---|---|
| `WECHAT_ILINK_BASE_URL` | 기본 iLink API 주소 재정의 |
| `CLAUDE_WECHAT_CHANNEL_DATA_DIR` | 기본 데이터 디렉토리 재정의 |
| `WECHAT_MAX_IMAGE_MB` | 이미지 업로드 크기 제한 재정의, 기본 20 MB |
| `WECHAT_MAX_FILE_MB` | 일반 파일 업로드 크기 제한 재정의, 기본 50 MB |
| `WECHAT_MAX_VOICE_MB` | 음성 업로드 크기 제한 재정의, 기본 20 MB |
| `WECHAT_MAX_VIDEO_MB` | 비디오 업로드 크기 제한 재정의, 기본 100 MB |
| `WECHAT_OPENCODE_DEBUG` | OpenCode 어댑터 디버그 출력 활성화 |

다음 명령을 실행하여 새 버전이 있는지 확인하십시오:

`wechat-check-update`

이 명령은 다음을 표시합니다:

- 현재 설치된 버전;
- 원격 저장소의 최신 버전;
- 업데이트가 있는 경우 상세한 업데이트 가이드 제공.

`wechat-bridge` 관련 명령(예: `wechat-bridge-codex`, `wechat-bridge-claude`)을 시작할 때, 프로그램은 자동으로 업데이트를 확인합니다 (24시간마다 1회). 자동 확인은 백그라운드에서 비동기적으로 실행되어 시작 속도에 영향을 주지 않습니다.

npm을 사용하여 전역(Global) 설치를 사용하는 경우, 다음을 직접 실행하는 것을 권장합니다:

`npm install -g @unlinearity/cli-wechat-bridge@latest`

업그레이드 후에는 실행 중인 bridge와 companion 터미널을 재시작하여 동일한 버전이 로드되도록 하십시오.

소스 코드 저장소를 사용하는 경우, 다음 명령을 사용하여 업데이트할 수 있습니다:

cd CLI-WeChat-Bridge
git pull
bun install
...

일반적인 원인은 다음과 같습니다:

- 대응하는 `wechat-bridge-*`를 먼저 시작하지 않음;
- bridge와 companion이 동일한 디렉토리에 있지 않음;
- 현재 워크스페이스 엔드포인트 파일이 존재하지 않거나 이전 프로세스의 것임.

두 터미널이 동일한 디렉토리에 있는지 먼저 확인하는 것을 권장합니다. 수동으로 두 개의 터미널을 나누기 번거롭다면, 대응하는 `wechat-codex-start`, `wechat-claude-start` 또는 `wechat-opencode-start`를 사용하는 방식으로 변경할 수 있습니다.

다음 중 하나를 실행했는지 확인하십시오:

npm install -g @unlinearity/cli-wechat-bridge@latest
npm install -g .
npm link

명령어를 찾을 수 없는 경우, npm 전역 bin 디렉토리가 `PATH`에 추가되었는지 확인하십시오.

프로젝트는 `codex.ps1` 사용을 최대한 피하도록 설계되었습니다:

- 우선적으로 vendor의 `codex.exe`를 찾습니다;
- 필요한 경우 `cmd.exe`를 통해 `codex.cmd`를 래핑(Wrapping)합니다.

로컬 PowerShell 프로필 자체가 실행 정책(Execution Policy) 제한을 받는 경우, 터미널에 관련 경고가 표시될 수 있습니다. 이는 일반적으로 bridge 자체의 결함이 아닙니다.

일반적으로 현재 연락인(Contact)과 사용 가능한 iLink 컨텍스트가 아직 구축되지 않았음을 의미합니다. 보통 소유자(Owner) 계정이 일반 메시지를 하나 보내면 컨텍스트가 구축됩니다.

이 프롬프트는 현재 실제로 활성 작업이 존재할 때만 나타나야 합니다.

간헐적으로 발생하는 경우:

- 로컬 `wechat-codex`가 실제로 여전히 작업을 수행 중인지 먼저 확인하십시오;
- 필요한 경우 `/stop`을 사용하십시오;
- 다음을 확인하십시오:

~/.claude/channels/wechat/bridge.log

먼저 `wechat-bridge-codex`와 `wechat-codex`가 일치하는지 확인하십시오.

모두 동일한 버전으로 재시작되었는지 확인하십시오.

일부 기기에서는 첫 번째 로컬 입력이 WeChat으로 동기화되지 않는 경우가 발생할 수 있으므로, 먼저 WeChat에서 명령어를 전송하여 연결을 구축할 수 있습니다.

`bridge-state.json`이 정상적으로 보이지만 WeChat이 여전히 응답을 받지 못하는 경우, 다음 사항을 우선적으로 확인하십시오:

~/.claude/channels/wechat/bridge.log

로그에 `wechat_send_failed`, `UND_ERR_CONNECT_TIMEOUT` 또는 `ilinkai.weixin.qq.com:443`이 나타난다면, 이는 일반적으로 로컬 CLI가 작업을 완료하지 못한 것이 아니라 bridge에서 iLink로 향하는 아웃바운드 네트워크 또는 프록시(Proxy) 문제입니다. 현재 터미널이 `HTTP_PROXY`, `HTTPS_PROXY`, `ALL_PROXY`를 상속받고 있는지, 그리고 Node가 `NODE_OPTIONS=--use-env-proxy`를 필요로 하는지 확인하십시오.

- WeChat `/resume`은 일시적으로 비활성화되었습니다 (대화 양방향의 불안정성을 초래할 수 있음) - Codex는 하위 수준 작업의 원격 승인(Remote Approval)을 지원하지 않습니다! 권한을 충분히 부여하여 정상적으로 사용하시기를 권장하며, 일반적인 사용 시에는 저수준의 원격 승인을 능동적으로 요청하는 경우가 거의 없습니다. Claude Code는 원격 승인을 지원하지만 테스트가 충분하지 않으므로, 문제가 발생하면 이슈(Issue)를 제기해 주세요.
- 현재 모델은 단일 소유자(Single Owner), 단일 브릿지(Single Bridge), 단일 활성 워크스페이스(Single Active Workspace) 구조입니다.

| 파일 | 역할 |
|---|---|
| `src/bridge/wechat-bridge.ts` | bridge 메인 이벤트 루프 (Event Loop) |
| `src/bridge/bridge-adapters.ts` | `codex` / `claude` / `opencode` / `shell` 어댑터 (Adapter) 엔트리 |
| `src/bridge/bridge-adapters.opencode.ts` | OpenCode 어댑터 구현 |
| `src/companion/local-companion.ts` | `wechat-claude` / `wechat-opencode` 로컬 컴패니언 (Companion) 엔트리 |
| `src/companion/codex-remote-client.ts` | `wechat-codex` 로컬 클라이언트 엔트리 |
| `src/companion/local-companion-start.ts` | `wechat-codex-start` / `wechat-claude-start` / `wechat-opencode-start` 단일 명령 실행 엔트리 |
| `src/wechat/wechat-transport.ts` | iLink 메시지 송수신 |
| `src/bridge/bridge-state.ts` | bridge 상태, 잠금(Lock) 및 로그 |
| `src/wechat/setup.ts` | 로그인 및 자격 증명 (Credential) 초기화 |

`bun test`는 디렉토리별로 실행할 수도 있습니다:

bun run test:bridge
bun run test:companion
bun run test:wechat

현재 테스트는 주로 다음 사항을 다룹니다:

- Windows 시작 파싱 (Parsing)
- Codex 스레드 추적 (Thread Following)
- 세션 로그 폴백 (Session Log Fallback)
- 패널 / 사용 중(Busy) / 완료(Completion) 복구
- 워크스페이스 경로 및 상태 격리

- Linux DO: AI를 배우려면 L站으로!
- openclaw-weixin: Claude Code Channel 지원, 빠른 오픈소스화에 감사드립니다.
- @modelcontextprotocol/sdk: TypeScript 버전 MCP SDK
- node-pty: 로컬 PTY / ConPTY 프로세스 브릿지
- @anthropic-ai/sdk: Anthropic TypeScript SDK
- qrcode-terminal: 터미널 QR 코드 출력

이슈(Issue) 피드백 제공자와 PR 기여자분들께 감사드립니다.

제작이 쉽지 않았습니다. 도움이 되었거나 흥미로우셨다면, 차 한 잔의 여유를 선물해 주세요. ❤️