--- name: configure-unikey-api description: Use when a user wants to connect UniKey to an AI product, coding agent, desktop client, CLI, or custom application and provides a UniKey API key. --- # Configure UniKey API for an AI product This skill is the operating guide for configuring UniKey in Codex, Claude Code, OpenClaw, WorkBuddy, or another product that can call an OpenAI-compatible or Anthropic-compatible API. The user normally supplies only: 1. the product they want to configure; and 2. one UniKey API key. Do not ask them to repeat either value. Infer the operating system, installation state, and configuration method from the local environment. Ask one concise question only when a required choice cannot be discovered safely (for example, two installed product versions use incompatible config formats). ## Non-negotiable secret handling - Treat the supplied API key as a secret. Never print it, echo it, put it in a tool result, commit it, paste it into a screenshot, or include it in the final response. - Use a redacted placeholder such as `UNIKEY_API_KEY`, `[REDACTED]`, or `PASTE_YOUR_UNIKEY_API_KEY_HERE` in explanations and examples. - Prefer the product's environment-variable or secret-manager mechanism. If a product requires a local JSON/TOML file, write the secret only to that file, preserve its permissions, and do not display the resulting file contents. - Before editing an existing config, make a local backup. Do not overwrite unrelated settings; merge the UniKey provider into the existing structure. - Do not ask the user to send wallet private keys, seed phrases, login cookies, or any credential other than the UniKey API key. - If the key was exposed in a terminal, chat, repository, log, or screenshot, tell the user to rotate it and use the replacement. Do not continue sharing the exposed value. ## UniKey caller contract Use these values unless the product-specific section below requires a different path: | Setting | Value | | --- | --- | | Official console | `https://www.getunikey.ai/` | | OpenAI-compatible base URL | `https://www.getunikey.ai/v1` | | Anthropic-compatible base URL | `https://www.getunikey.ai` | | OpenAI authentication | `Authorization: Bearer $UNIKEY_API_KEY` | | Anthropic authentication | `x-api-key: $UNIKEY_API_KEY` or the client's `ANTHROPIC_AUTH_TOKEN` variable | | Model discovery | `GET https://www.getunikey.ai/v1/models` | | Chat endpoint | `POST https://www.getunikey.ai/v1/chat/completions` | | Anthropic Messages endpoint | `POST https://www.getunikey.ai/v1/messages` | The OpenAI base URL ends at `/v1`; do not append `/chat/completions` to it. A UI that explicitly asks for a full endpoint URL (WorkBuddy is one example) should receive the full `/v1/chat/completions` URL. Claude Code's documented environment setup uses `https://www.getunikey.ai` as `ANTHROPIC_BASE_URL`, because Claude Code constructs the Messages path itself. The caller-facing API is OpenAI-format compatible for models, chat completions, legacy completions, and embeddings, and Anthropic-format compatible for Messages. Keep NewAPI management operations, channel administration, token administration, billing administration, and account-registration flows out of an ordinary product integration. ## The required workflow Follow this order for every product, including a product not named in this file. ### 1. Identify the product's configuration surface Inspect the installed product's version and official documentation or built-in help. Determine: - whether it expects OpenAI Chat Completions, OpenAI Responses, Anthropic Messages, or a custom protocol; - whether it accepts a base URL or a full endpoint URL; - the exact config path, environment-variable names, provider schema, and model field; - whether it needs a restart, gateway reload, or a separate model-selection command. Do not assume a similarly named product uses the same schema. Preserve existing configuration and select the smallest supported change. ### 2. Discover an account-authorized model Use the user's key through an environment variable and query `/v1/models` when network access and user authorization permit it. Choose a model returned for that account, or ask the user to select one from the current UniKey pricing/model page if the product requires a model before it can start. Model names and availability change. The examples in this file (`gpt-5.5`, `gpt-5.2`, `gpt-5.6-terra`, `claude-sonnet-4-6`, and similar IDs) are examples, not guarantees. Never silently substitute a model that was not returned by `/v1/models` or documented as available to the account. ### 3. Back up and write the configuration Back up the exact file you will edit, then merge the provider settings. Use the product's native onboarding flow when it is reliable; use a manual file only when onboarding is unavailable, skipped, or needs a known-good repair. Never replace an entire config file merely to add one provider unless the user explicitly requests a reset and a backup exists. ### 4. Verify at three levels Run checks in this order: 1. **Credential and gateway:** a real `GET /v1/models` request with the supplied key. 2. **Inference:** one minimal, non-sensitive request using an authorized model, for example `Reply with exactly OK`, with a small token limit and no user data. 3. **Product:** the product's own status command or a short test message through the configured agent. An HTTP 200 from `/v1/models` proves only that the key can reach the gateway. It does not prove that the product selected the provider, that the model supports the requested protocol, or that tool calls/streaming work. Report each level separately. Use a shell pattern that does not print the secret: ```bash export UNIKEY_API_KEY='[REDACTED_IN_EXAMPLE]' curl --fail-with-body --silent --show-error \ https://www.getunikey.ai/v1/chat/completions \ -H "Authorization: Bearer $UNIKEY_API_KEY" \ -H 'Content-Type: application/json' \ -d '{"model":"MODEL_FROM_MODELS","messages":[{"role":"user","content":"Reply with exactly OK."}],"max_tokens":16,"temperature":0,"stream":false}' ``` Replace `MODEL_FROM_MODELS` locally; never put the real key into this document or into a command copied to the user. If a pre-response HTTP/2 framing error occurs, retry the same minimal request with `curl --http1.1` before judging the key or endpoint. ### 5. Report the result without leaking credentials State the product, config path or UI fields changed, base URL/protocol, selected model, and the verification evidence. Redact the key and any authorization header. Distinguish “configured” from “live inference verified”; do not claim success from an exit code, a file edit, or a model-list check alone. ## Product recipes Use the recipe that matches the user's product and then complete the generic workflow above. ### ChatGPT Codex CLI The documented setup uses an environment variable and the per-user `config.toml`. - macOS/Linux: `~/.codex/config.toml`; key variable `UNIKEY_API_KEY`. - Windows: `%USERPROFILE%\\.codex\\config.toml`; persist `UNIKEY_API_KEY` as a user environment variable in PowerShell. - Provider values: `model_provider = "unikey"`, `base_url = "https://www.getunikey.ai/v1"`, and `env_key = "UNIKEY_API_KEY"`. - Use a model returned by `/v1/models`. The current project examples use `wire_api = "responses"`; confirm the installed Codex version's supported wire protocol before changing it. Minimal TOML shape (merge with existing settings): ```toml model = "MODEL_FROM_MODELS" model_provider = "unikey" [model_providers.unikey] name = "UniKey" base_url = "https://www.getunikey.ai/v1" env_key = "UNIKEY_API_KEY" wire_api = "responses" ``` Verify with `codex --version`, the `/v1/models` probe, and a short Codex prompt. If the product reports an unsupported Responses endpoint, inspect the installed Codex help/version and use its supported OpenAI-compatible protocol; do not invent a `/v1/responses` capability for UniKey. ### Claude Code Claude Code uses the Anthropic-compatible Messages interface. The documented cross-platform settings file is: - macOS: `~/.claude/settings.json` - Linux/WSL: `~/.claude/settings.json` - Windows: `%USERPROFILE%\\.claude\\settings.json` Merge this `env` object into the existing JSON: ```json { "env": { "ANTHROPIC_AUTH_TOKEN": "[REDACTED]", "ANTHROPIC_BASE_URL": "https://www.getunikey.ai", "ANTHROPIC_MODEL": "MODEL_FROM_MODELS", "API_TIMEOUT_MS": "3000000" } } ``` An environment-variable alternative uses the same names in the user's shell profile or PowerShell profile. Restart the terminal and run `claude --version`, then a short Claude Code prompt. For a model that fails tool use, try a Claude-compatible model returned by `/v1/models` before changing unrelated settings. ### OpenClaw Prefer `openclaw onboard` and choose an OpenAI-compatible/custom OpenAI-compatible provider. For manual repair, back up: - macOS/Linux/WSL2: `~/.openclaw/openclaw.json` - Windows: `%USERPROFILE%\\.openclaw\\openclaw.json` Merge this provider shape: ```json { "models": { "mode": "merge", "providers": { "unikey": { "baseUrl": "https://www.getunikey.ai/v1", "apiKey": "[REDACTED]", "api": "openai-completions", "models": [{"id": "MODEL_FROM_MODELS", "name": "MODEL_FROM_MODELS"}] } } }, "agents": { "defaults": { "model": {"primary": "unikey/MODEL_FROM_MODELS"} } } } ``` Do not append `/chat/completions` to `baseUrl`; OpenClaw adds the path. Verify with `openclaw --version`, `openclaw models status`, `openclaw gateway status`, and a short chat message. Restore the backup if the gateway cannot start, then inspect the version-specific schema. ### WorkBuddy WorkBuddy's custom-model UI asks for a full API URL, so use `https://www.getunikey.ai/v1/chat/completions` (not only the `/v1` base URL), the UniKey key, and a lowercase model ID from `/v1/models` or the current UniKey pricing page. In the UI, choose **Custom**, add the model, save, fully restart WorkBuddy, and test a short message. For file-based setup, quit WorkBuddy and back up `~/.workbuddy/models.json` before editing. Preserve the existing array and add an entry with the product's current schema. The current project examples use `vendor: "Custom"`, the full `url`, `apiKey`, and capability flags such as tool calls, images, and reasoning. Enable a capability only if the selected model and WorkBuddy version support it; otherwise disable that flag rather than treating a failed tool/image call as an API-key failure. ### Any other OpenAI-compatible product Find the product's fields for **provider**, **base URL**, **API key**, **model**, and **protocol**. Use: - provider name: `UniKey` or a local ID such as `unikey`; - base URL: `https://www.getunikey.ai/v1` when the field is a base URL; - full endpoint: `https://www.getunikey.ai/v1/chat/completions` only when the UI explicitly asks for an endpoint; - authentication: Bearer API key, preferably referenced by an environment variable or secret store; - model: a model returned by `/v1/models`; - protocol: OpenAI Chat Completions unless the product explicitly requires another supported protocol. For an Anthropic-compatible product, use its equivalent Messages fields, `https://www.getunikey.ai` as the documented base where the client appends `/v1/messages`, and `x-api-key`/`ANTHROPIC_AUTH_TOKEN` as required by that client. If the product has no custom base URL or provider support, do not claim it can be configured with UniKey. Explain the limitation and offer the product's supported proxy/adapter boundary only if one is documented and safe. ## Troubleshooting matrix | Symptom | Diagnose first | Safe next action | | --- | --- | --- | | `401 Unauthorized` | Missing, expired, truncated, or whitespace-polluted key; wrong header | Re-enter through the secret mechanism, check the redacted variable is non-empty, rotate if exposed. | | `403 Forbidden` | Account/model permission or policy | Select a model returned by `/v1/models`; check account access and credits. | | `404 Model not found` | Stale, misspelled, or wrong-case model ID | Query `/v1/models` and use the exact returned ID. | | `404` on request path | Base URL/full endpoint was combined incorrectly | Use `/v1` as a base, or the full `/v1/chat/completions` only in a full-URL field. | | `429` or insufficient credits | Rate limit, balance, or application loop | Check balance/limits; add bounded retries and request/tool budgets. | | Timeout or idle stream | Network, upstream latency, or client stream handling | Use a bounded timeout; test non-streaming once; then inspect client logs with secrets redacted. | | Product command missing | Installation or `PATH` problem | Check the product's version command and official installer; do not change API settings yet. | | Config ignored | Wrong path, invalid JSON/TOML, or process not restarted | Validate syntax, confirm the exact per-user path, restart the product/gateway. | | HTTP/2 framing error before response | Transport negotiation issue | Retry the same request with `curl --http1.1`; only then evaluate credentials/API behavior. | Do not “fix” an API error by changing several variables at once. Reproduce with the direct minimal request, then change one product setting and repeat the product-level check. ## Production safety - Use separate keys for development, staging, production, and different teams where practical. - Keep request budgets, maximum agent/tool iterations, timeouts, and stop conditions in the application. - Record model, endpoint, token usage, Credits consumed, latency, error code, and request owner without recording prompts that contain secrets or personal data. - Handle non-2xx responses and upstream errors without exposing raw authorization headers or internal gateway details to end users. - Do not put UniKey keys in browser code, mobile bundles, public repositories, screenshots, support tickets, or client-side logs. - Review the current pricing and model page before high-volume or high-cost traffic. The project documentation records `$1 = 10,000 AI Credits`, but model pricing and availability can change. ## Boundaries This skill configures a caller-facing UniKey API integration. It does not authorize account creation, wallet registration, CAPTCHA solving, proxy evasion, private-key generation or storage, bypassing access controls, or changes to unrelated product infrastructure. Stop and ask the user before any destructive reset, production deployment, paid bulk test, or external message. ## Source of truth When this file is available, read it before the rest of the UniKey documentation. For current endpoint/model details, consult [https://docs.getunikey.ai/](https://docs.getunikey.ai/) and the official [UniKey console](https://www.getunikey.ai/). The repository's detailed references are: - API contract: `docs/api-reference.md` - key safety: `docs/api-keys.md` - models and pricing: `docs/models.md`, `docs/pricing-and-usage.md` - product recipes: `docs/chatgpt-codex/`, `docs/claude-code/`, `docs/openclaw/`, and `docs/workbuddy/` If a live product version conflicts with an example here, trust the installed product's current schema and verify it with a real, minimal request; update only the product-specific mapping, not the UniKey secret-handling rules.