# T3 Code 接入 QCode

> **最后核实**：2026-11-09 · 📄 依据官方文档（T3 Code v0.1.7，2026-11-04 发布；T3 Code 主分支文档于 2026-11-09 读取）

## 接入速览

| 项目 | 说明 |
|---|---|
| 它是什么 | T3 Code 是一个 "agent harness control surface"，有桌面端、网页端和手机端。它调度你机器上已有的 agent，本身不是 harness |
| 可用模型 | Claude ✅（指向 Anthropic 端点的 Claude 实例）· 国产模型（GLM / Kimi / DeepSeek / Qwen）在该端点上同样可用，见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) · GPT ❌（这条路径不支持）· Gemini ❌（QCode 暂不提供 Gemini 模型） |
| 协议与 Base URL | Anthropic：`https://api.qcode.cc/api` |
| 配置位置 | **Settings > Providers** → Claude 实例 → **Environment variables** |
| 官方文档 | [T3 Code Claude 说明](https://github.com/pingdotgg/t3code/blob/main/docs/user/providers-claude.md) · [FAQ](https://github.com/pingdotgg/t3code/blob/main/docs/user/faq.md) |

## 走哪个协议

T3 Code 自己不调用模型 API。官方 FAQ 的原话是："T3 Code uses those harnesses. It is not a harness, and it does not work without one."。Claude 这一侧的 harness 是 Claude Code，所以接 QCode 的方式与 Claude Code 本身一致：Anthropic Messages 的 base URL 加一把 QCode key。

官方 FAQ 对「能不能用 API key 或 OpenRouter 代替订阅」的回答是可以：在 Settings 里再添加一个 provider 实例，给它单独的 key 和端点，原有的订阅配置不受影响。

| 你要用 | 在 T3 Code 里用 | QCode 的 `ANTHROPIC_BASE_URL` |
|---|---|---|
| Claude（`claude-sonnet-5`、`claude-opus-5` 等） | 带独立 **Environment variables** 的 Claude 实例 | `https://api.qcode.cc/api` |
| Codex / GPT | Codex 实例，见下文「Codex 实例」 | 不适用 |

Claude 模型只能走 Anthropic 协议，所以 base URL 到 `/api` 为止，`/v1/messages` 由 Claude Code 自己补上；末尾不要加 `/`。完整的协议对照表见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

## 安装

T3 Code 要求运行 agent 的那台机器上至少装好一个 provider。本文用的是 Claude Code，请先按 [QCode 安装指南](/docs/getting-started/installation) 装好；下文「配置」里添加的 Claude 实例用你的 QCode key 完成认证。

然后安装 T3 Code，官方命令如下：

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

Windows 在 PowerShell 里：

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

运行 `t3` 启动服务并打开本地网页端。只想试一下可以用 `npx t3@latest`。桌面端可从 [GitHub Releases](https://github.com/pingdotgg/t3code/releases) 下载，或用包管理器：

| 平台 | 安装命令 |
|---|---|
| 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` |

Intel Mac 没有 `t3` 可执行文件，请用桌面端。其他平台和手机端见 [官方安装说明](https://github.com/pingdotgg/t3code/blob/main/docs/user/install.md)。

## 配置

官方给"讲 Anthropic 协议的路由"的做法，是单独建一个带独立配置目录的 Claude 实例。下面把它套到 QCode 上。

官方安装说明还写明：每个 provider 实例都可以有自己的环境变量，例如 API key 或自定义 base URL；标为 sensitive 的值保存后不再显示原文。

1. 打开 **Settings > Providers**，添加一个 Claude 实例。**Binary path** 保持 `claude`，**CLAUDE_CONFIG_DIR path** 填它专用的目录；官方 OpenRouter 示例用的是 `~/.claude_openrouter`，类似地可以用 `~/.claude_qcode` 这样的名字。
2. 在该实例的 **Environment variables** 里添加：

   | 变量 | 值 |
   |---|---|
   | `ANTHROPIC_BASE_URL` | `https://api.qcode.cc/api` |
   | `ANTHROPIC_AUTH_TOKEN` | 你的 QCode key（`cr_` 开头），勾选 Sensitive |
   | `ANTHROPIC_API_KEY` | 明确留空 |

   变量赋值写在 **Environment variables**，不要写进 **Launch arguments**。
3. 如果这个 Claude 配置目录里缓存过 Anthropic 登录，开始前先在使用同一目录的 Claude Code 会话里执行 `/logout`。官方提醒：缓存的登录凭据可能与路由的 token 冲突。
4. 在 T3 Code 里选模型。内置列表之外的模型，要在 **Settings > Providers** 里打开该 Claude 实例，用 **Add custom model** 添加完整的模型 ID，例如 [qcode.cc/models](https://qcode.cc/models) 上的 `claude-sonnet-5`，然后在聊天的模型选择器里选中它。

官方还说明了两点：`ANTHROPIC_DEFAULT_*_MODEL` 变量只是映射 `sonnet` 这类 Claude Code 别名，不会替代你在 T3 Code 里选定的明确模型 ID；自定义模型的 effort、thinking 或上下文控制项可能比内置模型少。

同一把 key 也可以用于 QCode 的其他接入域名（`us.qcode.cc`、`asia.qcode.cc`）：把 `ANTHROPIC_BASE_URL` 里的主机名换掉，路径仍是 `/api`。见 [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths)。

### Codex 实例

T3 Code 的 Codex 说明介绍了用 ChatGPT 登录和沿用已有 Codex CLI 登录两种方式。沿用本机 Codex 的实例从哪里读配置，T3 Code 源码里可以看到（v0.1.7 版本；2026-11-09 读取的主分支行号相同）：

- 使用本机已装 Codex 的实例，T3 Code 会启动 Codex 的 app server，并把 `CODEX_HOME` 设为你填的 **CODEX_HOME path**（`apps/server/src/provider/CodexProvider.ts`，476–482 行）。Codex 说明里的示例在这一栏填的是 `~/.codex`。
- 源码自带的 Codex app-server schema 把用户配置层描述为 `$CODEX_HOME/config.toml`（`packages/effect-codex-app-server/src/_generated/schema.gen.ts`，19730 行）。
- 在 T3 Code 里用 ChatGPT 连接则不同：T3 Code 为它设置自己的 `model_provider` 并移除 `OPENAI_BASE_URL`（`apps/server/src/provider/CodexManagedRuntime.ts`，24–26 行与 124 行），QCode 的设置在那里不生效。

也就是说，在 T3 Code v0.1.7 中，沿用本机 Codex 的实例会读它 Codex home 下的 `config.toml`。先按 [Codex 文档](/docs/ide/codex) 把 Codex 配好 QCode：`~/.codex/config.toml` 里写 `qcode` provider，key 以 `OPENAI_API_KEY` 写进 `~/.codex/auth.json`。然后在 **Settings > Providers** 里添加 Codex 实例，选 **Configure manually** 并走完向导；实例的 **CODEX_HOME path** 指向放这两个文件的目录（例如 `~/.codex`）。之后在会话的模型选择器里选中这个实例。

## 验证

1. 新建会话，选中该 Claude 实例和自定义模型，发一条 `ping` 之类的短消息。
2. 打开 [probe.qcode.cc](https://probe.qcode.cc)，输入你的 QCode key，确认请求出现并且模型是你选的那个。这相当于官方建议的"到路由商的活动面板里核对所用模型"。
3. 不经过 T3 Code，也可以直接测 key 和路径：

```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"}]}'
```

## 排错

| 现象 | 原因 | 处理 |
|---|---|---|
| provider 不出现 | 运行服务的那台机器上没装 CLI，或不在 `PATH` 里 | 在那台机器上安装 `claude`，或在 provider 设置里把 **Binary path** 指向它（官方 FAQ） |
| `Invalid API key` | key 错误或带了多余空格 | 确认以 `cr_` 开头，填在 `ANTHROPIC_AUTH_TOKEN`，`ANTHROPIC_API_KEY` 保持为空 |
| key 没错却鉴权失败 | 同一个 Claude 配置目录里有缓存的 Anthropic 登录 | 在使用该目录的 Claude Code 会话里执行 `/logout`，或给实例换一个新的配置目录 |
| 404 | base URL 末尾带了 `/`，或写进了 `/v1/messages` | 严格填 `https://api.qcode.cc/api` |
| 请求因模型被拒 | 在 Claude 实例里选了 GPT 模型 ID；Anthropic 端点不提供 GPT | 这里用 Claude 或国产模型 ID，GPT 走 Codex |
| 选择器里没有想要的模型 | 不在内置列表里 | 用 **Add custom model** 添加完整 ID |
| 402，带 `*_cost_limit_exceeded` | 这把 key 的额度用完了 | 见 [错误码](/docs/reference/errors#402-quota-exhausted) |

## 已知限制

- T3 Code 官方自述还很早期："We are very very early in this project. Expect bugs."
- 官方文档的路由接法是为 Claude 实例写的；GPT 模型走 Codex 实例，见上文「Codex 实例」。
- 远程连接时，T3 Code 使用的是所连服务器上的 Claude 配置，因此请在那台机器上设置实例。

## 相关文档

- [接入点与 API 格式](/docs/getting-started/endpoints-and-api-paths) —— 协议 × 模型族对照表
- [工具兼容性总览](/docs/ide/tool-compatibility) —— 各工具走哪种协议
- [Codex CLI](/docs/ide/codex) —— 面向 QCode 的 `config.toml`
- [DeepSeek Harness（dsh）](/docs/ide/deepseek-harness) —— 带自定义模型 API 表单的 agent harness