Gan-Xing/CodexBridge

CodexBridge는 여러 채팅 플랫폼을 하나의 공유된 Codex 엔진에 연결하는 동시에, 필요할 때 Codex 내부의 백엔드 제공자 프로필(backend provider profiles)을 전환할 수 있는 Codex 중심의 게이트웨이입니다.

• 첫 번째 인도 대상:
  WeChat + Codex

• 패키지 측 실험은 현재 일시 중단되었습니다
  packages/codex-gateway는 현재 활발히 개발 중이지 않습니다.
  packages/mission-control은 현재 활발히 개발 중이지 않습니다.
  packages/codex-native-api는 향후 작업을 위해 계획된 유일한 패키지로 유지되지만, 이 또한 현재는 일시 중단된 상태입니다.

• 핵심 규칙: 플랫폼은 어댑터(adapters)이며, Codex는 실행 엔진(execution engine)으로 유지되고, Codex 스레드 상태(thread state)가 신뢰할 수 있는 유일한 원천(source of truth)으로 유지됩니다.

• 핵심 아키텍처 (Core architecture)

• 로드맵 TODO (Roadmap TODO)

• Codex Native API TODO

• Codex Gateway TODO - 일시 중단됨

• Mission Control TODO - 일시 중단됨

• Mission Control 아키텍처 - 역사적 참조 (historical reference)

• WeChat 슬래시 명령어 참조 (WeChat slash command reference)

packages/
src/
core/
...

프로젝트 부트스트랩(Project bootstrap)은 현재 다음 사항에 집중하고 있습니다:

• WeChat + Codex를 제품의 중심으로 유지
• 브리지(bridge)의 방향이 더 명확해질 때까지 추가적인 백엔드/패키지 확장을 지양
• codex-gateway와 mission-control을 일시 중단된 워크스트림(workstreams)으로 취급
• codex-native-api를 활발한 작업이 아닌, 유지된 미래의 옵션으로만 관리

현재 구현된 브리지 구성 요소:

• WeChat 친화적인 슬래시 명령어(slash commands)를 포함한 핵심 세션 라우팅(Core session routing). 명령어 목록:
  /helps, /status, /usage, /login, /stop, /review, /plan, /skills, /plugins, /automation, /weibo, /new, /uploads, /as, /log, /todo, /remind, /note, /provider, /models, /model, /personality, /instructions, /fast, /threads, /search, /next, /prev, /open, /peek, /rename, /permissions, /allow, /deny, /reconnect, /retry, /restart, 그리고 /lang

/open 명령어는 이제 현재 범위를 다시 바인딩(rebinds)하고 즉시 짧은 최근 턴 미리보기를 반환하므로, 사용자가 /peek을 호출하는 대신 하나의 명령어로 이전 스레드를 재개할 수 있습니다.

• 영구적인 브리지 상태 (bridge state)를 위한 파일 기반 (File-backed) JSON 저장소
• Hermes 호환 iLink 설정 로딩, QR 계정 상태 재사용, 인바운드 DM 정규화 (normalization), 롱 폴링 (long-poll) 클라이언트/폴러 (poller) 배선, 컨텍스트 토큰 (context-token) 영속성, 텍스트 청킹 (chunking), 그리고 아웃바운드 텍스트/타이핑 전달을 위한 WeChat 플랫폼 스켈레톤 (skeleton)
• 공유 스레드 실행을 위한 Codex 프로필 로더 및 초기 Codex 앱 서버 클라이언트/플러그인 경로
• 폴링 (poll) 이벤트를 공유 브리지 코디네이터 (bridge coordinator)에 공급하고 WeChat 전송 계층 (transport)을 통해 응답을 다시 보내는 WeChat 런타임 배선
• 비 OpenAI Chat Completions 제공자를 위한 OpenAI 호환 응답 (Responses) 어댑터 (compact fallback, SSE 스트림 변환, 도구 호출 (tool-call) 복구, 제공자/모델 기능 규칙, 그리고 게이트형 라이브 제공자 스모크 테스트 (gated live-provider smoke tests) 포함)

패키지 워크스트림 (workstream) 상태:

packages/codex-gateway : 일시 중지 (paused)
packages/mission-control : 일시 중지 (paused)
packages/codex-native-api : 나중을 위해 유지; 현재 일시 중지 (paused)

라이브 제공자 검증은 선택 사항 (opt-in)이므로 일반 테스트는 API 할당량 (quota)을 소모하지 않습니다.

CODEXBRIDGE_TEST_LIVE_OPENAI_COMPATIBLE=1 pnpm exec tsx --test test/providers/openai_compatible/live_provider_smoke.test.ts

지원되는 스모크 (smoke) 환경 이름:

DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_DEFAULT_MODEL
MINIMAX_API_KEY / MINIMAX_BASE_URL / MINIMAX_MODEL
QWEN_API_KEY 또는 DASHSCOPE_API_KEY / QWEN_BASE_URL / QWEN_MODEL
...

서버에 업그레이드 핸들러 (upgrade handler)가 추가될 때까지 로컬 OpenAI 호환 어댑터에 대한 런타임 웹소켓 (WebSocket)은 여전히 비활성화되어 있습니다. CLIProxyAPI 스타일의 웹소켓 전사 (transcript)/도구 호출 (tool-call) 복구 로직은 먼저 테스트된 모듈로 구현되었으므로, 나중에 웹소켓을 활성화하더라도 전사 데이터 손상 (transcript corruption)을 재발시키지 않고 호출할 수 있는 안전한 코어를 갖추게 됩니다.

WeChat 브리지는 이제 버튼이 아닌 채팅을 위해 설계된 텍스트 우선 명령 인터페이스 (command surface)를 사용합니다. 권장되는 진입점 (entrypoints):

/helps
/h
/st
...

현재 제공자 프로필에 대해 사용 가능한 모델 목록을 표시합니다.

예시:

/models
/ms

예약된 백그라운드 작업 (background jobs)을 생성하고 관리합니다. 결과는 항상 동일한 WeChat 채팅으로 전달됩니다.

예시:

/auto
/auto add 每30分钟检查一次系统状态，有变化发送给我
/auto add 每天早上7点调用 news skill 给我发送到微信
...

WeChat용 개인 비서 기록. /as는 로그 (logs), 할 일 (todos), 알림 (reminders), 그리고 노트 (notes)를 위한 자연어 입력 방식입니다. Codex가 해당 메시지가 새로운 기록인지, 아니면 기존 기록에 대한 관리 작업인지를 결정하도록 요청합니다. 로컬 키워드 규칙은 제공자 (provider)를 사용할 수 없을 때를 대비한 보수적인 대체 수단 (fallback)일 뿐입니다. 카테고리를 강제하고 싶을 때는 /log, /todo, /remind, /note가 바로가기 (shortcuts)로 유지됩니다.

예시:

/as 今天修复了 /pg search 日记召回太宽的问题 #CodexBridge
/as 明天上午10点提醒我给王总回电话
/as ok
...

/as는 자연어를 사용하여 기존 기록도 관리합니다. Codex는 먼저 메시지를 생성 (create), 업데이트 (update), 완료 (complete), 취소 (cancel), 또는 아카이브 (archive)로 라우팅 (route)합니다. 메시지가 명확하게 동일한 구체적 항목을 참조할 때만 기존 기록을 대상으로 하며, 그렇지 않으면 새로운 로그/할 일/알림/노트를 생성합니다. 기존 기록의 변경 사항은 대기 중인 초안 (pending draft)으로 표시되며, /as ok 이후에만 기록됩니다. 대기 중인 업데이트 초안을 수정하려면 /as edit <변경 지침>을 사용하고, 이를 폐기하려면 /as cancel을 사용하세요.

자연어 업데이트의 경우, 브릿지 (bridge)는 수명이 짧은 Codex 앱-서버 재작성 스레드 (rewrite thread)를 선호하므로, 호스트 Codex 구독이 "원본 기록 + 수정 지침" 병합을 처리합니다. API 키 기반의 Agents SDK 정규화 (normalization)는 Codex 정규화를 사용할 수 없을 때만 대체 수단으로 사용되며, 로컬 규칙이 최종적인 대체 수단입니다.

/up을 사용하여 파일을 먼저 스테이징 (stage)할 수 있습니다. 최종 메시지가 /as, /log, /todo, /remind, 또는 /note인 경우, 스테이징된 파일은 ~/.codexbridge/assistant/attachments/YYYY/MM/DD/<recordId>/ 경로 아래의 비서 기록으로 아카이브됩니다. 구조화된 기록은 ~/.codexbridge/runtime/assistant_records.json에 저장됩니다.

경계 (Boundary): /remind는 알림만 수행하고, /todo는 사용자가 소유한 작업을 추적하며, /auto는 예약된 시스템 작업을 실행합니다.

향후 턴(turn)을 위해 세션 수준의 협업 모드 (collaboration mode)를 검사하거나 전환합니다.

예시:

/plan
/pl
/plan on
...

/plan on은 현재 브리지 세션의 이후 턴들을 위해 네이티브 plan 모드를 활성화합니다. /plan off는 네이티브 default 협업 모드로 복구합니다. 이는 모드 토글 (mode toggle)이며, 승인 흐름 (approval flow)이 아닙니다.

OpenAI 호환 런타임 어댑터 (OpenAI-compatible runtime adapter):

• Codex 앱 서버가 여전히 Responses 형태의 엔드포인트 (endpoint)와 통신하는 동안, CodexBridge는 로컬 Responses 어댑터를 통해 비(非) OpenAI 제공자 (providers)를 노출할 수 있습니다.
• 어댑터는 이제 /responses/compact, Chat Completions 변환, 스트림 오류 매핑 (stream error mapping), CLIProxyAPI 최상위 스트림 오류 청크 (stream error chunks), 스트림 읽기 실패 프레이밍 (stream read failure framing), 구성된 일시적 업스트림 재시도 (transient upstream retry), Gemini 제품군(Gemini-family)의 usageMetadata를 포함한 사용량 폴백 (usage fallback), 제공자/모델 사고 정책 (provider/model thinking policy), CLIProxyAPI 스타일의 페이로드 호환성 (default, default-raw/defaultRaw, override, override-raw/overrideRaw, filter, root, 프로토콜/모델 매칭), 멀티모달 입력 기능 플래그 (multimodal input capability flags), 그리고 모델 기능 메타데이터 (model capability metadata)를 처리합니다.
• DeepSeek, MiniMax, Qwen, OpenRouter, Kimi, Gemini, iFlow는 providerKind: openai-compatible로 로드됩니다. 이들은 별도의 제공자 플러그인 클래스가 아닌, 환경 변수 (env vars)와 기능 프리셋 (capability presets)에 의해서만 구분됩니다.
• 모델 기능 카탈로그 (model capability catalog)는 CLIProxyAPI와 동일한 방향을 따릅니다. 모델의 특이 사항 (quirks)은 데이터(thinking, payload, 도구 지원, 멀티모달 지원, 토큰 제한)로 표현되는 반면, 실행기 (executor)는 범용성을 유지합니다.
• 현재 내장된 카탈로그는 Codex 스타일의 라우팅 (routing)에서 사용되는 CLIProxyAPI 모델 제품군을 다룹니다: Codex, DeepSeek, MiniMax, Qwen, iFlow, Kimi, OpenRouter, Gemini/AI Studio/Vertex, Claude, 그리고 Antigravity.
• *_MODEL_CATALOG_PATH는 CLIProxyAPI의 models.json 형태의 카탈로그 객체를 가리킬 수도 있습니다. CodexBridge는 이를 평탄화 (flatten)하고 모델 토큰/사고 메타데이터를 런타임 기능 (runtime capabilities)으로 병합합니다. CLIProxyAPI의 네이티브 인증/헤더 시스템은 이 어댑터로 복사되지 않습니다. 제공자 환경 변수 또는 커스텀 CODEX_COMPAT_*를 사용하십시오.

배포별 자격 증명(credentials)을 위한 프로필입니다. - 인증 풀(Auth pools), 프록시 로테이션(proxy rotation), 그리고 커스텀 제공자 헤더 관리(custom provider header management)는 배포 계층(deployment-layer)의 관심사로 남으며, 일반적인 OpenAI 호환 어댑터(OpenAI-compatible adapter)와는 의도적으로 분리되어 있습니다.

런타임 제공자(Runtime provider) 예시:

DEEPSEEK_API_KEY=...
DEEPSEEK_DEFAULT_MODEL=deepseek-v4-flash
MINIMAX_API_KEY=...
...

이후 턴(turns)에 사용될 모델을 확인하거나 전환하십시오.

예시:

/model
/m
/model default
...

모든 슬래시 명령어(slash commands)는 명령어 범위 내의 도움말 플래그(help flags)를 지원합니다:

/threads -h
/open --help
/permissions -helps

권장 사항(Best-practice rule):

• 명령어 탐색을 위해 /helps를 사용하십시오.
• /login <index>로 계정을 전환하기 전에, 호스트 Codex 계정 풀(account pool)을 관리하려면 /login 및 /login list를 사용하십시오.
• 현재 스레드 바인딩(thread binding)을 변경하지 않고 네이티브 Codex 코드 리뷰(code review)를 수행하려면 /review, /review base <branch>, 또는 /review commit <sha>를 사용하십시오.
• 현재 세션의 이후 턴에서 계획(planning)을 우선시하려면 /plan on을 사용하고, 기본 협업 모드(collaboration mode)로 복구하려면 /plan off를 사용하십시오.
• Codex가 현재 활성 프로젝트에서 무엇을 볼 수 있는지 검사하려면 /skills를 사용하고, 관련 매칭 항목을 찾으려면 /skills search <keyword>를, 기능을 활성화하거나 비활성화하기 전에 해당 기능이 무엇인지 이해하려면 /skills show <index>를 사용하십시오.
• 먼저 자연어로 /auto add ...를 사용하십시오. 그러면 브릿지(bridge)가 일정을 초안으로 작성하며, 이후 /auto confirm이 작업을 생성합니다.
• WeChat에서는 원시 스레드 ID(raw thread ids)를 복사하는 대신 /threads와 숫자 인덱스(numeric indexes)를 사용하십시오.
• 현재 범위(scope) 내의 이후 턴에 대한 응답 스타일(response style)을 제어하려면 /personality를 사용하십시오.
• 활성 Codex AGENTS.md 커스텀 지침(custom instructions) 파일을 관리하려면 /instructions를 사용하십시오.
• 현재 범위의 응답 언어를 전환하려면 /lang zh-CN 또는 /lang en을 사용하십시오.
• Codex가 턴 중간에 승인을 요청할 때, 승인하려면 /allow 1 또는 /allow 2를 사용하고, 거부하려면 /deny를 사용하십시오.
• /retry를 사용하십시오.

중단된 턴 이후에 사용하십시오. 먼저 현재 Codex 세션을 새로고침한 다음, 동일한 스레드에서 이전 요청을 다시 실행합니다. 정확한 사용법과 예시가 필요한 경우 다음을 사용하십시오:
/helps <command>

전체 명령어 참조는 docs/usage/weixin-slash-commands.md를 확인하십시오.

npm install
npm run typecheck
npm test

검증 스위트 (validation suite)는 Linux와 Windows 모두에서 통과할 것으로 예상됩니다.

npm test는 격리된 기본 테스트 엔트리포인트 (entrypoint)입니다. 이는 node --test를 시작하기 전에 CODEXBRIDGE_AGENT_*, OPENAI_*, MINIMAX_API_KEY와 같은 라이브 에이전트 제공자 변수들을 삭제하므로, 호스트 셸, CI 러너 (CI runner), 또는 서비스 매니저가 실제 모델 자격 증명 (credentials)을 내보내더라도 단위 테스트 (unit test) 및 통합 테스트 (integration test)가 결정론적 (deterministic)인 상태를 유지할 수 있게 합니다.

라이브 에이전트 자격 증명을 의도적으로 유지하고 실제 외부 에이전트 경로를 실행하려면, 대신 명시적인 옵트인 (opt-in) 스크립트를 사용하십시오:

npm run test:live-agent

test:live-agent는 메인 스위트와 분리하여 유지하십시오. 이는 기본 npm test 게이트 (gate) 용도가 아니라, 의도적인 제공자 기반 검증 (provider-backed verification)을 위한 것입니다.

• Node.js >= 24
• npm
• 호스트에 작동하는 Codex CLI 로그인 상태

클론 (cloning) 후 권장되는 첫 번째 확인 사항:

npm install
npm run typecheck
npm test
...

Codex CLI가 아직 설치되지 않은 경우, 먼저 설치하십시오:

npm install -g @openai/codex@latest --include=optional
codex --version

codex --version이 여전히 실패한다면, weixin:login 또는 weixin:serve를 시도하기 전에 이를 먼저 해결하십시오.

npm install
npm run typecheck
npm test
...

장시간 실행되는 배포의 경우, 터미널 창을 열어두는 대신 아래에 설명된 서비스 매니저 흐름을 권장합니다.

저장소 루트에서 PowerShell을 열고 실행하십시오:

npm install
npm run typecheck
npm test
...

호스트의 PATH에 여러 개의 Codex 심 (shim)이 있는 경우, 브릿지를 시작하기 전에 실제 네이티브 바이너리 (native binary)를 명시적으로 설정하십시오:

$env:CODEX_REAL_BIN = (Get-Command codex.exe).Source
npm run weixin:serve -- --cwd C:\absolute\path\to\workspace

유용한 선택적 디버그 플래그 (debug flag):

$env:CODEXBRIDGE_DEBUG_WEIXIN = '1'

첫 번째 Windows 브링업 (bring-up) 과정에서 네 가지 플랫폼 특화 이슈가 발견되었습니다:

• 명령 발견 (Command discovery):
  프로바이더 설정 (provider config)이 원래 Unix 스타일의 명령 검색을 가정했습니다. 이제 로더 (loader)는 Windows 실행 파일을 직접 해결하며, 두 가지가 모두 존재할 경우 래퍼 스크립트 (wrapper script)보다 네이티브 codex.exe 또는 .com 바이너리를 우선시합니다. - Windows 실행 래퍼 (Windows launch wrappers):
  호스트가 codex.cmd 또는 codex.bat만 노출하는 경우, 브릿지 (bridge)는 spawn(...) 도중 실패하는 대신 Windows 셸 명령줄을 통해 해당 래퍼를 실행합니다. - 시작 진단 (Startup diagnostics):
  Codex를 실행할 수 없는 경우, 브릿지는 단순히 가공되지 않은 spawn codex ENOENT 오류를 남기는 대신 CODEX_REAL_BIN / codex.exe / codex.cmd에 대한 직접적인 힌트와 함께 실패합니다. - 스레드 실체화 (Thread materialization):
  Codex 세션 저장소로부터의 일시적인 빈 세션 파일 (empty session file) 읽기는 이제 치명적인 턴 실패 (fatal turn failures)로 처리되는 대신 자동으로 재시도됩니다.