文档

安装后的 Hangar

日常使用 Hangar 所需的一切:从第一个智能体,到 Hangar 保存设置的文件。

入门步骤

  1. 安装。下载 Hangar-Setup.exe 并运行。Hangar 仅为当前用户安装,无需管理员权限。
  2. 启动智能体。在“新建会话”下选择项目文件夹,选择“私人”或“团队”,然后点击一个智能体。Hangar 会列出在本机上找到的所有智能体及其版本;在“团队”下只列出能够作为团队会话运行的智能体。
  3. 邀请团队(可选)。点击侧边栏底部的“登录”,在浏览器中确认代码,然后连接项目。加入同一项目的成员可以在团队窗口中看到彼此。
  4. 头像(可选)。你 Hangar 账户的头像会显示在侧边栏中。你可以在本网站的账户 › 设置中上传。

下载 Hangar 支持的智能体

如果安装时 Windows 显示 SmartScreen 警告,请选择“更多信息”,然后选择“仍要运行”。安装程序尚未使用代码签名证书签名。Hangar 内的更新始终经过签名和验证。

系统要求:Windows 10 版本 1809 或更高版本,或 Windows 11(x64)。智能体需使用各自的账户自行安装。团队会话(worktree)、更改跟踪、提交和共享笔记需要 Git。

键盘快捷键

Hangar 只拦截 shell 和智能体用不到的组合键。不带 Shift 的对应组合键仍交给终端中的程序:Ctrl+B、Ctrl+F 或 Ctrl+P 依然会传到 shell 或智能体。

Hangar 中任意位置
按键操作
Ctrl+Shift+P快速访问:查找会话、程序、文件、最近的提交、设置以及每个菜单命令
Ctrl+Shift+S搜索所有会话的输出
Ctrl+Shift+M将所有会话显示为实时磁贴
Ctrl+Shift+H显示主页视图;会话会继续运行
Ctrl+Shift+T使用最近使用的程序新建会话
Ctrl+Shift+W关闭会话
Ctrl+Tab下一个会话
Ctrl+Shift+Tab上一个会话
Ctrl+Shift+A转到下一个等待中的会话
Ctrl+Shift+N快速笔记
Ctrl+Shift+D显示或隐藏会话文件夹中的更改
Ctrl+Shift+F搜索终端历史记录
Ctrl+Shift+B折叠或展开侧边栏
Ctrl+,打开设置
Ctrl++放大文字
Ctrl+-缩小文字
Ctrl+0重置文字大小
在终端中
按键操作
Ctrl+C复制所选内容;没有选中内容时,按键会传给程序(中断)
Ctrl+Shift+C复制所选内容并保持选中
Ctrl+V粘贴;剪贴板中有图片时,Hangar 会粘贴已保存图片文件的路径
Shift+Enter在智能体的提示中换行,不发送
Ctrl+Shift+空格按住进行语音输入;语音在你自己的电脑上识别
在历史记录搜索中
按键操作
Enter下一个匹配项
Shift+Enter上一个匹配项
Esc关闭搜索
笔记、侧边栏以及发送给多个会话
按键操作
F6 / Shift+F6笔记打开时,在终端、笔记列表和编辑器之间切换焦点
F2重命名笔记
Alt+↑ / Alt+↓在侧边栏中上移或下移当前焦点所在的会话
Ctrl+Enter向多个会话发送消息

profiles.toml 中的配置

自定义的终端和智能体位于配置文件夹中的 profiles.toml,在 Windows 上为 %APPDATA%\com.feoren.hangar\profiles.toml。如果该文件不存在,Hangar 会在启动时根据带注释的模板创建它,其中包含 PowerShell 7、Windows PowerShell 和命令提示符。

打开该文件最快的方式是在设置中选择“终端和智能体 › 打开配置文件”。

目录中的智能体无需配置,Hangar 自己就能识别。若要以不同方式启动其中某个智能体,请创建一个具有相同 id 的配置:它会替换目录条目的名称、图标、命令、参数和位置;项目页面和安装命令仍沿用目录中的内容。

配置的字段
字段含义
id必填。唯一,不含空格。仅大小写不同的两个 ID 会被 Hangar 拒绝。
name必填。侧边栏中显示的名称。
command必填。PATH 中的程序名或完整路径。不支持 shell 语法:Hangar 直接启动该程序。
args以列表形式给出的参数,例如 ["--model", "opus"]。
cwd固定的工作文件夹。没有此字段时,程序会在所选的文件夹中启动。
icon侧边栏图标使用的一个或两个字符。
[profile.env]环境变量,写成单独的表。请勿在此存放机密信息。
secret_env其值由 Hangar 保存在 Windows 凭据管理器中的变量名称,例如 ["GITHUB_TOKEN"]。
resume_args用于继续上次对话的参数。它们会替换 args,而不是追加在后面。
version_args用于查询版本的参数,默认为 ["--version"];[] 表示:从不为读取版本而启动该程序。
latest, packages, self_update, update_hint新版本的发布位置,以及 Hangar 如何一键更新该程序。文件中带注释的模板会说明每个字段。

示例

第一个配置以不同的模型启动目录中的 Claude Code。第二个是自定义的 PowerShell,带有固定的工作文件夹、一个普通变量和一个机密变量。

[[profile]]
id = "claude"
name = "Claude Code (Opus)"
command = "claude"
args = ["--model", "opus"]
icon = "C"

[[profile]]
id = "pwsh-shop"
name = "PowerShell (Shop)"
command = "pwsh"
args = ["-NoLogo"]
cwd = 'C:\src\shop'
icon = "SH"
secret_env = ["GITHUB_TOKEN"]

[profile.env]
DOTNET_CLI_TELEMETRY_OPTOUT = "1"

机密变量

secret_env 中变量的值永远不会出现在文件中。这些值在设置中编辑配置时输入。Hangar 将其保存在 Windows 凭据管理器中的服务 hangar 下,仅在会话启动时才放入该会话的环境中。同一个变量不能同时出现在 [profile.env] 和 secret_env 中。

保存后,只要回到 Hangar 的窗口,Hangar 就会重新加载该文件;也可以选择“重新加载配置”。Hangar 会显示出错的行和列;正在运行的会话保持不变。

等待中智能体的通知

侧边栏一眼就能看出哪个智能体在工作、哪个已完成、哪个在等待回应。其余选项都在设置的“提醒”中。

  • 突出显示等待中的会话:当视线在别处时,若智能体完成或在等待回应,相应会话会轻轻脉动。可以设置安静多少秒后显示提示。
  • 颜色和脉动:工作中、完成、在提问和暂停各有自己的颜色、脉动强度和脉动时长,并提供预览。
  • 提示音:当一个当前看不到的会话在等待时,会响起柔和的双音提示音。如果程序因错误结束,音调会更低。音量可调。
  • 桌面通知:仅在 Hangar 位于后台时显示。点击即可打开该会话。
  • 闪烁任务栏:仅在 Hangar 不在前台时闪烁。切换到 Hangar 窗口后立即停止。
  • 任务栏上的计数:任务栏按钮上的小图标显示等待中的会话数量,从 1 到 9,超过则显示 9+。
  • 推送到手机:当会话在等待你时,通过 ntfy 或 Pushover 推送。使用 ntfy 时,请选择一个难以猜到的主题,因为任何知道它的人都能看到内容。
  • 免打扰时段:在你选定的时段内,没有提示音、没有通知,没有手机推送,任务栏也不闪烁。颜色和等待中会话的数量会保留。
  • 在通知区域继续运行:关闭窗口后会话会继续运行,通知区域中的图标会显示有多少会话在等待。要退出 Hangar,请右键单击该图标。

Ctrl+Shift+A 可直接跳到下一个等待中的会话。

团队会话和 worktree

在“新建会话”下选择“私人”或“团队”。私人会话直接在你的文件夹中运行,只供你自己使用。团队会话拥有自己的 Git worktree,并对团队可见,因此多个智能体可以同时修改同一个项目,而不会互相抢占文件。

Hangar 会为每个团队会话从当前状态创建分支 hangar/…。当智能体要编辑另一个会话正在处理的文件时,Hangar 会先拦下并询问你;对某个文件或文件夹选择“始终允许”或“始终拒绝”,Hangar 会按项目记住。Claude Code、Codex CLI、OpenCode 和 Pi 可作为团队会话运行。

worktree 位于应用数据文件夹 %LOCALAPPDATA%\com.feoren.hangar\worktrees\ 下,而不是仓库旁边。这样仓库和同步文件夹都能保持整洁。

智能体在全新的 worktree 中启动时,会先检查上游是否有新提交,并在拉取前询问你。你可以在设置的“终端和智能体”中关闭它。

团队会话结束时,Hangar 会再次删除该 worktree,除非其中仍有更改或被忽略的文件(例如构建输出),或者另一个会话仍在其中工作。包含尚未合并提交的分支会保留。Hangar 从不强制执行任何操作。

这需要已安装 Git,并且文件夹位于 Git 仓库中。Hangar 不会在网络共享上运行 Git,在 WSL 中也不会进行编辑前的检查。

笔记

笔记属于会话所在的项目,或属于“通用”区域。它们是真正的 Markdown 文件,也可以在文件资源管理器中打开。

  • Ctrl+Shift+N 可在任何位置开始一条快速笔记。
  • 可将终端中选中的文本直接发送到笔记,也可将笔记发送到会话。在会话中粘贴时不会按 Enter,因此可以先检查内容。
  • 删除的笔记会进入“最近删除”,可在那里恢复。
  • 在笔记面板顶部,你可以在“私人”和“共享”之间切换,让你自己的笔记与团队的笔记保持分开。

共享的加密笔记

为项目开启共享笔记后,Hangar 会对其加密,并保存在仓库的 .hangar\notes\ 文件夹中。它们随提交一起流转。拥有仓库和代码的人都能读取。解密后的文本从不写入磁盘,Hangar 也从不自行提交。

开启时,Hangar 会显示一次笔记恢复代码。请妥善保管:如果这台计算机丢失了密钥,没有该代码,笔记将永久丢失。有了代码,也可以在其他克隆中打开这些笔记。

适用于所有智能体的一份指令文件

HANGAR.md 位于配置文件夹中,紧挨着 profiles.toml,作用类似 AGENTS.md 或 CLAUDE.md,只是不需要在你的仓库里放文件。Hangar 会把它的内容交给每个接受额外指令的智能体:Claude Code、Codex CLI 和 Aider。默认开启;模板是空的,在你写入内容之前不会发送任何东西。

你可以在设置的“终端和智能体”中通过“打开 HANGAR.md”打开该文件,也在那里开启或关闭“为每个智能体使用 HANGAR.md”。不要在里面写入机密:文本会出现在智能体的命令行中。

存储位置

Hangar 将设置保存在用户配置文件中,在 Windows 上即 %APPDATA% 和 %LOCALAPPDATA%。只有共享笔记位于项目中。

存储位置
位置内容
%APPDATA%\com.feoren.hangar\profiles.toml自定义配置
%APPDATA%\com.feoren.hangar\HANGAR.md你给所有智能体的指令
%APPDATA%\com.feoren.hangar\account.json所选服务器以及已登录的服务器;不含令牌
%LOCALAPPDATA%\com.feoren.hangar\workspace.json, scrollback\打开的会话及其历史记录,以便 Hangar 在重启后恢复它们
%LOCALAPPDATA%\com.feoren.hangar\notes\私人笔记,以 .md 文件形式按项目文件夹和 general 存放;已删除的位于 .trash
%LOCALAPPDATA%\com.feoren.hangar\worktrees\会话的 worktree
%LOCALAPPDATA%\com.feoren.hangar\pastes\粘贴的屏幕截图;Hangar 会在一周后删除
%LOCALAPPDATA%\Hangar程序本身
.hangar\notes\仓库中的加密共享笔记
Windows 凭据管理器机密配置变量、登录信息,以及团队和共享笔记的密钥

自有团队服务器

对于团队功能,Hangar 默认连接位于 https://hangar.feoren.com/api/v1 的官方服务。不登录时,除团队窗口外的所有功能都可正常使用。

如果团队运行着自己的 Hangar 服务器,请在设置的“账户 › 服务器地址(自托管)”中输入其地址并点击“应用”。留空则重新使用官方服务。

该地址是服务器的 API 根地址,例如 https://team.example.com/api/v1。它必须以 https:// 开头;Hangar 仅对 localhost、127.0.0.1 和 [::1] 允许使用不加密的 http。不允许包含用户名、密码、查询参数和片段。Hangar 将地址保存在 account.json 中;其他服务器的登录信息仍保存在设备上。

这样的服务器必须提供与官方服务相同的接口:通过 OAuth 设备流程登录、账户和项目,以及用于中继的票据,中继通过 WebSocket 传输团队数据。该协议的数据类型及其加密在应用仓库中的 crate hangar-team-protocol 和 hangar-team-crypto 中公开,采用 MIT 许可证。

与团队共享的所有内容都会在设备上加密。服务器负责存储和转发,但无法读取。新设备只有在有人比对并确认安全码后才能加入。

当前进展: 用于自托管的现成服务器软件尚未发布。应用已经可以使用自定义地址,但这里还没有安装指南。

正在为公司规划使用 Hangar,并需要自有服务器?请联系我们,我们会研究具体情况。

团队联系方式