入门指南
本指南从安装讲起，带你打开第一个终端和第一个 AI 智能体会话。读完即可开始工作；各项功能的详细说明见其他章节（参见手册概览）。
1. VelaTerm 是什么
VelaTerm 是一款为配合 AI 编程智能体工作而设计的终端管理器。它用项目 → 分组 → 会话的树形结构组织终端会话和智能体会话，并把 Claude Code、Codex 等编程智能体作为专门的会话来运行：你可以随时看到智能体是在工作、需要你输入，还是已经完成；重新打开会话后，对话会接着之前的内容继续。智能体既可以在自己的终端界面中运行，也可以在会话视图中运行，会话视图以消息、工具卡片和权限按钮的形式呈现对话。借助浏览器远程访问和 SSH 远程开发，你还可以在其他设备上继续使用这些会话。
2. 安装
请从下载页面获取适用于你所用平台的安装包：
| 平台 | 安装包 | 说明 |
|---|---|---|
| macOS | .dmg（Apple Silicon 与 Intel 分别提供） | 打开后将 VelaTerm 拖入“应用程序”文件夹。应用已通过 Apple 公证 |
| Windows | -setup.exe 安装程序，分为 min 和 full 两个版本 | full 版（约 360 MB）包含完整的 Git Bash；min 版（约 25 MB）会在需要时下载缺少的命令。两个版本安装到同一位置，请二选一 |
| Linux | .AppImage（x86_64 和 aarch64） | 添加可执行权限后直接运行，无需安装 |
VelaTerm 会自动检查更新；也可以在应用菜单中选择「检查更新…」立即检查。
3. 首次启动：添加项目
首次启动时左栏为空，并提供三种添加项目的方式：
- 「创建项目」：新建一个文件夹并将其添加为项目。
- 「打开项目」（⌘O；Windows 和 Linux 上为 Ctrl+Alt+O）：将一个已有的文件夹添加为项目。
- 「从 Git 克隆」：克隆一个仓库并将其添加为项目。
左栏顶部也提供这几项操作的按钮。在项目中可以创建分组（可任意嵌套，例如前端、后端、测试），并在分组中创建会话：
4. 打开第一个终端
以下任一方式都会打开一个临时终端：
- 按 ⌘T（Windows 和 Linux 上为 Ctrl+Alt+T）。
- 在左栏中将鼠标悬停在项目、分组或会话上，点击 ＋ 按钮，然后选择「新建终端」。终端会在该节点的目录中启动。项目和分组的右键菜单中也有这一项。
- 中栏为空时，点击「新建终端」。
临时终端只以标签页的形式存在：它不会成为项目树中的节点，关闭后即被丢弃，因此适合执行简短的命令。
5. 打开第一个 AI 智能体会话
右键点击项目或分组，选择「新建 Claude 会话」。菜单第一级提供 Claude、Codex 和 OpenCode；「更多智能体会话」中列出了全部十四种受支持的智能体。也可以按 ⌘N（Windows、Linux 以及普通浏览器中为 Ctrl+Alt+N）打开可搜索的智能体列表。
VelaTerm 会在项目目录中启动智能体。Claude、Codex、OpenCode、Pi 和 OMP 会话以会话视图打开：在底部的输入框中输入消息，按 Enter 发送。其他智能体以终端视图打开，显示智能体自身的终端界面。分屏顶部的切换按钮可以让会话在两种视图之间切换，详见会话视图。
此后，你将获得以下三项功能：
- 状态点：左栏中会话旁的圆点显示智能体的状态。绿色表示正在工作，黄色表示需要你处理（提问或权限请求），洋红色表示智能体已回复且你已查看。
- 系统通知：智能体停下来等待你时，你会收到系统通知。如果你正在查看该会话，则不会弹出通知。
- 自动恢复：关闭标签页或退出应用后，下次打开该会话时，对话会从中断处继续。如需开始新的对话，请新建一个会话。
如果尚未安装智能体的 CLI，会话中会显示安装卡片，其中包含适用于你所用系统的推荐安装命令和「一键安装」按钮。
6. 界面概览
- 左栏：项目树，附带搜索框和状态筛选。顶部按钮依次为：创建项目、导入项目、从 Git 克隆、搜索所有会话和已归档会话。
- 中栏：标签栏和已打开的会话。默认情况下，在项目树中点击智能体会话会复用当前标签页，之前的标签页在后台继续运行。关闭标签页会结束其中的进程。标签页可以拆分为多个分屏（⌘D 向右分屏，⌘⇧D 向下分屏）。
- 右栏：随当前会话切换，包含四个标签页：文件、信息（会话详情、账号用量、上下文与资源占用）、Git（分支、改动和提交）以及知识库。
- 状态栏：会话数量、当前会话类型、Git 分支、权限模式、通知开关，以及「工作中」「等待处理」「已查看」计数。点击某个计数后，左栏只显示处于该状态的会话。
- 标题栏右侧：主题切换、远程访问、连接远程服务、分享、设置、账号、反馈，以及用于显示或隐藏左右两栏的按钮。