GPTEAM CLI

Interactive GPTEAM API client configurator.

npx gpteam

The CLI asks for an API key, reads the key-scoped GPTEAM capability summary, shows only the available clients and models for that key's group, benchmarks production ingress endpoints with real API requests, then backs up old files and writes the selected client configuration. Legacy servers fall back to /v1/models for validation only.

When a selected client is missing, the interactive CLI shows the exact install command and asks before running it. --install-client skips that confirmation for scripted setup. Codex, Claude Code, OpenCode, OpenClaw, and Grok Build use npm-based install commands; OpenCode uses the current opencode-ai package. Windows is blocked for OpenClaw because GPTEAM's OpenClaw config writer currently supports macOS and Linux only.

Recommendation order is deterministic: success rate first, then an experience score. The score weighs first SSE event time, total completion time, p90 completion tail latency, and health-check time, so a node with one very slow probe is not recommended just because its median result looks good. The result table also marks the fastest full completion separately from the balanced recommendation, because deep or long-output model runs may care more about full completion time than first-token responsiveness. Model prompts use "configurable context" wording because the value is written to the client-side Codex model_context_window; it must not be confused with a public marketing total-window label.

The production endpoint is main (https://api.gpteamservices.com). Older scripted values jp, jp-direct, and jp-split remain compatibility aliases, but they write the main endpoint because the Japanese ingress is retired. Retired regional ingresses are not included in generated configs, help text, or release smoke tests.

Client config writing follows the same safety pattern as cc-switch: keep Codex top-level fields separate from provider tables, preserve unrelated sections such as MCP servers, merge OpenCode/OpenClaw providers additively, and stop before writing when an existing JSON/JSON5 config cannot be parsed. GPTEAM keeps two proxy-specific extensions on top of that baseline: Codex enables WebSocket capability for the GPTEAM provider, and Codex/OpenCode/Claude Code write the gpteam_image MCP server so Image 2 can be called from chat. Claude Code config intentionally removes stale ANTHROPIC_CUSTOM_HEADERS values instead of carrying old reasoning-effort headers forward.

The Image MCP config uses cc-switch-style per-client env blocks. Codex writes [mcp_servers.gpteam_image.env], OpenCode writes mcp.gpteam_image.environment, and Claude Code writes mcpServers.gpteam_image.env in ~/.claude.json. The MCP receives GPTEAM_API_KEY and GPTEAM_BASE_URL from that MCP config, so it does not depend on Codex auth.json or inherited OPENAI_API_KEY.

The Image MCP exposes an async-first local job flow plus a legacy compatibility alias:

• create_image_job: recommended for normal use. It starts a local background image job and returns job_id quickly, which avoids losing the whole generation when a VPN, proxy, or client has a 60-second idle timeout.
• get_image_job_status: checks whether the local job is queued, running, succeeded, failed, canceled, or expired.
• cancel_image_job: cancels a queued/running local job.
• download_image_result: returns the completed file metadata and image content. Use metadata_only, include_image, and include_revised_prompt to control large result payloads.
• get_capabilities: fetches the authenticated Key's schema-v1 contract and returns its revision, models, generate/edit actions, execution profiles, parameters, defaults, queue limits, and optional availability observation.
• generate_image: legacy compatibility alias. It now creates the same async job and returns job_id immediately instead of blocking until the image is complete.

Image MCP results are returned as stable JSON text and MCP structuredContent. Successful results include the final file path, selected model/action/profile, effective output metadata, byte size, SHA-256, MIME type, image dimensions, duration, retry count, job_id, trace_id, capability revision, and optional idempotency_key. Model-specific parameter names, defaults, accepted values, and bounds come only from get_capabilities; the README intentionally does not duplicate them. Error results use stable error.code, error.message, error.retryable, error.stage, error.upstream_status, and error.trace_id fields while keeping compatibility fields such as category and http_status.

Schema-v1 actions use only the authenticated /v1/gpteam/image-mcp/images/generations and /v1/gpteam/image-mcp/images/edits execution namespace. The client rejects capability documents that point dynamic actions at ordinary /v1/images/* routes or another Origin. Ordinary image API traffic is outside the Image MCP lifecycle and never enters its contract executor.

Clients always submit the model name published by get_capabilities. An account may internally accept a compatible alias or mapped target; the backend preserves that account-specific selection identity for scheduling and upstream dispatch while keeping the published request model as the user-visible logging and billing identity. Clients must not guess internal names such as preview.

The MCP supports text-to-image and image-to-image/edit only when the selected runtime contract advertises those actions. Image aliases, mask support, streaming fields, and other upstream-effective inputs are likewise emitted only by the selected execution profile. MCP-local output controls remain separate from upstream inputs. File writes create missing directories, avoid overwriting existing files by adding -v2, -v3, etc., and validate the returned file before reporting success.

For gpt-image-2, custom size, aspect_ratio, resize_mode, and upscale values follow the selected runtime profile. GPTEAM uses them for upstream size selection, composition guidance, and billing semantics, but current behavior preserves the upstream image bytes instead of stretching, cropping, or re-encoding generated output to force exact requested pixels. A request such as 2160x3840 can therefore return different positive dimensions with the same intended aspect. Use the result width and height as the actual output dimensions.

Image responses may contain base64/data-URL bytes or an ordinary public HTTPS result URL, depending on the repository-backed proxy adapter. HTTPS results are downloaded without API credentials. Every URL and redirect gets a fresh DNS snapshot; every address in that snapshot is vetted, and network or response-stream failure may advance only to another pinned public address from the same snapshot. The downloader never re-resolves during that attempt or replays the paid image generation. It also enforces a 64 MiB limit plus matching Content-Type and PNG/JPEG/WebP byte inspection. Local, private, reserved, credential-bearing, oversized, mismatched, or malformed result URLs fail closed.

For networks that require an outbound proxy, set GPTEAM_IMAGE_RESULT_PROXY_URL to an HTTP or HTTPS proxy. When it is absent, Image MCP follows the standard HTTPS_PROXY, HTTP_PROXY, ALL_PROXY, and NO_PROXY environment variables. The proxy tunnel targets only a public IP already resolved and vetted locally; TLS SNI and the HTTP Host header keep the original hostname, and GPTEAM API credentials are never attached to the result download. An invalid or unsupported proxy returns image_url_proxy_invalid. Keep proxy credentials only in the local MCP environment, and replace that private environment on another computer without changing tracked source.

Capability responses are cached for at most 60 seconds and isolated by an HMAC of the API Key. A queued job stores the discovery revision, then forces a refresh immediately before paid dispatch. A changed group, permission, model, action, or parameter contract fails with stale_capability before any upstream request. model_required asks the caller to select a model from the current response; unsupported_parameter identifies a field outside the selected profile. Authentication, empty capability, malformed schema, or unsupported schema versions fail closed and never resurrect a static model. A request that may already have reached an upstream is never automatically replayed.

Claude Code is written to ~/.claude/settings.json under the env section. ANTHROPIC_BASE_URL uses the current GPTEAM API root because Claude Code appends /v1/messages; the CLI removes legacy /anthropic suffixes instead of generating an unroutable URL. OpenClaw writes models.providers.gpteam and also selects gpteam/<model> under agents.defaults.model, so the chosen model is active without an extra manual step.

Grok Build

[email protected] configures the official @xai-official/[email protected] client and Key-scoped Grok models for Codex and OpenCode. The Grok Build writer refuses unknown client versions before touching ~/.grok/config.toml. Install the supported version with:

npm install -g @xai-official/[email protected]

Grok configuration is Key-scoped. The CLI reads the capability response, keeps only the authorized intersection for the selected client, selects Responses or Chat Completions per model, and emits reasoning effort only for models that accept it. Grok Build and OpenCode use the six verified text models below; Codex uses the returned grok-4.5/grok-4.3 Responses profiles. It does not expose media models as chat models or invent access from the package template. Claude Code remains hidden for Grok because the real Messages and token-count release gate has not passed.

| Model | Backend | Context | Reasoning effort | | --- | --- | ---: | --- | | grok-4.5 | Responses | 500,000 | low, medium, high, xhigh | | grok-4.3 | Responses | 1,000,000 | low, medium, high, xhigh | | grok-build-0.1 | Chat Completions | 256,000 | omitted | | grok-composer-2.5-fast | Chat Completions | 200,000 | omitted | | grok-4.20-0309-reasoning | Chat Completions | 1,000,000 | omitted; model-fixed | | grok-4.20-0309-non-reasoning | Chat Completions | 1,000,000 | omitted |

The CLI parses the existing TOML, preserves unrelated UI/MCP/plugin settings, removes GPTEAM-owned stale model entries, creates a backup, and atomically replaces the file. POSIX files use mode 0600; Windows applies a current-user ACL before any secret is written. Parse, permission, ACL, or replacement failures scrub temporary files and stop without silently replacing malformed configuration.

Generated Grok Build configuration writes web_search = "grok-4.5" only when grok-4.5 is in the Key-authorized model intersection; otherwise it removes the stale managed value. This is the client-executed tool path proven with Grok Build 0.2.99, not hosted backend search, and per-model supports_backend_search stays disabled. OpenCode receives limit.context and limit.output together; output: 0 is its unknown-limit sentinel when GPTEAM has no verified ceiling. For model not found, invalid reasoning, or an empty model intersection, return to the Key's 使用密钥 flow or rerun npx gpteam instead of copying an old static model list.

Supported clients:

• Codex
• Grok Build
• OpenCode
• Claude Code
• OpenClaw on macOS and Linux

Useful non-interactive smoke checks:

npx gpteam --help
npx gpteam --version

--install-client is for scripted setup after you also provide the usual non-interactive inputs such as --api-key, --client, --model, and --node.