返回应用
安装部署

配置守护进程

配置 Mopheus 守护进程，让机器成为可执行智能体任务的运行时。

配置守护进程

守护进程是 Mopheus 运行时的核心组件，负责接收和执行智能体任务。配置守护进程后，你的机器将成为可托管 AI 智能体的运行时。

前提条件

要求说明
Mopheus CLI已安装并登录（参考 安装 CLI 工具）
至少一个 Provider CLI安装 claude、kimi-code、agy 或其他受支持的二进制文件。没有 Provider CLI 时，守护进程不会注册任何运行时。注意：Provider CLI（如 ClaudeCode）自身也需要访问对应的 AI 服务商（如 Anthropic API）才能工作。
可访问 Mopheus 后端守护进程必须能通过出站连接访问你使用的 Mopheus 后端服务地址（默认 http://localhost:8080，或你配置的 MOPHEUS_SERVER_URL）。无需开放任何入站端口。

登录

守护进程会复用 CLI 的登录状态，因此启动前请先在本机完成 mopheus login。如果在 安装 CLI 工具 步骤中已经完成，可直接跳到 启动守护进程。

配置服务器地址

如果使用自托管 Mopheus 实例，需要配置服务器地址：

mopheus config set server_url https://your-mopheus.example.com

登录认证

# 方式一：交互输入 API Token（在 Web 界面 Settings → API Tokens 创建）
mopheus login --token

# 方式二：用邮箱密码登录，CLI 会自动创建长期 API Token
mopheus login --email your@email.com --password yourpassword

验证登录是否成功：

mopheus workspace list

如果列表正常返回（即使为空），说明连接成功。

启动守护进程

mopheus daemon start

请使用普通系统用户运行守护进程。直接以 root 启动 daemon 会被拒绝，因为 agent 子进程会继承 daemon 的文件系统和网络权限，而且 root 创建的任务目录会导致后续普通用户运行失败。在确实需要 root daemon 进程的受控环境中，必须显式选择：

mopheus daemon start --allow-root

该参数限制的是 daemon 进程，不是管理命令。root 用户仍可执行 mopheus daemon start 或 restart 管理已安装的系统级服务；Mopheus 会把操作委托给 systemd。

首次运行时，守护进程会执行以下操作：

  1. 在 ~/.mopheus/daemon.id 创建一个稳定的机器 ID（后续每次启动都复用此 ID）
  2. 扫描已知的 Provider CLI（claude、kimi-code、agy）以及通过环境变量指定的自定义路径
  3. 连接服务器并完成注册，列出所有发现的 Provider CLI
  4. 开始接受所有兼容智能体的任务
  5. 运行期间每 30 秒发送一次 HTTP 心跳保活

验证守护进程是否正常运行：

mopheus daemon status

几秒钟内，你的机器就会出现在侧边栏的 运行时 下，每个发现的 Provider CLI 对应一行记录。

持久运行

开发调试时，在终端保持 mopheus daemon start 进程前台运行即可。

对于长期运行的场景，建议使用进程管理器托管守护进程，以便在重启或崩溃后自动恢复。

推荐方式：mopheus daemon install

设置 systemd 服务最简单的方式是使用 mopheus daemon install，它会自动生成 unit 文件和环境变量模板：

# 安装 systemd 服务（root → 系统服务 /etc/systemd/system/mopheus-daemon.service，
# 非 root → 用户服务 ~/.config/systemd/user/mopheus-daemon.service）
mopheus daemon install

# 开机自启并立即启动
mopheus daemon install --enable --start

# 在 -- 之后传入额外的 'daemon start' 参数
mopheus daemon install -- --agent-idle-watchdog 0s

该命令会写入服务 unit 文件和环境变量文件，然后执行 systemctl daemon-reload。使用 --enable 开启开机自启，--start 立即启动。非 root（用户）服务会自动检查 linger 状态；若未启用（默认为 no），需执行 sudo loginctl enable-linger $USER，防止用户退出所有 SSH 会话后用户级 systemd 服务被关闭。

以 root 安装的系统级 unit 会在 ExecStart 中包含 --allow-root，明确允许其 daemon 进程以 root 运行。为保证升级兼容，Mopheus 也会通过 systemd 调用元数据识别已有的 root daemon 服务。用户级 unit 不包含该参数。除非 daemon 明确需要系统级权限，否则应优先使用用户级服务。

智能体任务物理资源画像（Telemetry）与 cgroup v2 委托

Mopheus 守护进程在每个智能体任务执行终态时，会自动采集并持久化物理资源消耗画像（resource_telemetry）。系统内置了两种采集模式，确保在任意环境下都能可靠沉淀数据：

  1. 内核硬件模式（cgroup_v2）：在支持 cgroup v2 的 Linux 环境下，守护进程为每个任务创建独立的内核切片。任务结束时瞬间（小于 1ms）读取内核硬件计数器，零轮询开销、不遗漏任何毫秒级闪退的短命子进程，并能完整捕获精确 CPU 耗时、堆栈/缓存内存细分、磁盘 I/O 读写量与 IOPS 以及系统 PSI 压力指标。
  2. 采样降级模式（sampler）：在 macOS 或未配置 cgroup 委托的 Linux 环境中，守护进程自动无感回退至进程树定期采样模式。通过复用看门狗的 2 秒轮询周期，同样能持续记录任务生命周期内的物理内存峰值（Peak Memory）与并发进程峰值（Peak Procs），确保零配置下依然有基础物理画像沉淀。

两种遥测模式在 Mopheus 中的表现对比

遥测维度 / 指标内核模式 (cgroup_v2，推荐)降级采样模式 (sampler，默认兜底)
数据源标识 (source)cgroup_v2sampler
物理内存峰值 (Peak Memory)内核硬件级瞬时峰值 (memory.peak)2 秒采样周期内捕获的最大物理内存 (VmRSS / Resident Size)
内存结构细分堆栈匿名页 (anonBytes)、文件缓存 (fileBytes)、Swap 峰值不细分（仅记录总物理内存峰值）
CPU 总耗时与节流 (CPU Time)内核微秒级用户态/内核态精确耗时与节流周期依据进程结束状态与采样汇总估算
并发峰值 (Peak Procs)记录生命周期内瞬时最大内核任务与线程峰值 (pids.peak)记录采样周期内观察到的最大并发子进程数
磁盘 I/O 吞吐与 IOPS读写吞吐字节数与读写 IOPS (io.stat)降级不记录
系统停顿压力 (psi)CPU、I/O 停顿微秒统计 (*.pressure)降级不记录
短命瞬时进程捕获100% 捕获（内核硬件计数器累加）若存活时间低于采样周期可能未及抓取
支持环境与配置要求Linux 普通用户配置 systemd cgroup 委托macOS / Linux（零配置开箱即用）

如何开启 Linux 满血内核模式 (cgroup_v2)

当在 Linux 系统（如 Ubuntu、Debian、Arch、WSL 2 等）上使用普通用户运行守护进程时，仅需一条指令为 systemd 用户服务开启 cgroup 委托即可升级为内核模式：

sudo mkdir -p /etc/systemd/system/user@.service.d
sudo tee /etc/systemd/system/user@.service.d/delegate.conf <<'EOF'
[Service]
Delegate=yes
EOF
sudo systemctl daemon-reload

提示：即使未配置该委托，Mopheus 守护进程也会自动以 sampler 降级模式正常工作并记录基础物理画像，绝不会因权限缺失而导致任务中断或报错。

手动配置 systemd（备用方案）

如果 daemon install 不可用或你需要完全控制，可以手动创建 unit 文件。先创建环境变量文件，集中管理配置：

mkdir -p ~/.mopheus
tee ~/.mopheus/daemon.env > /dev/null <<'EOF'
# MOPHEUS_DAEMON_DEVICE_NAME=my-server
# MOPHEUS_WORKDIR=~/mopheus_workspace
EOF
chmod 600 ~/.mopheus/daemon.env
# /etc/systemd/system/mopheus-daemon.service
[Unit]
Description=Mopheus agent runtime daemon
After=network.target

[Service]
Type=simple
ExecStart=%h/.local/bin/mopheus daemon start --foreground
Restart=always
RestartSec=5
# 允许运行中任务完成等待 45 秒；50 秒后 systemd 强制终止。
Environment="MOPHEUS_DAEMON_SHUTDOWN_DRAIN_TIMEOUT=45s"
TimeoutStopSec=50s
User=mopheus
Environment="HOME=/home/mopheus"
# 如需调整运行时行为，通过环境变量传入参数：
# Environment="MOPHEUS_DAEMON_MAX_CONCURRENT_AGENT_TASKS=5"
# Environment="MOPHEUS_DAEMON_DEVICE_NAME=DBA-Workstation"

[Install]
WantedBy=multi-user.target
sudo systemctl daemon-reload
sudo systemctl enable --now mopheus-daemon
journalctl -u mopheus-daemon -f

配置参数

守护进程的行为可以通过环境变量调整。所有参数均有合理的默认值。

连接配置

环境变量默认值说明
MOPHEUS_SERVER_URLhttp://localhost:8080守护进程连接的服务器 URL。
MOPHEUS_TOKEN—API 令牌。通常由 mopheus login 自动写入配置文件，无需手动设置。

运行时身份

环境变量默认值说明
MOPHEUS_DAEMON_ID首次运行时自动生成稳定的机器级唯一标识，持久化于 ~/.mopheus/daemon.id。
MOPHEUS_DAEMON_DEVICE_NAMEOS 主机名在运行时列表和悬停卡片中显示的设备名称。
MOPHEUS_AGENT_RUNTIME_NAME—运行时的显示名称。优先级高于设备名称。

运行时行为

环境变量默认值说明
MOPHEUS_DAEMON_HEARTBEAT_INTERVAL30sHTTP 心跳发送间隔。
MOPHEUS_AGENT_TIMEOUT0（禁用）可选的 Daemon 侧任务总执行超时。未设置或为 0 时，由服务端系统级 agent_task_timeout 清扫作为兜底。
MOPHEUS_AGENT_IDLE_WATCHDOG1h智能体无消息输出超过此时长后强制终止；设为 0 则禁用。
MOPHEUS_DAEMON_MAX_CONCURRENT_AGENT_TASKS20守护进程同时执行的最大任务数。
MOPHEUS_DAEMON_SHUTDOWN_DRAIN_TIMEOUT0（无限等待）守护进程停止认领后允许运行中任务完成的最长时间。达到该上限时，剩余任务会被取消并上报为 daemon_shutdown。生成的 systemd unit 固定为 45s。
MOPHEUS_SANDBOX_ENABLEDtrue将每个智能体子进程包裹进 bubblewrap 文件系统沙箱（仅 Linux）。未设置或为空时启用，仅设置为 false 或 off 时关闭。详见文件系统沙箱。
MOPHEUS_SANDBOX_DENY—额外对智能体隐藏的绝对路径，逗号分隔，用空 tmpfs 覆盖。

Provider CLI 路径

环境变量默认值说明
MOPHEUS_CLAUDE_PATH通过 $PATH 自动发现覆盖 claude 二进制文件的路径。
MOPHEUS_KIMI_CODE_PATH通过 $PATH 自动发现覆盖 kimi-code 二进制文件的路径。
MOPHEUS_ANTIGRAVITY_PATH通过 $PATH 自动发现覆盖 agy 二进制文件的路径。

工作目录与日志

环境变量默认值说明
MOPHEUS_WORKDIR~/mopheus_workspace每个任务工作目录的创建位置。
MOPHEUS_LOG_FILE~/.mopheus/daemon.log日志文件路径。
MOPHEUS_LOG_LEVELinfo日志级别：debug、info、warn、error。

健康检查端口

守护进程在 GET http://127.0.0.1:19515/health 暴露本地健康检查端点。该端口无环境变量覆盖，由内部规则根据 CLI profile 推导（默认 profile 为 19515，其他 profile 为 19515 加上 profile 字符串哈希偏移）。可用于容器或进程管理器的存活探针。

停止守护进程

干净地停止守护进程：

mopheus daemon stop

守护进程会发送注销请求，运行时状态在界面中随即切换为 离线。

故障排查

守护进程未出现在运行时列表中

  • 检查守护进程的日志输出——连接错误会立即显示
  • 运行 mopheus ticket list 确认 mopheus login 是否成功
  • 确认 MOPHEUS_SERVER_URL 与你登录时使用的地址一致
  • 如果处于代理环境，设置 HTTPS_PROXY，确保 WebSocket 升级请求可以到达服务器

运行时出现但任务未被认领

  • 验证 Provider CLI 是否在 $PATH 中（which claude），或确认覆盖环境变量指向有效的二进制文件
  • 确认智能体的 Provider CLI 与运行时声明的匹配——Claude 智能体不会在仅有 kimi-code 的运行时上运行
  • 检查智能体状态：如果显示为 错误，先清除错误再重新运行任务

安装新的 Provider CLI 后未出现在运行时列表中

守护进程每 30 秒会重新探测本机的 Provider CLI，无需重启。新安装的 CLI 最多等待一个探测周期（30 秒）即可自动被发现。如果长时间未出现，检查该 CLI 是否在 $PATH 中且可执行。

健康检查端点

# 检查守护进程是否存活
curl http://127.0.0.1:19515/health

安装 CLI 工具

安装 Mopheus CLI、Claude CLI、SwissQL 等命令行工具。

通过 CLI 发送邮件

在 Mopheus CLI 中配置 SMTP 凭据，无需在 Linux 服务器上额外安装 mail / sendmail 工具即可发送邮件。