# AI 工具接入总览

用一个 Felo API key，把终端编码工具、编辑器和 Agent 平台接入 Felo 模型。先选择客户端，再按对应指南设置 API key、协议地址和模型。

把你熟悉的编码工具、编辑器或 Agent 平台连接到 Felo API Platform，就能在原有工作流中调用 Felo 提供的模型。客户端负责对话、读取文件和执行工具，Felo 提供模型 API 接入；你需要配置的是 API key、Base URL 和模型 ID。

## 接入前准备

1. 在 [API Keys 页面](https://openapi.felo.ai/console/api-keys)创建并保存完整的 Felo API key。
2. 确认账户有可用服务额度；计费方式见[计费与额度](https://openapi.felo.ai/zh-CN/docs/faq/billing-and-credits.md)。
3. 安装并启动要使用的客户端，确认它支持自定义模型 provider 或兼容 API 地址。
4. 从[模型目录](https://openapi.felo.ai/zh-CN/models)选择模型。编码 Agent 需要模型支持工具调用，模型 ID 请按目录完整填写。

API key 是访问凭证；Base URL 决定请求发送到哪里；模型 ID 决定调用哪个模型。Felo key 应填写在自定义 API provider 中，不要作为客户端的官方订阅凭证使用。

## 选择接入范围

- **使用 Felo 模型**：配置客户端的模型 provider，模型调用消耗平台余额。Claude Code、Codex 等客户端的 CLI 自动配置方式以对应指南为准。
- **安装 Felo Skill**：让现有模型调用 Felo 的工具能力。OpenCode 的 `feloapi setup --agent opencode --skills-only --yes` 只安装 Skill；模型连接需按 OpenCode 指南单独设置。

CLI 安装、验证与恢复配置见 [FeloAPI CLI 指南](https://openapi.felo.ai/zh-CN/docs/cli.md)。

## 选择你的工具

| 使用场景 | 客户端设置指南 |
|----------|----------------|
| 终端编码、代码审查与仓库修改 | [Codex](https://openapi.felo.ai/zh-CN/docs/agent-clients/codex.md)、[Claude Code](https://openapi.felo.ai/zh-CN/docs/agent-clients/claude-code.md)、[OpenCode](https://openapi.felo.ai/zh-CN/docs/agent-clients/opencode.md) |
| 本地助手与 Agent 工作流 | [OpenClaw](https://openapi.felo.ai/zh-CN/docs/agent-clients/openclaw.md)、[Hermes Agent](https://openapi.felo.ai/zh-CN/docs/agent-clients/hermes-agent.md) |
| 编辑器内的模型接入 | [Cursor](https://openapi.felo.ai/zh-CN/docs/agent-clients/cursor.md)、[TRAE](https://openapi.felo.ai/zh-CN/docs/agent-clients/trae.md) |
| 编辑器中的编码扩展 | [Cline](https://openapi.felo.ai/zh-CN/docs/agent-clients/cline.md)、[Roo Code](https://openapi.felo.ai/zh-CN/docs/agent-clients/roo-code.md)、[Kilo Code](https://openapi.felo.ai/zh-CN/docs/agent-clients/kilo-code.md) |
| 通过本地网关管理多个 Agent 的模型连接 | [Magpie](https://openapi.felo.ai/zh-CN/docs/agent-clients/magpie.md) |
| 其他支持自定义 API 地址的客户端 | [通用接入指南](https://openapi.felo.ai/zh-CN/docs/agent-clients/other-tools.md) |

每篇客户端指南会说明配置文件、环境变量、模型选择和验证步骤。客户端版本或账户方案可能影响自定义 provider 的可用性，请以对应指南和客户端当前设置为准。

## 选择正确的协议地址

| 客户端使用的协议 | Base URL | 常见客户端 |
|------------------|----------|------------|
| OpenAI-compatible Chat Completions | `https://openapi.felo.ai/api/v1` | OpenCode，以及选择该模式的编辑器或扩展 |
| OpenAI-compatible Responses | `https://openapi.felo.ai/api/v1` | Codex |
| Anthropic-compatible Messages | `https://openapi.felo.ai/api` | Claude Code，以及明确选择 Messages 模式的客户端 |

填写 Base URL 时不要自行追加 `/chat/completions`、`/responses` 或 `/messages`；客户端适配器会构造请求路径。协议由客户端的 provider 配置决定，不能只根据模型名称判断。

## 通用接入流程

1. 打开上方对应客户端的指南，选择自定义 provider 或兼容 API 模式。
2. 填入 Felo key、对应协议的 Base URL 和模型 ID。优先用环境变量保存 key，再按客户端要求引用变量。
3. 在当前会话中选择 Felo provider 和配置好的模型；仅保存配置不一定会切换当前模型。
4. 发送一条简短消息，确认模型能返回回答。
5. 对编码 Agent，再运行一个简单的只读任务，例如「列出项目的主要目录」，验证工具调用。

环境变量的名称和加载方式因客户端而异。请按对应指南设置，不要假设所有工具都会自动读取 `FELO_API_KEY` 或 `OPENAI_BASE_URL`。

::: warning 保护 API key
不要将真实 key 提交到代码仓库，或放入浏览器前端、公开日志和截图中。环境变量持久化后，重新启动终端或客户端，让新进程读取配置。
:::

## 遇到连接问题

- 认证失败：检查 key 是否完整、有效，及客户端进程是否读取到了环境变量。
- 请求发往其他服务：检查当前模型的 provider，以及项目级配置是否覆盖了用户级配置。
- 接口路径或协议报错：核对 provider 的协议和上表中的 Base URL。
- 找不到模型或工具调用失败：核对模型 ID、当前可用性和工具调用支持。

更多处理方法见[故障排查](https://openapi.felo.ai/zh-CN/docs/faq/troubleshooting.md)和[协议与 SDK](https://openapi.felo.ai/zh-CN/docs/guides/protocols.md)。

## 接入模型之后

模型接入完成后，如果还需要联网搜索、网页提取、X 数据或 PPT，可以继续查看 [Felo OpenAPI 接入指南](https://openapi.felo.ai/zh-CN/docs/data-api/guides/felo-overview)。这些能力需要单独配置，不会因更换模型 provider 自动启用；不同 API 的扣费方式以对应文档为准。
