将 Open Terminal 连接到 Open WebUI
Open Terminal 已经 安装并运行。本指南将介绍如何将其连接到 Open WebUI。
推荐方案：管理 员面板
推荐用于所有部署场景，包括单用户部署。管理员面板可在服务器端保管 API 密钥，确保其不暴露。
1. 打开管理员面板
点击左侧边栏底部的您的姓名以打开用户菜单，然后点击 Admin Panel（管理员面板）。
2. 转到设置 → 集成
在管理员面板中，点击顶部导航栏中的 Settings（设置），然后点击 Integrations（集成）。
3. 找到 “Open Terminal” 部分
向下滚动直到您看到 Open Terminal 部分。
Open Terminal 在 Integrations（集成）下有其专属的部分 —— 请勿将其添加到 “External Tools”（外部工具）或 “Tool Servers” 下。使用专用部分可以为您提供内置的文件浏览器和终端侧边栏。
4. 点击 + 并填入详细信息
| 字段 | 输入内容 |
|---|---|
| URL | http://localhost:8000（如果使用 Docker Compose，则为 http://open-terminal:8000） |
| API Key | 您在安装期间选择的密码 |
| Auth Type | 保持默认的 Bearer |
5. 保存
点击 Save（保存）。绿色的 “Connected” 指示灯表示连接成功。
6. （可选）限制对特定用户组的访问
通过访问控制按钮限制特定用户组的终端访问权限。
7. 在聊天中选择终端
在聊天输入区域中，点击终端按钮（云图标 ☁）。您管理员配置的终端将显示在 System（系统）下。选择其中一个以在对话中激活它。
所选终端的名称将显示在云图标旁边。AI 现在可以通过该终端执行命令、读取文件并运行代码。
8. 启用原生函数调用
为了让 AI 能够稳定地使用终端工具，您需要在您的模型上启用原生函数调用：
- 转到 Workspace → Models
- 点击您正在使用的模型旁边的编辑按钮
- 在 Capabilities（功能）下，启用 Native Function Calling（原生函数调用，也称为 “tool use” 工具使用）
- 保存
原生函数调用可以让模型直接使用服务商内置的工具调用格式来调用工具。如果不启用它，Open WebUI 将退回到基于提示词（prompt-based）的工具调用，这种方式稳定性较差，甚至可能根本无法触发终端命令。
并不是所有的模型都具有相同的工具使用能力。前沿模型（GPT-5.4、Claude Sonnet 4.6、Gemini 3.1 Pro）可以很好地处理多步骤的终端工作流程。较小或较旧的模型在处理复杂任务时可能会遇到困难，无法调用工具，或者生成格式错误的工具调用。如果效果不佳，请尝试使用更强大的模型。
9. 尝试使用
问问您的 AI 类似以下的问题：
"你运行在什么操作系统上？"
AI 应该会使用 Open Terminal 运行命令并将答案告诉您。
对于 Docker 部署，您可以使用 TERMINAL_SERVER_CONNECTIONS 环境变量自动配置终端连接 —— 当您希望在启动时自动完成所有设置而无需手动操作时，这非常有用。
个人设置（仅用于测试）
通过个人 Settings（设置）添加终端连接会将 API 密钥发送到您的浏览器，并直接从中路由请求。这对于快速测试非常有用，但除此之外，建议使用 Admin Settings（管理员设置） —— 它更安全，且能自动供所有用户使用。
如果您需要在没有管理员权限的情况下测试连接，您可以从 Settings → Integrations → Open Terminal 中添加一个连接。使用相同的 URL 和 API 密钥字段。
问题排查
“连接失败”或超时
这几乎总是意味着 Open WebUI 无法通过网络访问 Open Terminal。使用哪个 URL 取决于您的设置：
| 您的设置 | 要使用的 URL |
|---|---|
| Docker Compose（推荐） | http://open-terminal:8000 |
| 独立的 Docker 容器 | http://host.docker.internal:8000 |
| 两者在同一台机器上，未使用 Docker | http://localhost:8000 |
| Open Terminal 部署在另一台机器上 | http://[该机器的IP]:8000 |
运行此命令以查看 Open WebUI 是否能访问 Open Terminal：
docker exec open-webui curl -s http://open-terminal:8000/health如果它输出 {"status": "ok"}，说明连接正常。如果报错，则说明容器之间无法相互访问。
终端已显示但 AI 未使用它
请确保：
- 连接旁边的切换开关已开启
- 添加连接后您已刷新页面
- 您的模型支持工具调用（大多数现代模型都支持）
API 密钥错误
如果您看到 “unauthorized”（未授权）或 “invalid key”（无效密钥）：
- 双击检查密钥是否与您在安装期间设置的密钥一致
- 如果您忘记了密钥，请运行
docker logs open-terminal并查找API key:行