Happy-Code 服务部署与说明文档

1. Happy-Code 的作用

Happy Coder（happy-coder）是面向 Claude Code 的第三方工具，用于建立远程加密通道，让你在离开电脑时仍可通过手机（iOS/Android）查看状态、继续对话并控制本机会话。

一句话概括：Happy Coder = Claude Code 的手机远程控制端 + 状态监控通道。

2. 核心功能

跨设备接力：电脑启动会话后，可在手机端无缝接管。
实时通知：任务完成、报错、权限确认等事件可推送到手机。
端到端加密：传输链路加密，降低中间链路明文暴露风险。
语音交互支持：移动端可语音下达指令。
会话历史同步：终端关闭后仍可在手机端查看历史。

3. 官方 Quick Start 要点（整理）

参考：https://happy.engineering/docs/quick-start/

3.1 下载客户端

iPhone/iPad：App Store
Android：Google Play
Web App：https://app.happy.engineering

3.2 安装 CLI

npm install -g happy-coder

3.3 运行要求

Node.js 18+
官方说明依赖了较新的 ESM / fetch 等能力与相关依赖版本。

3.4 手机与本机配对

happy --auth

执行后显示二维码，使用手机 App 扫码完成绑定。

3.5 首次使用

配对成功后，即可在手机端发起会话并远程使用本机 Claude Code。

4. `happy daemon` 子命令说明

happy daemon 用于以后台常驻方式管理 Happy 与会话连接，适合远程控制和长期运行场景。

4.1 `happy daemon start`

启动守护进程，建立手机端与本机会话的后台桥接。
适合服务器/远程主机长期运行。

4.2 `happy daemon stop`

停止守护进程。
用于重启服务、升级工具或临时释放资源。

4.3 `happy daemon status`

查看守护进程是否运行。
常用于排查手机端断连问题。

4.4 `happy daemon list`

列出当前活动会话。
适合多项目并行时确认哪些会话仍在运行。

4.5 `happy doctor clean`（维护命令）

用于异常状态下的清理（如卡死、残留进程、端口占用）。
建议仅在常规 stop/restart 无效时使用。

5. 环境要求（systemd 部署）

Linux（支持 systemd --user）
已安装 Happy CLI（happy 命令可用）
已安装并可正常使用 Claude Code
首次初始化阶段建议具备稳定网络

6. 服务部署（systemd –user）

将以下内容保存为：~/.config/systemd/user/happy-code.service

[Unit]
Description=Happy Code Assistant (user service)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/home/dev
ExecStart=/usr/local/bin/happy daemon start-sync
#Environment="http_proxy=socks5://192.168.114.9:7890"
#Environment="https_proxy=socks5://192.168.114.9:7890"
#Environment="all_proxy=socks5://192.168.114.9:7890"
#Environment="HTTP_PROXY=socks5://192.168.114.9:7890"
#Environment="HTTPS_PROXY=socks5://192.168.114.9:7890"
#Environment="ALL_PROXY=socks5://192.168.114.9:7890"
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

WorkingDirectory 请替换为你的实际工作目录。

6.1 启用与启动

systemctl --user daemon-reload
systemctl --user enable happy-code.service
systemctl --user start happy-code.service

6.2 无需登录自动启动（开机自启）

若希望在用户未登录图形会话时，systemd --user 服务仍可自动启动，需要开启 linger：

sudo loginctl enable-linger dev
loginctl show-user dev -p Linger

预期输出：Linger=yes。

7. 运行验证

systemctl --user is-enabled happy-code.service
systemctl --user status happy-code.service --no-pager
loginctl show-user dev -p Linger
happy daemon status

预期结果：

is-enabled 输出 enabled
happy-code.service 为 active (running)
Linger=yes
happy daemon status 显示守护进程健康

7.1 当前配置检查结果（本机）

用户：dev
happy-code.service：enabled
运行状态：active (running)
Linger：yes（满足“无需登录自动启动”条件）

8. 常用运维命令

# 查看服务状态
systemctl --user status happy-code.service --no-pager

# 查看近期日志
journalctl --user -u happy-code.service -n 100 --no-pager -o short-iso

# 重启服务
systemctl --user restart happy-code.service

# 停止服务
systemctl --user stop happy-code.service

9. 注意事项

ExecStart 建议使用 daemon 常驻模式：
- ✅ 推荐：/usr/local/bin/happy daemon start-sync
- ⚠️ 仅 happy 前台方式不适合 systemd 常驻托管
若日志出现以下报错，优先检查是否使用了正确的 daemon 启动方式：
- Error: protocol mismatch
- Error: Input must be provided either through stdin or as a prompt argument when using --print
修改 service 文件后必须执行：
- systemctl --user daemon-reload
需要代理时再启用 Environment 代理变量，避免无效代理导致连接异常。

10. 参考链接

Quick Start: https://happy.engineering/docs/quick-start/
Docs Home: https://happy.engineering/docs/
FAQ: https://happy.engineering/docs/faq/
Features: https://happy.engineering/docs/features/

1. Happy-Code 的作用#

2. 核心功能#

3. 官方 Quick Start 要点（整理）#

3.1 下载客户端#

3.2 安装 CLI#

3.3 运行要求#

3.4 手机与本机配对#

3.5 首次使用#

4. happy daemon 子命令说明#

4.1 happy daemon start#

4.2 happy daemon stop#

4.3 happy daemon status#

4.4 happy daemon list#

4.5 happy doctor clean（维护命令）#

5. 环境要求（systemd 部署）#

6. 服务部署（systemd –user）#

6.1 启用与启动#

6.2 无需登录自动启动（开机自启）#

7. 运行验证#

7.1 当前配置检查结果（本机）#

8. 常用运维命令#

9. 注意事项#

10. 参考链接#