ToolJet 本地部署接入外部 AI 接口的配置步骤

ToolJet 本地部署后，接入外部 AI 接口的关键不是界面操作本身，而是先让 ToolJet 容器能够访问目标 AI 服务，并把密钥放到 ToolJet 能读取的配置里。本页基于 Docker Compose 给出启动、环境变量、数据源配置和验证步骤，覆盖从容器启动到请求返回的完整链路。

本地部署 ToolJet 接入外部 AI 接口，应先确认容器可出网访问 AI 服务地址，再通过 .env 或界面保存认证信息。验证顺序建议为：容器内 curl → 界面测试连接 → 查看日志。不同 ToolJet 版本对“数据源”菜单的命名可能不同，但 REST API 连接配置思路一致。

准备 ToolJet 运行环境

在开始配置前，先确认本机已安装 Docker 与 docker-compose，并确认 Docker 服务正常运行。ToolJet 官方镜像通常采用多容器方式启动，需要依赖 PostgreSQL 和 Redis。下面是一个最小可用的 docker-compose.yml 示例，只保留 ToolJet 服务本身以及其依赖的简要声明：

version: '3.8'
services:
  tooljet:
    image: tooljet/tooljet:latest
    ports:
      - "3000:3000"
    environment:
      - TOOLJET_HOST=http://localhost:3000
      - LOCKBOX_MASTER_KEY=change_me
      - SECRET_KEY_BASE=change_me
      - DATABASE_URL=postgres://tooljet:tooljet@postgres:5432/tooljet
      - REDIS_URL=redis://redis:6379
    depends_on:
      - postgres
      - redis
    restart: unless-stopped

注意：实际部署时，需要根据 ToolJet 版本和环境变量要求补充数据库迁移、初始化等步骤。锁钥（LOCKBOX_MASTER_KEY）和 SECRET_KEY_BASE 必须自行生成并固定。端口映射可根据实际调整，容器内 3000 是默认 web 端口。

修改 ToolJet 环境变量以指向外部 AI 接口

ToolJet 本身不直接提供“AI 接口”专用配置，但可以通过环境变量定义请求地址和密钥，然后在数据源中引用。建议在 .env 文件中统一命名 AI 服务相关字段，例如：

AI_API_URL=https://api.example.com/v1/chat/completions
AI_API_KEY=sk-xxxxx
AI_API_HEADER_PREFIX=Bearer

启动 ToolJet 时，docker-compose 会读取这些变量并注入容器。在 ToolJet 的 REST API 数据源配置中，可以使用 {{env.AI_API_URL}}、{{env.AI_API_KEY}} 这类占位符引用环境变量，从而避免把密钥直接写在查询或数据源里。如果你的 ToolJet 版本不支持环境变量占位符，也可以在数据源的高级设置中手动粘贴变量值，但这样不利于后续更换密钥。

在 ToolJet 管理界面中添加 REST API 数据源

登录 ToolJet 管理界面，进入左侧菜单“数据源”。
点击“新增数据源”或右上角的“+”按钮，在类型列表中选择 REST API。
在“URL”字段填入 AI 服务的完整端点，例如 https://api.example.com/v1/chat/completions。
在“认证方式”中选择 Bearer Token，并填入令牌内容。如果环境变量已配置，可直接输入 {{env.AI_API_KEY}}。
展开“高级”选项，按需添加其他请求头，例如 Content-Type: application/json。
点击“测试连接”，确认返回 200 后再保存数据源。如果测试失败，先执行下一步的 curl 验证，再回头排查配置。

用 curl 模拟 ToolJet 所在网络调用 AI 接口

进入 ToolJet 容器，模拟与 ToolJet 相同的网络环境和鉴权信息。先找到容器名：

docker ps | grep tooljet

然后进入容器并执行 curl。这里假设环境变量已经注入到容器中：

docker exec -it <容器名> sh
curl -i -X POST "$AI_API_URL" \
  -H "Authorization: $AI_API_HEADER_PREFIX $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-3.5-turbo","messages":[{"role":"user","content":"hello"}]}'

如果返回 200 OK，说明容器能访问 AI 服务且鉴权通过。如果返回 401 或 403，检查令牌是否有效、前缀是否正确；如果出现 timeout 或 connection refused，则说明容器无法访问目标网络，需要检查宿主机的防火墙、路由或代理设置。

检查 ToolJet 后端日志确认连接成功

当数据源测试失败时，通过日志定位具体错误层。执行以下命令查看 ToolJet 后端日志：

docker logs <容器名> `--tail` 100 2>&1 | grep -i "tooljet\|error\|network"

常见日志含义与排查方向：

timeout 或 connect ETIMEDOUT：请求超时，容器无法到达 AI 服务地址，优先检查 DNS 解析、出网路由和防火墙规则。
401 Unauthorized / 403 Forbidden：鉴权信息错误或令牌过期，核对令牌内容、请求头前缀，以及 AI 服务端是否识别该密钥。
self-signed certificate / TLS 相关错误：AI 服务使用了自签证书，需要在 ToolJet 容器内配置对应 CA 证书，或临时禁用 TLS 校验（不建议生产环境使用）。

日志只能区分网络层、鉴权层和证书层的问题，不能覆盖所有业务错误。如果日志中没有明确错误，可以调整日志级别或直接在容器内执行 curl 对比输出。