GPTeam CLI

Interactive GPTeam API client configurator.

npx gpteam

The CLI asks for an API key, validates it with /v1/models, checks whether the selected client command is installed, detects available models, benchmarks all production ingress endpoints with real API requests, then backs up old files and writes the selected client configuration. The next steps are blocked until the key validation succeeds. Client detection runs before model selection and benchmarking, so a missing local client does not waste API probes.

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, and OpenClaw 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.

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 three proxy-specific extensions on top of that baseline: Codex explicitly disables WebSocket prewarm, Codex/OpenCode/Claude Code write the gpteam_image MCP server so Image 2 can be called from chat, and Claude Code writes the reasoning-effort header through ANTHROPIC_CUSTOM_HEADERS.

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: returns supported sizes, formats, quality values, async support, cancellation semantics, queue limits, and image-to-image support.
• 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 final file path, model, action, size, format, quality, byte size, SHA-256, MIME type, image dimensions, duration, retry count, job_id, trace_id, and optional idempotency_key. 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.

The MCP supports normal text-to-image generation and image-to-image/edit inputs. Pass images as data URLs, HTTPS URLs, or local file paths. For easier tool calling, image, image_path, image_paths, input_image, and input_images are accepted as aliases. Pass mask or mask_path the same way for masked edits. input_fidelity is accepted for compatibility but is not forwarded to the current GPTeam Image 2 bridge because upstream Codex image edits reject it. The MCP requests GPTeam image endpoints with stream=true and reads the final image event, so long image jobs get early stream bytes instead of sitting idle until the final JSON body. File writes create missing directories, avoid overwriting existing files by adding -v2, -v3, etc., and validate PNG/JPEG/WebP before returning success. overwrite: true is available for explicit replacement. return_revised_prompt controls whether the upstream revised prompt is included in the result.

Claude Code is written to ~/.claude/settings.json under the env section, using the GPTeam /anthropic base 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.

Supported clients:

• Codex
• 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.