process.ts —— OpenClaw 如何像开发者一样管理后台进程

关键词：进程管理｜服务监控｜日志追踪｜自动恢复｜权限隔离｜状态快照

在现代开发运维中，“部署”只是开始，真正的挑战在于服务的持续运行与可观测性。一个合格的开发者会：

• 启动 Web 服务并确认其监听端口
• 实时跟踪日志中的错误
• 在崩溃后自动重启
• 根据资源使用调整配置

OpenClaw 的 src/agents/process.ts 模块，正是为了让 AI 智能体具备这种全生命周期进程管理能力。它不是简单地调用 ps 或 kill，而是构建了一套语义化、可观察、自愈式的进程控制系统。

本文将详解其核心机制：服务注册、状态感知、日志绑定、安全终止与自动恢复。

一、为什么需要专用进程管理？

直接让 AI 执行 systemctl start app 存在诸多问题：

• 无法知道服务是否真正就绪（端口监听？健康检查？）
• 日志分散在 /var/log/，AI 难以关联
• 崩溃后不会自动恢复
• 无统一视图，多服务管理混乱

process.ts 的目标是：将进程抽象为“受管服务”（Managed Service），提供一致的 CRUD 接口。

二、服务模型：ManagedProcess 抽象

每个受管进程由一个 ManagedProcess 对象表示：

interface ManagedProcess {
  id: string;                // 服务 ID，如 "web-server"
  cmd: string;               // 启动命令，如 "npm run dev"
  cwd: string;               // 工作目录
  env?: Record<string, string>;
  port?: number;             // 期望监听的端口（用于就绪检测）
  logFile?: string;          // 日志文件路径（可选）
  autoRestart: boolean;      // 崩溃是否自动重启
  ownerSession: string;      // 所属会话（用于租户隔离）
  pid?: number;              // 当前 PID
  status: 'stopped' | 'starting' | 'running' | 'crashed';
  lastExitCode?: number;
  startTime?: number;
}

关键创新：将进程从“操作系统实体”提升为“应用层对象”。

三、核心能力一：语义化启动与就绪检测

AI 不再说“运行 npm start”，而是：

# SKILL.md 示例
- name: start_web_server
  description: "启动开发服务器并等待就绪"
  parameters:
    port: 3000
    command: "npm run dev"

启动流程（startProcess()）

验证权限：检查 cwd 是否在 allowedPaths 内

派生子进程：

const proc = spawn(cmd, [], { cwd, env: sanitizedEnv });

就绪检测（若指定 port）：

• 每 500ms 检查 localhost:port 是否响应
• 超时 30 秒标记为 crashed

绑定日志流：

• 若未指定 logFile，自动捕获 stdout/stderr
• 通过 ACP 事件 process.log 实时推送

就绪 ≠ 启动成功：只有端口就绪才视为 running。

四、核心能力二：实时日志与错误诊断

传统方式：用户需手动 tail -f nohup.out OpenClaw 方式：AI 自动关联日志并分析

日志绑定机制

每个 ManagedProcess 生成唯一 logStreamId

所有输出（stdout/stderr）写入内存环形缓冲区（默认 1000 行）

客户端可通过 ACP 订阅：

{ "method": "process.subscribeLogs", "params": { "processId": "web-server" } }

错误模式识别（初步）

process.ts 内置常见错误关键词检测：

const ERROR_PATTERNS = [
  /EADDRINUSE/,
  /FATAL ERROR/,
  /segmentation fault/,
  /Cannot find module/
];

proc.stderr.on('data', (chunk) => {
  if (ERROR_PATTERNS.some(p => p.test(chunk))) {
    markAsCrashed(processId);
    suggestFix(processId, chunk); // 如：“端口被占用，建议换端口或 kill 占用进程”
  }
});

AI 可基于日志上下文回答：“你的服务因端口冲突崩溃，要我帮你查占用进程吗？”

五、核心能力三：安全终止与资源清理

直接 kill -9 可能导致：

• 数据未 flush
• 子进程残留（僵尸进程）
• 端口未释放

process.ts 实施优雅终止协议：

终止流程（stopProcess()）

1. 发送 SIGTERM
2. 等待 5 秒 grace period
3. 若仍运行，发送 SIGKILL
4. 清理临时文件、释放端口记录
5. 更新状态为 stopped

租户隔离

• 用户只能管理自己会话创建的进程
• 通过 ownerSession 字段强制校验

干净退出，不留痕迹。

六、核心能力四：自动恢复与健康看护

对于关键服务，可启用 autoRestart: true：

自愈逻辑

if (proc.exitCode !== 0 && config.autoRestart) {
  if (recentCrashCount > 5) {
    disableAutoRestart("Too many crashes"); // 防止无限重启
    notifyUser("服务连续崩溃，已暂停自动重启");
  } else {
    setTimeout(() => startProcess(id), 2000); // 2秒后重启
  }
}

健康看护扩展（未来）

• 集成 HTTP 健康检查（/healthz）
• 内存/CPU 使用率监控
• 异常行为告警（如频繁重启）

从“一次性执行”到“持续托管”。

七、与 exec.ts 的协同：分层职责

image

exec.ts 是“手”，process.ts 是“管家”。

八、配置示例：托管一个 Next.js 应用

# agents/dev-assistant/config.yaml
managedProcesses:
  - id: "next-app"
    cmd: "npm run dev"
    cwd: "/home/user/my-next-app"
    port: 3000
    autoRestart: true
    logFile: "./logs/dev.log"  # 可选，否则自动捕获

用户指令：

“启动我的 Next.js 应用”

AI 行为：

1. 调用 process.start("next-app")
2. 等待端口 3000 就绪
3. 返回：“应用已在 http://localhost:3000 运行！”
4. 后台持续推送日志：“Compiled successfully...”

九、安全边界：防止滥用

尽管功能强大，process.ts 严格限制风险：

1. 禁止特权命令：不能启动 sshd、nginx 等系统服务
2. 路径限制：cwd 必须在 allowedPaths 内
3. 资源限制：子进程继承 exec.ts 的 CPU/内存限制
4. 无 root 权限：所有进程以网关用户身份运行

能力越大，约束越明。

结语：从“执行命令”到“托管服务”

process.ts 标志着 OpenClaw 从任务执行者向环境管理者的演进。它不再满足于“运行一次命令”，而是致力于维持一个稳定、可观测、自愈的开发/运行环境。

这正是 AI 智能体走向“真正助手”的关键一步——不仅做事，更懂如何把事做好、做稳、做久。

在下一篇中，我们将探讨 OpenClaw 的技能系统：如何通过 SKILL.md 让 AI 学会新能力。

下一篇预告： 第 13 篇：技能即文档 —— SKILL.md 如何让 AI 自主学习新工具