CodexBridge

CodexBridge is a Codex-centered gateway for connecting multiple chat platforms to one shared Codex engine, while switching backend provider profiles inside Codex when needed.

Current Direction

• First delivery target: WeChat + Codex
• Package-side experiments are paused for now
• packages/codex-gateway is not under active development
• packages/mission-control is not under active development
• packages/codex-native-api is retained as the only package planned for possible future work, but it is also paused for now
• Core rule: platforms are adapters, Codex stays the execution engine, and Codex thread state stays the source of truth

Documents

• Core architecture
• Roadmap TODO
• Codex Native API TODO
• Codex Gateway TODO - paused
• Mission Control TODO - paused
• Mission Control architecture - historical reference
• WeChat slash command reference

Repository Layout

packages/
src/
  core/
  platforms/
  providers/
  runtime/
  store/
test/
docs/

Status

Project bootstrap is now focused on:

1. Keeping WeChat + Codex as the product center
2. Avoiding more backend/package expansion until the bridge direction is clearer
3. Treating codex-gateway and mission-control as paused workstreams
4. Keeping codex-native-api only as a retained future option, not as active work

Current implemented bridge pieces:

• Core session routing with WeChat-friendly slash commands, including /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, and /lang
• /open now rebinds the current scope and immediately returns a short recent-turn preview, so users can resume an old thread with one command instead of calling /peek first
• File-backed JSON repositories for persistent bridge state
• WeChat platform skeleton for Hermes-compatible iLink config loading, QR account state reuse, inbound DM normalization, long-poll client/poller wiring, context-token persistence, text chunking, and outbound text/typing delivery
• Codex profile loader and initial Codex app-server client/plugin path for shared thread execution
• WeChat runtime wiring that feeds poll events into the shared bridge coordinator and sends responses back through the WeChat transport
• OpenAI-compatible Responses adapter for non-OpenAI Chat Completions providers, including compact fallback, SSE stream translation, tool-call repair, provider/model capability rules, and gated live-provider smoke tests

Package workstream status:

• packages/codex-gateway: paused
• packages/mission-control: paused
• packages/codex-native-api: retained for later only; currently paused

OpenAI-Compatible Provider Validation

Live provider validation is opt-in so normal tests do not spend API quota.

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

Supported smoke env names:

DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL / DEEPSEEK_DEFAULT_MODEL
MINIMAX_API_KEY / MINIMAX_BASE_URL / MINIMAX_MODEL
QWEN_API_KEY or DASHSCOPE_API_KEY / QWEN_BASE_URL / QWEN_MODEL
OPENROUTER_API_KEY / OPENROUTER_BASE_URL / OPENROUTER_MODEL
KIMI_API_KEY / KIMI_BASE_URL / KIMI_MODEL
GEMINI_API_KEY / GEMINI_BASE_URL / GEMINI_MODEL
IFLOW_API_KEY / IFLOW_BASE_URL / IFLOW_MODEL

Runtime WebSocket is still disabled for the local OpenAI-compatible adapter until the server grows an upgrade handler. The CLIProxyAPI-style WebSocket transcript/tool-call repair logic is implemented as a tested module first, so enabling WebSocket later has a safe core to call instead of reintroducing transcript corruption.

WeChat Slash Commands

The WeChat bridge now uses a text-first command surface designed for chat, not buttons. Recommended entrypoints:

/helps
/h
/st
/login
/lg
/login list
/review
/rv
/review base main
/plan
/pl
/plan on
/skills
/sk
/skills search 新闻
/skills show 1
/plugins
/pg
/pg search 日记
/pg show 1
/auto
/auto add 每30分钟检查一次系统状态，有变化发送给我
/auto confirm
/auto list
/auto rename 1 晚间部署巡检
/auto del 1
/as 今天修复了 /pg search 日记召回太宽的问题 #CodexBridge
/as 明天上午10点提醒我给王总回电话
/as ok
/as edit 把王总改成李总，时间改成明天上午11点
/log 今天测试微信桥接，发现插件搜索需要更高相关度
/todo 检查服务器磁盘空间
/todo done 1
/remind 每周一早上9点提醒我看项目进度
/note Notion 适合结构化日志，Google Drive 适合导出归档
/helps threads
/stop
/sp
/provider
/pd
/models
/ms
/model
/m
/model 1
/personality
/psn pragmatic
/instructions
/instructions edit
/fast
/fast off
/model gpt-5.4 xhigh
/model high
/threads
/th
/search bridge
/se bridge
/next
/nx
/prev
/pv
/open 2
/o 2
/peek 2
/pk 2
/rename 2 微信桥接排障
/rn 2 微信桥接排障
/model default
/models
/lang
/permissions
/perm
/allow
/al
/allow 1
/allow 2
/deny
/dn
/retry
/rt

/models and /ms

List available models for the current provider profile.

Examples:

/models
/ms

/automation and /auto

Create and manage scheduled background jobs. Results are always delivered back to the same WeChat chat.

Examples:

/auto
/auto add 每30分钟检查一次系统状态，有变化发送给我
/auto add 每天早上7点调用 news skill 给我发送到微信
/auto add 工作日晚上6点检查部署状态，异常时通知我
/auto add 每天早上8点、中午13点、下午17点半，把待办事项整理后发到微信
/auto confirm
/auto edit 只把时间改成每小时，任务内容不变
/auto cancel
/weibo
/weibo top 10
/auto add 每5分钟把微博热搜前10条发给我
/auto list
/auto show 1
/auto pause 1
/auto resume 1
/auto rename 1 晚间部署巡检
/auto delete 1
/auto del 1

/as, /log, /todo, /remind, and /note

Personal assistant records for WeChat. /as is the natural-language entry for logs, todos, reminders, and notes. It asks Codex to decide whether the message is a new record or a management action on an existing record; local keyword rules are only a conservative fallback when the provider is unavailable. /log, /todo, /remind, and /note remain shortcuts when you want to force a category.

Examples:

/as 今天修复了 /pg search 日记召回太宽的问题 #CodexBridge
/as 明天上午10点提醒我给王总回电话
/as ok
/as 给王总回电话这件事已经完成了
/as ok
/as 修马桶发票已经拿回来了
/as edit 备注：还差医药发票不确定
/as ok
/log 今天测试微信桥接，发现插件搜索需要更高相关度
/todo 检查服务器磁盘空间
/todo done 1
/remind 每周一早上9点提醒我看项目进度
/note Notion 适合结构化日志，Google Drive 适合导出归档

/as also manages existing records with natural language. Codex first routes the message as create, update, complete, cancel, or archive. It only targets an existing record when the message clearly refers to the same concrete item; otherwise it creates a new log/todo/reminder/note. Existing-record changes are shown as a pending draft and are only written after /as ok. Use /as edit <change instruction> to refine that pending update draft, or /as cancel to discard it.

For natural-language updates, the bridge prefers a short-lived Codex app-server rewrite thread, so the host Codex subscription handles the “original record + modification instruction” merge. API-key based Agents SDK normalization is only a fallback when Codex normalization is unavailable; local rules are the final fallback.

/up can stage files first. If the final message is /as, /log, /todo, /remind, or /note, the staged files are archived onto the assistant record under ~/.codexbridge/assistant/attachments/YYYY/MM/DD/<recordId>/; structured records are stored in ~/.codexbridge/runtime/assistant_records.json.

Boundary: /remind only notifies, /todo tracks user-owned work, and /auto runs scheduled system work.

/plan and /pl

Inspect or switch the session-level collaboration mode for future turns.

Examples:

/plan
/pl
/plan on
/plan off

/plan on enables native plan mode for later turns in the current bridge session. /plan off restores the native default collaboration mode. This is a mode toggle, not an approval flow.

OpenAI-compatible runtime adapter:

• CodexBridge can expose non-OpenAI providers through a local Responses adapter while Codex app-server still talks to a Responses-shaped endpoint.
• The adapter now handles /responses/compact, Chat Completions conversion, stream error mapping, CLIProxyAPI top-level stream error chunks, stream read failure framing, configured transient upstream retry, usage fallback including Gemini-family usageMetadata, provider/model thinking policy, CLIProxyAPI-style payload compatibility (default, default-raw/defaultRaw, override, override-raw/overrideRaw, filter, root, protocol/model matching), multimodal input capability flags, and model capability metadata.
• DeepSeek, MiniMax, Qwen, OpenRouter, Kimi, Gemini, and iFlow are loaded as providerKind: openai-compatible; they differ by env vars and capability presets only, not separate provider plugin classes.
• The model capability catalog follows the same direction as CLIProxyAPI: model quirks are represented as data (thinking, payload, tool support, multimodal support, token caps), while the executor stays generic.
• Current built-in catalog covers the CLIProxyAPI model families used by Codex-style routing: Codex, DeepSeek, MiniMax, Qwen, iFlow, Kimi, OpenRouter, Gemini/AI Studio/Vertex, Claude, and Antigravity. *_MODEL_CATALOG_PATH can also point at a CLIProxyAPI models.json-shaped catalog object; CodexBridge flattens it and merges model token/thinking metadata into runtime capabilities. Native auth/header systems from CLIProxyAPI are not copied into this adapter; use provider env vars or the custom CODEX_COMPAT_* profile for deployment-specific credentials.
• Auth pools, proxy rotation, and custom provider header management remain deployment-layer concerns and are intention