跳到主要内容
AI教程

Harp 教程：在简洁的 macOS 侧边栏中管理 Claude Code 和 Codex 代理

了解如何在 macOS 上安装 Harp，将 Claude Code 和 Codex 会话整理到持久化分组中，监控代理状态，配置使用限额环，并通过 tmux 连接会话。

AI我搜编辑部阅读约 8 分钟
Harp 教程：在简洁的 macOS 侧边栏中管理 Claude Code 和 Codex 代理

Harp 是开源 Warp 终端的非官方 macOS 分支。它保留了 Warp 的终端、AI 和云端功能，同时将传统标签栏替换为专为长期运行的编码代理设计的侧边栏。

使用 Harp，你可以并排运行多个 Claude Code 和 Codex 会话，并快速查看哪些会话正在工作、等待你的操作、已完成、在后台运行或被暂时搁置。Harp 不运行自己的服务器；上游 Warp 功能仍会像在 Warp 中一样与 Warp 的服务器通信。

显示已整理代理会话的 Harp 侧边栏

Harp 新增的功能

一目了然的代理状态

侧边栏中的每一行都可以显示 Claude Code 或 Codex 会话的状态。未读标记会一直保留，直到你查看该会话；圆点表示后台工作仍在运行；月亮图标表示你暂时搁置了该标签页。使用 Cmd+R 可重命名标签页。

持久化分组

你可以将标签页放入命名分组，以便整理项目和代理。启用 tmux 集成后，Harp 会将分组和排序存储在 tmux 会话中。这使布局能够在重启后保留，并让其他 tmux 客户端看到相同的排列。

用量限制环

侧边栏底部可以为每个提供商显示两个环：一个表示五小时窗口，另一个表示每周限制。Harp 从由你选择的工具维护的本地 JSON 文件中读取这些数值。它不会自行获取用量数据。有关预期文件格式，请参阅限制环格式文档。

适合手机使用的 tmux 会话

连接到 tmux 的会话可以携带其名称、分组、已读状态和非活动标记。从其他位置启动的 tmux 会话（例如通过 SSH 从手机启动的会话）可以将 tmux 选项 @warp_adopt 设置为 1，以请求 Harp 创建一个标签页。

安装 Harp

安装最新的 macOS 版本

  1. 从 GitHub Releases 页面打开最新的 Harp 发布版本。
  2. 下载 Harp-<version>.dmg 文件。
  3. 打开磁盘映像，并将 Harp 拖入 Applications 文件夹。

Harp 使用独立的 bundle 标识符 com.dominikmartn.Harp、URL 方案 harp:// 和设置目录 ~/.harp。因此，它可以与 Warp 并行运行，而不会共享这些资源。

从源代码构建

如需自行构建 Harp，请使用 macOS 以及 rust-toolchain.toml 中指定的 Rust 工具链。在仓库根目录中运行一次引导脚本：

./script/bootstrap

然后编译并启动调试应用程序：

./script/run

构建会生成 target/debug/bundle/osx/Harp.app 并启动它。macOS 运行脚本会使用钥匙串中的第一个 Apple Development 身份为应用签名；如果找不到，则使用临时签名。若要生成已签名且可进行公证的发布 DMG，请使用 script/release_macos 并查看其帮助输出。

配置 Harp

Harp 的附加集成默认处于禁用状态。创建或编辑 ~/.harp/settings.toml，然后启用所需功能。设置文件发生变化时，Harp 会重新加载该文件。

[integrations.limit_rings]
enabled = true
file = "~/.cache/limit-rings.json"

[integrations.tmux]
enabled = true

启用用量限制环

将 integrations.limit_rings.enabled 设置为 true，并将 integrations.limit_rings.file 指向包含提供商用量数值的本地 JSON 文件。字符 ~ 代表你的主目录。

启用 tmux 同步

将 integrations.tmux.enabled 设置为 true，即可启用 tmux 同步、会话接管以及 tmux 内的代理检测。Harp 每 10 秒轮询一次 tmux。

启用 tmux 后，可以同步名称、分组、排序、已读标记、非活动标记和已接管的会话。如需自定义行为，可以让 integrations.tmux.session_script 指向一个负责重命名和重新分组的脚本。该脚本接收以下形式的命令：

<script> rename <shell_pid> <group> <title>
<script> group <session_id> <old_group> <new_group>

调整侧边栏和代理工具栏

  • appearance.vertical_tabs.full_tab_menu 默认值为 true。将其设置为 false，可将标签页和分组菜单精简为必要操作。Settings > Appearance > Tabs 中也提供相同选项。
  • agents.third_party.should_render_cli_agent_toolbar 默认值为 false。将其设置为 true，可恢复 CLI 代理会话下方的上游工具栏。

禁用第三方 CLI 代理工具栏后，请通过 Claude Code 的插件市场更新用于 Claude Code 的 Warp 插件，具体方式以项目说明为准。

将 Harp 与编码代理配合使用

  1. 打开 Harp，并为 Claude Code 或 Codex 工作流创建会话。
  2. 使用 Cmd+R 重命名标签页，使其用途一目了然。
  3. 将相关会话放入命名分组，例如为每个项目创建一个分组。
  4. 查看侧边栏状态指示器，识别需要你关注、仍在工作或已经完成的会话。
  5. 暂时搁置当前不需要的会话；Harp 会用月亮图标标记它们。
  6. 准备好查看输出时，打开未读会话。

可以使用 Cmd+T、双击，或通过侧边栏空白区域的右键菜单创建新标签页。该项目有意移除了一些标签栏控件，包括搜索框、视图选项和标签页配置按钮。

接管其他位置启动的会话

如果 tmux 会话是在其他设备或终端中创建的，可以让 Harp 将其接管为一个标签页。在相应的 tmux 会话中运行：

tmux set-option @warp_adopt 1

启用 tmux 集成后，Harp 可以跟踪该会话，并在侧边栏中显示其名称、分组和状态。这对于继续通过 SSH（包括使用手机）开始的工作非常有用。

连接 Claude Code 后台任务报告

该代码库包含一个 Claude Code 钩子，可将后台任务报告给 Harp。集成说明位于 integrations/claude-code。需要在侧边栏中显示后台活动时，请按照这些说明操作。

高级开发选项

跟踪状态变化

如需针对代理记录进行回归检查，请使用 WARPOSS_STATUS_TRACE=1 启动调试版本。Harp 会将状态变化以 [status-check] 行的形式写入 ~/Library/Logs/harp.log。

不使用真实登录运行

在启动时设置 WARPOSS_SKIP_LOGIN=1，即可使用测试用户启动，并使经过身份验证的请求失败。此选项适用于不使用登录功能的自动化运行。

使用隔离的调试数据配置文件

对于调试版本，设置 WARP_DATA_PROFILE=<name>，即可将设置和数据保存在 ~/.harp-<name> 中，而不是默认的配置文件位置。

验证贡献

提交更改前，请运行代码库的预提交检查：

./script/presubmit

该命令会运行格式检查、Clippy 和测试。

结语

Harp 将 Warp 终端变成了一个用于管理多个长期运行的 Claude Code 和 Codex 会话的工作区。安装 macOS 应用或从源代码构建，需要时启用 tmux 和 limit-ring 集成，然后使用分组和状态指示器，让代理驱动的开发井然有序。Harp 是 Warp 的非官方分支，因此 Harp 特有的问题应反馈到其代码库，而不是 Warp。