WeClaw is a Codex-only bridge with a local Vue 3 / TypeScript / Tencent TDesign management page. Python handles WeChat iLink, durable routing, events and request answers; the official Codex App Server executes tasks through asynchronous stdio JSON-RPC.
See the Chinese guide, capability matrix and Windows cutover guide for operating details.
The maintained branch is master. See the changelog and v2.0.0 release notes for migration requirements and verified limits. Distribution assets are published under GitHub Releases.
WeChat iLink ↔ Python + SQLite ↔ official Codex App Server ↔ local workspace
↕
Vue + TDesign UI
The old codex exec adapter, Claude and other agent providers, ACP/HTTP agent switching and broadcasts are removed. The official runtime is still required and is pinned to openai-codex-cli-bin==0.162.1; a global npm Codex installation is not required. This UI is supplied by WeClaw, not by the App Server package.
Use Python 3.13, uv and Node.js 24. Dependencies are locked in uv.lock and web/package-lock.json.
Clone the maintained branch before building:
git clone --branch master https://github.com/creamtea47/weclaw.git
cd weclawnpm --prefix web ci
npm --prefix web run build
uv sync --frozen
uv run python -c "import shutil; shutil.copytree('web/dist','src/weclaw/static',dirs_exist_ok=True)"
uv run weclaw start --port 18012Run uv run weclaw web in a second terminal to open the authenticated management page. The token is read from the protected state directory and passed through a URL fragment, never printed. After authentication the UI clears the fragment and uses a same-origin HttpOnly cookie.
start runs in the foreground and does not poll WeChat by default. Explicit start --wechat enables real polling; on Windows it refuses to do so while the old weclaw.exe is running. Do not run two pollers for the same Bot.
Commands: start, stop, status, web, login, send, migrate, version. login opens the management page for QR pairing. stop requests graceful shutdown using the current instance ID and never kills another process by name or stale PID. All commands accept --state-dir; start also accepts --cwd, --port, --no-codex and explicit --wechat.
Windows scripts/install.ps1 prepares %LOCALAPPDATA%\WeClaw\next without changing the old scheduled task or starting polling. migrate first backs up old configuration, credentials, sync cursors and session mappings into the protected v2 state directory. Legacy mappings lack a Bot dimension, so choose their Bot explicitly in the UI before cutover. scripts/switch.ps1 is a separate manual step that snapshots the scheduled task XML, preserves triggers/principal, changes its action, and starts it only with -Start.
The installer forces project reinstallation and hashes the actual installed backend/frontend against the source build. An unchanged 2.0.0 version string is insufficient proof that a newer same-version repair was installed.
State defaults to ~/.weclaw/v2; use WECLAW_STATE_DIR to isolate tests or previews. Model/provider and credentials stay under the official CODEX_HOME (default ~/.codex); WECLAW_CWD selects the workspace and WECLAW_PORT selects the local port. When no explicit workspace is supplied, the CLI can inherit the imported legacy Codex workspace.
The compatibility defaults remain danger-full-access and never approval. Review the allowed WeChat senders before enabling polling. Threads have their own workspace, model and supported permission settings. Full-access execution uses the current OS user's file and command privileges.
Public /health checks liveness; /ready separately checks Codex and enabled WeChat accounts. Business /api/* endpoints require a local administrator token or session. POST /api/send preserves to, text, media_url and adds account_id; it needs a stored conversation context and rejects ambiguous multi-account routing. SSE, thread operations, uploads and request answers use the same local authenticated service.
WeChat text follows Tencent's partial Markdown support by default: supported formatting is preserved, and only incompatible markers are filtered. The same rule applies to model replies, history and proactive messages, with no Markdown toggle. Images are sent as media; fenced examples do not trigger uploads. Client rendering and the retained syntax are separate acceptance checks; see the capability matrix.
The bridge stores account-scoped sync cursors, inbox/outbox state and thread mappings in SQLite. Official Codex owns the full conversation history. Interrupted operations with unknown results are marked for review rather than automatically replayed. Logs rotate and contain timestamps, levels and operational identifiers, not tokens or message contents. Uploaded local paths must remain under their authorized roots after symlink resolution.
uv run ruff check src tests
uv run pytest -q
npm --prefix web run typecheck
npm --prefix web test
npm --prefix web run build
uv build
docker build -t weclaw:2 .CI runs Windows/Linux Python checks and offline tests, frontend checks, wheel/static-file checks, and the Linux image build. Releases contain a Python wheel and source archive. The Docker image runs in the foreground as UID 10001, requires writable state/workspace/Codex volumes, and does not enable WeChat polling by default.
Protocol coverage is documented separately from real acceptance. Current provider compatibility, legacy conversation restoration, real QR pairing and media exchange require live verification; passing mocks or building a package does not establish those outcomes.
Evidence recorded on 2026-10-13 includes text continuation of the legacy thread, PNG/TXT delivery and TXT ingestion visible in WeChat. The paired image retry correctly identified the green left half and white right half. An earlier provider stream interruption remains recorded as failed; successful retries do not establish a permanent upstream fix. See the verification record for evidence and remaining limits.