Sliverkiss/workbuddy2api

WorkBuddy2API – OpenAI‑compatible gateway for Tencent CodeBuddy

What it is

• A self‑hosted reverse‑proxy that turns one or many Tencent CodeBuddy (copilot.tencent.com) accounts into an OpenAI‑compatible /v1/chat/completions API.
• It handles the whole OAuth‑device‑flow, token refresh, account‑pool scheduling, rate‑limit / cooldown logic and session stickiness, exposing a single endpoint that any OpenAI SDK or tool can call without code changes.

Why it exists

• CodeBuddy does not provide a public OpenAI‑style API. WorkBuddy2API lets you reuse your personal CodeBuddy credits as if they were an OpenAI service, useful for personal projects, scripts or local tooling that expect the OpenAI schema.
• Designed for multi‑account use: you can add several CodeBuddy accounts, and the gateway will automatically rotate them, avoid exhausted or rate‑limited accounts, and keep costs low.

Key capabilities

Feature	What it does
OAuth one‑click login	login.sh runs the device‑authorization flow, saves the accessToken/refreshToken and restarts the container.
Account pool	Stores credentials in auths/, selects an account using a three‑factor weighted random algorithm (credits, idle time, success rate) and keeps a top‑5 candidate list.
Circuit‑breaker & cooldown	Handles 429, 402, 404 and other errors with exponential back‑off, soft‑cooldown (600 s → up to 2 h) and hard‑cooldown (until next day 04:00 for balance‑exhausted accounts).
Session stickiness	Binds a conversation_id to the same upstream account for the life of the conversation (default TTL 30 min) and mirrors the binding to Redis if configured.
Cost‑aware routing	After each successful response the gateway records usage.credit per (account, model) and prefers free or cheaper accounts for subsequent calls.
Scheduled tasks	Automatic daily sign‑in, activity reporting, “cat travel” gamified task and token keep‑alive at configurable local‑time hours.
Streaming & non‑streaming	Forces stream:true upstream, rewrites SSE frames to the OpenAI format; non‑streaming requests are aggregated locally.
Prompt‑system handling	Replaces client‑provided system messages with a built‑in prompt (or passes them through) and can strip black‑listed fingerprint fields.
Observability	One‑line table log per request (model, tokens, latency, UID prefix, etc.) and a /healthz endpoint that reports pool health.
Persistence	Pool state (state.json) is atomically written to disk and optionally mirrored to Upstash Redis.

How to run

1. Prerequisites – Docker + Docker‑Compose (recommended) or a Go 1.22+ toolchain for building from source.
2. Clone and prepare configuration:

   git clone https://github.com/Sliverkiss/workbuddy2api.git
   cd workbuddy2api
   cp config.example.json config.json   # edit at least "api_key" if you expose the service publicly
   

3. Add accounts (repeat for each account you want in the pool):

   ./login.sh   # opens a browser, you log in, token is saved under auths/
   

4. Start the service:

   docker compose up -d --build
   

5. Verify:

   curl -s http://localhost:7863/healthz
   # → {"healthy":2,"total":3,"service":"workbuddy2api"}
   

6. Use it like any OpenAI endpoint, e.g.:

   curl -sN http://localhost:7863/v1/chat/completions \
        -H "Authorization: Bearer <your‑api‑key>" \
        -H "Content-Type: application/json" \
        -d '{"model":"deepseek-v4-flash","messages":[{"role":"user","content":"hi"}],"stream":true}'
   

Configuration highlights (all options are in config.example.json)

• listen – address the gateway binds to (default :7863).
• api_key – optional bearer token required by clients; leave empty for an open service (not recommended on the public internet).
• auth_dir – directory where workbuddy‑<uid>.json credential files live.
• state_file – JSON file that persists pool metrics, cooldown timers, etc.
• server.max_body_mb – request‑body size limit (default 8 MiB, excess returns 413).
• Cool‑down parameters: cooldown.soft_rate, cooldown.soft_rate_max, pool.breaker_threshold, pool.breaker_cooldown, etc.
• Session stickiness: session_sticky.enabled, session_sticky.ttl.
• Prompt handling: prompt.mode (custom or passthrough) and optional prompt.file for a custom system prompt.
• Optional Redis mirroring: upstash.url / upstash.token.

API surface

Method & Path	Auth	Description
POST /v1/chat/completions	Bearer (if api_key set)	OpenAI‑compatible chat endpoint, supports streaming (stream:true) and non‑streaming modes.
GET /v1/models	Bearer (if api_key set)	Returns the model list fetched from CodeBuddy (cached 1 h).
GET /status	Bearer (if api_key set)	Summary of the whole pool plus per‑account details (credits, cooldown, disabled reason, etc.).
GET /healthz	None	Light health check – returns 200 when at least one account is healthy, otherwise 503. Includes service field for LB discrimination.

Safety & compliance notes (from the README)

• The gateway is unofficial; it only forwards traffic to accounts you own and have authorized via OAuth.
• Tokens are stored in plain JSON files under auths/; keep the directory permission‑restricted (chmod 600).
• No TLS is built‑in – if you expose the service publicly you must put it behind a reverse proxy or set an api_key.
• Use is limited to personal, private testing. Redistribution or commercial use of the upstream CodeBuddy accounts may violate Tencent’s terms.

Typical use‑cases

• Running local LLM‑powered tools (e.g., IDE assistants, CLI chat bots) that only understand the OpenAI API while leveraging your CodeBuddy credits.
• Experimenting with multi‑account cost optimisation: the gateway automatically prefers free/cheaper accounts for each model.
• Automating CodeBuddy “growth” tasks (daily sign‑in, activity reporting, the gamified “cat travel” feature) without manual browser interaction.

---

All information above is taken directly from the repository’s README; no additional features have been inferred.