Daemon 使用与运维指南

把开发机安全地连接到 PocketCtl

从安装到日常控制，再到后台服务、权限策略与故障恢复。你可以先用五分钟完成接入，需要时再进入高级运维。

开始安装 打开 Web 客户端
01安装 02登录 03启动 04远程控制
01

核心概念

Daemon 是什么

PocketCtl Daemon 是运行在开发机上的轻量进程。它发现本机 AI 编程会话、把不同 Agent 的能力转换成统一协议，并通过已认证的 Relay 与 Web、iOS 客户端保持连接。

i

代码仓库和 Agent 进程留在开发机上；为实现跨设备控制和历史重放，Relay 会处理并存储规范化的会话事件。详细边界见数据与安全。

02

快速开始

安装 Daemon

官方安装器支持 macOS 与 Linux 的 x86-64、ARM64。它会下载对应平台的发布二进制，并使用发布附带的 SHA-256 校验值进行验证。

macOSApple Silicon / Intel
Linuxx86-64 / ARM64
终端curl + bash

运行安装命令

Terminal
curl -fsSL https://www.pocketctl.me/install.sh | bash

安装完成后运行 pocketctl version。如果 shell 找不到命令，请按照安装器提示重新打开终端或刷新 PATH。

03

连接账号

登录、启动并验证

登录只需完成一次。Daemon 会使用保存的认证信息连接生产 Relay，并保持稳定的主机身份。

1

在有浏览器的开发机登录

pocketctl login --prod
2

启动 Daemon

pocketctl daemon start --prod
3

确认连接与 Agent 发现状态

pocketctl daemon status
⌁

无浏览器的服务器可使用 pocketctl login --prod --email，根据终端提示完成邮箱验证码登录。

✓
接入成功的判断标准

status 显示 Daemon 正在运行、Relay 已连接，并列出至少一个已发现的 Agent。随后在 Web 或 iOS 的主机列表中应看到这台开发机。

04

能力接入

连接你的 AI Agent

Daemon 会自动发现兼容的 CLI，但远程能力按 Agent 和运行模式明确区分。Launcher 是可选且可逆的，不会安装、替换或升级底层 Agent。

C

Claude Code

自动发现

可观察本机会话；PocketCtl 创建的 PTY 支持远程输入与审批。独立终端会话保留原生终端的权威控制。

pocketctl agent claude-code status
⌘

Codex CLI

可选受管控制

启用后，官方 TUI 与 PocketCtl 共享同一个 app-server，支持输入、审批、问题、steer 与 interrupt。

pocketctl agent codex enable
O

OpenCode

可选受管控制

启用透明 launcher 后，终端仍使用官方 TUI，并与 Web/iOS 共享输入、permission 和 question。

pocketctl agent opencode enable
Z

ZCode

只读同步

显式启用后同步本地会话历史，供 Web/iOS 查看；不提供远程输入、审批、恢复或控制。

pocketctl agent zcode sync enable
!

需要临时绕过受管 launcher 时，使用 codex --native 或 opencode --native。长期关闭则运行对应的 pocketctl agent … disable。

05

日常操作

启动、查看与停止

pocketctl daemon status查看连接、Agent 和最近 10 个会话
pocketctl daemon status --all查看全部已记录会话
pocketctl daemon logs输出最近的 Daemon 日志
pocketctl daemon keep-awake on任务期间阻止系统休眠；电池供电时自动关闭
pocketctl daemon stop安全停止当前 Daemon
06

会话内远程操作

远程执行 Slash 命令与项目 Skills

在 Web 或 iOS 的会话输入框中输入 /，会列出当前会话可用的命令与 Skills；筛选后选中发送，指令在你主机上的 Agent 会话中执行。

/在输入框开头输入 / 唤起命令面板，可按“命令 / Skills”筛选，也可刷新清单
/{name} {args}选中即作为指令发送到会话；命令与 Skills 都在你的主机上执行
.claude/项目目录下的 commands 与 skills 会被自动发现并列入清单
~/.claude/用户级命令与 Skills 同样可用；同名时项目优先于用户

Claude Code

合并内置命令、项目、用户与已启用插件四个来源，并以会话启动时 Agent 上报的清单为准；当前环境实际不可用的内置命令不会出现。

Codex

通过 Codex 运行时原生目录提供项目、用户与插件级 Skills；同名多来源时需要先选择其一。Codex 与 OpenCode 均不注入 Claude 的内置命令表。

i

命令与 Skills 清单来自你主机上的真实目录与运行时上报，PocketCtl 只做发现与转发，不会安装、启用或修改任何 Skill；在主机上被禁用的 Skill 会显示为不可用。

07

远程查看产物

会话文档快照

开启采集后，会话中 Agent 生成或修改的 Markdown / HTML 文档会自动上传，你可以在 Web 或 iOS 会话详情的“文档”面板中随时查看最新内容。

开启采集（默认关闭）
pocketctl daemon stop
POCKETCTL_SESSION_DOCUMENT_CAPTURE=on pocketctl daemon start --prod

该开关通过环境变量在 daemon 启动时传入；使用后台服务时，需要在服务的启动环境中设置后重装或重启服务。

  • 触发范围：目前仅 Codex 受管会话（app-server 实时变更通知）会产生快照；Claude Code、OpenCode 与 ZCode 会话暂不采集。
  • 格式：仅 .md / .markdown / .html / .htm，且文件必须位于会话允许目录内。
  • 配额：单文档 ≤ 2MB，会话与账号另有总量上限；超限或无法校验的文档会标记为不可用并保留原因。
i

面板中的快照是采集时刻的内容，不是文件的历史版本；出现不可用状态（编码无效、完整性校验失败、超出配额）时可在列表中查看原因。

!

文档内容会经 Relay 处理并存储以支持跨设备查看，与数据边界一章的会话事件一致，并非端到端加密；连接敏感仓库前请先确认。

ADVANCED OPERATIONS · 高级运维

以下设置适用于长期运行、多仓库、多账号或自建 Relay 的主机。首次接入不需要修改。

08

系统托管

安装后台自动重启服务

macOS 使用 LaunchAgent，Linux 使用 systemd 用户服务。服务会以前台模式托管 Daemon，在崩溃或登录环境恢复时自动拉起。

推荐配置
pocketctl daemon service install --prod
pocketctl daemon service status

macOS · launchd

服务定义写入当前用户的 LaunchAgents，并由 launchd 管理。无需手工编辑 plist。

Linux · systemd

使用 systemd --user 单元。安装后按照终端提示确认 linger 设置，确保注销后仍可运行。

!

安装服务时只会记录当前 PATH，不会把 token、代理或 API Key 写入服务定义。移动 Node/Codex/OpenCode 安装位置后，请重新运行 service install 生成服务定义。

要退出系统托管，运行 pocketctl daemon service uninstall。该命令移除服务定义，不会卸载 PocketCtl 或删除账号数据。

09

执行边界

远程目录与高权限策略

Daemon 默认允许在其运行用户的主目录及子目录创建远程会话。生产主机建议显式收窄到实际仓库根目录。

持久化允许目录
pocketctl daemon service install --prod \
  --allowed-cwd-root "$HOME/projects" \
  --allowed-cwd-root "/Volumes/DevDisc/shared/repos"
  • 参数可重复；一旦显式设置，就会替换默认的整个主目录范围，不会自动追加 ~/。
  • 目录授权不会提升文件系统权限，Daemon 仍受运行用户本身的读写权限约束。
  • --allow-dangerous-remote-permissions 会允许远程会话请求绕过审批类高权限模式，只应在已理解风险的隔离主机上启用。
  • --trusted-action-policy off|observe|on 可配置可信审批策略；先用 observe 验证，再决定是否开启执行。
10

账号隔离

一台主机使用多个 Codex 账号

每个账号使用独立的 CODEX_HOME，并把额外目录加入 Daemon allowlist。PocketCtl 会为每个目录隔离 app-server、socket 与恢复状态，但 Dashboard 仍只显示一台主机。

前台或普通启动
pocketctl daemon start --prod \
  --codex-home ~/.codex-a \
  --codex-home ~/.codex-proxy
后台服务
pocketctl daemon service install --prod \
  --codex-home ~/.codex-a \
  --codex-home ~/.codex-proxy

每个 shell 命令仍需指定自己的账号，例如 CODEX_HOME="$HOME/.codex-a" codex。只修改命令别名而不改变 CODEX_HOME，不能区分账号。

11

连接配置

自建 Relay 与运行环境

命令行参数优先于环境变量。公共服务默认使用 wss://www.pocketctl.me/ws；自建环境应使用受信任证书的 wss:// 地址。

设置用途建议
--relay / POCKETCTL_RELAY_URL覆盖 Relay WebSocket 地址服务模式优先固化 --relay
POCKETCTL_CODEX_HOMESPATH 风格的额外 Codex Home 列表服务模式优先使用 --codex-home
POCKETCTL_RUNTIME_DIR覆盖 PID、锁与本机 IPC 运行目录必须是当前用户拥有的绝对私有目录
POCKETCTL_TOKEN临时覆盖认证令牌日常使用应通过 login 保存，不写入脚本
自建 Relay 示例
pocketctl login --email --relay wss://relay.example.com/ws
pocketctl daemon service install --relay wss://relay.example.com/ws

默认运行身份目录是 ~/.pocketctl/run（权限 0700）；按日轮转的日志位于 ~/.pocketctl/logs/daemon-YYYY-MM-DD.log。不要手工删除正在运行的 PID、锁或 state 文件。

12

可观测性

按层诊断，而不是直接重启

先确认进程身份，再检查 Relay 与 Agent 能力。这样能区分“Daemon 没运行”“网络未连接”和“特定 Agent 只能只读”等不同问题。

  1. 1
    进程与身份pocketctl daemon status

    检查 PID、版本、Relay 状态、事件积压和最近会话。

  2. 2
    配置与网络pocketctl daemon doctor

    依次检查配置、token、DNS、HTTP 健康、WebSocket、认证和主机额度。

  3. 3
    Agent 有效模式pocketctl agent codex status

    把 codex 替换为 opencode 或 claude-code，确认 launcher、版本与 runtime 能力。

  4. 4
    日志证据pocketctl daemon logs

    查看最近日志；需要实时观察时，跟踪 ~/.pocketctl/logs 中当天的日志文件。

临时前台调试
pocketctl daemon stop
pocketctl daemon start --prod --debug
!

如果 status 报告运行身份不确定，不要直接删除 daemon.pid 或 daemon.lock，也不要启动第二个 Daemon。先保留现场并查看日志；运行中的锁、state 和进程身份必须一起验证。

13

版本维护

更新、固定版本与恢复

pocketctl daemon update下载、校验并切换到最新发布版本，然后恢复 Daemon
pocketctl daemon update --version vX.Y.Z安装指定发布版本，可用于受控升级或回退
pocketctl daemon update --no-restart只替换二进制，把重启留到维护窗口
✓

更新后依次检查 version、daemon status 和 daemon doctor。使用系统服务时再检查 daemon service status；不要只以命令退出码判断恢复完成。

受管 Agent 出现上游兼容问题时，优先使用 codex --native 或 opencode --native 做单次回退，而不是卸载 Daemon。

14

安全说明

理解数据边界

开发机本地

仓库与 Agent 进程

  • 代码仓库与 Agent CLI 在本机运行
  • 受管 runtime endpoint 与本地凭据不发送到客户端
  • 本机 IPC 与运行身份目录仅限当前用户
经 Relay 处理

跨设备会话事件

  • 消息、命令、路径、diff 与工具输入输出可能被同步
  • Relay 为路由、历史重放和通知持久化事件
  • 内容使用 TLS 传输，但不是端到端加密

连接敏感仓库前，请阅读最新的隐私政策，并确认你信任所配置的 Relay。不要把未知的 --relay 地址当作本地存储。

15

随手查阅

常用命令速查

命令用途
pocketctl login [--prod] [--email]浏览器设备授权或邮箱验证码登录
pocketctl daemon start [--prod]启动并发现本地 Agent
pocketctl daemon stop停止当前 Daemon
pocketctl daemon status [--limit N|--all|--pager]查看状态与近期会话
pocketctl daemon doctor诊断认证与连接链路
pocketctl daemon logs输出最近日志
pocketctl daemon service install|status|uninstall管理系统后台服务
pocketctl daemon keep-awake on|off|status管理防休眠状态
pocketctl daemon update [--version TAG]更新或切换发布版本
pocketctl agent <agent> enable|disable|status管理 Agent 集成

运行 pocketctl help 或任一子命令的 --help 查看当前版本的完整参数。

16

清理

卸载 PocketCtl

卸载前先确认是否需要保留账号配置、主机身份和本地状态。默认卸载会要求确认，并清理 PocketCtl 本地数据。

交互式卸载
pocketctl uninstall
  • 如果安装了后台服务，先运行 pocketctl daemon service uninstall。
  • 需要保留二进制时使用 pocketctl uninstall --keep-binary。
  • 卸载本机 Daemon 不等于删除 Relay 中已有的会话或账号；这些数据需在 Web/iOS 中单独管理。
READY

让 Agent 继续工作，你不必守在终端前

完成安装后，从 Web 或 iOS 打开同一个账号即可查看主机与会话。

打开 Web 客户端 ↗下载 iOS App ↗