moshi-best-practices

Moshi 最佳实践

使用此技能，让任何主机都能轻松配合 Moshi 使用。

适用于：

• 全新设置
• 验证现有设置

Moshi 将 Herdr、tmux 和 Zellij 视为一等多路复用器。Herdr 支持已在 iOS 3.1 中推出；以下工作流功能要求 3.10 或更高版本。Agent 工作优先使用 Herdr：跳转到、聊天视图、Agents 收件箱、深层链接、双指滑动切换会话／空间／窗格，以及打开终端，都能更顺畅地跳转到 Herdr 工作区和 Agent 标签页。即使主机优先使用 Herdr，也请保留已安装的 tmux ——打包的 moshi DIR 启动器和 Moshi 的“最近目录”一键流程仍会创建 tmux 会话。如果用户已经在使用 Zellij，也支持继续使用。

规则

• 编辑前先检查。
• 优先直接编辑配置，而不是使用特定平台的设置脚本。
• 更改后验证每项结果。
• 不要安装旧版 moshi shell 助手或别名。当前安装会将同一个二进制文件作为 moshi 提供（这是 moshi-hook 的便捷别名）。
• 编码 Agent 会话优先使用 Herdr，而非 tmux。仍需保留已安装的 tmux：moshi DIR 启动器和 Moshi 的“最近目录”一键会话都会创建 tmux。若无法安装 Herdr，或者用户已经一直使用 tmux 并希望继续使用，则默认仅使用 tmux。
• 在使用 Herdr 的主机上，必须配对 moshi-hook 并运行 moshi-hook install。与 tmux 不同，Herdr 没有用于捕获 Agent 提示词的屏幕抓取回退方案，提示词只能来自钩子。

1. 主机就绪情况

首次设置 Moshi SSH/Mosh 时，如果有 moshi-hook，优先使用 轻松配对：

moshi-hook host setup
# or: moshi host setup

告知用户从 Moshi 扫描轻松配对二维码。此操作会创建已保存的主机连接、生成手机端私钥，并在主机上安装 Moshi 的公钥。说明安全边界：二维码过期前，任何扫描二维码的人都可以获得该主机的 SSH 访问权限，因此用户不应分享屏幕或设置链接。

不要将轻松配对与 moshi-hook pair --token 混淆；令牌配对仅用于 Agent 钩子、收件箱、实时活动和 Apple Watch 事件。

目标结果：

• 首选传输方式为 Mosh 加多路复用器；备用方式为 SSH（或 Pro 可用时使用 Eternal Terminal）加多路复用器
• 主机具有可用的 SSH 入口
• 已安装 Herdr（首选），并保留已安装的 tmux，供启动器／最近项目流程使用；如果已安装 Zellij，使用 Zellij 也可以
• 用户需要使用 Mosh 时，已安装 mosh-server
• 在当前 shell 和登录 shell 的非交互模式下都能解析到二进制文件
• 至少存在一个多路复用器会话，以便显示 Moshi 会话选择器
• 选择 Herdr 作为多路复用器时，已配对 moshi-hook 并安装钩子

使用少量实际检查进行检查。尽量减少特定于操作系统的操作，但不要跳过验证。

实用检查：

command -v herdr || true
command -v tmux || true
command -v zellij || true
command -v mosh-server || true
herdr session list --json 2>/dev/null || true
tmux list-sessions 2>/dev/null || true
LOGIN_SHELL="${SHELL:-/bin/sh}"
"$LOGIN_SHELL" -c 'command -v herdr'
"$LOGIN_SHELL" -c 'command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server'

相关时可使用的 macOS 特定检查：

dscl . -read "/Users/$USER" UserShell
systemsetup -getremotelogin || true

更改后验证：

command -v herdr || command -v tmux
herdr session list --json 2>/dev/null || tmux list-sessions
"$LOGIN_SHELL" -c 'command -v herdr || command -v tmux'
"$LOGIN_SHELL" -c 'command -v mosh-server' || true
moshi-hook status || true   # human output reports resolved tmux/zellij/herdr binaries; keep stderr

然后请用户从 Moshi 重新连接。预期结果：多路复用器选择器会显示（Herdr 会话／工作区和／或 tmux 会话），并且在配置后，传输方式可以使用 Mosh，而不是纯 SSH。

2. 多路复用器：优先使用 Herdr

Herdr 是一款以 Agent 为先的终端多路复用器。Moshi 对其提供一等支持（会话卡片、工作区选择器、标签页上显示 Agent 标志的“跳转到”、聊天视图、深层链接、滑动切换标签页／空间／窗格、滚动到底部、鼠标模式、Agents 收件箱复用已打开的 Herdr 会话，以及“打开终端”跳转到事件对应的 Herdr 标签页）。

**前提条件：**Moshi 中的 Herdr Agent 功能依赖已配对的 moshi-hook，并且已运行 moshi-hook install。与 tmux 不同，Herdr 没有用于捕获 Agent 提示词的屏幕抓取回退方案；钩子捕获是唯一的提示词来源。

安装

curl -fsSL https://herdr.dev/install.sh | sh
# or: brew install herdr
# or: mise use -g herdr

验证：

command -v herdr
herdr --version
"$LOGIN_SHELL" -c 'command -v herdr'

守护进程会从 PATH、Nix 配置文件目录、~/.local/bin、/opt/homebrew/bin 和 /usr/local/bin 中解析 herdr。只有在非标准位置安装时（Nix、自定义前缀），才需要设置覆盖项：

# Linux: put it in the systemd user unit
systemctl --user edit moshi-hook    # Environment=MOSHI_HERDR_PATH=/path/to/herdr
systemctl --user restart moshi-hook.service

# macOS: add MOSHI_HERDR_PATH to the brew services plist, then
brew services restart moshi-hook

运行 moshi-hook status 确认——其人类可读输出会报告守护进程可解析的 tmux、Zellij 和 Herdr 二进制文件（--json 不包含此诊断信息）。

启动项目会话

在项目所在位置启动 Herdr：

cd ~/projects/app
herdr

面向编码 Agent 的推荐布局（使用工作区／标签页，而非固定的窗口名称）：

1. 在主机上保留 一个 Herdr 会话，每个项目对应一个工作区——只有在运行单个 Herdr 会话时，Moshi 才会显示工作区以供直接连接
2. 为主 Agent、审查、测试、服务器和其他任务创建标签页
3. 让 Herdr 检测窗格中的 Agent；需要时安装相应的集成：

herdr integration install claude
herdr integration install codex
# herdr integration install --help  # full target list
# herdr integration status

只有在主机确实需要多个会话时，才使用命名会话（此时 Moshi 会显示会话列表，而不是工作区选择器）：

herdr --session app

Herdr 自带的集成和 moshi-hook install 都会写入 Agent 钩子配置（例如写入 ~/.claude/settings.json）。它们不会造成破坏，且可以共存——将 Herdr 与 Moshi 配合使用时，请同时运行两者。

完成用户侧设置后，提供 Herdr Agent 技能，让会话中的 Agent 能够操控窗格：

npx skills add ogulcancelik/herdr --skill herdr -g

使用 Herdr 的默认方式分离会话（除非重新映射，否则为 Ctrl+b q；Moshi 还提供可配置的 Herdr 前缀，包括 Opt/Alt 修饰键）。使用 herdr 或 herdr --session <name> 重新连接。

然后请用户在 Moshi 中重新连接。预期结果：Herdr 会话会出现在选择器中；如果主机只有一个会话，Moshi 可以显示工作区以供直接连接。

为什么 Moshi Agent 选择 Herdr 而非 tmux

Moshi 中的功能	Herdr	tmux
会话／空间／窗格滑动 + 跳转到	工作区、标签页、感知 Agent 的标签	窗口／窗格
Agent 收件箱 → 打开终端	重用会话，聚焦工作区 + Agent 标签页	连接会话／窗口
聊天视图／审批／粘贴图像	通过 herdr CLI 提供完整桥接（需要钩子）	通过 tmux 提供完整桥接（优先使用钩子；也支持基于屏幕／标题的回退方式）
感知 Agent 的 TUI	内置 Agent 生命周期管理 + 技能	通用窗格
打包的一次性项目启动器	在项目目录中启动 herdr	moshi DIR → tmux 会话
在应用中一键打开最近目录	—	创建 tmux 会话

默认建议：安装 Herdr，并让用户在其中开展 Agent 工作，同时保留已安装的 tmux，以支持 moshi DIR 启动器和最近目录的一键会话。

3. tmux 回退方案

Herdr 不可用或用户更喜欢 tmux 时，将 tmux 设为主要的多路复用器。即使主机优先使用 Herdr，也要保留已安装的 tmux，以支持打包的启动器和最近目录流程。

默认设置

除非用户另有要求：

set -g history-limit 100000
set -g mouse on
set -g set-titles on
set -g set-titles-string "#I: #W"
set -g base-index 1
setw -g pane-base-index 1
set -g renumber-windows on

工作流：

• 检查现有的 tmux 配置
• 更新相互冲突的设置，而不是追加重复项
• 编辑后重新加载 tmux

项目会话（moshi DIR）

通过 Homebrew 或 install.sh 安装 moshi-hook 后，打包的启动器仍以 tmux 为目标：

moshi .
moshi ~/projects/app

它会解析目录，并根据目录的基本名称命名 tmux 会话（基本名称中的 : 会变成 _）。在 tmux 外部，它会执行 tmux new-session -A -s <name> -c <dir>（不会有 Moshi 包装进程继续运行）。如果已在 tmux 中，则会在需要时以分离模式创建会话，然后切换到该会话，而不是执行 exec。

手动创建新会话时：

• 读取当前工作目录
• 简洁地询问一个问题：会话是否应从此处启动？
• 如果答案是否定的，则询问目录
• 将会话名称默认为目录的基本名称
• 以分离模式创建会话
• 对每个初始窗口使用所选目录，命令格式为 tmux ... -c <dir>

推荐的窗口：

1. agent
2. review
3. tests
4. servers
5. misc

然后请用户在 Moshi 中重新连接。预期结果：会话会显示在 tmux 选择器中。

Enterprise Linux 10 说明

某些 RHEL/Alma/Rocky 10 的 tmux-3.3a-12 至 3.3a-14 RPM 会在执行 capture-pane 时损坏服务器。不要只相信 tmux -V（受影响的构建可能会报告 next-3.4）。检查软件包：

rpm -q tmux

对于这些构建，Moshi 会自动禁用所有 capture-pane 功能，而不是静默失败；基于 hook、标题和转录文本的状态功能仍可使用。在这些主机上优先使用 Herdr，或安装上游 tmux 3.5a+，并在替换二进制文件后重启 tmux 服务器。完整版本范围请参阅 app-hook/docs/usage.md。

4. MOSHI_CLIENT 信号

MOSHI_CLIENT=1 是一个选择启用的环境变量，由 Moshi 客户端导出到远程 shell，以便 rc 文件、提示词和多路复用器配置能够检测由 Moshi 启动的会话并进行相应调整。用户可在应用的 Settings → Integrations → Shell → Export ENV 中启用此功能（默认关闭；启用需要 Pro；禁用后仍可免费使用）。启用后，该变量在 Mosh 路径（通过 mosh-server -l MOSHI_CLIENT=1）和 SSH 回退路径（在 shell 启动时注入 export）中设置方式相同。

一个常见用途是在 Moshi 下让 tmux 状态栏处理保持可预测。Moshi 会清除其启动的会话中的 status-right，但自定义主题仍可能重新填充 status-left / status-right，从而与之冲突。在设置了 MOSHI_CLIENT 时有条件地清除这些选项，可保留本地主题，同时让 Moshi 的状态栏处理保持可预测。其他用途：使用更窄的提示符、移除 nerd-font 字形、采用不同的按键绑定。

Shell（在用户的 rc 文件中）：

if [ -n "$MOSHI_CLIENT" ]; then
  # running under Moshi — trim prompts, skip heavy glyphs, etc.
fi

tmux（在 ~/.tmux.conf 中）：

# propagate the variable into tmux sessions attached by this shell
set-option -ga update-environment " MOSHI_CLIENT"

# keep status regions clean for Moshi clients when a theme would repopulate them
if-shell '[ -n "$MOSHI_CLIENT" ]' {
  set -g status-left ''
  set -g status-right ''
}

编辑后，重新加载 tmux（tmux source-file ~/.tmux.conf）。

用户开启该设置并从 Moshi 重新连接后，验证：

echo "$MOSHI_CLIENT"                       # expect: 1
tmux show-environment | grep MOSHI_CLIENT  # expect a value in new sessions (tmux only)

如果 echo 没有输出任何内容，说明应用中的开关处于关闭状态——修改主机配置前请先向用户确认。该变量只会出现在开关切换后打开的会话中。

5. Agent Hooks（moshi-hook）

Moshi 使用 moshi-hook（单数形式），这是一个可移植的 Go 守护进程。该守护进程会与 Moshi 保持持久 WebSocket 连接，因此审批是双向的——用户可以通过 iOS 实时活动或 Apple Watch 批准或拒绝工具调用，并将结果返回给 Agent。一次安装即可支持多个 Agent。

在 Herdr 上，本节是必需的，而非可选项：Moshi 中的交互式提示和 Agent 状态只能通过 hooks 获取。

支持的 hook 目标（截至当前版本的 moshi-hook install）：Claude Code、Codex CLI、OpenCode、Gemini CLI、Antigravity、Cursor、Kimi、Qwen Code、Grok Build、OMP（Oh My Pi）、Pi 和 Hermes Agent。如果 hooks 和对话记录运行正常，Moshi Pro 中的聊天视图也会显示其中一些工具（包括 Grok、Kimi、Pi/OMP、OpenCode、Codex）。

除非用户明确要求手动编辑，否则请使用 moshi-hook / moshi，不要手动编写配置。

通过 Homebrew tap（macOS）安装，然后配对并安装 hooks：

brew tap rjyo/moshi
brew install moshi-hook
moshi-hook pair --token <YOUR_TOKEN>   # token comes from the Moshi mobile app
moshi-hook install                     # writes hook configs for installed agents
brew services start moshi-hook         # keeps the daemon alive across reboots

Linux / 手动安装：

curl -fsSL https://getmoshi.app/install.sh | sh
moshi-hook pair --token <YOUR_TOKEN>
moshi-hook install
moshi-hook service install             # systemd user unit

如果 Easy Pair 已运行 host setup，守护进程通常已在该流程中完成配对；仍需运行 moshi-hook install，以便 Agent 配置指向该守护进程。

在 macOS 上，moshi-hook pair 默认使用 Keychain。如果通过 SSH 配对失败是因为 Keychain 已锁定或不可用，请优先选择以下明确指定的方式之一：

security unlock-keychain ~/Library/Keychains/login.keychain-db
moshi-hook pair --token <YOUR_TOKEN>

对于不希望或无法可靠使用 Keychain 的无头主机：

moshi-hook pair --token <YOUR_TOKEN> --store file

--store file 会将主机密钥写入 ~/.config/moshi/secrets.json，并设置 0600 权限；它还会记住此存储选项，供后续的 serve、status、usage --sync 和 pair 命令使用。不要默默使用此选项；请明确说明这会将密钥存储在 Keychain 之外。

moshi-hook install 采用非破坏性安装方式——它会将 Moshi 条目写入找到的 Agent 配置中（例如 ~/.claude/settings.json、~/.codex/config.toml、OpenCode 插件、Grok hooks、Pi/OMP 扩展、Hermes 插件），并保留用户自有的 hooks。如果未找到某些 Agent，默认会跳过；除非使用 --target 强制指定目标。若两者同时存在，它可以与 herdr integration install … 共存。

实用的配套命令：

moshi-hook status              # pairing, socket, WS, resolved tmux/zellij/herdr binaries
moshi-hook logs -f             # tail the daemon log
moshi-hook usage --sync        # push Claude / Codex / OpenCode / Kimi / Grok usage
moshi diff .                   # local git diff viewer (host gateway)
moshi-hook servers             # discover local web servers for in-app browser / serve-sim

验证：

moshi-hook status
moshi-hook logs -f

然后运行一个简短的真实 Agent 任务，确认 Moshi 收到了推送通知或实时活动更新，并且从实时活动 / Watch 批准后，Agent 可以继续运行。在 Herdr 主机上，还要确认点击“Agents → Open Terminal”会聚焦到正确的工作区/标签页。

如需完整 CLI 参考（包括所有子命令、标志、环境变量和路径），请参阅 monorepo 中的 app-hook/docs/usage.md，或 rjyo/homebrew-moshi tap 中的镜像文档。

6. 快速验证清单

设置完成后，主机应满足以下条件：

1. Easy Pair 或 SSH 密钥可用；从 Moshi 重新连接成功
2. 存在 mosh-server 时优先使用 Mosh
3. 对于登录时的非交互式 shell，Herdr（首选）、tmux 或 Zellij 位于 PATH 中——即使 Herdr 是主要工具，也要保留 tmux
4. 选择器至少有一个 Herdr 会话/工作区、tmux 会话或 Zellij 会话
5. moshi-hook status 显示已配对且已连接；当前使用的 Agent 已安装 hooks（选择 Herdr 作为复用器时必需）
6. 可选：仅当守护进程无法解析非标准 Herdr 安装位置时，才设置 MOSHI_HERDR_PATH
7. 可选：仅当用户启用了 Export ENV（Pro）且需要调整 rc/tmux 时，才设置 MOSHI_CLIENT