Sign In
11

How to Connect AI Agents to CostRouter with One API Key

 

AI agents are becoming a practical way to automate coding, document generation, data processing, research, and daily technical workflows. Instead of only chatting with an AI model in a web interface, an AI agent can read files, understand a project directory, generate code, edit documents, run commands, and help complete multi-step tasks.

To use these agents efficiently, you usually need two things: an API key and a model endpoint. CostRouter makes this easier by providing one API key for multiple AI models. In many tools, you only need to replace the default provider endpoint with CostRouter’s API request URL and use your CostRouter API key.

This guide explains how to connect an AI agent to CostRouter, using Codex and CC Switch as the example workflow.

What You Need Before Starting

Before connecting your agent, make sure you have the following:

  • A CostRouter account

  • A valid CostRouter API key

  • Enough account balance or access to the model you want to use

  • Git installed on your computer (Download: https://git-scm.com/downloads/win)

  • Node.js installed on your computer (Download: https://git-scm.com/downloads/win)

  • Codex installed on your computer

  • CC Switch installed, if you want an easier way to manage provider settings (Download: https://github.com/farion1231/cc-switch)

  • A model name you want to call, such as gpt-5.5, gpt-4o, or another model supported in your CostRouter dashboard

The basic idea is simple:

AI Agent → CC Switch or Agent Config → CostRouter API → Target AI Model

Instead of configuring every model provider separately, you configure the agent once with your CostRouter API key and CostRouter API request URL.

Step 1: Install Git

If you are using Windows, we recommend installing Git before setting up your AI agent environment.

Visit the official Git download page:

https://git-scm.com/downloads/win

During installation, we recommend using the default installation path, usually on the C drive. This can help avoid unnecessary path or permission errors later.

For most users, you can simply click “Next” through the installation process without changing the default options.

If you are using macOS, you may not need to install Git separately. Many macOS development environments already include Git or can install it automatically when required.

Step 2: Install Node.js

Next, install Node.js. Some AI agent tools and command-line utilities depend on Node.js, so it is a good idea to install it before setting up Codex or related tools.

Visit the official Node.js download page:

https://nodejs.org/zh-cn/download

For Windows users, we also recommend using the default installation path on the C drive. In most cases, you can keep all default settings and continue clicking “Next” until the installation is complete.

After installing Node.js, you can open a terminal and check whether it is installed correctly:

node -v

You can also check npm:

npm -v

If both commands return version numbers, Node.js has been installed successfully.

Step 3: Install Codex

After Git and Node.js are installed, you can install Codex on your computer.

For Windows users, open PowerShell and run the following command:

npm install -g @openai/codex

This command installs Codex globally, so you can start it from your terminal later.

After installation, you can check whether Codex is available by running:

codex

If Codex starts normally, the installation is complete.

Step 4: Get Your CostRouter API Key

Log in to your CostRouter dashboard and create or copy your API key.

Your API key is used to authenticate requests. Keep it private and do not share it publicly. Never upload it to GitHub, paste it into public documents, or expose it in frontend code.

In API requests, the key is usually passed as a Bearer token:

Authorization: Bearer sk-xxxx

Replace sk-xxxx with your real CostRouter API key.

Step 5: Connect Codex with CC Switch

Codex is an AI coding agent that can run in your terminal and work with files in your local project directory. CC Switch is useful because it lets you manage different providers and switch between them without manually editing every configuration file.

Open CC Switch first. On the provider list page, click the orange + button in the top-right corner to add a new provider.

Weixin Image_2026-07-07_140353_956.png

 

After clicking the + button, CC Switch will open the Add New Provider page.

On this page, fill in the CostRouter API information as follows:

Website URL: https://costrouter.ai/
API Key: Your CostRouter API key from the dashboard
API Request URL: https://costrouter.ai/v1
Model Name: gpt-5.5

image.png

 

A few important notes:

  • The API key should be copied from your CostRouter dashboard.

  • The API request URL should normally be https://costrouter.ai/v1.

  • The model name must match a model available in your CostRouter account.

  • Do not add /chat/completions to the API Request URL field unless the tool specifically asks for a full endpoint URL.

After filling in the information, click Add to save the provider.

Then return to the CC Switch main page and select the CostRouter provider. If Codex is already open in your terminal, close the terminal and reopen it before launching Codex again.

After restarting your terminal, run:

codex

Then test it with a simple prompt:

Hello, please briefly introduce yourself and confirm which model you are using.

If the model responds normally, your Codex agent is now connected through CostRouter.

Step 6: Manual Codex Configuration

Advanced users can also configure Codex manually.

Codex usually stores API authentication and model provider settings in local configuration files. A typical setup may include an API key file and a configuration file.

Example ~/.codex/auth.json:

{
  "OPENAI_API_KEY": "sk-xxxx"
}

Example ~/.codex/config.toml:

model_provider = "costrouter"
model = "gpt-5.5"
model_reasoning_effort = "high"
disable_response_storage = true

[model_providers.costrouter]
name = "CostRouter"
base_url = "https://costrouter.ai/v1"
wire_api = "responses"
requires_openai_auth = true

In this example:

  • model_provider tells Codex which provider profile to use.

  • model tells Codex which model to request.

  • base_url points requests to CostRouter.

  • requires_openai_auth = true allows the provider to use OpenAI-style API key authentication.

  • wire_api = "responses" is suitable for Codex-style Responses API workflows.

After saving the configuration, restart your terminal and run:

codex

Step 7: Test the Agent in a Real Project

Open a project folder and start Codex:

cd your-project-folder
codex

Try a practical task:

Read this project and create a clear README.md file. Explain the installation steps, main features, and basic usage.

You can also ask the agent to:

Review this codebase and suggest three improvements.

Or:

Create a simple Python script that reads a CSV file and generates a summary report.

If Codex can read the project, generate suggestions, and produce files normally, your agent setup is ready for real work.

Step 8: Use Other AI Agents with the Same Logic

The same integration logic applies to many AI agent tools.

In most cases, you only need to find the tool’s API settings and replace two fields:

API Key: your CostRouter API key
Base URL or API Request URL: https://costrouter.ai/v1

Some tools call this setting Base URL, API Endpoint, OpenAI Base URL, Custom Provider URL, Gateway URL, or API Request URL.

If the tool supports OpenAI-compatible APIs, it can often work with CostRouter by changing only the API request URL and API key.

Common Problems and Fixes

1. Authentication Failed

This usually means the API key is missing, incorrect, expired, or pasted in the wrong field.

Check that your request uses:

Authorization: Bearer sk-xxxx

Also confirm that there are no extra spaces before or after the key.

2. No Access or No Balance

If the API key is correct but the request still fails, check your CostRouter account balance, billing settings, and model access.

3. Wrong Model Name

The model name must match a model available in CostRouter. If the model name is not recognized, open your CostRouter dashboard and copy the exact model ID.

4. Codex Still Uses the Old Provider

After switching providers in CC Switch, close and reopen your terminal. Codex may not immediately reload the new provider configuration in an already-open terminal session.

5. Endpoint Format Error

Make sure the API request URL is:

https://costrouter.ai/v1

Do not add /chat/completions to the API Request URL or Base URL field unless the tool specifically asks for a full endpoint URL.

Usually:

Base URL or API Request URL = https://costrouter.ai/v1
Endpoint path = /chat/completions

6. Streaming or Tool Calling Does Not Work

Streaming, tool calling, structured output, and other advanced features depend on both the agent tool and the selected upstream model. If one model does not work as expected, test another model or check whether the selected model supports the required feature.

Best Practices for API Key Security

API keys should be treated like passwords.

Follow these basic rules:

  • Do not share your API key publicly.

  • Do not commit your key to GitHub.

  • Do not put your key in frontend JavaScript.

  • Use environment variables when possible.

  • Create separate keys for different projects or team members.

  • Rotate the key if you suspect it has been exposed.

For team usage, we recommend creating a separate CostRouter key for each workflow or team member. This makes usage tracking and troubleshooting easier.

Why Use CostRouter for AI Agents?

AI agents can consume a large number of tokens when they read files, reason through tasks, generate code, and iterate on results. For teams using agents every day, model cost, stability, routing, and visibility become important.

CostRouter helps by giving developers and teams a unified way to access multiple AI models through one API key. Instead of rebuilding integrations for every model provider, you can keep a familiar API format and manage usage in one place.

This is especially useful for:

  • Coding agents

  • Document generation workflows

  • Data analysis agents

  • Customer support automation

  • Internal productivity tools

  • Multi-model AI applications

Conclusion

Connecting an AI agent to CostRouter is usually straightforward. You only need four key pieces of information:

Website URL: https://costrouter.ai/
API Key: your CostRouter API key
API Request URL: https://costrouter.ai/v1
Model Name: the model you want to use

For Codex users, CC Switch provides a convenient way to manage this setup without manually editing configuration files. After adding CostRouter as a provider, enable it, restart your terminal, and launch Codex.

Once connected, your AI agent can use CostRouter to access powerful AI models through one unified API key.

Contact us

Choose the channel that best matches your request.

Customer supportsupport@costrouter.aiSales inquirysales@costrouter.ai
Contact us