跳到主要内容

将 Open Terminal 连接到 OPL 数据空间

假设 Open Terminal 已经安装并启动。这份指南只关注如何把它接进 OPL 数据空间。

推荐方式：管理员面板​

推荐所有部署都使用这种方式，包括单用户部署。管理员面板 会把 API key 保留在服务端，不会暴露给浏览器。

1. 打开 管理员面板​

点击左侧边栏底部的用户名，打开用户菜单，再点击 管理员面板。

User menu showing Admin Panel option

2. 进入 设置 → Integrations​

在 管理员面板 顶部导航中点击 设置，再进入 Integrations。

管理员面板 — 设置 →扩展功能

3. 找到 Open Terminal 区域​

向下滚动，找到 Open Terminal 这一节。

The Open Terminal section under Integrations

不要和 “Tools” 混淆

Open Terminal 在 Integrations 下有单独的配置区域，不要把它加到 “External Tools” 或 “Tool Servers” 里。使用专门区域，才能获得内建文件浏览器和 terminal 侧栏。

4. 点击 + 并填写连接信息​

字段填写内容
URLhttp://localhost:8000，或 Docker Compose 下的 http://open-terminal:8000
API Key安装时设置的密钥
Auth Type保持默认 Bearer

Connection form filled in with URL and API key

5. 保存​

点击 Save。如果连接成功，你会看到绿色的 “Connected” 提示。

Connected status with green indicator

6. 可选：限制访问范围​

你可以通过 access control 按钮，把 terminal 访问权限限制给特定用户组。

7. 在聊天中选择 terminal​

在聊天输入区域点击 terminal 按钮（云图标 ☁），你在管理员侧配置的 terminals 会显示在 System 分组下。选择其中一个，即可在当前会话中启用。

Terminal dropdown showing Docs Terminal under System

选中的 terminal 名称会显示在云图标旁边。之后 AI 就能通过它执行命令、读取文件和运行代码。

8. 启用 native function calling​

为了让 AI 稳定调用 terminal 工具，还需要在模型上启用 native function calling：

  1. 打开 Workspace → Models
  2. 编辑你当前使用的模型
  3. 在 Capabilities 中启用 Native Function Calling
  4. 保存

Model capabilities showing Builtin Tools enabled

不启用会影响工具调用

Native function calling 会让模型使用 provider 原生工具调用格式直接调用 Open Terminal。不开启时， OPL 数据空间只能退回到基于 prompt 的工具调用，稳定性会明显下降，甚至根本不会触发 terminal 命令。

性能与模型强相关

不是所有模型都同样擅长用工具。前沿模型通常更适合多步骤 terminal 工作流；较小或较老模型更容易漏调工具、调错工具，或者生成畸形 tool calls。

9. 试一下​

你可以直接问模型：

“你现在运行在什么操作系统上？”

如果配置成功，AI 会通过 Open Terminal 执行命令并给出答案。

AI using run_command to check the operating system

也可以通过环境变量预配置

在 Docker 部署中，你也可以使用 TERMINAL_SERVER_CONNECTIONS 环境变量预先配置 terminal 连接，这样实例启动时就能自动带上，无需手动点界面。

Personal 设置（仅适合测试）​

不建议长期使用

通过个人 设置 添加 terminal 连接时，API key 会被发送到浏览器，并由浏览器直连该 terminal。它适合快速测试，但如果要稳定使用，还是应改走 Admin 设置。

如果你没有管理员权限，也可以在 设置 → 扩展功能 → Open Terminal 中手动添加连接，填写方式与上面相同。

故障排查​

“Connection failed” 或 timeout​

这通常意味着 OPL 数据空间在网络层无法访问 Open Terminal。不同部署对应的 URL 不同：

部署方式推荐 URL
Docker Composehttp://open-terminal:8000
分开的 Docker 容器http://host.docker.internal:8000
同机且不用 Dockerhttp://localhost:8000
Open Terminal 在另一台机器http://that-machines-ip:8000
快速检查

你可以执行下面命令验证 OPL 数据空间容器是否能访问 Open Terminal：

docker exec open-webui curl -s http://open-terminal:8000/health

如果返回 {"status": "ok"}，说明网络连通；否则就需要先解决容器之间的可达性问题。

Terminal 出现在列表里，但 AI 不使用​

请检查：

  • 连接旁边的开关是否已打开
  • 添加连接后是否刷新过页面
  • 当前模型是否支持工具调用

API key 不正确​

如果看到 “unauthorized” 或 “invalid key”：

  • 核对 key 是否与你安装时设置的一致
  • 如果忘了，可以执行 docker logs open-terminal，查看其中的 API key: 行

下一步​