n8n 接入自定义 API 教程：OpenAI 节点、Key 与工作流（2026）

n8n 是一个可视化的自动化平台，把触发器、处理节点和输出节点连成工作流。它本身不提供模型，模型来自你配置的 API 服务。对国内团队来说，常见做法是准备一个 OpenAI 兼容网关，然后在 n8n 里配置自定义 Base URL，把对话、摘要、分类等步骤接进业务流程。

本文按实际搭建顺序展开：安装、准备参数、配置凭证、跑通工作流、处理错误，最后讲团队部署。界面名称会随版本变化，以你当前使用的版本为准。

说明：n8n 是 n8n GmbH 的商标，OpenAI 是 OpenAI, Inc. 的商标。本文仅作技术接入说明，与相关公司无隶属或合作关系。模型范围与价格以站内模型价格页为准。

一、云端还是自托管

n8n 提供云端托管和自托管两种方式。云端省去服务器维护，适合快速验证；自托管能控制数据路径、网络出口和升级节奏，适合有合规要求或需要内网访问的团队。本文以自托管为主，因为自定义 Base URL、环境变量和团队权限这些内容，在自托管场景下更常遇到。

自托管也有成本：服务器、数据库、备份、HTTPS、升级和安全配置都要自己负责。先明确谁来运维，再决定是否自托管。

二、安装与初始化

官方推荐的生产方式是 Docker Compose；单机试用可以用一条 docker run 启动。镜像名是 n8nio/n8n，默认端口 5678，数据卷挂到 /home/node/.n8n。这个目录不仅放 SQLite 数据库，也放加密密钥等文件，必须持久化。

docker volume create n8n_data

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="Asia/Shanghai" \
  -e TZ="Asia/Shanghai" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

启动后访问 http://localhost:5678，按提示创建所有者账号。生产环境不要长期用 SQLite 单机跑：配置 DB_TYPE=postgresdb 和 DB_POSTGRESDB_* 连接 PostgreSQL，并把数据库纳入备份。npm 方式（npx n8n 或全局安装）适合本地测试；官方文档已说明 npm 安装从 n8n 3.0 起废弃，生产应使用 Docker。Node.js 版本要求以官方安装文档为准，当前文档给出的范围是 20.19 到 24.x。

三、准备 Key、Base URL 和模型 ID

接入任何 OpenAI 兼容服务，只需要三样参数：

参数	填法	常见错误
API Key	网关控制台创建，按项目命名	复制时带空格或换行
Base URL	`https://ai.zhongshangqihang.com/v1`	填成完整 `/chat/completions` 路径
模型 ID	价格页的 API 标识	用了展示名或旧版本后缀

Key 在注册中商起航 AI 网关后创建。建议一个环境一把 Key，测试和正式分开，泄露时可以单独吊销。模型 ID 从模型价格页复制，注意大小写和版本后缀。具体可用模型和计费方式会调整，以控制台和价格页为准。

四、配置 OpenAI 凭证

在 n8n 左侧进入 Credentials，新建 OpenAI 类型凭证。当前版本的字段包括 API Key、Organization ID（可选）和 Base URL。使用网关时，把 Base URL 改成网关地址，通常填到 /v1 为止，不要带 /chat/completions。Organization ID 只在连接 OpenAI 官方且账号属于多个组织时需要，走兼容网关一般留空。

几条实践：

Key 只放凭证，不写进 Code 节点、Set 节点或工作流 JSON。
凭证名称写清用途，例如“网关-生产-内容摘要”，不要用“测试1”。
保存后点测试；测试失败先查 Base URL 和网络出口。
团队实例按项目建凭证，不要多人共用一把 Key。
自托管时保管好 N8N_ENCRYPTION_KEY，更换后已有凭证可能无法解密。

五、跑通第一条工作流

以“表单提交后生成回复草稿”为例：

新建工作流，添加 Form Trigger 或 Manual Trigger。
添加 OpenAI 节点，Resource 选 Text。
Operation 选 Generate a Chat Completion；旧版本里对应的名称是 Message a Model。
选择刚建的凭证和模型，把表单字段用表达式传入，例如 {{ $json.message }}。
在提示词里限定角色、输出格式和长度，减少无关内容。
添加 Set 节点，只保留后续要用的字段。
添加 Gmail、Slack 或表格节点，把结果写到目标位置。
先手动执行，逐节点检查输入输出，确认后再启用。

如果网关不支持 Responses API，不要选 Generate a Model Response，改用 Chat Completions 对应的操作。节点支持哪些参数，以你当前 n8n 版本和网关文档为准。

六、用 HTTP Request 节点调用兼容接口

节点没有暴露的参数、批量请求或特殊字段，可以改用 HTTP Request 节点直接请求 /v1/chat/completions。Method 选 POST，URL 填完整接口地址，Authentication 选 Predefined Credential Type 并选中 OpenAI 凭证，或者选 Generic Credential Type 里的 Bearer Auth。Body 选 JSON，填入模型、消息和参数。

请求体不要包含 Key；鉴权由凭证注入。返回结构按 OpenAI Chat Completions 格式解析，通常取 choices[0].message.content。如果返回的是流式数据，n8n 侧要先关闭流式或改用能处理 SSE 的方式，否则容易解析失败。

七、测试与错误处理

先在 n8n 外用 curl 验证地址、Key 和模型，再回工作流排查，能少走很多弯路。无人值守的工作流要把失败当成常态：

在节点设置里开启 Retry On Fail，对 429、5xx 和超时重试 2 到 3 次。
设置重试间隔，避免限流时继续加压。
按业务选择 On Error：停止、继续，或把错误输出接到异常分支。
给 HTTP 请求设置超时，长文本生成可以放宽，但不能无限等待。
配置错误工作流，把执行 ID、节点名和输入摘要发到 Slack 或邮件。
重试前检查幂等，避免重复发消息或重复写表。

现象	常见原因	处理
401	Key 错误、过期或凭证未选中	重新选凭证，检查空格和状态
403	模型未开通或权限不足	核对模型权限和项目限额
404	Base URL 或接口路径不对	只填到 `/v1`，不要带完整路径
429	并发过高或超出配额	降低并发，开启退避重试
400	参数不被网关支持	去掉不兼容字段，核对模型 ID
超时	网络出口或上游响应慢	检查代理、DNS 和超时设置

八、团队部署要点

团队使用 n8n，重点不是多建几个账号，而是把凭据、项目和运维边界划清：

用 Projects 隔离业务线，工作流和凭证按项目归属。
按人按项目发 Key，离职或泄露时能单独吊销。
生产实例统一走 HTTPS，配置 N8N_WEBHOOK_URL 指向外部可访问地址；旧版本变量名是 WEBHOOK_URL。
队列模式下所有 worker 使用同一个 N8N_ENCRYPTION_KEY，否则凭证无法解密。
生产环境使用外部 task runner，不要把 Code 节点放在主进程里跑。
备份数据库和加密密钥，两者分开存放并控制访问。
设置执行数据保留时间，避免历史记录无限增长，也减少敏感数据暴露面。

自托管不等于自动合规。上游模型是否保留请求、是否用于训练，仍要单独确认；涉及客户隐私的流程，增加脱敏和人工复核节点。

常见问题

n8n 的 OpenAI 节点支持自定义 Base URL 吗？

支持。当前 OpenAI 凭证里有 Base URL 字段，默认是 https://api.openai.com/v1，改成网关地址即可。若你的版本没有该字段，用 HTTP Request 节点加 Bearer Auth 也能调用。

Base URL 要填到哪一级？

一般填到 /v1，例如 https://ai.zhongshangqihang.com/v1。不要填 /v1/chat/completions，节点会自己拼接路径。填错层级最常见的表现是 404。

为什么凭证测试通过，执行时却说模型不存在？

凭证测试通常只验证 Key 和地址，不代表每个模型都对你开放。检查模型 ID 是否与价格页一致、项目是否有该模型权限，以及请求是否被路由到了别的 Base URL。

自托管 n8n 一定要用 PostgreSQL 吗？

不是必须，SQLite 可以用于测试和小流量。生产环境通常改用 PostgreSQL，便于备份、并发和扩容；具体以官方 Docker Compose 文档为准。无论用哪种数据库，/home/node/.n8n 目录都要持久化。

团队多人使用要注意什么？

按项目和人员拆分凭证，不共用长期 Key；用项目角色控制工作流和凭证访问；生产环境启用 HTTPS、MFA 和外部 task runner；备份加密密钥并限制访问。需要统一模型入口和用量管理，可以用网关的虚拟 Key 和额度功能。

下一步

n8n 接入自定义 API 的难点不在拖节点，而在三处对齐：Base URL、Key 和模型 ID。先用 curl 跑通，再配 OpenAI 凭证，最后补上重试、错误分支和团队权限。需要统一入口，可以注册中商起航 AI 网关，模型与价格以模型价格页为准。