> ## Documentation Index
> Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating your LLM

> Configure cloud and local LLM providers for Trading Agents

Condor supports multiple LLM providers through two integration methods:

* **ACP Protocol**: Native integration with Claude Code, Gemini, GitHub Copilot, and Codex
* **PydanticAI**: Direct API access to OpenRouter and to local models via Ollama and LM Studio

See [ACP documentation](https://agentclientprotocol.com/get-started/introduction) for the full protocol specification.

<Note>
  <strong>Before installing Condor:</strong> Install and authenticate your LLM provider in the CLI first.<br />
  <strong>Already installed Condor?</strong> Set up your LLM provider, then restart Condor for the changes to take effect.
</Note>

## Using the `/agent` Command

The `/agent` command in Telegram is how you connect Condor to your LLM and run autonomous Trading Agents. From the `/agent` menu you can:

* **Change LLM** — pick which installed provider to use for new sessions
* **Start** — launch an agent session with the currently selected LLM
* **Stop** — end the active session
* **Status** — view the currently active provider and model

A typical first-time flow is: install and authenticate your provider in the CLI, then in Telegram run `/agent` → **Change LLM** → pick your provider → `/agent` → **Start**. Full step-by-step instructions are in [Configure in Telegram](#configure-in-telegram).

## Supported Providers

### Cloud Providers (ACP Protocol)

| Provider           | Agent Key     | Installation                                    |
| ------------------ | ------------- | ----------------------------------------------- |
| **Claude Code**    | `claude-code` | `curl -fsSL https://claude.ai/install.sh \| sh` |
| **Gemini**         | `gemini`      | `npm install -g @google/gemini-cli`             |
| **GitHub Copilot** | `copilot`     | `npm install -g @github/copilot-cli`            |
| **Codex**          | `codex`       | `npx @zed-industries/codex-acp`                 |

### API Key Providers (PydanticAI)

| Provider       | Agent Key    | Setup                                                    |
| -------------- | ------------ | -------------------------------------------------------- |
| **OpenRouter** | `openrouter` | Set `OPENROUTER_API_KEY` — see [OpenRouter](#openrouter) |

### Local Providers

| Provider      | Agent Key  | Installation                                     |
| ------------- | ---------- | ------------------------------------------------ |
| **Ollama**    | `ollama`   | `curl -fsSL https://ollama.com/install.sh \| sh` |
| **LM Studio** | `lmstudio` | Download from [lmstudio.ai](https://lmstudio.ai) |

## Setup Instructions

### Claude Code

Claude Code is the default and most integrated option for Condor Trading Agents.

**1. Install Claude Code:**

Install via CLI:

```bash theme={null}
# macOS/Linux
curl -fsSL https://claude.ai/install.sh | sh
```

**2. Authenticate:**

```bash theme={null}
claude auth login
```

Follow the prompts to sign in with your Anthropic account.

**3. Verify installation:**

```bash theme={null}
claude --version
claude  # Run Claude and see if it starts up without issues
```

**4. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `Claude Code` label.

### Gemini

**1. Install Gemini CLI:**

```bash theme={null}
npm install -g @google/gemini-cli
```

**2. Authenticate:**

Start Gemini CLI — on first run it will prompt you to authenticate:

```bash theme={null}
gemini
```

Select **Login with Google** and follow the OAuth flow in your browser. Your credentials are cached locally for future sessions. Alternatively, set a `GEMINI_API_KEY` environment variable from [Google AI Studio](https://aistudio.google.com/).

**3. Verify:**

```bash theme={null}
gemini --version
```

**4. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `Gemini CLI` label.

### GitHub Copilot

**1. Install prerequisites:**

```bash theme={null}
# Install Copilot CLI
npm install -g @github/copilot-cli
```

**2. Authenticate:**

```bash theme={null}
gh auth login
copilot auth login
```

**3. Verify:**

```bash theme={null}
copilot --version
copilot  # Run Copilot and see if it starts up without issues
```

**4. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `Github Copilot CLI` label.

### Codex

Condor connects to Codex through Zed's ACP bridge (`@zed-industries/codex-acp`). You'll need the Codex CLI installed and authenticated, plus the ACP bridge available for Condor to invoke.

**1. Install the Codex CLI:**

Download and install Codex from [openai.com/codex](https://openai.com/codex).

**2. Sign in:**

Open Codex and sign in with your ChatGPT account or an OpenAI API key.

**3. Install the ACP bridge:**

```bash theme={null}
npx @zed-industries/codex-acp
```

Running this once fetches the package so Condor can invoke it via `npx`. You can also install it globally with `npm install -g @zed-industries/codex-acp`.

**4. Verify installation:**

```bash theme={null}
codex --version
codex  # Run Codex and see if it starts up without issues
```

**5. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `ChatGPT Codex` label.

### OpenRouter

OpenRouter routes requests to many models — including some free ones — through a single API key, often at lower cost than going to a provider directly. Condor connects to it through PydanticAI's OpenAI-compatible client, so no CLI install is required.

**1. Get an API key:**

Create a key at [openrouter.ai/keys](https://openrouter.ai/keys).

**2. Set the environment variable:**

Add your key to Condor's `.env`:

```bash theme={null}
OPENROUTER_API_KEY=sk-or-...
```

**3. Configure in Telegram:**

Run `/agent` → **Change LLM** → **OpenRouter — Pick Model**. Condor fetches the live OpenRouter catalog and lists only models that advertise tool-call support (Condor's agents depend on tool calling, so models without it are filtered out). Pick one from the list, or choose **Enter model manually** to provide a model slug.

Your selection is stored as `openrouter:<model>` — for example `openrouter:anthropic/claude-sonnet-4-5`. To run at no cost, choose one of the `openrouter/free` models.

<Note>
  If a request fails with an insufficient-credits error, add credits to your OpenRouter account or switch to a `openrouter/free` model.
</Note>

### Ollama (Local)

Perfect for development, testing, and cost-effective experimentation.

**1. Install Ollama:**

Visit [ollama.com](https://ollama.com) and download for your platform.

```bash theme={null}
# macOS/Linux
curl -fsSL https://ollama.com/install.sh | sh
```

**2. Start Ollama service:**

```bash theme={null}
ollama serve
```

**3. Pull a model:**

```bash theme={null}
# Recommended for trading agents
ollama pull llama3.1:70b        # Large, capable model
ollama pull qwen2.5:32b         # Good balance
ollama pull llama3.1:8b         # Fast, lightweight
```

Verify the downloaded model is listed

```bash theme={null}
ollama list
```

**Model Selection:**

When you don't specify an explicit model (e.g., `agent_key: ollama`), Condor automatically selects one:

1. Checks environment variables (`CONDOR_DEFAULT_LOCAL_MODEL` or `OLLAMA_MODEL`)
2. Queries the Ollama API (`/api/tags`) and uses the first available model
3. If no model is found, prompts you to specify one explicitly

**4. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `Ollama - Default Model` label.

<Note>
  Local models have a reduced tool surface depending on parameter count — see [Tool Filter Modes](#tool-filter-modes).
</Note>

**Custom server (optional):**

To point Condor at a specific model or a remote Ollama server, add the following to your Condor agent configuration (e.g., `config/agents.yaml`):

```yaml theme={null}
agent_key: ollama:llama3.1:70b
model_base_url: http://your-server:11434/v1
```

### LM Studio (Local)

GUI-based local model hosting with OpenAI-compatible API.

**1. Install LM Studio:**

Download from [lmstudio.ai](https://lmstudio.ai)

**2. Download a model:**

* Open LM Studio
* Browse the model library
* Download a model (e.g., Qwen 2.5, Llama 3.1)

**3. Start local server:**

* Go to "Local Server" tab
* Click "Start Server"
* Default port: 1234
* Make sure a model is loaded

**4. Configure in Telegram:**

Follow the [Configure in Telegram](#configure-in-telegram) steps and select the `LM Studio - Default Model` label.

<Note>
  Local models have a reduced tool surface depending on parameter count — see [Tool Filter Modes](#tool-filter-modes).
</Note>

**Custom port or model (optional):**

To target a specific model or a non-default port, add the following to your Condor agent configuration (e.g., `config/agents.yaml`):

```yaml theme={null}
agent_key: lmstudio:your-model-name
model_base_url: http://localhost:1234/v1
```

## Configure in Telegram

Once your provider is installed and authenticated, connect it to Condor from Telegram.

**1. Select your provider:**

Run the `/agent` command and select `Change LLM`, then choose your provider using the label from the table below.

You should see a confirmation message:

```
LLM set to <Provider Label>. New sessions will use this model.

Use /agent to continue.
```

**2. Start the agent:**

Run the `/agent` command again and click `Start`.

Once the agent is ready you'll see:

```
Condor is ready. Send a message to start chatting.

Use /agent to see options or any other command to exit.
```

You can now send a message to the agent and start chatting.

### Provider labels

| Provider       | Telegram label              |
| -------------- | --------------------------- |
| Claude Code    | `Claude Code`               |
| Gemini         | `Gemini CLI`                |
| GitHub Copilot | `Github Copilot CLI`        |
| Codex          | `ChatGPT Codex`             |
| OpenRouter     | `OpenRouter — Pick Model`   |
| Ollama         | `Ollama - Default Model`    |
| LM Studio      | `LM Studio - Default Model` |

## Tool Filter Modes

Local models automatically adjust tool availability based on size:

* **Essential** (≤8B params): Minimal tools, basic operations
* **Moderate** (9-32B params): Common trading operations
* **Full** (>32B params, cloud): All available tools

Larger models handle more complex tool interactions. Cloud providers always get full tool access.

## Choosing the Right Provider

### For Production Trading

**Recommended:** Claude Code or ChatGPT Codex

* High reliability and uptime
* Strong reasoning capabilities
* Full tool access
* Consistent performance

### For Development

**Recommended:** Ollama or LM Studio

* No API costs
* Fast iteration
* Full control over model
* Privacy (runs locally)

### Performance Comparison

| Provider           | Reasoning | Speed | Cost   | Reliability |
| ------------------ | --------- | ----- | ------ | ----------- |
| Claude Code        | ⭐⭐⭐⭐⭐     | ⭐⭐⭐⭐  | 💰💰   | ⭐⭐⭐⭐⭐       |
| ChatGPT Codex      | ⭐⭐⭐⭐⭐     | ⭐⭐⭐⭐⭐ | 💰💰💰 | ⭐⭐⭐⭐⭐       |
| Gemini CLI         | ⭐⭐⭐⭐      | ⭐⭐⭐⭐⭐ | 💰     | ⭐⭐⭐⭐        |
| GitHub Copilot CLI | ⭐⭐⭐⭐      | ⭐⭐⭐⭐  | 💰💰   | ⭐⭐⭐⭐        |
| Ollama (70B)       | ⭐⭐⭐⭐      | ⭐⭐⭐   | Free   | ⭐⭐⭐         |
| Ollama (8B)        | ⭐⭐⭐       | ⭐⭐⭐⭐⭐ | Free   | ⭐⭐⭐         |

## Troubleshooting

### "Command not found" errors

If Condor can't find your LLM CLI:

1. **Verify installation:**

```bash theme={null}
which claude
which gemini
which copilot
which codex
```

2. **Check PATH:**

```bash theme={null}
echo $PATH
```

3. **Restart Condor** after installing LLM tools:

```bash theme={null}
# If running via make
make stop
make run

# If running via Docker
docker compose restart
```

### Changed LLM but Condor still uses the old one

`Change LLM` only affects **new sessions**. Stop any active agent session with `/agent` → `Stop` (or send any non-agent command), then run `/agent` → `Start` to pick up the new provider. If it still persists, restart Condor:

```bash theme={null}
# If running via make
make stop && make run

# If running via Docker
docker compose restart
```

### Authentication Issues

**Claude Code:**

```bash theme={null}
claude auth logout
claude auth login
```

**Gemini:**

Re-run `gemini` and select a different authentication method, or clear cached credentials and restart the interactive login:

```bash theme={null}
rm -rf ~/.gemini/oauth_creds.json
gemini
```

**Copilot:**

```bash theme={null}
gh auth logout
gh auth login
copilot auth login
```

### Local Model Connection Errors

**Ollama not running:**

```bash theme={null}
# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama
ollama serve
```

**LM Studio not running:**

* Open LM Studio app
* Go to "Local Server" tab
* Click "Start Server"

### Model Not Found (Ollama)

If you get "No local model found":

```bash theme={null}
# List available models
ollama list

# Use exact model name in agent_key
agent_key: ollama:llama3.1:70b-instruct-q4_0
```

Or set a default:

```bash theme={null}
export CONDOR_DEFAULT_LOCAL_MODEL=llama3.1:70b
```

## Best Practices

**Installation Order:**

1. Install LLM provider CLIs first
2. Authenticate with each provider
3. Test the CLI tools independently
4. Then install / start Condor

**Security:**

* Use CLI authentication tools (not environment variables when possible)
* Never commit credentials to git
* Use separate API keys for development and production

**Model Selection:**

* Start with Claude Code or ChatGPT Codex for best results
* Use Ollama 70B+ for cost-effective alternatives
* Avoid models under 8B for complex trading strategies

## Additional Resources

<CardGroup cols={2}>
  <Card title="ACP Documentation" icon="link" href="https://agentclientprotocol.com">
    Agent Client Protocol specification
  </Card>

  <Card title="Claude Code Guide" icon="book" href="https://claude.ai/code/docs">
    Official Claude Code documentation
  </Card>

  <Card title="Ollama Library" icon="database" href="https://ollama.ai/library">
    Browse available Ollama models
  </Card>

  <Card title="Trading Agents" icon="rocket" href="/trading-agents/overview">
    Build your first Trading Agent
  </Card>
</CardGroup>