---
access: pub
create: 2026-07-31
update: 2026-07-31
author: thinkycx
title: Happy CLI 使用指南 — Claude Code 移动端远程控制
description: Happy CLI 是 Claude Code 的移动端/远程控制封装，支持通过手机 App 或浏览器远程操控 Claude Code 会话。本文整理了全部命令、常用 flags 和 daemon 模式的用法。
category: workflow
tags: [claude-code, happy-cli, remote-control, tools, pub]
keywords: [happy, claude-code, daemon, mobile, remote, codex, agy]
refs:
  - https://happy.engineering/
  - https://github.com/slopus/happy-cli/issues
---

# Happy CLI 使用指南 — Claude Code 移动端远程控制

## 一、背景

问题：Claude Code 只能在电脑终端本地使用，离开电脑后无法操控或查看会话状态。

目标：通过手机 App / Web 远程启动、操控、恢复 Claude Code 会话，实现 on-the-go 场景。

## 二、结论

**Happy CLI 是 Claude Code 的移动端封装，核心价值是 daemon 模式 + 手机推送 + 远程会话管理。**

1. 支持所有 Claude Code 原生 flags（`happy` = `claude` + 移动控制层）
2. daemon 后台常驻，可远程创建/恢复会话
3. 支持 Codex、agy（Antigravity）等多 agent 模式
4. 已知问题：Ink 框架在非 TTY 环境下报 raw mode 错误，需在真实终端运行

## 三、主要内容

### 3.1 安装与认证

```bash
# 安装（全局 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）创建和管理会话：

```bash
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 云端，手机远程启动会话时可用：

```bash
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 — 推送通知

```bash
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 沙箱管理

```bash
happy sandbox configure  # 交互式配置沙箱
happy sandbox status     # 查看当前配置
happy sandbox disable    # 禁用沙箱
```

### 3.8 Doctor 诊断

```bash
happy doctor        # 完整诊断（进程、日志、配置、daemon 状态）
happy doctor clean  # 清理所有 happy 相关残留进程
```

### 3.9 ACP 多 Agent 模式

```bash
happy agy                         # 启动 Antigravity CLI
happy acp gemini                  # 通过 ACP runner 启动 Gemini
happy acp -- opencode --acp       # 启动自定义 ACP 命令
happy acp opencode --verbose      # 打印原始 ACP 事件
```

### 3.10 已知问题

1. **Raw mode 报错**：在非 TTY 环境（管道、脚本、Claude Code `!` 命令）中运行交互式命令会报 `Raw mode is not supported`。必须在真实终端中运行。
2. **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` 后是否可以纯手机端完成所有操作

## 参考链接

- [Happy CLI 官网](https://happy.engineering/)
- [Happy CLI GitHub Issues](https://github.com/slopus/happy-cli/issues)
- [Ink Raw Mode 文档](https://github.com/vadimdemedes/ink/#israwmodesupported)