⚡ Open Terminal

一款轻量级、自托管的终端，为 AI 助手和自动化工具提供了一个专用环境，用于运行命令、管理文件和执行代码——所有这些都通过一个简单的 API 完成。

为什么选择 Open Terminal？

AI 助手非常擅长编写代码，但它们需要一个地方来“运行”这些代码。Open Terminal 就是这样一个地方——一个带有文件管理、搜索等功能的远程 Shell，可以通过简单的 REST API 访问。

你可以通过两种方式运行它：

• Docker（沙箱化） — 在一个隔离的容器中运行，预装了完整的工具集：Python、Node.js、git、构建工具、数据科学库、ffmpeg 等。非常适合为 AI 助手提供一个安全的实验环境，而不会影响你的主机系统。
• 裸机 — 使用 pip 安装并运行在任何支持 Python 的环境中。命令会直接在你的机器上执行，访问你的真实文件、真实工具和真实环境，非常适合本地开发、个人自动化，或者让 AI 助手完全访问你的实际项目。

快速开始

Docker（推荐）

docker run -d --name open-terminal --restart unless-stopped -p 8000:8000 -v open-terminal:/home/user -e OPEN_TERMINAL_API_KEY=your-secret-key ghcr.io/open-webui/open-terminal

仅此而已——你现在就可以在 http://localhost:8000 上使用它了。

[!TIP] 如果你不设置 API 密钥，系统会自动生成一个。你可以通过 docker logs open-terminal 来获取它。

镜像变体

	latest	slim	alpine
最适合	AI 助手沙箱	生产/加固	边缘/CI/极简占用
大小	~4 GB	~430 MB	~230 MB
捆绑工具	Node.js、gcc、ffmpeg、LaTeX、Docker CLI、数据科学库	git、curl、jq	git、curl、jq
运行时安装包	✔（有 sudo）	✘	✘
多用户模式	✔	✘	✘
出站防火墙	✔	✔	✔

slim 和 alpine 具有相同的功能集。Slim 使用 Debian（glibc）以获得更广泛的二进制兼容性；Alpine 使用 musl libc，体积更小，但某些 C 扩展的 pip 包可能需要从源码编译。

docker run -d -p 8000:8000 -e OPEN_TERMINAL_API_KEY=secret ghcr.io/open-webui/open-terminal:slim
docker run -d -p 8000:8000 -e OPEN_TERMINAL_API_KEY=secret ghcr.io/open-webui/open-terminal:alpine

[!NOTE] Slim 和 Alpine 不支持 OPEN_TERMINAL_PACKAGES / OPEN_TERMINAL_PIP_PACKAGES / OPEN_TERMINAL_NPM_PACKAGES。要添加软件包，可以扩展 Dockerfile.slim 或 Dockerfile.alpine。

更新

docker pull ghcr.io/open-webui/open-terminal
docker rm -f open-terminal

然后重新运行上面的 docker run 命令。

裸机

没有 Docker？没关系。Open Terminal 是一个标准的 Python 包：

# 使用 uvx 的一行命令（无需安装）
uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

# 或者使用 pip 全局安装
pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

[!CAUTION] 在裸机环境下，命令会直接在你的机器上以你的用户权限执行。如果你希望实现沙箱化执行，请使用 Docker。

自定义 Docker 环境

添加额外软件包最简单的方式就是使用环境变量，无需分叉：

docker run -d --name open-terminal -p 8000:8000 \
  -e OPEN_TERMINAL_PACKAGES="cowsay figlet" \
  -e OPEN_TERMINAL_PIP_PACKAGES="httpx polars" \
  -e OPEN_TERMINAL_NPM_PACKAGES="typescript tsx" \
  ghcr.io/open-webui/open-terminal

变量	描述
OPEN_TERMINAL_PACKAGES	启动时要安装的 apt 软件包列表，用空格分隔
OPEN_TERMINAL_PIP_PACKAGES	启动时要安装的 pip 软件包列表，用空格分隔
OPEN_TERMINAL_NPM_PACKAGES	启动时要全局安装的 npm 软件包列表，用空格分隔

[!NOTE] 每次容器启动时都会安装这些软件包，因此如果软件包列表较大，启动时间会更长。对于重度定制，建议构建自定义镜像。

Docker 访问权限

该镜像包含 Docker CLI、Compose 和 Buildx。要让助手能够构建镜像、运行容器等，可以挂载主机的 Docker socket：

docker run -d --name open-terminal -p 8000:8000 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v open-terminal:/home/user \
  ghcr.io/open-webui/open-terminal

[!CAUTION] 挂载 Docker socket 会使容器获得对主机 Docker 守护进程的完全控制权，这实际上等同于主机上的 root 权限。任何拥有终端访问权限的人都可以拉取/运行任意容器（包括 --privileged 容器），挂载主机目录，访问主机网络，并管理主机上的所有容器。请仅在完全可信的环境中执行此操作。

若需完全控制，可以 fork 仓库，编辑 Dockerfile，然后构建自己的镜像：

docker build -t my-terminal .
docker run -d --name open-terminal -p 8000:8000 my-terminal

配置

Open Terminal 可以通过 TOML 配置文件、环境变量和 CLI 标志进行配置。设置的优先级顺序如下（优先级越高越有效）：

1. CLI 标志（--host、--port、--api-key 等）
2. 环境变量（OPEN_TERMINAL_API_KEY 等）
3. 用户配置 — $XDG_CONFIG_HOME/open-terminal/config.toml（默认为 ~/.config/open-terminal/config.toml）
4. 系统配置 — /etc/open-terminal/config.toml
5. 内置默认值

在上述任一位置创建配置文件，可以包含以下键（均为可选）：

host = "0.0.0.0"
port = 8000
api_key = "sk-my-secret-key"
cors_allowed_origins = "*"
log_dir = "/var/log/open-terminal"
binary_mime_prefixes = "image,audio"
execute_timeout = 5  # 等待命令输出的最大时间（秒），默认未设置

[!TIP] 使用 /etc/open-terminal/config.toml 设置站点范围内的主机和端口默认值，而将 API 密钥等个性化设置放在用户配置中——这样可以避免密钥出现在 ps 或 htop 中。

你也可以指定一个特定的配置文件：

open-terminal run --config /path/to/my-config.toml

与 Open WebUI 配合使用

Open Terminal 可以与 Open WebUI 集成，使你的 AI 助手能够直接从 AI 界面运行命令、管理文件并交互式地使用终端。请务必在集成设置中将其添加为 Open Terminal，而不是作为工具服务器。将其添加为 Open Terminal 连接后，你会获得一个内置的文件导航侧边栏，可以在其中浏览目录、上传、下载和编辑文件。连接方式有两种：

直接连接

用户可以从个人设置中连接自己的 Open Terminal 实例。当终端运行在本地机器上，或者仅限特定网络访问时，这种方式非常有用，因为请求会直接从 浏览器 发送。

1. 前往 用户设置 → 集成 → Open Terminal
2. 添加终端的 URL 和 API 密钥
3. 启用连接

系统级连接（多用户）

管理员可以在管理面板中为所有用户配置 Open Terminal 连接，无需额外服务。可以设置多个终端，并按用户或用户组级别控制访问权限。请求会通过 Open WebUI 的 后端 代理转发，因此终端只需能被服务器访问即可。

1. 前往 管理员设置 → 集成 → Open Terminal
2. 添加终端的 URL 和 API 密钥
3. 启用连接

内置多用户隔离

[!CAUTION] 单容器多用户模式 并不适用于生产环境中的多用户部署。所有用户共享相同的内核、网络和系统资源，彼此之间没有严格的隔离边界。如果某个用户的进程出现异常，可能会影响到系统中的其他所有用户。此模式仅作为轻量级的便捷方案，适用于小型且可信的团队，而非可依赖的安全模型。

对于小型且可信的部署，您可以在单个容器内启用每用户隔离：

docker run -d --name open-terminal -p 8000:8000 \
  -v open-terminal:/home \
  -e OPEN_TERMINAL_MULTI_USER=true \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal

每个用户将自动获得一个独立的 Linux 账户及专属的主目录。文件、命令和终端均通过标准的 Unix 权限实现用户间的隔离。

API 文档

实例运行后，完整的交互式 API 文档可在 http://localhost:8000/docs 查看。

星标历史

[!TIP] 需要容器级别的用户隔离吗？ 请查看 Terminals，它会为每个用户单独 provision 并管理 Open Terminal 容器。对于更轻量级的部署，内置的多用户模式（OPEN_TERMINAL_MULTI_USER=true）可在单个容器内提供每用户隔离。

许可证

MIT — 详情请参阅 LICENSE 文件。

Open Terminal 快速上手指南

Open Terminal 是一个轻量级、可自托管的终端工具，专为 AI 智能体和自动化工具设计。它通过简单的 REST API 提供命令执行、文件管理和代码运行环境，是连接 AI 与本地系统的桥梁。

1. 环境准备

在开始之前，请确保您的系统满足以下任一条件：

• 方案 A：Docker 环境（推荐）

  • 已安装 Docker 和 Docker Compose。
  • 适用于需要沙箱隔离、预装完整开发工具链（Python, Node.js, git, ffmpeg 等）的场景。
  • 注意：国内用户若拉取镜像缓慢，建议配置 Docker 镜像加速器。

• 方案 B：原生 Python 环境

  • 已安装 Python 3.8+。
  • 已安装 pip 或 uv 包管理工具。
  • 适用于直接在宿主机运行命令、访问本地真实文件和环境的场景。

2. 安装步骤

方式一：使用 Docker 部署（推荐）

这是最安全且功能最全的方式，容器内预装了丰富的开发工具。

启动容器：

docker run -d --name open-terminal --restart unless-stopped -p 8000:8000 -v open-terminal:/home/user -e OPEN_TERMINAL_API_KEY=your-secret-key ghcr.io/open-webui/open-terminal

提示：

• 将 your-secret-key 替换为您自定义的强密码作为 API 密钥。
• 如果不设置 OPEN_TERMINAL_API_KEY，系统会自动生成一个密钥，可通过 docker logs open-terminal 查看。
• 数据卷 -v open-terminal:/home/user 用于持久化用户文件。

可选：安装额外依赖 您可以在启动时通过环境变量动态安装 apt、pip 或 npm 包（仅适用于 latest 镜像）：

docker run -d --name open-terminal -p 8000:8000 \
  -e OPEN_TERMINAL_PACKAGES="cowsay figlet" \
  -e OPEN_TERMINAL_PIP_PACKAGES="httpx polars" \
  -e OPEN_TERMINAL_NPM_PACKAGES="typescript tsx" \
  -e OPEN_TERMINAL_API_KEY=your-secret-key \
  ghcr.io/open-webui/open-terminal

方式二：原生安装 (Bare Metal)

如果您不想使用 Docker，可以直接在宿主机运行。

使用 uvx (无需预先安装):

uvx open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

或使用 pip 全局安装:

pip install open-terminal
open-terminal run --host 0.0.0.0 --port 8000 --api-key your-secret-key

警告：原生模式下，AI 执行的命令将直接使用您当前用户的权限运行，并访问您的真实文件系统。如需沙箱隔离，请务必使用 Docker 模式。

3. 基本使用

安装完成后，服务默认运行在 http://localhost:8000。

验证服务状态

打开浏览器访问 http://localhost:8000/docs，即可查看完整的交互式 API 文档并测试接口。

集成到 Open WebUI

Open Terminal 旨在与 Open WebUI 无缝协作，让 AI 助手具备操作终端的能力。

1. 登录 Open WebUI。
2. 进入 用户设置 (User Settings) -> 集成 (Integrations) -> Open Terminal。
3. 输入您的终端地址（如 http://host-ip:8000）和设置的 API Key。
4. 启用连接。

启用后，您在对话界面中将获得侧边栏文件导航功能，可直接浏览目录、上传/下载文件，AI 也能直接在此环境中执行代码和命令。

高级配置 (可选)

您可以通过配置文件或环境变量调整行为。优先级顺序为：CLI 参数 > 环境变量 > 用户配置 (~/.config/open-terminal/config.toml) > 系统配置。

示例 config.toml 内容：

host = "0.0.0.0"
port = 8000
api_key = "sk-my-secret-key"
execute_timeout = 5  # 命令执行超时时间（秒）

运行指定配置文件：

open-terminal run --config /path/to/my-config.toml