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

# 常见问题

> 使用 Teio API 时的常见问题

配置 AI 编程工具连接 Teio API 时常见的问题和解决办法。

## 认证与连接

<AccordionGroup>
  <Accordion title="报错 401 / API key 无效">
    * 检查密钥有没有多余空格或换行
    * 确认密钥分组正确：Claude 系工具用 **Claude 分组**密钥，OpenAI 兼容工具用 **OpenAI 分组**密钥
    * 确认密钥没有过期或被禁用
  </Accordion>

  <Accordion title="工具启动后卡住，没有响应">
    1. 先去 Teio 控制台「操练场」手动测试一下
    2. 操练场也没反应 → 分组、模型或密钥有问题
    3. 操练场正常 → 检查 Base URL 是否填对（Claude 系用 `https://teio.me`，OpenAI 兼容用 `https://teio.me/v1`）
  </Accordion>

  <Accordion title="提示模型不存在 / model not found">
    * 去控制台「操练场」确认该模型在你的分组下可用
    * Claude 分组和 OpenAI 分组支持的模型不同，别搞混
  </Accordion>
</AccordionGroup>

## 环境变量

<AccordionGroup>
  <Accordion title="设了环境变量但不生效">
    * **macOS**：执行 `source ~/.zshrc` 或重启终端
    * **Windows**：必须完全关闭再重开终端或 VS Code，光重新加载窗口没用
    * 验证是否生效：
      * macOS: `echo $ANTHROPIC_BASE_URL`
      * Windows CMD: `echo %ANTHROPIC_BASE_URL%`
      * PowerShell: `$env:ANTHROPIC_BASE_URL`
  </Accordion>

  <Accordion title="macOS 从 Dock 启动 VS Code 后环境变量不生效">
    从 Dock / Spotlight 启动的应用不会读取 shell 配置文件。解决办法：

    * 从终端用 `code` 命令启动 VS Code
    * 或在 VS Code 的 `settings.json` 里直接配置环境变量
  </Accordion>
</AccordionGroup>

## 调用问题

<AccordionGroup>
  <Accordion title="模型思考太久迟迟没输出怎么办？">
    如果模型思考时间过长，但实际要输出的内容并不多，可以直接中断当前对话，然后重新输入让它继续。

    上下文不会丢失，对最终结果也没有影响，相当于催它一下，跳过卡住的思考过程直接出结果。
  </Accordion>

  <Accordion title="为什么一个任务消耗了很多次 API 调用？">
    这是正常的。AI 编程工具（如 Claude Code、Cursor、Cline 等）本质上是 Agent，不是普通聊天机器人。1 个任务 ≠ 1 次调用。

    Agent 会自主循环执行多个步骤（读文件、搜索、写代码、跑测试、修 bug...），每个步骤都是一次独立调用。一个简单任务可能 3-5 次，复杂任务可能几十次。

    影响消耗的主要因素：

    * 任务复杂度 — 改一行和开发一个功能差别很大
    * 调试循环 — 一次写对消耗少，反复调试成倍增加
    * 指令清晰度 — 模糊指令会让 Agent 走弯路
    * 对话长度 — 越长每次调用携带的上下文越多

    省次数的技巧：

    * 给清晰具体的指令
    * 复杂任务拆成小任务
    * 及时压缩或清理对话上下文

    *注：调用次数由 AI 编程工具客户端自主决定，Teio 仅提供接口转发，无法干预 Agent 的调用行为。次数消耗属于正常使用，不作为退款依据。*
  </Accordion>

  <Accordion title="如何节省 Token 消耗？">
    Token 消耗主要来自上下文长度和模型思考过程，下面这些技巧能明显降低开销：

    * **新任务就新开对话** — 上下文和当前任务无关时，别在旧对话里继续，每次调用都会重复携带历史消息，越积越多
    * **简单任务关掉思考模式** — 改个变量名、写个简单函数这种不需要推理的，关掉 Thinking / 推理模式直接出结果，省掉思考部分的 Token
    * **模型按难度选** — 简单任务用 Haiku / 小模型，复杂任务才上 Opus / 大模型，别一上来就拉满
    * **及时压缩上下文** — Claude Code 用 `/compact`，Cursor 等工具有清理历史功能，对话超过几十轮就该清一次
    * **指令一次说清** — 模糊指令会让 Agent 反复试错，每次试错都是一次完整调用
    * **大文件别整个塞进去** — 只贴相关片段，或用工具的文件引用功能让模型按需读取
  </Accordion>
</AccordionGroup>