n8n

OpenAI 凭据的 Base URL 字段填写 https://api.kunavo.com/v1，并保留 /v1，即可让 n8n 工作流中的所有 OpenAI Chat Model 使用 Kunavo；模型节点本身没有端点字段。

Credentials  →  Create credential  →  OpenAI
  API Key                      sk-kn-...
  Organization ID (optional)   leave empty
  Base URL                     https://api.kunavo.com/v1     <- keep the /v1

Workflow  →  AI Agent or Basic LLM Chain  →  Chat Model: OpenAI Chat Model
  Credential to connect with   the OpenAI credential above
  Model                        ID mode:  claude-sonnet-5
  Use Responses API            on   → POST /v1/responses
                               off  → POST /v1/chat/completions

分步操作

1. 在 /app/keys 创建密钥并复制——它只会显示一次。
2. 在 n8n 中创建一个类型为 OpenAI 的凭据。在 API Key 中填写密钥，将 Organization ID（可选） 留空，并将 Base URL 的默认值 https://api.openai.com/v1 替换为 https://api.kunavo.com/v1。保存。
3. 添加一个 AI Agent 或 Basic LLM Chain 节点，并附加一个使用该凭据的 OpenAI Chat Model 子节点。将 Model 字段从 From List 切换为 ID，然后按 GET /v1/models 中显示的格式输入模型 ID，例如 claude-sonnet-5。列表也可以使用，但手动输入 ID 能让工作流更易读。
4. 决定是否启用 Use Responses API：除非链中的工具需要 Chat Completions，或你希望 n8n 执行日志显示 chat completions 请求，否则请保持启用。
5. 先用一行提示运行一次工作流，再将它连接到触发器。401 表示密钥有误；带有代码 missing_v1_prefix 的 404（或在较早的运行中，以 <!DOCTYPE html> 开头的消息）表示 Base URL 中遗漏了 /v1。

已于 2026年10月1日 对照 n8n 在 n8n@2.41.4 标签下的 OpenAI 凭据源代码 检查。第三方设置会发生变化；如果这里的字段名称不再与你看到的内容一致，应以该页面为准，而不是本页。

调试客户端前先验证

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

# 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 的美元，格式为输入 / 输出。

为什么 Base URL 位于凭据中

较早的教程会在模型节点内设置端点。在已发布的源代码中，从节点版本 1.1 起，节点内的 Base URL 选项已隐藏，因此你今天添加的节点没有此字段，实际生效的是凭据中的 Base URL。n8n 自己的 OpenAI Chat Model 文档及其凭据页面都没有介绍该字段；源代码中有说明：“覆盖 API 的默认 base URL”。HTTP Request 节点则是完全不同的方式——它可以使用，但你需要手动构建 AI Agent 节点会替你构建的请求。

启用或关闭 Responses API

• 启用（节点 1.3 中的默认设置）——请求发送到 /v1/responses。只有此模式会显示节点的 内置工具：Web Search、File Search 和 Code Interpreter。这些工具由 OpenAI 托管；尚无人测试它们能否通过 Kunavo 使用，因此请先进行测试，再构建依赖这些工具的工作流。
• 关闭——请求发送到 /v1/chat/completions。这是支持最广泛的格式；如果工具调用在另一种设置下表现异常，可切换到此设置。
• 你附加到 AI Agent 的工具会以函数定义的形式发送给模型。这次检查未涵盖这一往返过程，因此在依赖它之前，请先在测试工作流中运行一次工具调用。

n8n 与 OpenRouter

n8n 提供单独的 OpenRouter Chat Model 节点，并配有独立的 OpenRouter 凭据。该凭据有一个 API Key 字段，以及一个隐藏且固定为 https://openrouter.ai/api/v1 的 Base URL；其测试会调用 OpenRouter 自己的 /key 路由，因此 OpenRouter 节点只能连接 OpenRouter。如果你想使用 OpenRouter，请使用该节点并填写 OpenRouter 密钥；无需使用本页中的任何内容。

包括 Kunavo 在内的其他任何兼容 OpenAI 的端点，都如上所述通过 OpenAI Chat Model 和 OpenAI 凭据的 Base URL 连接。应根据实际差异来选择——需要哪些模型、希望如何付费、是否希望 n8n 与其他工具共用一个余额——而不是根据节点来选择。关于 Kunavo 的对比，请参阅 Kunavo 与 OpenRouter。

控制无人值守工作流的账单上限

• 节点的 Max Retries 默认为 2，Timeout 默认为 60000 ms。请求超时后会重试，而每次重试都会产生一笔新的计费请求。
• 对于逐项运行的节点，请设置 Maximum Number of Tokens——遍历 1,000 行的循环会将单次调用的费用放大相应倍数。
• 为每个生产工作流单独使用一个 Kunavo 密钥，这样使用情况页面就能显示各密钥的支出；需要撤销其中一个密钥时，也不会影响其他密钥。

错误信息的样子

• “401 缺少或无效的 API 密钥” — Base URL 正确，但密钥不正确。在 2.41.4 上复现。
• “404 <!DOCTYPE html>…”，LangChain 将其归类为 MODEL_NOT_FOUND——这具有误导性：模型没有问题，Base URL 缺少 /v1，请求落到了网站上。在 2.41.4 上复现。
• JSON 中显示模型不可用的信息——模型 ID 与 GET /v1/models 不完全一致。