Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
17.7 KB
Raw Blame
"""Catalog-derived Admin provider fields."""

from dataclasses import replace
from typing import TypedDict

from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.settings import Settings

from .specs import ConfigFieldSpec


class ProviderFieldOverride(TypedDict, total=False):
    """Optional catalog-field presentation overrides."""

    label: str
    description: str
    restart_required: bool


_PROVIDER_FIELD_OVERRIDES: dict[str, ProviderFieldOverride] = {
    "ANTHROPIC_API_KEY": {
        "description": "Anthropic API access with separate usage billing. Messages requests use Anthropic tools and client thinking controls. Native fallback uses other Anthropic models. FCC local web tools apply to compatibility routes.",
    },
    "OPENAI_API_KEY": {
        "label": "OpenAI API Keys",
        "description": "API key for the OpenAI Platform. Separate from ChatGPT sign-in.",
    },
    "OPENAI_PROXY": {
        "description": (
            "Optional network proxy. Leave blank unless you use one. "
            "Used for OpenAI sign-in and ChatGPT Codex requests. "
            "Changing it restarts FCC."
        ),
        "restart_required": True,
    },
    "AZURE_OPENAI_API_KEY": {
        "description": "API key for the Azure OpenAI resource.",
    },
    "AZURE_OPENAI_BASE_URL": {
        "description": (
            "Resource-specific OpenAI v1 base URL, for example "
            "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/."
        ),
    },
    "NVIDIA_NIM_API_KEY": {
        "label": "NVIDIA NIM API Keys",
        "description": "Used by NVIDIA NIM chat and optional NIM voice transcription.",
    },
    "MISTRAL_API_KEY": {
        "label": "Mistral API Keys",
        "description": (
            "Mistral La Plateforme (api.mistral.ai); Experiment plan is free tier with rate limits."
        ),
    },
    "CODESTRAL_API_KEY": {
        "label": "Codestral API Keys",
        "description": (
            "Mistral Codestral endpoint (codestral.mistral.ai); distinct from Mistral "
            "La Plateforme ``MISTRAL_API_KEY``. See Mistral docs for coding/FIM domains."
        ),
    },
    "OPENCODE_API_KEY": {
        "label": "OpenCode API Keys",
        "description": (
            "OpenCode Zen curated gateway (opencode.ai/zen/v1) and OpenCode Go subscription "
            "gateway (opencode.ai/zen/go/v1); single key from opencode.ai/auth."
        ),
    },
    "AI_GATEWAY_API_KEY": {
        "label": "Vercel AI Gateway API Keys",
        "description": (
            "Vercel AI Gateway API key for the OpenAI-compatible endpoint at "
            "ai-gateway.vercel.sh/v1."
        ),
    },
    "AWS_BEARER_TOKEN_BEDROCK": {
        "label": "Amazon Bedrock API Keys",
        "description": (
            "Amazon Bedrock bearer API key for the region-specific Mantle "
            "OpenAI-compatible endpoint."
        ),
    },
    "BEDROCK_BASE_URL": {
        "description": (
            "Amazon Bedrock Mantle OpenAI base URL for the same region as the "
            "API key and selected models."
        ),
    },
    "HUGGINGFACE_API_KEY": {
        "label": "Hugging Face API Keys",
        "description": (
            "Hugging Face token with Inference Providers permission; also used "
            "for local Whisper model downloads when voice notes need gated models."
        ),
    },
    "COHERE_API_KEY": {
        "label": "Cohere API Keys",
        "description": "Cohere API key for the OpenAI-compatible Compatibility API.",
    },
    "ZAI_API_KEY": {
        "label": "Z.ai API Keys",
        "description": (
            "Shared Z.ai key for Coding Plan (zai/...) and the general API "
            "(zai_api/...). The selected model prefix chooses Coding Plan quota "
            "or pay-as-you-go balance."
        ),
    },
    "FIREWORKS_API_KEY": {
        "label": "Fireworks API Keys",
        "description": "Fireworks AI inference API key.",
    },
    "NOVITA_API_KEY": {
        "label": "Novita AI API Keys",
        "description": (
            "Novita AI OpenAI-compatible API key (create at "
            "[novita.ai/settings/key-management](https://novita.ai/settings/key-management))."
        ),
    },
    "MINIMAX_API_KEY": {
        "label": "MiniMax API Keys",
        "description": (
            "MiniMax API key for the OpenAI-compatible Chat Completions API at "
            "free_claude_code.api.minimax.io/v1."
        ),
    },
    "KIMI_CODE_API_KEY": {
        "label": "Kimi Code API Keys",
        "description": (
            "Personal Kimi Code subscription key from kimi.com/code/console; "
            "separate from KIMI_API_KEY credits on the Kimi API platform."
        ),
    },
    "CLOUDFLARE_API_TOKEN": {
        "label": "Cloudflare API Tokens",
        "description": (
            "Cloudflare API token for account-scoped AI REST requests. "
            "Use with CLOUDFLARE_ACCOUNT_ID."
        ),
    },
    "GEMINI_API_KEY": {
        "label": "Gemini API Keys",
        "description": (
            "Google AI Studio Gemini API key (Google AI Studio / Gemini API "
            "[OpenAI-compatible](https://ai.google.dev/gemini-api/docs/openai)); "
            "free tier has per-model rate limits and data may be used for improvement "
            "outside the UK/CH/EEA/EU."
        ),
    },
    "GROQ_API_KEY": {
        "label": "Groq API Keys",
        "description": (
            "GroqCloud OpenAI-compatible API key ([console.groq.com/keys]("
            "https://console.groq.com/keys)); see Groq "
            "[OpenAI compatibility docs](https://console.groq.com/docs/openai)."
        ),
    },
    "CLINE_API_KEY": {
        "label": "Cline API Keys",
        "description": (
            "Subscribe to ClinePass, then create a programmatic API key under "
            "Settings > API Keys at app.cline.bot. This is not the Cline CLI's "
            "managed account token."
        ),
    },
    "XAI_API_KEY": {
        "label": "xAI API Keys",
        "description": (
            "xAI OpenAI-compatible API key for Grok chat and image-understanding "
            "models."
        ),
    },
    "ALIBABA_CLOUD_API_KEY": {
        "description": (
            "Alibaba Cloud Model Studio pay-as-you-go API key. Use a key from "
            "the same region as the base URL."
        ),
    },
    "ALIBABA_CLOUD_BASE_URL": {
        "description": (
            "Optional Model Studio OpenAI-compatible base URL ending in "
            "/compatible-mode/v1. Defaults to Singapore. Set your regional "
            "or workspace URL when using a key from another region."
        ),
    },
    "QWENCLOUD_API_KEY": {
        "label": "QwenCloud Token Plan API Keys",
        "description": (
            "Dedicated QwenCloud Token Plan key (sk-sp-...). Token Plan, Coding "
            "Plan, and pay-as-you-go keys use separate endpoints and cannot be "
            "mixed."
        ),
    },
    "QWENCLOUD_CODING_API_KEY": {
        "label": "QwenCloud Coding Plan API Keys",
        "description": (
            "Dedicated QwenCloud Coding Plan key (sk-sp-...) for personal, "
            "interactive coding-agent use. Token Plan, Coding Plan, and "
            "pay-as-you-go keys use separate endpoints and cannot be mixed."
        ),
    },
    "TOGETHER_API_KEY": {
        "label": "Together AI API Keys",
        "description": (
            "Together AI OpenAI-compatible API key for serverless and dedicated "
            "chat models."
        ),
    },
    "DEEPINFRA_API_KEY": {
        "label": "DeepInfra API Keys",
        "description": (
            "DeepInfra API key for OpenAI-compatible chat and reasoning models."
        ),
    },
    "SILICONFLOW_API_KEY": {
        "label": "SiliconFlow API Keys",
        "description": (
            "SiliconFlow API key for OpenAI-compatible chat, reasoning, and "
            "vision models."
        ),
    },
    "NEBIUS_API_KEY": {
        "label": "Nebius Token Factory API Keys",
        "description": (
            "Nebius Token Factory API key for OpenAI-compatible chat, reasoning, "
            "and tool-capable models."
        ),
    },
    "OPPER_API_KEY": {
        "label": "Opper API Keys",
        "description": (
            "Opper gateway key for OpenAI-compatible chat, reasoning and "
            "tool-capable models across its EU-hosted model pools."
        ),
    },
    "SCW_SECRET_KEY": {
        "label": "Scaleway API Keys",
        "description": (
            "Scaleway Generative APIs secret key for OpenAI-compatible chat and "
            "tool-capable models."
        ),
    },
    "CHUTES_API_KEY": {
        "label": "Chutes API Keys",
        "description": (
            "Chutes API key for OpenAI-compatible chat, reasoning, and "
            "tool-capable models."
        ),
    },
    "FEATHERLESS_API_KEY": {
        "label": "Featherless AI API Keys",
        "description": (
            "Featherless AI API key for plan-available OpenAI-compatible chat, "
            "reasoning, and tool-capable models."
        ),
    },
    "SAMBANOVA_API_KEY": {
        "label": "SambaNova API Keys",
        "description": (
            "SambaNova Cloud OpenAI-compatible API key (create at "
            "[cloud.sambanova.ai/apis](https://cloud.sambanova.ai/apis))."
        ),
    },
    "CEREBRAS_API_KEY": {
        "label": "Cerebras API Keys",
        "description": (
            "Cerebras Inference API key (create in [Cloud Console](https://cloud.cerebras.ai)); "
            "see [Quickstart](https://inference-docs.cerebras.ai/quickstart) and "
            "[OpenAI compatibility](https://inference-docs.cerebras.ai/resources/openai)."
        ),
    },
    "OLLAMA_API_KEY": {
        "description": (
            "Ollama API key for direct OpenAI-compatible Cloud access at ollama.com/v1."
        ),
    },
    "TOKENROUTER_API_KEY": {
        "label": "TokenRouter API Keys",
        "description": (
            "TokenRouter OpenAI-compatible gateway API key for api.tokenrouter.com/v1."
        ),
    },
    "NARAROUTE_API_KEY": {
        "label": "NaraRoute API Keys",
        "description": (
            "NaraRoute OpenAI-compatible gateway API key for router.bynara.id/v1. "
            "Keys begin with sk-nry-; create one at router.bynara.id/keys."
        ),
    },
    "LIGHTNING_API_KEY": {
        "label": "Lightning AI API Keys",
        "description": (
            "Lightning AI Model APIs key for the OpenAI-compatible endpoint at "
            "lightning.ai/api/v1. Create one on lightning.ai under Model APIs."
        ),
    },
    "ORCAROUTER_API_KEY": {
        "label": "OrcaRouter API Keys",
        "description": (
            "OrcaRouter OpenAI-compatible multi-provider gateway API key for "
            "api.orcarouter.ai/v1. Keys begin with sk-orca-; create one at "
            "www.orcarouter.ai/console."
        ),
    },
    "ATLASCLOUD_API_KEY": {
        "label": "Atlas Cloud API Keys",
        "description": (
            "Atlas Cloud OpenAI-compatible multi-provider gateway API key for "
            "api.atlascloud.ai/v1; create one at console.atlascloud.ai/api-keys."
        ),
    },
    "XKIRO_API_KEY": {
        "label": "xKiro API Keys",
        "description": (
            "xKiro API key for api.xkiro.com/v1. "
            "Create one at xkiro.com/dashboard/api/keys."
        ),
    },
    "AGNES_API_KEY": {
        "label": "Agnes AI API Keys",
        "description": (
            "Agnes AI OpenAI-compatible API key for apihub.agnes-ai.com/v1."
        ),
    },
    "ZENMUX_API_KEY": {
        "label": "ZenMux API Keys",
        "description": (
            "ZenMux OpenAI-compatible gateway API key for zenmux.ai/api/v1. "
            "Create one at zenmux.ai/platform/pay-as-you-go."
        ),
    },
    "WANDB_API_KEY": {
        "label": "W&B Inference API Keys",
        "description": (
            "W&B API key for Serverless Inference at api.inference.wandb.ai/v1. "
            "Create one in [W&B User Settings](https://wandb.ai/settings)."
        ),
    },
    "EXPLABS_API_KEY": {
        "label": "Experiential Labs API Keys",
        "description": (
            "Experiential Labs OpenAI-compatible gateway API key for "
            "api.experientiallabs.ai/v1. Keys look like xpl_ followed by 40 "
            "hex characters; mint one at platform.experientiallabs.ai/settings/api-keys."
        ),
    },
    "CHEAPER_INFERENCE_API_KEY": {
        "label": "Cheaper Inference API Keys",
        "description": (
            "Cheaper Inference OpenAI-compatible gateway API key for "
            "api.cheaperinference.com/v1. "
            "Keys start with ci_live_; create one at cheaperinference.com/signup."
        ),
    },
}


def provider_field_specs() -> tuple[ConfigFieldSpec, ...]:
    """Return provider fields generated from the provider catalog."""

    return (
        *_credential_field_specs(),
        ConfigFieldSpec(
            key="ANTHROPIC_WORKSPACE_ID",
            label="Anthropic Workspace ID",
            section_id="providers",
            settings_attr="anthropic_workspace_id",
            provider_ids=("anthropic",),
            description="Optional for workspace-scoped keys. Required for multi-workspace API keys.",
        ),
        *_cloudflare_account_field_specs(),
        *_vertex_field_specs(),
        *_base_url_field_specs(),
        *_proxy_field_specs(),
    )


def _credential_field_specs() -> tuple[ConfigFieldSpec, ...]:
    specs: list[ConfigFieldSpec] = []
    seen_env_keys: set[str] = set()
    for descriptor in PROVIDER_CATALOG.values():
        if descriptor.credential_env is None:
            continue
        if descriptor.credential_env in seen_env_keys:
            continue
        seen_env_keys.add(descriptor.credential_env)
        specs.append(
            _with_override(
                ConfigFieldSpec(
                    key=descriptor.credential_env,
                    label=f"{descriptor.display_name} API Keys",
                    section_id="providers",
                    field_type="api_key_list",
                    settings_attr=descriptor.credential_attr,
                    provider_ids=tuple(
                        provider.provider_id
                        for provider in PROVIDER_CATALOG.values()
                        if provider.credential_env == descriptor.credential_env
                    ),
                    secret=True,
                )
            )
        )
    return tuple(specs)


def _base_url_field_specs() -> tuple[ConfigFieldSpec, ...]:
    specs: list[ConfigFieldSpec] = []
    for descriptor in PROVIDER_CATALOG.values():
        if descriptor.base_url_attr is None:
            continue
        key = _settings_env_key(descriptor.base_url_attr)
        specs.append(
            _with_override(
                ConfigFieldSpec(
                    key=key,
                    label=f"{descriptor.display_name} Base URL",
                    section_id="providers",
                    settings_attr=descriptor.base_url_attr,
                    provider_ids=(descriptor.provider_id,),
                )
            )
        )
    return tuple(specs)


def _cloudflare_account_field_specs() -> tuple[ConfigFieldSpec, ...]:
    return (
        ConfigFieldSpec(
            key="CLOUDFLARE_ACCOUNT_ID",
            label="Cloudflare Account ID",
            section_id="providers",
            settings_attr="cloudflare_account_id",
            provider_ids=("cloudflare",),
            description=(
                "Cloudflare account ID used to build the /accounts/{id}/ai/v1 endpoint."
            ),
        ),
    )


def _vertex_field_specs() -> tuple[ConfigFieldSpec, ...]:
    return (
        ConfigFieldSpec(
            key="VERTEX_PROJECT_ID",
            label="Google Cloud Project ID",
            section_id="providers",
            settings_attr="vertex_project_id",
            provider_ids=("vertex",),
            description=(
                "Google Cloud project used for Vertex AI. Authentication uses "
                "Application Default Credentials (ADC)."
            ),
        ),
        ConfigFieldSpec(
            key="VERTEX_LOCATION",
            label="Vertex AI Location",
            section_id="providers",
            settings_attr="vertex_location",
            provider_ids=("vertex",),
            description=(
                "Use global for the global Vertex AI endpoint or a region such as "
                "us-central1."
            ),
        ),
    )


def _proxy_field_specs() -> tuple[ConfigFieldSpec, ...]:
    specs: list[ConfigFieldSpec] = []
    for descriptor in PROVIDER_CATALOG.values():
        if descriptor.proxy_attr is None:
            continue
        specs.append(
            _with_override(
                ConfigFieldSpec(
                    key=_settings_env_key(descriptor.proxy_attr),
                    label=f"{descriptor.display_name} Proxy",
                    description="Optional network proxy. Leave blank unless you use one",
                    section_id="providers",
                    field_type="secret",
                    settings_attr=descriptor.proxy_attr,
                    provider_ids=(descriptor.provider_id,),
                    secret=True,
                    advanced=True,
                )
            )
        )
    return tuple(specs)


def _with_override(spec: ConfigFieldSpec) -> ConfigFieldSpec:
    override = _PROVIDER_FIELD_OVERRIDES.get(spec.key)
    if override is None:
        return spec
    return replace(
        spec,
        label=override.get("label", spec.label),
        description=override.get("description", spec.description),
        restart_required=override.get("restart_required", spec.restart_required),
    )


def _settings_env_key(settings_attr: str) -> str:
    model_field = Settings.model_fields[settings_attr]
    alias = model_field.validation_alias
    return str(alias) if alias is not None else settings_attr