Happy Coder 使用教程：用手机远程控制 Claude Code / Codex

如果你想在通勤、外出或者离开工位时，继续操作电脑上的 AI 编程会话，Happy Coder 是一个很直接的方案。

它的核心能力很简单：让手机变成你电脑上 Claude Code 或 Codex 的远程控制端。你可以在手机上查看终端输出、输入指令、确认操作，并继续推进本地项目里的任务，而不用把代码搬到云端沙箱里。

这篇文章把原始教程整理成更适合站内发布的版本，重点回答四个问题：

• Happy Coder 是什么，适合什么场景
• 电脑和手机分别要准备什么
• 怎样连接 Claude Code / Codex 并开始使用
• 如果只是短期试用，后续怎样关闭和卸载

基础认识

概述

Happy Coder 是一个免费开源工具，可以让你用手机实时连接电脑上的 Claude Code 或 Codex 会话。

• 官网：happy.engineering
• GitHub：slopus/happy
• 开源协议：MIT License
• 官方网页端：app.happy.engineering
• 项目属性：社区项目，并非 Anthropic 或 OpenAI 官方客户端

它的一个重要特点是：项目仍然运行在你自己的电脑上。手机更多像是一个远程操作窗口，而不是把代码重新托管到第三方云环境。

设备兼容性

电脑端

手机端

如果你在国区网络环境下使用，网页版通常更容易直接开始。

工作原理

Happy Coder 主要由三部分组成：

[你的电脑]                    [中继服务]                       [你的手机]
Claude Code / Codex  <->  happy CLI (加密)  <->  relay.happy.engineering  <->  Happy Coder App / Web

你可以把它理解成：

1. happy CLI 安装在电脑上，负责建立会话、转发内容和做加密处理。
2. 中继服务只负责转发，按官方说明不会直接读取你的会话内容。
3. 手机 App 或网页端负责显示会话、接收输入和推送交互。

原始资料中提到其设计目标是端到端加密，服务器侧不直接读取你的代码或指令内容。对于重视本地开发环境控制权的人来说，这是它相对更有吸引力的一点。

开始使用

环境准备

电脑端前置条件

1. 安装 Node.js 18 或更高版本

先确认本机 Node.js 版本：

node --version

输出建议为 v18.x.x 或更高。如果尚未安装，可以前往 nodejs.org 下载 LTS 版本。

2. 安装 Claude Code 或 Codex

你至少需要准备一个本地 AI CLI，Happy Coder 才有可连接的目标会话。

Claude Code：

npm install -g @anthropic-ai/claude-code

Codex：

npm install -g @openai/codex

如果两个都装了，后续可以根据项目场景自由切换。

安装与连接教程

第一步：电脑端安装 Happy Coder CLI

在电脑终端执行：

npm install -g happy-coder

安装完成后，先确认命令可用：

happy --version

第二步：手机端准备

你可以任选下面三种方式之一：

方式 A：iOS App

App Store 链接：

Happy Coder for iPhone / iPad

方式 B：Android App

在 Google Play 搜索 Happy Coder 安装即可。

方式 C：网页版

直接在手机浏览器打开 app.happy.engineering。

如果你希望更像原生 App 一样使用，也可以在 Safari 中选择“添加到主屏幕”。

第三步：连接电脑与手机

不同客户端的连接方式略有区别，但都以电脑上的 happy 命令为入口。

使用 App 扫码连接

在电脑终端运行：

happy

然后根据终端提示选择移动端配对方式。常见情况下会出现移动端 App 配对选项，终端会展示二维码，打开手机 App 扫描即可完成绑定。

不同版本的 CLI 提示文案可能略有差异。如果你本机没有单独的认证命令入口，直接运行 happy 并按提示完成配对即可。

使用网页端连接

1. 手机上先打开 app.happy.engineering
2. 电脑终端运行 happy
3. 根据终端提示选择网页连接方式
4. 终端通常会输出一个带有连接密钥的 URL
5. 在手机浏览器中打开该 URL，即可把手机和当前电脑会话绑定起来

链接格式一般类似下面这样：

https://app.happy.engineering/terminal/connect#key=xxxxxxxxxx

这里要注意一个细节：真正要打开这个链接的是手机，而不是电脑浏览器本身。

远程控制体验

连接成功后的使用教程

使用 Claude Code

进入你的项目目录后，直接运行：

cd ~/你的项目目录
happy

此时电脑上的 Claude Code 会话会同步到手机端。你可以在手机上完成这些操作：

• 输入任务，例如“帮我把这个模块拆分一下”
• 查看 AI 的回复和终端输出
• 在需要时确认或拒绝写文件、执行命令等操作

一些常见输入示例：

帮我给这个项目补单元测试
修复 src/api.js 中的 TypeError
审查 components/ 目录下的所有组件
将当前改动提交到 git，提交信息写“修复登录问题”

使用 Codex

如果你希望连接 Codex，会话入口可以这样启动：

cd ~/你的项目目录
happy codex

后续的手机端使用体验与 Claude Code 基本一致。

例如你可以直接在手机上输入：

写一个 Python 函数，解析 CSV 文件并返回字典列表
解释 utils/parser.js 的逻辑
将 main.py 中的 for 循环改成列表推导式
运行测试并修复所有失败的用例

手机端界面操作说明

连接建立后，手机端通常会包含下面几个主要区域：

同时管理多个项目

如果你经常并行处理多个仓库，可以在电脑上分别打开多个终端窗口：

# 前端项目
cd ~/projects/frontend && happy
 
# 后端项目
cd ~/projects/backend && happy codex
 
# 数据处理项目
cd ~/projects/data-pipeline && happy

手机端会把这些会话分别列出来，你可以随时切换查看。

关闭会话

如果只是结束当前连接，而不是彻底卸载 Happy Coder，通常有三种方式：

方法一：在电脑终端直接结束

找到正在运行 happy 的终端窗口，按下：

Ctrl + C

这是最直接也最稳妥的关闭方式。

方法二：在 Claude Code / Codex 内部退出

如果当前已经进入 AI 交互界面，可以尝试：

/exit

或者同样使用 Ctrl + C。

方法三：在手机端关闭会话

在会话列表中长按某个会话条目，通常可以看到关闭或删除选项。

典型使用场景

场景 1：通勤途中安排任务

离开电脑后，你仍然可以在手机上输入类似这样的任务：

帮我重构 src/components/UserForm.tsx，
提取验证逻辑为独立的 hook，
完成后提交 git

这样等你回到电脑前时，往往已经能直接查看结果。

场景 2：远程盯住长时间任务

例如测试、构建、代码生成这类会占用几十分钟的任务，手机端可以帮你持续看进度，也方便及时处理 AI 发起的确认请求。

场景 3：突然有想法时先让 AI 动起来

很多零碎想法并不需要立刻回到工位，只要电脑会话还在线，手机上就可以先把任务布置下去。

维护与排障

卸载与清理

如果你只是阶段性试用，或者想改用别的远程方案，这一节可以直接留作备忘。

卸载 CLI

npm uninstall -g happy-coder

如果你本机同时安装过新版包名 happy，也可以一并卸载：

npm uninstall -g happy

验证是否卸载成功

which happy

如果没有输出，一般就说明对应命令已经不在当前环境里了。

可选：清理本地配置

如果你还想一并删除本地授权信息和配置文件，可以再执行：

rm -rf ~/.happy

这一步会清除本机保存的配对信息，适合更换设备或彻底停用时使用。

常见问题排查

问题 1：运行 happy 后无法连接

• 先确认 Node.js 版本是否大于等于 18
• 检查当前网络能否访问中继相关域名
• 如果你在中国大陆网络环境下，优先尝试网页版并结合可用的网络代理

问题 2：网页端打开链接后提示连接失败

• 先确保手机已经正常打开 app.happy.engineering
• 再在手机浏览器中打开电脑终端生成的连接 URL
• 不要把这个 URL 直接在电脑本机浏览器里当成最终连接入口

问题 3：App 扫码后连接失败

• 确认当前终端展示的是移动端 App 的配对方式
• 检查电脑是否被防火墙或网络策略拦截了出站连接
• 关闭当前会话后重新运行 happy，再完成一次新的扫码配对

问题 4：通知没有收到

• iOS 检查通知权限是否打开
• Android 检查后台运行权限和电池优化设置

问题 5：全局安装时报错

你可以先尝试重新安装：

npm install -g happy-coder

如果本机 npm 本身较旧，也可以先升级 npm 再重试：

npm install -g npm@latest
npm install -g happy-coder

安全说明

使用时仍然建议保留工程上的基本谨慎：

• 不要把生产环境密钥随意暴露给任何自动化会话
• 公共网络环境下尽量避免处理高敏感代码或配置
• 更换手机或停用前，记得清理旧设备上的授权信息

能力与进阶

功能详解

实时双向同步

• 手机上的输入会立即发送到电脑端会话
• 电脑端的 AI 输出会同步显示到手机
• 会话上下文会延续，不需要重复建立一套新的对话环境

语音输入

如果你的手机端版本支持语音输入，可以直接点击麦克风图标，用语音下达任务。这对走路、通勤、临时记录想法会更方便。

推送通知

当 Claude Code 或 Codex 需要你确认某项操作时，手机通常会收到通知提醒。

• iOS：到系统通知设置里确认是否给 Happy Coder 开了通知权限
• Android：确认后台运行权限和电池优化策略没有把它拦掉

离线消息队列

原始资料中提到，断网期间输入的指令会排队，待网络恢复后再发送。这对移动网络不稳定的场景比较友好。

MCP 工具支持

如果你已经在本地 CLI 中配置了 MCP、Agent、斜杠命令等能力，Happy Coder 也能把这些交互继续映射到手机端。

进阶配置

自托管中继服务器

如果你对中继层有更严格的可控性要求，可以考虑自托管。原始资料给出的 Docker 示例是：

docker run -d \
  --name happy-server \
  -p 3000:3000 \
  -e NODE_ENV=production \
  -e DATABASE_URL="postgresql://用户名:密码@localhost:5432/happy-server" \
  -e REDIS_URL="redis://localhost:6379" \
  -e SEED="你的随机密钥字符串" \
  -e PORT=3005 \
  --restart unless-stopped \
  happy-server:latest

切换到自托管服务器时，可以按实际环境修改配置，例如：

happy config set server https://你的服务器地址.com
happy config set port 8443

常用配置动作

查看当前配置：

happy config list

重新配对设备：

• 删除旧的本地授权信息
• 重新运行 happy
• 按终端提示重新选择移动端连接方式

查看连接状态：

happy status

方案对比与资源

与其他方案对比

Happy Coder 最核心的差异点在于：它更像是把手机变成 Claude Code / Codex 的远程操作面板，而不是另起一套独立的 AI 环境。

资源链接