CodexBridge: running Codex app-server from WeChat

The problem CodexBridge targets: one Codex engine, many chat front ends

Most chat-to-model bridges treat the chat platform as the system of record. CodexBridge inverts that. The README states the core rule directly: platforms are adapters, Codex stays the execution engine, and Codex thread state stays the source of truth. That single sentence explains almost every design decision in the repository.

The intended audience is narrow. You need a working Codex app-server, a WeChat account you can drive through an iLink-compatible client, and enough patience to run a TypeScript project from source rather than install a binary. The README names the first delivery target as WeChat plus Codex and says package-side experiments are paused. This is a personal-scale tool, not a multi-tenant service.

The payoff is that thread continuity lives in Codex, not in the bridge. If you open a thread from WeChat today and from another client tomorrow, the bridge is not holding a divergent copy of the conversation. That is a real architectural commitment, and it is also the reason the project cannot easily support chat platforms that want to own conversation state.

How the bridge routes WeChat messages into a Codex thread

The repository layout splits the code into core, platforms, providers, runtime, and store directories under src. The README describes the runtime as wiring that feeds poll events into a shared bridge coordinator and sends responses back through the WeChat transport. So the flow is roughly: the WeChat poller receives a direct message, the platform layer normalizes it into an inbound event, the coordinator resolves which Codex thread and provider profile the message belongs to, the Codex app-server client executes it, and the reply is chunked and sent back as text.

State persistence is file-backed. The README says the project uses file-backed JSON repositories for persistent bridge state, and separately mentions context-token persistence in the WeChat platform skeleton. That is a deliberate simplicity choice: no database to provision, but also no concurrency story beyond what the file layer provides.

The provider layer is where the project gets more interesting. There is an OpenAI-compatible Responses adapter for non-OpenAI Chat Completions providers, and the README lists its responsibilities: compact fallback, SSE stream translation, tool-call repair, provider and model capability rules, and gated live-provider smoke tests. The README also states that runtime WebSocket is still disabled for the local OpenAI-compatible adapter until the server grows an upgrade handler, and that the CLIProxyAPI-style WebSocket transcript and tool-call repair logic exists as a tested module first. That is an unusually honest way to describe unfinished work.

Installing CodexBridge and sending your first WeChat command

The README does not give a step-by-step install guide. It gives the repository layout, a package.json with scripts, and Windows batch entry points at the top level: start-weixin-login.cmd, start-weixin-serve.cmd, and install-weixin-service-after-login.cmd. The package.json declares the project private and version 0.1.0, with start mapped to tsx src/index.ts. So the realistic path is to clone the repository and run it from source with pnpm.

Start by installing dependencies and building. The build script runs the TypeScript compiler against tsconfig.json.

pnpm install
pnpm run build

To launch the bridge directly from source, the package.json start script is the entry point. On Windows the batch files wrap the same flow, with the login script handling the WeChat login step before the serve script starts the runtime.

pnpm start

Once the bridge is running, the README's recommended entrypoint is a text-first command surface. The first command to try is the help command, which the README lists alongside its short alias.

/helps

From there, the README shows a short status alias and a login command with a list variant for choosing an account.

/st
/login list

Threads are resumed by number rather than by pasting a thread id. The README notes that /open now rebinds the current scope and immediately returns a short recent-turn preview, so you can resume an old thread with one command instead of calling /peek first.

/threads
/open 2

If you want to validate a non-OpenAI provider before trusting it with real work, the README documents an opt-in smoke test that is gated so normal test runs do not spend API quota.

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

The README lists the supported environment variable names for that test, including DEEPSEEK_API_KEY, MINIMAX_API_KEY, QWEN_API_KEY or DASHSCOPE_API_KEY, OPENROUTER_API_KEY, KIMI_API_KEY, GEMINI_API_KEY, and IFLOW_API_KEY, each with a matching BASE_URL and model variable. It does not document what a passing run prints, so treat the test output as the thing to read rather than something the README pre-describes.

The slash command surface is the product, and it is large

The README enumerates roughly forty commands with aliases: /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. Most have one or two short aliases. That breadth is the strongest argument for the project and also its largest maintenance liability.

A few commands deserve attention because they show the design intent. /automation creates scheduled background jobs, and the README states results are always delivered back to the same WeChat chat. The examples include natural-language schedules such as a job that checks system status every thirty minutes and only reports when something changes, and a job that collects Weibo hot search results. /as is the natural-language entry for logs, todos, reminders, and notes: the README says Codex decides whether a message is a new record or a management action on an existing record, with local keyword rules used only as a conservative fallback when the provider is unavailable. Existing-record changes are shown as a pending draft and written only after /as ok.

That draft-then-confirm pattern is the most thoughtful thing in the command surface. It acknowledges that a language model routing a message like a reminder edit can be wrong, and it puts a confirmation step between the model's guess and the stored record. /log, /todo, /remind, and /note remain as shortcuts when you want to force a category instead of letting the router decide.

What is paused, and why that matters before you adopt it

The README is unusually explicit about scope cuts. 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. The status section repeats the same three statuses. There are no releases retrieved for the repository.

The last push to the default branch was on 2026-06-24. That is roughly three months before the date this article was written, which is recent enough that the project is not abandoned, but the README's own status language is the better signal: this is a bootstrap, and the author is deliberately avoiding more backend and package expansion until the bridge direction is clearer.

Practically, that means the package.json scripts for mission-control, codex-gateway, codex-native-api, and codex-provider-relay exist but point at workstreams the README labels paused. If you build a dependency on any of them, you are depending on code the author has said is not moving. The safe surface is the WeChat plus Codex path described in the current implemented bridge pieces list.

The other limitation is the disabled WebSocket path in the OpenAI-compatible adapter. The README says runtime WebSocket is still disabled until the server grows an upgrade handler, and that the repair logic is implemented as a tested module first. That is a sensible sequencing choice, but it means the adapter's behaviour over WebSocket is not something you can rely on today.

CodexBridge compared with a generic chat-to-LLM bot

A generic chat bot typically owns the conversation: it stores message history in its own database, calls a model API per message, and treats the chat thread as the unit of context. CodexBridge does the opposite. It routes to a Codex app-server and treats the Codex thread as the unit of context, with the bridge holding only routing state and file-backed JSON repositories.

The difference shows up in failure modes. A generic bot that loses its database loses the conversation. CodexBridge that loses its JSON state loses the binding between a WeChat scope and a Codex thread, but the Codex thread itself still exists and can be reopened with /open and a number. The README's note that /open rebinds the current scope and returns a recent-turn preview is exactly the recovery path for that scenario.

The trade-off runs the other way too. A generic bot works with any model endpoint that speaks HTTP. CodexBridge requires a Codex app-server to be running and reachable, which is a heavier dependency than an API key. If your team does not already run Codex app-server, the bridge is the wrong starting point; you would be adopting two systems to get one outcome.

Licence, maintenance and upgrade cost

The repository metadata does not include a licence, and the README does not mention one. The package.json marks the project private and version 0.1.0. Without a licence file, the default copyright position applies, which means you should not assume you have redistribution or commercial-use rights. That is a factual gap, not a legal opinion; if you need clarity, the repository is the place to ask for it.

Upgrade cost is dominated by the command surface. Roughly forty commands with aliases are documented in the README and in docs/usage/weixin-slash-commands.md. Any change to a command name, an alias, or the draft-then-confirm semantics of /as is a user-visible break. Because the project has no releases retrieved, there is no changelog to diff against; you would be tracking the main branch.

The paused packages reduce one kind of cost and increase another. You do not have to keep codex-gateway or mission-control in sync with anything, because they are not moving. But the package.json scripts for them remain, so a naive pnpm run of every script will build and typecheck code the README says is paused. Read the status section before wiring CI around the full script list.

Editorial conclusion

Adopt CodexBridge only if you already run Codex app-server and want a chat front end for it, and you are comfortable with a bootstrap-stage repository whose gateway and mission-control packages are paused. Skip it if you need a packaged installer, a documented licence, or a stable command surface. Before you commit, run the live provider smoke test against your own provider keys and read docs/usage/weixin-slash-commands.md end to end, because the README's command list is the contract you are depending on.

Frequently asked questions

Official sources

1. Gan-Xing/CodexBridge on GitHub
2. Issues
3. Project website
4. README