# T3 Code Setup with QCode.cc

> **Last verified**: 2026-11-09 · 📄 Per official docs (T3 Code v0.1.7, released 2026-11-04; the T3 Code docs on the main branch were read on 2026-11-09)

## At a glance

| Item | Details |
|---|---|
| What it is | T3 Code is an "agent harness control surface" with a desktop app, a web app and a mobile app. It uses the agents already on your machine and is not a harness itself |
| Models you can use | Claude ✅ (a Claude instance pointed at the Anthropic endpoint) · Chinese models (GLM / Kimi / DeepSeek / Qwen) are also served on that endpoint, see [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) · GPT ❌ on this path · Gemini ❌ (QCode does not offer Gemini models for now) |
| Protocol & Base URL | Anthropic: `https://api.qcode.cc/api` |
| Where to configure | **Settings > Providers** → a Claude instance → **Environment variables** |
| Official docs | [T3 Code Claude provider guide](https://github.com/pingdotgg/t3code/blob/main/docs/user/providers-claude.md) · [FAQ](https://github.com/pingdotgg/t3code/blob/main/docs/user/faq.md) |

## Which protocol

T3 Code does not call a model API on its own. In the official FAQ: "T3 Code uses those harnesses. It is not a harness, and it does not work without one." For Claude, the harness is Claude Code, so QCode is wired in the same way as for Claude Code itself: an Anthropic Messages base URL and a QCode key.

The official FAQ answers yes to whether you can use an API key or OpenRouter instead of a subscription: add another provider instance in Settings and give it its own keys and endpoint; your subscription setup stays untouched.

| You want | Use in T3 Code | QCode `ANTHROPIC_BASE_URL` |
|---|---|---|
| Claude (`claude-sonnet-5`, `claude-opus-5` …) | A Claude instance with its own **Environment variables** | `https://api.qcode.cc/api` |
| Codex / GPT | A Codex instance, see "Codex instances" below | not applicable |

Claude models only work on the Anthropic protocol, so the base URL stops at `/api`; Claude Code appends `/v1/messages` itself. Do not add a trailing `/`. The full protocol table is in [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

## Install

T3 Code needs at least one provider installed on the machine that runs the agents. For this guide that is Claude Code; install it first with the [QCode installation guide](/docs/getting-started/installation). The Claude instance you add under Configure authenticates with your QCode key.

Then install T3 Code. Official commands:

```bash
curl -fsSL https://t3.codes/install.sh | sh
```

On Windows, in PowerShell:

```powershell
irm https://t3.codes/install.ps1 | iex
```

Run `t3` to start the server and open the local web app. To try it once without installing, run `npx t3@latest`. The desktop app is also available from [GitHub Releases](https://github.com/pingdotgg/t3code/releases) or a package manager:

| Platform | Install |
|---|---|
| Windows | `winget install T3Tools.T3Code` |
| macOS | `brew install --cask t3-code` |
| Debian, Ubuntu | `sudo apt install ./T3-Code-*.deb` |
| Arch Linux | `yay -S t3code-bin` |

There is no `t3` executable for Intel Macs; use the desktop app there. Other platforms and the mobile apps are listed in the [official install guide](https://github.com/pingdotgg/t3code/blob/main/docs/user/install.md).

## Configure

The official recipe for a router that speaks the Anthropic protocol is a separate Claude instance with its own config directory. These steps apply it to QCode.

The official install guide adds that each provider instance can have its own environment variables, such as API keys or a custom base URL, and that T3 Code does not display values marked sensitive after saving.

1. Open **Settings > Providers** and add a Claude instance. Keep **Binary path** set to `claude`. Set **CLAUDE_CONFIG_DIR path** to a folder of its own; the official OpenRouter example uses `~/.claude_openrouter`, so a name such as `~/.claude_qcode` follows the same idea.
2. In that instance's **Environment variables**, add:

   | Variable | Value |
   |---|---|
   | `ANTHROPIC_BASE_URL` | `https://api.qcode.cc/api` |
   | `ANTHROPIC_AUTH_TOKEN` | Your QCode key (starts with `cr_`), marked Sensitive |
   | `ANTHROPIC_API_KEY` | An explicitly empty value |

   Variable assignments belong in **Environment variables**, not in **Launch arguments**.
3. If that Claude config directory has a cached Anthropic login, run `/logout` in a Claude Code session that uses the same directory before you start. The official guide warns that cached login credentials can conflict with the router token.
4. Select the model in T3 Code. For a model outside the built-in list, open that Claude instance in **Settings > Providers** and add its full model ID with **Add custom model**, for example `claude-sonnet-5` from [qcode.cc/models](https://qcode.cc/models). Then select it in the chat model picker.

Two details from the official guide: `ANTHROPIC_DEFAULT_*_MODEL` variables map Claude Code aliases such as `sonnet`; they do not replace the explicit model ID selected in T3 Code. Custom models may have fewer effort, thinking, or context controls than built-in models.

The same key works on the other QCode access domains (`us.qcode.cc`, `asia.qcode.cc`); swap the host in `ANTHROPIC_BASE_URL` and keep the `/api` path. See [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths).

### Codex instances

T3 Code's Codex guide covers signing in with ChatGPT or with an existing Codex CLI login. Where an instance that uses your installed Codex reads its configuration is visible in the T3 Code source (v0.1.7 release; the main branch read on 2026-11-09 has the same lines):

- For an instance that uses an installed Codex, T3 Code starts Codex's app server and sets `CODEX_HOME` to the **CODEX_HOME path** you entered (`apps/server/src/provider/CodexProvider.ts`, lines 476–482). The Codex guide's own example uses `~/.codex` there.
- The Codex app-server schema bundled in the source describes the user config layer as `$CODEX_HOME/config.toml` (`packages/effect-codex-app-server/src/_generated/schema.gen.ts`, line 19730).
- The connection made with ChatGPT inside T3 Code is different: T3 Code sets its own `model_provider` and removes `OPENAI_BASE_URL` for it (`apps/server/src/provider/CodexManagedRuntime.ts`, lines 24–26 and 124), so QCode settings do not apply there.

So, as of T3 Code v0.1.7, a Codex instance that uses your existing Codex install reads the `config.toml` of its Codex home. Set up Codex for QCode first as described in the [Codex guide](/docs/ide/codex): the `qcode` provider in `~/.codex/config.toml` and your key as `OPENAI_API_KEY` in `~/.codex/auth.json`. Then, in **Settings > Providers**, add a Codex instance, choose **Configure manually** and complete the wizard; point the instance's **CODEX_HOME path** at the folder that holds these two files (for example `~/.codex`). Select that instance from the thread's model picker.

## Verify

1. Start a new thread, choose the Claude instance and the custom model, and send a short message such as `ping`.
2. Open [probe.qcode.cc](https://probe.qcode.cc), enter your QCode key and check that the request appears with the model you chose. This is the QCode counterpart of the official advice to verify the model in the router's activity dashboard.
3. To test the key and path without T3 Code:

```bash
curl -X POST https://api.qcode.cc/api/v1/messages \
  -H "x-api-key: YOUR_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":32,"messages":[{"role":"user","content":"ping"}]}'
```

## Troubleshooting

| Symptom | Cause | Fix |
|---|---|---|
| The provider does not show up | The CLI is not installed or not on the `PATH` of the machine that runs the server | Install `claude` there, or point **Binary path** at it in provider settings (official FAQ) |
| `Invalid API key` | Wrong key or stray whitespace | Check the key starts with `cr_`; set it in `ANTHROPIC_AUTH_TOKEN` and keep `ANTHROPIC_API_KEY` empty |
| Authentication errors although the key is right | A cached Anthropic login in the same Claude config directory | Run `/logout` in a Claude Code session that uses that directory, or give the instance a new config directory |
| 404 | Trailing `/` or `/v1/messages` written into the base URL | Use exactly `https://api.qcode.cc/api` |
| The request is rejected for the model | A GPT model ID was selected in the Claude instance; the Anthropic endpoint does not serve GPT | Use a Claude or Chinese model ID there; GPT models go through Codex |
| The model is missing from the picker | It is not in the built-in list | Add the full ID with **Add custom model** |
| 402 with `*_cost_limit_exceeded` | The key's quota is used up | See [Error Codes](/docs/reference/errors#402-quota-exhausted) |

## Known limitations

- T3 Code states that it is early software: "We are very very early in this project. Expect bugs."
- The router setup in the official guide is written for Claude instances; GPT models go through a Codex instance, as described under Codex instances above.
- On a remote connection, T3 Code uses the Claude configuration on the connected server, so set the instance up on that machine.

## Related

- [Endpoints & API Paths](/docs/getting-started/endpoints-and-api-paths) — protocol × model-family table
- [Tool Compatibility Overview](/docs/ide/tool-compatibility) — which tools speak which protocol
- [Codex CLI](/docs/ide/codex) — `config.toml` for QCode
- [DeepSeek Harness (dsh)](/docs/ide/deepseek-harness) — an agent harness with a custom model API form