- FreeToken claude code works best as a local gateway workflow for coding agents.
- Start locally by installing the launcher, opening the Admin UI, and selecting a provider.
- Route models with a default model plus optional tier-specific overrides.
- Protect credentials by using environment variables, proxy authentication, and restricted directories.
- Troubleshoot methodically by checking the server, port, token, model ID, and client restart state.
What FreeToken Claude Code Does
FreeToken claude code is best understood as a configuration layer between Claude Code and compatible model providers. Instead of changing every client setting separately, you can run a local gateway, select a model in one Admin UI, and connect terminal or editor clients to that gateway.
The practical advantage is centralized routing. A default model can handle normal requests, while separate settings can route Fable, Opus, Sonnet, or Haiku-style tiers to different compatible models. This makes testing easier and lets you change providers without rebuilding your entire client setup.
Centralized Routing
Select models from one interface and apply the configuration across connected coding clients.
Client Flexibility
Use terminal launchers, VS Code, JetBrains, Codex App, or messaging integrations when supported.
Fallback Handling
Add ordered fallback models so a failed provider request can move to another configured option.
| Layer | Main purpose | Recommended starting point |
|---|---|---|
| Local server | Hosts the gateway and Admin UI | Run fcc-server |
| Provider | Supplies the model endpoint | Choose one compatible provider |
| Model | Handles coding requests | Use a tool-capable model |
| Client | Sends prompts and tool calls | Start with Claude Code |
| Security | Controls access to the proxy | Enable authentication when needed |
Begin with one provider and one model. Add routing rules only after the basic Claude Code connection works.
Step-by-Step Setup
Follow these steps in order. The goal is to confirm each layer before moving to the next one, which makes connection errors much easier to isolate.
Install or Update the Launcher
Use the installer appropriate for your operating system, then rerun the same installer when an update is available. Review installation scripts before execution if your environment requires manual approval.
Start the Local Server
On Windows or macOS, open the FreeToken Claude Code launcher. On Linux, start fcc-server from a terminal and keep that terminal available while the server is running.
Open the Admin UI
Use the local Admin UI address shown by the server or tray application. Configure the provider key, proxy port, and authentication token from this interface.
Select and Validate a Model
Search the model picker, select an exact provider model ID, then click Validate and Apply. If a provider cannot list models, enter the provider prefix and exact model ID manually.
Launch Claude Code
Start the matching client command, such as fcc-claude, and test a small coding request before adding editor extensions or fallback routes.
The first successful test should be deliberately simple: ask the agent to inspect a small project file, explain a function, or suggest a minor change. Avoid starting with a large refactor because a small request confirms authentication, model access, context handling, and tool permissions together.
| Setup checkpoint | What to verify | If it fails |
|---|---|---|
| Server | Local process remains active | Restart fcc-server |
| Admin UI | Page loads at the configured address | Check the port and firewall |
| Provider | Key validates successfully | Recheck key scope and provider terms |
| Model | Exact model ID is accepted | Use the model picker or full prefix |
| Client | Claude Code reaches the gateway | Match URL, token, and port |
Do not configure several clients at once. Confirm Claude Code first, then duplicate the working gateway settings in VS Code or JetBrains.
Model Routing and Provider Choices
Model selection should reflect the task rather than the brand name alone. Coding agents need reliable tool calling, enough context for project instructions, and stable output formatting. A model that performs well in chat may still be a poor fit for an agent that must inspect files and run commands.
Use the default MODEL setting for ordinary requests. Tier-specific variables can override individual Claude Code tiers when you need different behavior for complex reasoning, fast edits, or lightweight tasks.
| Routing setting | Role | Practical use |
|---|---|---|
MODEL | Global fallback | Use for most requests |
MODEL_OPUS | Complex reasoning override | Large design or debugging tasks |
MODEL_SONNET | Balanced override | Daily implementation work |
MODEL_HAIKU | Lightweight override | Short explanations and quick edits |
| Fallback Models | Ordered backup route | Provider outages or quota limits |
Hosted Provider
Convenient setup and broad model access, but availability, quotas, and terms can change.
Local Runtime
Useful for privacy-sensitive work and offline experimentation, provided the model supports tools and sufficient context.
Hybrid Route
Keep a hosted default and use a local or secondary provider as a fallback when appropriate.
When adding fallbacks, remember that a failed request may reach more than one provider before succeeding. That can consume usage from multiple accounts. Keep the list short, order it intentionally, and avoid routing sensitive project content to a provider you have not reviewed.
Reasoning controls may be inherited from the client, disabled, or set to a selected effort level. Start with the client default. Increase reasoning only for tasks that benefit from deeper planning, because higher effort can increase latency and resource use.
Free-tier access, quotas, model catalogs, and acceptable-use rules are controlled by individual providers. Check current terms before routing project data.
Client Connections and Safety
Claude Code can connect through a local base URL and authentication token. In editor integrations, the same values must match the gateway configuration exactly. A single character error in the port, URL, or token can look like a provider failure even when the provider is working normally.
For VS Code, add the gateway environment variables to the Claude Code extension settings, then reload the extension. For Codex App or Codex in VS Code, place the provider and model settings in the appropriate config.toml file and restart the client after changing models.
| Client surface | Core configuration | Restart required |
|---|---|---|
| Terminal | Launch with fcc-claude | Usually no extra restart |
| VS Code | Extension environment variables | Reload the extension |
| JetBrains | Claude ACP environment | Restart the IDE |
| Codex App | Provider block in config.toml | Restart the app |
| Messaging | Bot token, user ID, directory | Restart server if requested |
Use these safety practices:
- Store provider credentials outside project files.
- Enable proxy authentication before exposing the gateway beyond localhost.
- Restrict Discord or Telegram integrations to approved users, channels, and directories.
- Avoid placing secrets in prompts, logs, screenshots, or shared configuration files.
- Review the permissions requested by each bot and client integration.
- Keep the project directory narrow rather than granting access to an entire home folder.
Before Your First Real Project:
- Confirm the gateway listens on the intended local port
- Validate one provider and one tool-capable model
- Enable proxy authentication when required
- Restrict allowed directories and messaging users
- Remove credentials from shell history and project files
Treat the local gateway as a development service, not a public endpoint. Do not expose it to the internet unless you understand its authentication and network controls.
Troubleshooting and FAQ
Most setup problems fall into four categories: the server is not running, the client points to the wrong address, the token does not match, or the selected model is unavailable. Check those conditions in that order before changing multiple settings.
| Symptom | Likely cause | Fix |
|---|---|---|
| Admin UI will not open | Server stopped or wrong port | Start fcc-server and use its displayed address |
| Client asks for login | Onboarding state is incomplete | Finish the client setup, then restart it |
| Model list is empty | Provider cannot return a catalog | Enter the exact model ID manually |
| Request fails after validation | Model lacks required capabilities | Select a tool-capable model |
| Editor still uses old settings | Extension cached configuration | Reload the extension or restart the IDE |
| Fallback behaves unexpectedly | Multiple providers receive retries | Review fallback order and usage impact |
Q: What is FreeToken claude code used for?
It refers to a local gateway workflow that connects Claude Code with configured hosted or local model providers. The gateway centralizes model selection, authentication, and optional fallback routing.
Q: Which model should I choose first?
Start with a provider model that supports coding tools and has enough context for your agent instructions. Use the model picker when available, and enter the exact provider-prefixed ID when manual setup is required.
Q: Why does Claude Code keep asking me to log in?
The client may still be using its normal onboarding flow, or the gateway URL and token may not match. Verify both values, complete any required local onboarding, and restart Claude Code or the editor.
Q: Can I use fallback models?
Yes. Add an ordered fallback list in the gateway configuration, but review provider terms and usage because a failed request may be sent to more than one configured provider.
A stable setup has one confirmed server, one validated provider, one tested model, and a client that has been restarted after configuration changes.