Install Mimi Remote

安装与维护 Mimi Remote

目标

把 Mimi Remote 安装成一个可验证、可恢复、权限最小化的本地闭环：

1. 在普通 macOS 用户场景中优先使用已签名、公证且内嵌 agentd 的 Mimi Remote Mac 菜单栏 App。
2. 通过 Tailscale 或同一局域网连接 iPhone / iPad，不部署公网中继。
3. 保持 Codex 为默认稳定 Runtime，仅在用户明确要求时启用 Claude Code 实验通道。
4. 保留现有配置、Token、Runtime 凭证、配对关系和源码改动。

Mimi Remote 是第三方开源客户端，不是 OpenAI、Anthropic 或 Tailscale 的官方产品。项目代码、Codex / Claude 凭证和完整会话继续留在用户自己的设备上。

执行原则

• 先执行只读检查，再安装或修改；复用已有安装，不重复初始化。
• 优先使用正式 Release，不把开发分支、未固定 commit、snapshot 或 devel 二进制当作稳定版本。
• macOS 普通用户默认安装 Mimi-Remote-Mac.dmg；Homebrew 只用于命令行、服务器、自动化、旧安装维护或故障恢复。
• 不假设本 Skill 所在目录或调用时的当前目录就是源码仓库。源码和正式产物统一从 https://github.com/gaixianggeng/mimi-remote 获取。
• 不覆盖有未提交改动的源码目录，不在现有脏工作树中切换 tag 或执行清理。
• 不使用 agentd setup --force，除非用户明确要求轮换凭据并接受现有配对失效。
• 不输出、转述、上传或写入任务总结中的长期 Token、Authorization header、连接链接、二维码内容、完整 Endpoint、Tailscale IP 或私有项目路径。
• 不把 agentd 暴露到公网，不自动配置端口转发、反向代理或公网 Tunnel。
• 不通过关闭审批、设置 danger-full-access、启用 CLAUDE_BRIDGE_BYPASS_PERMISSIONS 或自动重试写操作来解决 Runtime 问题。
• 不运行 tccutil reset。macOS 文件权限、登录项审批和签名信任必须由用户在系统界面确认。
• Linux 安装和服务操作使用普通登录用户，不使用 sudo 运行安装脚本。
• 只有用户明确要求 Claude Code 时才启用该 Runtime；Claude 失败不能破坏 Codex 主通道或轮换现有 Token。
• 升级、回滚或卸载前阅读 安装、升级与回滚。
• Claude 相关操作前阅读 Claude bridge 架构。
• iOS 构建、签名或真机部署前阅读 iOS 开发说明。

确定操作范围

选择能完成用户目标的最小路径：

• macOS App 安装：下载 DMG，在菜单栏 App 内完成设置、配对、诊断和服务管理。这是默认路径。
• Homebrew 后端：只维护命令行 agentd，用于服务器、自动化、旧安装或恢复。
• Linux 后端：安装 Release 归档中的 agentd 和 user-systemd service。
• iOS 源码构建：仅在用户需要安装当前未公开上架的 iPhone/iPad App 或开发客户端时执行。
• Runtime 维护：检查 Codex，或显式启用、升级、诊断 Claude Code。
• 维护操作：对现有安装执行迁移、升级、回滚或卸载，不重新生成 Token。

只询问会改变结果的信息：

1. 要授权的最小项目扫描根目录。
2. 目标是 Mac App、CLI/Linux 后端、iOS 构建还是 Runtime 配置。
3. 是否明确需要 Claude Code；未说明时只配置 Codex。
4. 是否存在需要由 Mac App 接管的 Homebrew 服务。
5. 用户要求固定版本时使用哪个 tag；未指定时选择最新正式 Release，并在修改前告知版本。

执行预检

先执行不修改系统的检查：

uname -s
uname -m
id -u
command -v git
command -v codex
codex --version
codex app-server --help

确认 Codex CLI 已安装并登录。不要读取、复制或展示 Codex 凭证。若缺失，使用 OpenAI 当前官方安装说明，不凭记忆拼接安装命令。

确认 Mac 与移动设备位于同一私有网络。跨网络优先使用同一 Tailnet；同一局域网可以不安装 Tailscale。tailscale CLI 不在 PATH 时，允许用户通过 Tailscale App 确认状态。

macOS App 路径只要求 macOS 15 或更高版本和 Codex CLI；不要求 Homebrew、Go、Rust、Xcode 或 XcodeGen。仅在源码构建时检查相应工具链。

用户明确要求 Claude Code 时再检查：

command -v claude
claude --version

让用户在 Mac 本机确认 Claude Code 已登录。不要读取、复制或展示 Claude 凭证文件、Keychain 内容或 OAuth Token。

安装 Mimi Remote Mac

使用 gaixianggeng/mimi-remote 的最新正式 Release；用户指定版本时固定到对应 tag。下载：

Mimi-Remote-Mac.dmg
Mimi-Remote-Mac.dmg.sha256

在同一目录严格校验：

shasum -a 256 -c Mimi-Remote-Mac.dmg.sha256

校验失败时停止，不打开 DMG。让用户完成必须的人机操作：

1. 打开 DMG，把 Mimi Remote Mac 拖到“应用程序”。
2. 首次打开 App，在菜单栏进入设置。
3. 选择最小代码扫描根目录并启动服务。
4. macOS 显示登录项或文件访问审批时，在系统设置中确认；不要绕过。

App 内已包含 agentd 和兼容的 alleycat-claude-bridge，普通安装不需要 Homebrew 或单独 cargo install。

若检测到 homebrew.mxcl.mimi-remote：

1. 保持旧服务运行，不要先手工停止。
2. 在 Mac App 中执行接管，让 App 先跑 Doctor、停止 Homebrew service、注册内嵌 LaunchAgent 并等待就绪。
3. 接管失败时确认 App 已尝试恢复 Homebrew；不要让两个服务同时抢占端口。
4. 迁移成功后保留原配置、Token 和配对关系。

macOS App 安装成功必须满足：

• 菜单栏显示服务就绪且 owner 为 Mimi Remote Mac。
• App 中的版本、Endpoint 和 Doctor 状态可读取。
• 登录启动状态符合用户选择。
• 配对页能生成短期二维码。

安装 Homebrew 后端

仅在用户选择 CLI、服务器、自动化、旧安装维护或恢复时使用：

brew update
brew install gaixianggeng/tap/mimi-remote
agentd version

普通修复不要无条件升级。首次初始化通过 Agent 或自动化执行时必须隐藏配对信息，并使用用户确认的最小目录：

agentd up --no-pair \
  --scan-root "/absolute/path/to/projects" \
  --browse-root "/absolute/path/to/projects"
agentd status --json | grep -E '"(process_ok|service_ok|doctor_ok)"'
agentd doctor

只以 service_ok=true 作为成功条件。process_ok=true 只表示 HTTP 进程存活。

从当前 agentd 托管的远程任务重启时使用：

agentd restart --no-pair

不要执行 brew services restart mimi-remote，避免旧服务退出后无法完成启动步骤。

安装 Linux 后端

使用 gaixianggeng/mimi-remote 的正式 Release，不从开发工作树安装 devel 二进制。根据架构选择归档：

mimi-remote_VERSION_linux_amd64.tar.gz
mimi-remote_VERSION_linux_arm64.tar.gz

下载目标归档和同一 Release 的 checksums.txt，严格校验 SHA-256 后解压。在 Release 根目录执行：

bash ./scripts/install-linux.sh install

安装器会原子维护：

~/.local/bin/agentd
~/.config/systemd/user/mimi-remote.service
~/.local/share/mimi-remote/install-linux.sh
~/.config/mimi-remote/

不设置非默认 AGENTD_CONFIG，不在自定义 XDG_CONFIG_HOME 下套用固定模板。使用绝对路径验收：

"$HOME/.local/bin/agentd" status --json | grep -E '"(process_ok|service_ok|doctor_ok)"'
"$HOME/.local/bin/agentd" doctor

构建 iOS/iPadOS App

仅在 macOS、Xcode 26 或更高版本、iOS 26 SDK 和 XcodeGen 可用时继续。确认当前目录是完整且干净的源码仓库；否则克隆到用户确认的新目录，并优先检出与后端匹配的正式 tag。

xcodegen generate \
  --spec ios/MimiRemote/project.yml \
  --project ios/MimiRemote

bash ./scripts/ios-dev.sh build-for-testing

open ios/MimiRemote/MimiRemote.xcodeproj

测试构建始终使用统一脚本固定的 M5 Simulator。需要人工安装到真机时，让用户在 Xcode 中选择自己的 Development Team、已信任真机和 MimiRemote scheme；不要替用户选择未知 Team，不导出或上传签名证书，不关闭代码签名。日常命令行部署必须使用 bash ./scripts/ios-dev.sh run。

完成配对与验收

Mac App 安装从菜单栏选择“配对设备…”。CLI/Linux 安装让用户在不会进入 Agent 日志的本机 Terminal 执行：

agentd pair --qr-only

Linux 使用 "$HOME/.local/bin/agentd" pair --qr-only。

短期 Pair 链接是单次兑换票据，不直接包含长期 Token。失败、过期或已使用时重新生成；扫码不可用时才使用高级手动连接，不让用户把 Token 粘贴到模型对话中。

至少验证：

1. iOS App 能显示当前 Mac 和 agentd 版本。
2. App 能加载已授权项目列表。
3. App 能打开已有 Codex 会话或创建最小测试会话。
4. 用户启用 Claude 时，Runtime 选择器能显示 Claude，并能创建最小只读测试会话。
5. 断网后不重复提交写操作；恢复连接后会话能通过事件 replay 或权威历史恢复。

前三项完成后才判定基础安装成功；Claude 验收失败不能推翻已通过的 Codex 主通道。