Theia IDE

在 ai-features.openAiCustom.customOpenAiModels 中添加一条配置 — model、url 和 apiKey — 即可让 Theia Coder、Architect 和内联补全使用 Kunavo。

{
  "ai-features.openAiCustom.customOpenAiModels": [
    {
      "model": "claude-sonnet-5",
      "url": "https://api.kunavo.com/v1",
      "id": "kunavo-sonnet-5",
      "apiKey": "sk-kn-...",
      "developerMessageSettings": "system"
    },
    {
      "model": "claude-haiku-4-5",
      "url": "https://api.kunavo.com/v1",
      "id": "kunavo-haiku-4-5",
      "apiKey": "sk-kn-...",
      "developerMessageSettings": "system"
    }
  ]
}

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 启用此功能：Theia 文档说明，前往 偏好设置 并启用 “AI-features => AI Enable”。完成之前，下方内容都不会显示。
3. 打开 AI Configuration 视图——Alt+A，或在左下角的 Manage（齿轮）菜单中点击 AI Configuration，该项位于 Settings 正下方。其类别包括 General、Providers & Models、Model Aliases、Agents、Prompts & Skills、Variables、Tools、Token Usage 和 MCP Servers。
4. 添加上方条目。文档说明，需要点击设置部分中 OpenAI 兼容模型旁的链接——该偏好设置是一个结构化列表，Theia 指出，没有专用编辑器的结构化设置“会交由 settings.json 处理”，你会进入该文件。每个模型 ID 对应一个对象；url 和 apiKey 需重复填写。
5. 将某项配置指向它。在 Agents 下，每个代理都有一个 Language Model 选择器；许多代理实际上使用模型别名，因此在 Model Aliases 下设置 default/code、default/universal、default/code-completion、default/summarize 和 default/fast，即可一次调整多个代理。
6. 向 Theia Coder 发送一条聊天消息，然后提出一个涉及文件的请求。这个 IDE 中的代理依赖工具调用和工作区内容，因此首次运行时让它读取或编辑某项内容，比只打个招呼更能说明情况；同一视图中的 Token Usage 还会显示这一轮消耗了多少令牌。

已于 2026年9月21日 对照 Theia IDE 的 AI 功能页面中“OpenAI Compatible Models”一节 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

一个请求即可确定故障来自端点、密钥还是配置文件。如果返回 JSON，则相同的基础 URL 和密钥可以在 Theia IDE 中使用。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/models \
  -H "Authorization: Bearer sk-kn-..."

字段中应填写哪个模型 ID

每个文本模型都可通过模型 ID 访问——实时列表见 GET /v1/models，包含价格的目录见模型页面。费率单位为每 1M token 的美元，格式为输入 / 输出。

Theia 对此提供商的说明

Theia 自己页面上的 LLM 提供商概览表会从三个维度评估各提供商。这是 Theia 对 Theia 的说法，依据上方日期从该表复制而来——这不是 Kunavo 的测试结果；本页写出的只是标题为“模型 ID 的要求”的那一列内容。

Theia 在该表上方两段处还补充了一条说明，值得在此重申，因为它为本页内容提供了诚实的背景：“并非所有模型都能开箱即用，因为它们可能需要特定的自定义或优化”。

实际费用来自哪里

Theia IDE 是开源软件，可免费下载；其 AI 功能本身不收费。产生费用的是模型调用，由持有 apiKey 中密钥的一方计费。两个设置对账单的影响超过模型选择，而且文档中都提到了它们：

1. 自动代码补全默认开启，文档称其会“在编码过程中持续向底层 LLM 发送请求”。这是一天会运行数千次的代理。将 default/code-completion 固定为低价模型 ID，或在 'AIFeatures'=>'CodeCompletion' 中将代理切换为手动模式，并通过 Ctrl+Alt+Space 触发。
2. 同一设置组中的 Max Context Lines 会限制每次补全请求所包含的周边文件内容。每次由按键触发的调用中，其中每一行都会按输入计费。

聊天代理则恰好相反：调用次数较少，上下文大得多，而且每一轮都会再次发送相同的工作区文件。这正是提示缓存的适用场景——参见 /docs/caching；也因此，上方模型表格的两部分是按代理的触发频率划分，而不是按它有多聪明划分。

连接失败时

1. 404——检查 url。Kunavo 提供的是 /v1/chat/completions，因此该字段应填写 /v1 根路径；只填源站地址或填写完整的 .../chat/completions 都不正确。
2. 401 — 密钥问题。Theia 的 Readme 说明，apiKey“将作为 Bearer Token 在授权请求中发送”，这正是 sk-kn- 密钥所需的格式。请注意文档记载的默认行为：如果完全没有 apiKey，Theia 会发送 no-key，因此字段缺失看起来会像是密钥被拒绝，而不是密钥缺失。（true 表示“使用全局 OpenAI API 密钥”——此处不适用。）
3. 模型 ID 未出现在选择器中——该列表来自你自己的 customOpenAiModels 条目，而不是端点，因此缺少某个 ID 就表示缺少相应对象。id 字段会显示在界面中；如果省略该字段，就会改用模型名称。
4. 第一条系统消息被拒绝或忽略——这是由 developerMessageSettings 导致的。其默认值为 developer，这是 OpenAI 风格的角色；Theia 为非 OpenAI 厂商提供的示例设置了 system，因此上方配置块也采用了该值。user、mergeWithFollowingUserMessage 和 skip 是文档列出的其他选项。
5. 所有地方都完全没有响应——检查 Workspace Trust。Theia 将所有 AI 功能置于该功能的控制之下；工作区未受信任时，聊天输入和行内补全都会被禁用，并显示 AI Features are Restricted 消息。