WorkBuddy2API-Hub: OpenAI-compatible gateway setup

Why WorkBuddy2API-Hub sits between WorkBuddy and OpenAI clients

WorkBuddy2API-Hub addresses a specific compatibility problem: the international service at `www.workbuddy.ai` and the Chinese service at `codebuddy.cn` are not presented by the project as ordinary OpenAI endpoints. The gateway converts their native service behavior into OpenAI-compatible Chat Completions and Responses interfaces. That lets standard OpenAI clients use an OpenAI-style base URL while the gateway handles WorkBuddy accounts, regional selection, model catalogs, limits, and request logs.

The intended users are operators of multiple authorized WorkBuddy accounts, particularly developers using Codex, Claude Code, DSH, or an OpenAI-compatible client. The project is not a general multi-provider AI router. Its account onboarding, OAuth flow, token handling, model declarations, and scheduled activities are tied to WorkBuddy and CodeBuddy.

The repository implements the gateway primarily in Python. Files such as `wb_proxy.py`, `wb_egress.py`, `wb_upstream_pool.py`, `wb_catalog.py`, `wb_accounts.py`, and `wb_scheduler.py` separate proxying, routing, model discovery, account state, and background work. The same layout indicates that the dashboard is not a separate front-end service. `dashboard.html` is copied into the Python container alongside the `wb_*.py` modules.

Account credentials and settings are persisted under `accounts/`, while usage records are stored under `usage/`. This split matters operationally because those directories must remain writable and should survive container replacement. The README also assigns separate maintenance rules to API keys, models, accounts, regions, and scheduled tasks.

OpenAI request flow across international and Chinese accounts

A request enters the local `/v1` endpoint and passes through account and key policy before reaching the selected regional upstream. WorkBuddy2API-Hub defaults the local service to `http://127.0.0.1:8788`, exposes OpenAI-compatible routes at `http://127.0.0.1:8788/v1`, and serves its dashboard at `http://127.0.0.1:8788/`.

Regional routing is explicit. International and Chinese accounts have independent configuration and scheduling, and the dashboard provides a global outlet switch. API keys can also be bound to one region, which is useful when separate clients must not share the same destination. A key may carry model patterns such as `deepseek*` or `gpt-6-astra`; unmatched models receive a local HTTP 400 response and are not forwarded or charged to an account. This check is meant to prevent a regional mismatch from surfacing later as an upstream WAF error.

The gateway also derives a stable device fingerprint through `derive_id`. According to the README, it derives machine and session identifiers from the account UID, keeping the same account from drifting while preventing different accounts from being associated through those identifiers. Account imports use browser OAuth on the dashboard. Windows can import encrypted tokens from a running desktop client, while macOS and Linux require a decoded key to be pasted manually.

The model catalog is generated from the official desktop configuration. It removes inline-completion and private-route variants, then exposes declared context size, output limits, vision support, tools, and reasoning levels. The documented international catalog contains 17 models, while the Chinese catalog contains 14. This is a curated compatibility layer, not a promise that every WorkBuddy model or parameter will be accepted by every client.

Starting WorkBuddy2API-Hub and opening its dashboard

Windows users can start the packaged environment by running `start-wb-proxy.bat`. On macOS, the documented entry point is `start-wb-proxy.command`, or the shell launcher with an optional port. The service defaults to port `8788`. After it starts, open the dashboard and use the OAuth account control described as `+ 添加账号 (OAuth)`.

On macOS, the following command starts the local service. If execution permission is refused after extracting the archive, the README directs macOS and Linux users to make the launchers executable first.

chmod +x start-wb-proxy.sh start-wb-proxy.command start-wb-proxy-lan.sh start-wb-proxy-lan.command allow-firewall.command
./start-wb-proxy.sh [端口]

The expected API base is:

http://127.0.0.1:8788/v1

Open `http://127.0.0.1:8788/` to reach the Web dashboard. The default panel password is `admin`, but it is separate from the API key and is stored as a PBKDF2-SHA256 digest in `accounts/settings.json`. The README says to change it after the first login. This is the first real configuration boundary to verify: the API client needs the `/v1` address and an API key, while the dashboard needs the panel password.

The README does not provide a generic OpenAI client configuration file or a documented first-request `curl` example. It does, however, describe `/v1/models` as the live model list. The first useful client check is therefore to point the chosen OpenAI-compatible client at `/v1`, select an account through the dashboard, and confirm that the client receives the region-appropriate catalog before submitting a model request.

Docker deployment for a persistent WorkBuddy gateway

The container image is built from `python:3.11-alpine`, listens on port `8788`, and declares `/health` for container health checks. It copies `wb_*.py` and `dashboard.html` into `/app`. The Dockerfile states that the image has no external pip dependencies.

The repository's `docker-compose.yml` uses `ghcr.io/ardeyouxipianyi/workbuddy2api-hub:latest`, runs with `--lan` through the container command, and maps host port `8788` to container port `8788`. It mounts `./accounts` at `/app/accounts` and `./usage` at `/app/usage`. These mounts retain credentials, settings, and usage data when the image is replaced.

Start and update the service with the documented commands:

docker compose up -d
docker compose pull && docker compose up -d

The first command starts the published `latest` image. The second pulls a newer image and recreates or restarts the service while retaining the mounted data. If no `API_KEY` is supplied, container startup generates one, writes it to `accounts/settings.json`, and prints it in the logs. The README gives this command for retrieving it:

docker compose logs wb-proxy | grep -i "api key"

One deployment trade-off is that the container defaults to user `0:0`. The Compose file allows `PUID` and `PGID` overrides, but the mounted directories must then be writable by that user. Another boundary is the `latest` tag, which does not pin a release. Operators who need a repeatable version should change the image tag to a specific project version and update that tag deliberately.

Operations, automation, and the cost of upgrades

The dashboard centralizes account and task administration, request flow, token usage, cache hits, estimated spending, and model distribution. Account-level guardrails can track points, daily tokens, daily points, and tokens by model. Each account has separate counters, and the documented local unlock time is 00:00. All four guardrails are disabled by default, so installing the service does not impose these limits unless they are enabled.

Background automation includes Chinese-version check-ins, growth and point tasks, and a cat travel task. The international service has a daily activity check-in described as completing the web session. The scheduler places work at 09:00 and 21:00, 22:00, and 01:00. These are WorkBuddy account operations rather than generic gateway maintenance, and operators need authorized accounts before enabling them.

Maintenance activity is recent. The repository is not archived, its last push was on 2026-10-15, and releases `v1.7.4`, `v1.7.5`, and `v1.7.6` were published on 2026-10-14, 2026-10-15, and 2026-10-15 respectively. That cadence still creates an operational upgrade decision because model catalogs and WorkBuddy protocol behavior can change. The Docker instructions preserve data across image updates, while `latest` makes upgrades easy to initiate but less exact to reproduce.

The repository is distributed under the MIT license. The README identifies the license but does not summarize deployment obligations, so redistribution or modification should be checked against the repository's `LICENSE` file. For a hosted gateway, the more immediate costs are securing the panel password and API keys, preserving account data, limiting network exposure, and reviewing changes to protocol conversion before replacing a running container.

WorkBuddy2API-Hub limits and the direct-alternative boundary

The clearest limitation is the optional Anthropic Messages adapter. The README says that conversion is intended for Claude Code and Anthropic SDK clients, but cache compatibility has not been verified. It is disabled by default and must be selected explicitly. An operator who depends on Anthropic prompt caching should not treat this path as equivalent to a native Anthropic service until that compatibility gap is resolved.

The project also does not present itself as a provider-independent gateway. Its fingerprint derivation, OAuth onboarding, model declarations, scheduled account activity, and regional catalogs are all tied to WorkBuddy and CodeBuddy. The choice is therefore between a managed native integration and a gateway with additional local controls.

Another wrong-fit case is a server that does not allow credential persistence or account automation. The service stores account tokens and settings under `accounts/`, and its background scheduler is designed to perform daily account activity. Organizations with strict credential-handling rules should review those files and features before deployment.

The alternative for teams that need stable Anthropic cache semantics is an actual Anthropic-compatible endpoint rather than this project's experimental converter. For teams standardized on OpenAI clients and operating authorized WorkBuddy accounts, the gateway removes repetitive client configuration, although it also becomes a security and maintenance component that must be backed up and controlled.

Editorial conclusion

Operators running multiple authorized WorkBuddy accounts and standard OpenAI clients should evaluate this gateway after checking regional model availability, account import requirements, and the persistence of `accounts/` and `usage/`. It is a poor fit for users who need a verified Anthropic Messages cache path or expect a conventional public upstream with its own service guarantees. The first project-specific check should be a small request through `http://127.0.0.1:8788/v1`, followed by inspection of the account and request views in `http://127.0.0.1:8788/`.

Frequently asked questions

Official sources

1. ardeyouxipianyi/workbuddy2api-hub on GitHub
2. License: MIT
3. Project website
4. README
5. Releases