Terminal Chat (TUI)

终端聊天，也称为 TUI，是 OpenSquilla 的命令行聊天界面。当你想要在 shell 中进行交互式对话时使用它，尤其是在本地项目目录中工作时。

Start Chat

启动默认的终端聊天：

opensquilla chat

这会使用稳定的 Python-native 终端 backend。它不需要 Bun、npm、tmux 或 OpenTUI 依赖。

如果 gateway-backed 聊天无法连接，请先启动 gateway：

opensquilla gateway start --json
opensquilla chat

为会话使用指定的 model：

opensquilla chat --model gpt-5.4-mini

恢复一个已有的会话：

opensquilla chat --session <session-key>

终端聊天是交互式的，需要一个真实的 TTY。对于脚本、管道、CI 或一次性自动化，请使用：

opensquilla agent -m "Inspect this workspace"

默认情况下，opensquilla chat 使用 gateway-backed 聊天路径，因此它会与 Web UI 及其他 gateway 客户端共享会话、配置、审批、用量以及 model/provider 状态。

当你想要不依赖 gateway 守护进程的直接终端聊天时，使用 standalone 模式：

opensquilla chat --standalone

standalone 模式接受用于本地文件和工具工作的 workspace 标志：

opensquilla chat --standalone --workspace /path/to/project --workspace-strict

在 gateway 模式下，终端聊天会忽略 --workspace。请使用 gateway 可见的路径配合 /path，或使用 /file 从 CLI 机器上上传本地文件。

在终端聊天中输入 /help 可以查看当前模式支持的命令。

gateway 和 standalone 聊天中都可用的命令包括：

Command	Purpose
`/help`	Show command help.
`/status` or `/session`	Show the active session and model.
`/new [title]`	Start a new session.
`/model [model]`	Show or change the active model.
`/cost`	Show usage for the current chat state.
`/clear` or `/reset`	Clear the current session context.
`/compact` or `/cmp`	Compact long context when possible.
`/save [path]`	Save the transcript.
`/image <path> [prompt]`	Send an image file with an optional prompt.
`/path <path> [prompt]`	Attach a file by path.
`/theme ...`	Change terminal theme settings when the active backend supports it.
`/quit` or `/exit`	Leave chat.

gateway-backed 聊天还支持会话和操作命令：

Command	Purpose
`/sessions [limit]`	List recent sessions.
`/resume <id>`	Resume a session.
`/delete <id>`	Delete a session.
`/models`	List available models.
`/usage`	Show aggregate usage.
`/meta`	List MetaSkills.
`/meta <name>`	Run a MetaSkill in the current session.
`/file <path> [prompt]`	Upload a local file and send it with a prompt.
`/permissions ...`	Inspect or change interactive permission mode.
`/approvals ...`	Inspect or reset approval state.
`/forget`	Clear remembered approvals.

standalone 聊天支持上面的核心命令，但 /models、/meta 以及 gateway 范围的用量或审批命令需要 gateway 模式。

对图像文件使用 /image：

/image ./screenshot.png Describe the UI issue

当文件路径对运行中的聊天进程可见时使用 /path：

/path ./docs/quickstart.md Summarize the setup steps

在使用远程 gateway 的 gateway 模式下，优先使用 /file，这样 CLI 会在发送该 turn 之前先上传本地文件：

/file ./report.pdf Extract the action items

默认终端聊天是常规使用的受支持路径。OpenTUI 是一个可选启用的预览 backend，用于从源码检出评估更丰富的终端 UI。它对于日常终端聊天不是必需的。

从源码检出：

bun install --frozen-lockfile --cwd=src/opensquilla/cli/tui/opentui/package
OPENSQUILLA_TUI_BACKEND=opentui uv run opensquilla chat

不设置 OPENSQUILLA_TUI_BACKEND 即可使用稳定的终端聊天。

关于 OpenTUI backend 状态、Router HUD 详情以及 replay benchmarks，请阅读 features/tui-frontend.md。仅当你在运行终端渲染的 maintainer 集成测试时，才阅读 tui-real-terminal-harness.md。