workbuddy2api-panel: an OpenAI-compatible gateway for Tencent CodeBuddy accounts

The gap workbuddy2api-panel fills

Tencent's CodeBuddy, referred to in this project as WorkBuddy, does not publish an OpenAI-shaped API. The README states that the gateway obtains account credentials through OAuth device authorization, then handles token refresh, account scheduling and traffic governance on the server side, so that existing SDKs, front ends and tools connect without modification. That is the whole pitch: one self-hosted process that speaks /v1/chat/completions and fans requests out across several personal accounts.

The intended user is an individual with more than one CodeBuddy account, not a team. The README frames the scope as "personal multi-account": shared capacity, automatic account switching when one fails, cooldown and circuit breaking to prevent a cascade, and session stickiness so multi-turn context does not jump between accounts. A single-account user gains little beyond the OpenAI shim itself.

Account selection, cooldown and session stickiness

Selection is weighted random over three factors: credit share times ten, an idle bonus, and success rate times three. The README says the scheduler takes the top five candidates and applies an anti-thundering-herd guard. That is a reasonable shape for a small pool, though it means a freshly added account with a large credit balance will absorb a disproportionate share of traffic until its success rate and idle figures catch up.

Failure handling is tiered by status code. A 429 triggers a soft cooldown starting at 600 seconds with exponential backoff, capped by soft_rate_max. A 404 gets a fixed 60-second cooldown. A 402 puts the account into a hard cooldown until 04:00 the next day. Repeated failures trip the circuit breaker, and in-flight leases limit concurrency. The 402 rule is the interesting one: it treats insufficient credit as a daily condition rather than a transient error, which matches how the vendor resets quotas but also means an account that is topped up at 10:00 stays parked until the following morning unless the balance refresh job unfreezes it.

Session stickiness binds a conversation_id to one account with a rolling TTL, and unbinds on failure. When a client does not send conversation_id, a fork-specific fallback derives a session key from a hash of the system prompt plus the first user message, prefixed with d-, so generic OpenAI clients get stickiness too. The README notes the mapping can be mirrored to Redis to survive restarts.

Running it with Docker Compose

The repository ships a Dockerfile and a docker-compose.yml. The container listens on 7863 and runs as user app with uid 10001 by default. The compose file warns that a host directory owned by a different uid produces permission denied errors when writing auths/*.json.tmp, and offers three fixes: pass PUID and PGID, chown the mounted directories to 10001, or run as root.

Create the config file before the first start. The compose comments are explicit that if config.json is missing, Docker creates the mount point as a directory and the container fails to start:

cp config.example.json config.json
PUID=$(id -u) PGID=$(id -g) docker compose up -d

The container exposes a health endpoint that the image's HEALTHCHECK polls every 30 seconds, and the README describes /healthz as carrying a service identity field for load balancers or host probes. A successful start shows the panel on port 7863 and a healthy container status.

To add an account you do not need the command line. The README says the panel's "add account" button completes the OAuth device flow, writes credentials to disk, and hot-loads them into the pool without a restart, replacing the login.sh flow. The command-line path still exists: login.sh performs device authorization, persists credentials, and restarts the container to load the new account.

What the panel changes compared with the upstream fork

This project is a fork of Sliverkiss/workbuddy2api. The README lists the panel as the main addition: internal/panel, with the front end embedded into the binary through go:embed, so there is no external asset dependency. The panel shows pool health, credit bars and cooldown countdowns, and supports per-account operations, batch tasks, log viewing and light and dark themes.

Configuration editing is the second addition worth noting. The panel writes back to config.json using a deep merge plus atomic replacement that preserves unknown keys. API keys, soft_rate, the fingerprint-scrubbing toggle, pool parameters and task scheduling take effect immediately; fields consumed at assembly time, such as listen, prompt for a restart after saving. That split is a real constraint rather than a rough edge: a single process cannot rebind a listener without restarting, and the panel says so instead of pretending otherwise.

On first start with no config.json present, the program generates a recommended configuration including a crypto/rand API key. That is convenient, but it also means the generated key is the only thing standing between your pool and anyone who can reach port 7863. The README mentions constant-time key comparison in internal/httpauth, CSP and security headers, and a UID whitelist against path traversal, so the author has thought about this. Whether you expose the port beyond localhost is still your call.

Task automation and its hard boundary

The growth-task feature is the part with no upstream equivalent. According to the README, 17 of the 18 official growth tasks can be completed from the panel with a single click, purely over API, with no official client installed. The gateway constructs the event chain each task expects, waits for asynchronous scoring to settle, and then calls the reward endpoint. A new account that runs all of them collects roughly 1950 credits and 78 energy, with only a few tasks involving real conversations.

The mechanism is fingerprint-dependent. Different tasks accept different client fingerprints: a CLI fingerprint, a desktop fingerprint using the copilot.tencent.com host with a WorkBuddy/5.5.6 user agent and the workbuddy-desktop event family, and a web fingerprint using www.workbuddy.cn with x-client-platform: web. The gateway builds the matching chain per task type in internal/upstream/desktop.go, and expert tasks additionally require a real expert id and a real conversation receipt. A 200 from the report endpoint does not mean the task scored, so the panel polls progress and claims the reward only once the target is met.

One task cannot be automated. Expert_Philanthropy requires a real donation, and the README states the server validates the donation receipt at claim time and that this was found impossible to bypass. The seasonal activity running until 2026-09-24 is a separate case: four of its five tasks are automated, while student verification needs a real WeChat student identity and is left out. The README also notes that behavior events are idempotent per day, so pressing the button twice does not double-spend resources.

Where this is the wrong tool

The README is direct about the compliance boundary: this is an unofficial gateway, it uses CodeBuddy accounts as an upstream, and it is limited to accounts you have authorized yourself, on a local or private environment. If you need an OpenAI-compatible endpoint with a contract, a rate guarantee, or the ability to serve customers, this is not it. The upstream can change its endpoints, its fingerprints or its scoring rules at any time, and the fork's task coverage is tied to a protocol the author had to reverse engineer.

There is a second, quieter limitation. The whole design assumes a small pool of accounts you control. Weighted random selection, cooldowns and stickiness are all heuristics tuned for that shape. Point a high-concurrency workload at it and the in-flight lease limit will throttle you long before the upstream does, and the 402 rule will park accounts for most of a day. For a single heavy user, a direct client integration is simpler than running a gateway.

The natural alternative is a general-purpose OpenAI-compatible proxy such as LiteLLM, which routes across many providers and models and is built for team and multi-tenant use. The difference in approach is the upstream: LiteLLM assumes each provider offers a documented API and an API key, while workbuddy2api-panel assumes the opposite and reconstructs the client behavior the vendor expects. If your upstream is already a documented API, LiteLLM is the shorter path. If your upstream is a CodeBuddy account, the fork exists because nothing else does that job.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-09-16, the day of the v1.9.2 release. Three releases landed within two days: v1.9.0 added usage and credit composition views plus hot-reload for max_body_mb, v1.9.1 fixed a regression in the account pool credit bar rendering introduced by v1.9.0's CSS, and v1.9.2 added a seasonal coupon query with a ticket popup and QR code. That cadence tells you two things. Fixes arrive quickly. Regressions also arrive, and the panel's front end is part of the release surface, so a CSS change can break a view.

Upgrade cost is low for the binary itself: the front end is embedded, so there is no separate asset step, and the Dockerfile builds all four binaries (wb2api, signin_bin, login, credit) in one pass. Configuration survives upgrades because the panel writes with a deep merge that preserves unknown keys. The real cost is protocol drift. The README documents two rounds of upstream synchronization, the second absorbing sanitization fixes and outbound header changes, which means staying current is an ongoing task rather than a one-time install.

The license is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. The repository includes a LICENSE file at the top level. Note that the license covers this code, not your use of the upstream service; the compliance boundary in the README is a separate matter, and nothing here is legal advice.

Editorial conclusion

Adopt it if you already hold several personal CodeBuddy accounts, want one OpenAI-shaped endpoint, and accept that the upstream is an unofficial reverse proxy that can break without notice. Skip it for production traffic, multi-tenant use, or anything that needs a vendor SLA; the README itself limits use to accounts you own, on a private host. Before wiring a client to it, confirm three things: that your host can write ./config.json as a file rather than a directory, that PUID/PGID match the owner of ./auths and ./data, and that your CodeBuddy account is not one you would mind losing if Tencent tightens the endpoint.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. linguo2625469/workbuddy2api-panel on GitHub
4. README
5. Releases