一、背景¶
问题：Claude Code 只能在电脑终端本地使用，离开电脑后无法操控或查看会话状态。
目标：通过手机 App / Web 远程启动、操控、恢复 Claude Code 会话，实现 on-the-go 场景。
二、结论¶
Happy CLI 是 Claude Code 的移动端封装，核心价值是 daemon 模式 + 手机推送 + 远程会话管理。
- 支持所有 Claude Code 原生 flags（
happy=claude+ 移动控制层） - daemon 后台常驻，可远程创建/恢复会话
- 支持 Codex、agy（Antigravity）等多 agent 模式
- 已知问题：Ink 框架在非 TTY 环境下报 raw mode 错误，需在真实终端运行
三、主要内容¶
3.1 安装与认证¶
# 安装（全局 npm 包）
npm install -g happy
# 认证（首次使用）
happy auth login # 选择 Mobile App 或 Web Browser 认证
happy auth login --force # 强制重新认证（清除凭证+machine ID+停 daemon）
happy auth status # 查看认证状态
happy auth logout # 登出
3.2 完整命令列表¶
| 命令 | 说明 |
|---|---|
happy |
启动 Claude Code 会话（移动端控制） |
happy auth |
认证管理（login/logout/status） |
happy resume <id> |
恢复之前的会话（按 Happy session ID） |
happy codex |
启动 Codex 模式 |
happy agy |
启动 agy (Antigravity CLI) 模式 |
happy acp |
启动通用 ACP 兼容 agent |
happy connect |
连接 AI 供应商 API keys 到 Happy 云端 |
happy sandbox |
配置和管理 OS 级别沙箱 |
happy notify |
发送推送通知到手机 |
happy daemon |
管理后台服务（远程启动新会话） |
happy doctor |
系统诊断和故障排查 |
3.3 Daemon 模式（核心功能）¶
daemon 是后台常驻进程，允许远程（手机 App）创建和管理会话：
happy daemon start # 启动 daemon（detached 后台运行）
happy daemon stop # 停止 daemon（已有会话保持存活）
happy daemon status # 查看 daemon 状态
happy daemon list # 列出活跃会话
状态文件：~/.happy/daemon.state.json（记录 PID、HTTP 端口、启动时间）。
3.4 Connect — 存储 API Keys¶
将 API key 加密存储到 Happy 云端，手机远程启动会话时可用：
happy connect codex # 存储 Codex API key
happy connect claude # 存储 Anthropic API key
happy connect gemini # 存储 Gemini API key
happy connect status # 查看各厂商连接状态
管理面板：https://app.happy.engineering
3.5 Notify — 推送通知¶
happy notify -p "Deployment complete!"
happy notify -p "System update" -t "Server Status" # 自定义标题
3.6 常用 Flags¶
| Flag | 说明 |
|---|---|
--yolo |
跳过权限确认（sugar for --dangerously-skip-permissions） |
--chrome |
启用 Chrome 浏览器访问 |
--no-chrome |
禁用 Chrome |
--no-sandbox |
禁用 Happy 沙箱 |
--resume |
恢复上次会话 |
--js-runtime bun |
用 bun 代替 node 启动 Claude Code |
--claude-env KEY=VAL |
设置自定义环境变量（如 API endpoint） |
3.7 Sandbox 沙箱管理¶
happy sandbox configure # 交互式配置沙箱
happy sandbox status # 查看当前配置
happy sandbox disable # 禁用沙箱
3.8 Doctor 诊断¶
happy doctor # 完整诊断（进程、日志、配置、daemon 状态）
happy doctor clean # 清理所有 happy 相关残留进程
3.9 ACP 多 Agent 模式¶
happy agy # 启动 Antigravity CLI
happy acp gemini # 通过 ACP runner 启动 Gemini
happy acp -- opencode --acp # 启动自定义 ACP 命令
happy acp opencode --verbose # 打印原始 ACP 事件
3.10 已知问题¶
- Raw mode 报错：在非 TTY 环境（管道、脚本、Claude Code
!命令）中运行交互式命令会报Raw mode is not supported。必须在真实终端中运行。 - React key 重复 warning：
Encountered two children with the same key— 这是 Happy 自身 Ink 组件的 bug，不影响功能。
3.11 文件路径¶
| 路径 | 说明 |
|---|---|
~/.happy/ |
Happy 主目录 |
~/.happy/logs/ |
日志目录 |
~/.happy/daemon.state.json |
daemon 状态文件 |
~/.happy/settings.json |
配置文件 |
四、Action¶
- 验证 daemon 远程启动会话的完整流程（手机 App → daemon → Claude Code 会话）
- 探索
happy connect claude后是否可以纯手机端完成所有操作