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

# AI Coding 工具

> Cursor、Cline、Codex 等工具的接入说明

AI Coding 工具只建议接 Tapapi 的文本模型。这里的判断标准很简单：工具必须明确支持自定义 OpenAI-compatible Base URL、API Key 和 Model ID，才适合直接接入。

<Warning>不要把 Tapapi Key 写进项目仓库、`.env.example`、截图或团队共享文档。AI Coding 工具通常能读写本地文件，API Key 应放在工具自己的本机配置或系统密钥管理里。</Warning>

这类工具的版本变化很快。公开文档只写已经能按 OpenAI-compatible 文本接口验证的路径；图片、视频、浏览器自动化、终端执行、MCP、工具调用等能力，不要因为模型能聊天就默认可用。

## 支持边界

| 工具          | 当前建议      | 说明                                                          |
| ----------- | --------- | ----------------------------------------------------------- |
| Cline       | 可优先配置     | 官方有 OpenAI Compatible Provider，填写 Base URL、API Key、Model ID |
| Cursor      | 谨慎使用      | 只有在你的版本明确支持自定义 OpenAI-compatible Base URL 时才配置              |
| Codex       | 不作为公开默认教程 | Codex 配置和认证边界更复杂，建议先走官方 OpenAI 路径；高级用户再单独验证                 |
| Claude Code | 暂不写成支持    | 需要 Anthropic-compatible 路径确认后再补                             |

## 能力边界

| 能力                      | 当前建议                               |
| ----------------------- | ---------------------------------- |
| 文本对话                    | 可按 `POST /v1/chat/completions` 验证  |
| 流式输出                    | 工具支持 SSE 时可验证；异常时先关闭流式             |
| Responses API           | 仅当工具明确支持 Responses 时再评估            |
| 工具调用 / function calling | 按模型和工具逐项测试，不写成通用承诺                 |
| 图片 / 视频                 | 不建议通过 AI Coding 工具接 Tapapi 多模态 API |
| 终端 / 文件修改               | 属于工具自身权限，Tapapi 只提供模型响应            |

## Cline 配置

在 Cline 设置里选择 OpenAI Compatible Provider：

| 字段               | 值                       |
| ---------------- | ----------------------- |
| API Provider     | `OpenAI Compatible`     |
| Base URL         | `https://tapapi.ai/v1`  |
| API Key          | Tapapi 控制台创建的 `sk-` Key |
| Model ID         | 控制台可用的文本模型，例如 `gpt-5.4` |
| Context / Output | 先用默认值，跑通后再按模型能力调整       |

如果 Cline 版本要求完整接口路径，不要填 `https://tapapi.ai/v1/chat/completions` 作为 Base URL。优先填 `https://tapapi.ai/v1`，让工具自己拼接 `/chat/completions`。

验收方式：

1. 用一个很小的代码解释或文本问题测试。
2. 确认 Cline 能正常返回。
3. 到 Tapapi 控制台检查调用记录。
4. 再测试真实代码任务和流式输出。
5. 记录失败时的 HTTP 状态码、错误 message、模型名和时间。

## Cursor 怎么判断能不能接

Cursor 版本变化较快。只有当你的 Cursor 设置里能明确配置以下三项时，才按 Tapapi OpenAI-compatible 方式接入：

| 必须有                                 | 推荐值                    |
| ----------------------------------- | ---------------------- |
| Custom / OpenAI-compatible Base URL | `https://tapapi.ai/v1` |
| API Key                             | Tapapi `sk-` Key       |
| Model ID                            | 控制台可用文本模型              |

如果你的 Cursor 只能填写 OpenAI 官方 API Key，不能填写自定义 Base URL，就不要把 Tapapi 当作 Cursor 供应商来配置。

Cursor 接入前先用低成本模型和小任务验证，不要直接跑大型代码库重构。团队场景建议给 Cursor 单独创建 Tapapi Key，设置额度、模型范围和过期时间。

## Codex 说明

Codex 可以在用户级配置里定义模型供应商，但这不是 Tapapi 公开文档的默认接入路径，原因是：

* Codex 的供应商、认证和协议模式会随版本变化；
* 项目级 `.codex/config.toml` 不适合保存供应商密钥；
* 当前文档还没有对 Tapapi + Codex 的工具调用、流式、错误恢复做完整验收。

因此公开文档先不提供一键复制的 Codex 配置。需要内部验证时，应在本机用户级配置里单独测试，并记录模型、协议、错误码和回滚方式。

## Claude Code 说明

Claude Code 默认面向 Anthropic / Claude 协议。Tapapi 文本主线是 OpenAI-compatible 的 `/v1/chat/completions`；只有当工具和模型的 Anthropic-compatible 路径、认证方式、工具调用和流式行为都验证完成后，才适合补公开教程。

当前不要把 Claude Code 写成 Tapapi 的默认支持工具。

## 安全和成本

| 项      | 建议                          |
| ------ | --------------------------- |
| Key 存放 | 放工具本机配置或系统密钥管理，不进仓库         |
| Key 隔离 | 每个工具单独 Key，便于限额和停用          |
| 模型范围   | 只开放已验证文本模型，不默认开放图片和视频       |
| 额度     | 设置低额度或临时额度，先小任务验证           |
| 日志     | 记录工具名、模型、时间、HTTP 状态、错误信息和用量 |
| 团队共享   | 不共享个人 Key；离职或换机器后及时停用       |

## 排障

Tapapi OpenAI-compatible 接口失败时通常返回：

```json theme={null}
{
  "error": {
    "message": "...",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}
```

如果工具能显示响应头，排障时保存 `X-Oneapi-Request-Id`。如果工具看不到响应头，至少保存工具名、模型名、Base URL、HTTP 状态码、错误 message 和发生时间。

## 常见问题

| 现象                | 优先检查                                               |
| ----------------- | -------------------------------------------------- |
| `Invalid API Key` | 是否填的是 Tapapi Key，是否有多余空格                           |
| `Model Not Found` | Model ID 是否与 Tapapi 控制台一致                          |
| 连接失败              | Base URL 是否写成 `https://tapapi.ai/v1`，是否多写 endpoint |
| 工具调用异常            | 先确认该模型是否支持 tool/function calling                   |
| 输出很慢              | 先换轻量模型验证，再调整上下文和输出长度                               |
| 流式卡住              | 先关闭 streaming 跑通，再检查工具版本和网络代理                      |
| 用量异常              | 检查是否多个工具共用同一个 Key 或后台任务重复触发                        |

## 下一步

| 场景                   | 文档                                        |
| -------------------- | ----------------------------------------- |
| 文本模型接入               | [文本 API](/text-generation/overview)       |
| OpenAI-compatible 迁移 | [OpenAI SDK 迁移](/integrations/openai-sdk) |
| HTTP 底层规则            | [HTTP REST](/integrations/http-rest)      |
| 错误与重试                | [错误码与重试](/errors)                         |
| 成本控制                 | [成本控制](/production/cost-control)          |

## 官方参考

* [Cline: OpenAI Compatible](https://docs.cline.bot/provider-config/openai-compatible.md)
* [OpenAI Codex manual](https://developers.openai.com/codex/codex-manual.md)