简体中文 | English

AgentHub Agent

随时随地移动端远程操控智能体工具。跑在PC上，根据PC实际安装支持的智能体进行远程管理，把智能体的输入与控制体验延伸到移动端App。

移动端App  ↔  AgentHub Server  ↔  AgentHub Agent（本包）  ↔  Agent CLI

Agent 是常驻后台进程：连 Server 接收 App 指令，调 Agent 驱动 Agent CLI 跑会话，把 thinking / 文本 / 工具调用 / 结果等事件流式回推给 App。SDK 只起「下达命令 + 监管」作用，不干扰智能体的自主决策。

支持的智能体

| 智能体 | CLI / 安装体 | 状态 | |---|---|---| | Claude | 任意带 claude 进程的安装体（Claude Code VSCode 扩展 / Claude CLI 等） | ✅ 已支持 | | Codex | codex | 🚧 即将支持 |

功能

• 📱 远程操控：手机发指令、中断生成、切换/新建会话、切模型、压缩上下文
• 🌊 实时监管：thinking / 文本 / 工具调用 / 工具结果 / 任务完成 事件流，逐字流式
• 🤖 自主决策：默认 bypassPermissions，智能体的 agentic loop 不被打断
• 💬 人机交互：ask_remote_user MCP 工具，智能体主动向手机提问（多问题向导）
• 📁 文件浏览：远程查看工作目录文件树、分块读文件（带进度）、文件搜索、写文件
• 🕘 历史会话：扫描 ~/.claude/projects 项目列表 + 会话列表 + resume + 历史消息重放
• 🔔 外部会话同步：监听 VSCode 端智能体的会话活动（busy/完成），多端同步推 App
• ⚙️ 开机自启：Windows 注册表 Run（当前用户登录后启动，免管理员）/ Linux systemd / macOS launchd（开机即起）
• 🔄 自动更新：App 远程触发 update，停 daemon + npm install + 重启
• 🌐 中英双语：控制台输出按系统语言自动切换

使用说明

安装

npm install -g agenthub-ai

启动与配对

agenthub                  # 启动（首次打印配对码）

启动后终端打印 4 位配对码，在 App 智能体页点 + 输入码完成配对。配对成功后 token 持久化，后续启动自动重连；token 失效（App 解绑/删除）会清本地 token 并退出，需重新配对。

系统命令

agenthub            # 默认启动（有 token 重连，无 token 申请配对码；daemon 已在跑则提示后退出）
agenthub install    # 安装自启服务（Windows 当前用户免管理员；Linux/macOS 需 root）
agenthub uninstall  # 卸载自启服务
agenthub status     # 查看绑定信息与服务状态（不连 server）
agenthub update     # 检查并更新到最新版（停 daemon + npm install + 重启）
agenthub unbind     # 解绑当前账号（清 token + Server 归档该 agent），退出
agenthub repair     # 重新配对（忽略旧 token 申请新码；成功后旧 agent 归档，绑新账号）
agenthub lang       # 切换界面语言（中文/English），交互选序号，重启后生效
agenthub -v         # 查看版本号（agent + SDK）
agenthub help       # 显示帮助

环境变量

| 变量 | 说明 | 默认 | |---|---|---| | MACHINE | 机器名 | hostname | | AGENT_NAME | Agent 显示名 | default | | AGENT_TOKEN_FILE | token 文件路径 | ~/.agenthub/agent-token-<kind>.json | | CLAUDE_CONFIG_DIR | Claude 配置目录 | ~/.claude |

自启服务

# Windows（免管理员）
agenthub install

# Linux / macOS（root）
sudo agenthub install

• Windows：HKCU\...\Run + daemon.vbs，用户登录后启动，免管理员（开机未登录不运行）
• Linux：systemd system unit（User=），开机即起
• macOS：LaunchDaemon（UserName=），开机即起

更新

agenthub update

勿用 npm update -g 更新：agent 运行时常驻被占用，npm 直接替换会因文件锁失败并残留临时目录。App 也可远程触发更新。

权限与风险说明

本 Agent 具备以下较高权限操作，说明实际作用以便审查：

| 操作 | 实际作用 | 风险控制 | |---|---|---| | 文件读写 | App 可远程读工作目录文件树、分块读文件、写文件、搜索。FileRead/FileWrite/FileSearch/FileTree action | 只读写 App 指定路径，不主动扫描敏感目录 | | Agent CLI 子进程 | Agent spawn 用户的智能体 CLI 跑会话（不内嵌智能体，复用用户安装） | 找不到 Agent CLI 则报错退出，不下载执行 | | 自启注册 | Windows 写 HKCU Run（登录后启动），Linux 写 systemd，macOS 写 LaunchDaemon | Windows 免管理员；Linux/macOS 需 root；uninstall 撤销 | | 运行账户 | Windows 当前用户；Linux/macOS 以指定用户运行 | 不用 SYSTEM/root 跑会话 | | 文件监听 | external-watcher 用 chokidar 监听 ~/.claude/projects 变化，识别外部智能体活动 | 只读 jsonl 元数据 + 尾部预览，不传完整内容 | | 网络 | WebSocket 连 AgentHub Server，收发 App 指令与事件流 | 仅连配置的 Server 地址，不连其他外部服务 |

依赖

| 库 | 用途 | |---|---| | chokidar | 跨平台文件监听（外部会话 watcher） | | ws | WebSocket 客户端（连 Server） | | zod | 协议 schema 校验 |

要求

• Node.js 22+
• 工作机已装任意支持的智能体助手

License

见 LICENSE。