# @buzzni/happy-cli 中文文档

规范地址：https://npmcn.com/package/%40buzzni/happy-cli/

版本：1\.1\.10-aplus\.402
npm 元数据更新时间：2026-11-08T15:39:47.626Z
中文译文更新时间：2026-11-08T20:49:38.330Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40buzzni/happy-cli
原文对照：https://npmcn.com/package/%40buzzni/happy-cli/?lang=original
项目主页：https://github.com/buzzni/happy
源码仓库：https://github.com/buzzni/happy

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：140 MB，1352 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：42 个
- 首次发布：2026-07-20T09:27:36.729Z
- 最新版本发布：2026-11-08T15:39:47.313Z
- 近 30 天下载量：54987（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：336（近 12 个月 336 个）

## 中文简介

A+ Dev Studio分叉 slopus/happy. 中国植物物种信息数据库. Claude Code和Codex的移动和网络客户端.

## 安装

```sh
npm install @buzzni/happy-cli
```

也可以使用：`pnpm add @buzzni/happy-cli`、`yarn add @buzzni/happy-cli`、`bun add @buzzni/happy-cli`

## README

# 快乐

运行的代码——从您的手机,浏览器或终端控制AI编码代理.

免费 开源 暗号任何地方.

## 安装

```bash
npm install -g happy
```

安装或更新 Happy 还安装了两个伴行的 CLI 证书 运行时间驱动器 : `codex-multi-auth` 进入 npm 的全局前缀 `happy` 本身,和 `saycode-claude-swap` 以 uv 安装,将 `claude-swap` 财务报告和审定财务报表 `cswap` 命令在 uv 的工具 bin 目录中 —— 快乐在那里寻找它们甚至 当目录不在时 `PATH`。两者都安装在准确的 快乐的版本需要而不是最新的 因为快乐检查这些 如果发现其他东西,则重新安装自己的被封存副本。 设定 `HAPPY_SKIP_COMPANION_TOOLS=1` 跳过此步骤; Happy 安装任一 当它需要的时候需要它。 快乐的安装也不可能失败 `npm`编号 :`uv` 或安装失败只是警告.

> 迁出 `happy-coder` 软件包。 感谢 [@franciscop (英语)](https://github.com/franciscop) 捐赠 `happy` 软件包名称 !

## 使用量

### Claude 代码( 默认)

```bash
happy
# or
happy claude
```

这将:

1.  启动 Claude 代码会话
2.  显示要从移动设备或浏览器连接的 QR 代码
3.  允许实时会话控制——所有通信都是端到端加密的
4.  计算机在线时直接从手机或网络启动新会话

### 更多探员

```
happy codex
happy gemini
happy openclaw

# or any ACP-compatible CLI
happy acp opencode
happy acp -- custom-agent --flag
```

## 守护进程

守护进程是一个背景服务, 它继续运行在您的机器上 。 它让你可以远程地——从你的手机或网络应用——培育和管理编码会话,而不需要开放的终端.

```bash
happy daemon start
happy daemon stop
happy daemon status
happy daemon list
```

运行时自动启动守护进程 `happy`,所以你通常不需要手动管理.

### 不停地让守护进程穿越反弹

如果你想让守护进程在重启后自动回来——而不打开 `happy` 会话第一——从您 shell 配置开始, 从而继承您正常的用户会话上下文( PATH, keychain access, OAuth certain):

```bash
# ~/.zshrc or ~/.bashrc
if [[ -o interactive ]] && [[ -z "$HAPPY_DAEMON_CHECKED" ]]; then
    export HAPPY_DAEMON_CHECKED=1
    () {
        local state=$HOME/.happy/daemon.state.json
        local pid=$(grep -oE '"pid"[[:space:]]*:[[:space:]]*[0-9]+' "$state" 2>/dev/null | grep -oE '[0-9]+')
        if [[ -z "$pid" ]] || ! kill -0 "$pid" 2>/dev/null; then
            happy daemon start >/dev/null 2>&1
        fi
    } &!
fi
```

重启后的第一个交互 shell会触发启动;后续的贝壳会因为守护进程已经运行而短路.

> **macOS 用户 :** 宁可采用这种外壳闪电法,而不是 `launchd` 发射特工 一个启动代理运行在一个代理域,即 **从您的 GUI/ Aqua 登录会话中脱离**,这意味着捆绑 `claude-agent-sdk` 无法到达 macOS 密钥链并默默地失败认证( “ 未能认证 ” ) 。 API 错误: 401 终止,", `duration_api_ms: 0`) (中文(简体) ). 如果您必须使用已发射的, 您的包装必须读取 OAuth 访问符 `~/.claude/.credentials.json` 并导出为 `CLAUDE_CODE_OAUTH_TOKEN` 在执行守护进程之前,你需要自己处理符号旋转.

## 认证

```bash
happy auth login
happy auth logout
```

Happy使用密码密钥对进行认证——你的私人密钥留在你的机器上. 所有会话数据在离开设备前都会加密 .

要连接第三方代理 API :

```bash
happy connect gemini
happy connect claude
happy connect codex
happy connect status
```

## 图标

| 命令 | 说明 |
| --- | --- |
| `happy` | 启动 Claude 代码会话( 默认) |
| `happy codex` | 开始代码模式 |
| `happy gemini` | 开始双子体 CLI 会话 |
| `happy openclaw` | 开始 OpenClaw 会话 |
| `happy acp` | 启动任何 ACP 兼容剂 |
| `happy resume <id>` | 恢复上届会议 |
| `happy agent <verb>` | 让人工智能人员检查并控制自有儿童会议 |
| `happy notify` | 向设备发送按键通知 |
| `happy doctor` | 诊断和解决问题 |

### 代理指挥

`@buzzni/happy-cli` 包括精确的相容性 `@buzzni/saycode-cli` 运行时间,所以乐乐开始的会话可以使用 `happy agent` 没有单独的 Saycode CLI安装. 此命令用于在 A 内部运行的 AI 代理 Happy/Saycode会话; 它在该会话环境外关闭失败 .

所支持的动词包括能力发现和自有儿童生命周期 操作,例如 `whoami`, (中文(简体) ), `ls`, (中文(简体) ), `spawn`, (中文(简体) ), `prompt`, (中文(简体) ), `steer`, (中文(简体) ), `stop`, (中文(简体) ), `read`, (中文(简体) ), 财务报告和审定财务报表 `wait`运行 `happy agent --help` 用于当前机器可读合同. 乐乐故意不安装顶层 `saycode` 二进制,所以 独立安装的 Saycode CLI 仍然未受影响.

* * *

## 高级

### 环境变量

| 变量 | 说明 |
| --- | --- |
| `HAPPY_SERVER_URL` | 自定义服务器 URL( 默认 ): `https://api.cluster-fluster.com`(中文(简体) ) |
| `HAPPY_WEBAPP_URL` | 自定义网络应用 URL( 默认 ): `https://app.happy.engineering`(中文(简体) ) |
| `HAPPY_HOME_DIR` | 自定义 Happy 数据的主目录( 默认 ): `~/.happy`(中文(简体) ) |
| `HAPPY_DISABLE_CAFFEINATE` | 禁用 MacOS 睡眠预防 |
| `HAPPY_EXPERIMENTAL` | 启用实验特性 |

### 沙盒(实验)

Happy可以在OS级沙盒内运行代理,以限制文件系统和网络访问.

```bash
happy sandbox configure
happy sandbox status
happy sandbox disable
```

### 从源头建楼

```bash
git clone https://github.com/slopus/happy
cd happy-cli
yarn install
yarn workspace happy cli --help
```

## 所需资源

-   节点.js >= 20.0.0
-   克劳德: `claude` 已安装的 CLI 登录( L)
-   对于代码 : `codex` 已安装的 CLI 登录( L)
-   对于双子座: `npm install -g @google/gemini-cli` + 键 `happy connect gemini`

## 解决问题

### `Cannot find package '@slopus/happy-wire'`

症状 :

```text
Error [ERR_MODULE_NOT_FOUND]: Cannot find package '@slopus/happy-wire'
```

原因: 源包使用工作空间依赖性 `@slopus/happy-wire: file:../happy-wire`。安装或连接源 目录可以在没有运行时间的情况下直接离开全局软件包 依赖性.

从此检出中修正 :

```bash
# from the aplus-dev-studio repo root
cd vendor/happy/packages/happy-cli
corepack pnpm run cli:install
```

避免 `npm install -g .` 财务报告和审定财务报表 `npm link` 用于守护进程运行时间安装 。 供出版 工作,先准备一个干净的包裹并守护它:

```bash
tmp=$(mktemp -d)
corepack pnpm run build
node scripts/prepare-publish-package.cjs --out "$tmp/package"
node scripts/guard-publish-artifact.cjs "$tmp/package" --install-smoke
```

### 远程终端 - `posix_spawnp failed.` 在 macOS 上显示

症状(web-ui "Q" tab QQ守护进程日志):

```
[REMOTE-TERMINAL] terminal-open-fwd spawn failed: posix_spawnp failed.
```

原因: npm 提取 `node-pty/prebuilds/darwin-{arm64,x64}/spawn-helper` 不包含可执行文件位( n)`0o644`所以马科斯 `posix_spawnp` 拒绝 改为 `execve()` 这个 Linux 用户 `forkpty + execvp` 且不受影响.

**自动修复**: 运入 `@namsangboy/happy-cli@1.1.4-aplus.9+` —— 说 postinstall在macOS上翻转了该位. 只是升级:

```bash
npm i -g @buzzni/happy-cli@latest
happy daemon stop && happy daemon start
```

**手动修补(旧版)**数字 :

```bash
chmod +x $(npm root -g)/@buzzni/happy-cli/node_modules/node-pty/prebuilds/darwin-arm64/spawn-helper
chmod +x $(npm root -g)/@buzzni/happy-cli/node_modules/node-pty/prebuilds/darwin-x64/spawn-helper
happy daemon stop && happy daemon start
```

**或者从源头重建** (同样可行,但需要Xcode CLT):

```bash
xcode-select --install   # if not already
npm i -g @buzzni/happy-cli@latest --build-from-source
```

### 其它

-   `happy doctor` 运行平台诊断 并且是第一个尝试 在打开一个问题之前.
-   守护进程日志 `~/.happy/logs/*-daemon.log`Grep 用于 `[REMOTE-TERMINAL]` 检查终端中继流量而不漏出 有效载荷体(只记录元数据) - `bytesIn`, (中文(简体) ), `bytesOut`, (中文(简体) ), `exitCode`, (中文(简体) ), `signal`, (中文(简体) ), `durationMs`) (中文(简体) ).

## 许可证

麻省理工学院

## 常见问题

### @buzzni/happy-cli 是什么？

A\+ Dev Studio分叉 slopus/happy\. 中国植物物种信息数据库\. Claude Code和Codex的移动和网络客户端\.

### 如何安装 @buzzni/happy-cli？

在项目目录运行 npm install @buzzni/happy-cli，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 happy、happy-mcp、happy-browser-session-broker，可以用 npx happy 直接运行。

### @buzzni/happy-cli 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @buzzni/happy-cli 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @buzzni/happy-cli 可以商用吗？

@buzzni/happy-cli 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @buzzni/happy-cli 的下载量有多少？

根据 npm 官方下载统计，@buzzni/happy-cli 在 2026/10/09 – 2026/11/07 这 30 天内被下载 54,987 次，日均约 1,833 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @buzzni/happy-cli 还在维护吗？

最新版本 1\.1\.10-aplus\.402 发布于 2026/11/08（今天）；至今共发布 336 个版本，其中过去 12 个月发布了 336 个；首次发布于 2026/07/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。