AlphaClaw

终极 OpenClaw 框架。几分钟部署，持续运行数月。
可观测性、可靠性、代理纪律性——无需 SSH 救援。

AlphaClaw 在 OpenClaw 的基础上，提供了便捷的设置向导、自愈看门狗、基于 Git 的回滚功能以及完整的浏览器端可观测性。它还内置了防漂移提示加固机制，以保持代理的规范操作，并简化各类集成（如 Google Workspace、Google Pub/Sub、Telegram Topics、Slack、Discord），让您只需通过一个 UI 而不必编辑配置文件即可管理多个代理。

首次部署后，不到五分钟即可发送第一条消息。

平台: AlphaClaw 目前面向 Docker/Linux 部署。暂不支持 macOS 本地开发。

功能特性

• 设置 UI: 受密码保护的 Web 控制台，用于引导接入、配置及日常管理。
• 引导式接入: 分步设置向导——模型选择、提供商凭据、GitHub 仓库、频道绑定。
• 多代理管理: 侧边栏驱动的代理导航，支持创建、重命名和删除操作。每个代理都有概览卡片、频道绑定以及 URL 驱动的代理选择功能。
• 网关管理器: 作为受管子进程启动、监控、重启并代理 OpenClaw 网关。
• 看门狗: 崩溃检测、崩溃循环恢复、自动修复（openclaw doctor --fix）、Telegram/Discord/Slack 通知，以及直接在浏览器中监控网关输出的实时交互终端。
• 频道编排: 支持 Telegram、Discord 和 Slack 机器人与各代理的频道绑定、凭据同步，并提供引导式向导，帮助您根据使用规模将 Telegram 切分为多线程话题组。
• Google Workspace: OAuth 集成，支持 Gmail、日历、云端硬盘、文档、表格、任务、联系人和 Meet；同时提供 Gmail 监控的引导式设置，包括 Google Pub/Sub 主题、订阅及推送端点处理。
• 定时任务: 专用的 Cron 选项卡，支持作业管理、交互式滚动日历、运行历史下钻、趋势分析以及每次运行的用量分解。
• 节点: 为 VPS 部署提供本地节点的引导式设置，包含每节点的浏览器连接检查、重连命令以及路由/配对控制。
• Webhook: 具名 Webhook 端点，配备每钩子转换模块、请求日志记录、有效载荷检查、可编辑的投递目标，以及支持第三方认证流程的 OAuth 回调。
• 文件管理器: 浏览器端工作区资源管理器，支持文件可见性、内联编辑、差异视图以及 Git 感知同步，实现无需 SSH 的快速修复。
• 提示加固: 内置防漂移引导提示（AGENTS.md、TOOLS.md），会在每次消息发送时注入到代理的系统提示中——开箱即用，强制执行安全实践、提交规范和变更摘要。
• Git 同步: 自动每小时将您的 OpenClaw 工作区提交至 GitHub，且 Cron 计划可配置。结合提示加固，所有代理操作均可版本控制并审计。
• 版本管理: AlphaClaw 和 OpenClaw 均支持原地更新，内置应用内发布说明、变更日志查看及一键应用功能。
• Codex OAuth: 内置 PKCE 流程，用于访问 OpenAI Codex CLI 模型。

为什么选择 AlphaClaw

• 一次部署即投入生产: Railway/Render 模板自带完整堆栈，无需手动设置网关。
• 自愈能力: 看门狗可检测崩溃，进入修复模式，重新启动网关并通知您。
• 全程浏览器操作: 无需 SSH、无需手动编辑配置文件，首次部署后无需再使用 CLI。
• 轻量无侵入: AlphaClaw 负责基础设施管理，而 OpenClaw 处理 AI 逻辑。

无锁定，随时退出

AlphaClaw 只是对 OpenClaw 的封装，并非其依赖项。移除 AlphaClaw 后，您的代理仍可继续运行。无专有技术，无需迁移任何内容。

快速开始

部署（推荐）

部署时设置 SETUP_PASSWORD，然后访问您的部署 URL。欢迎向导会为您完成剩余步骤。

Railway 用户: 部署完成后，请升级到 Hobby 计划 并重新部署，以确保服务至少拥有 8 GB 内存。Trial 计划的内存限制可能导致正常运行时出现内存不足崩溃。

本地 / Docker

npm install @chrysb/alphaclaw
npx alphaclaw start

或使用 Docker：

FROM node:22-slim
RUN apt-get update && apt-get install -y git curl procps cron && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"
ENV ALPHACLAW_ROOT_DIR=/data
EXPOSE 3000
CMD ["alphaclaw", "start"]

设置界面

选项卡	管理的内容
常规	网关状态、通道健康状况、待配对设备、Google Workspace、仓库同步计划、OpenClaw仪表板
浏览	工作区可见性的文件浏览器、内联编辑、差异审查以及基于Git的同步
使用情况	Token汇总、按会话和按代理的成本及Token细分，并支持按来源/代理维度进行比较
Cron	Cron任务管理、交互式滚动日历、运行历史钻取、趋势分析以及每次运行的使用情况细分
节点	针对VPS部署的引导式本地节点设置、每个节点的浏览器连接、重连命令以及路由/配对控制
看门狗	健康监控、崩溃循环状态、自动修复开关、通知、事件日志、实时日志尾部查看、交互式终端
提供商	AI提供商凭证（Anthropic、OpenAI、Gemini、Mistral、Voyage、Groq、Deepgram）以及模型选择
环境变量	环境变量——查看、编辑、添加——并带有网关重启提示
Webhook	Webhook端点、转换模块、请求历史、负载检查、OAuth回调、Gmail监听推送流程

CLI

命令	描述
alphaclaw start	启动服务器（设置界面 + 网关管理器）
alphaclaw git-sync -m "message"	提交并推送OpenClaw工作区
alphaclaw telegram topic add --thread <id> --name <text>	注册Telegram话题映射
alphaclaw version	打印版本
alphaclaw help	显示帮助

架构

graph TD
    subgraph AlphaClaw
        UI["设置界面<br/><small>Preact + htm + Wouter</small>"]
        WD["看门狗<br/><small>崩溃恢复 · 通知</small>"]
        WH["Webhooks<br/><small>转换 · 请求日志</small>"]
        UI --> API
        WD --> API
        WH --> API
        API["Express服务器<br/><small>JSON API · 认证 · 代理</small>"]
    end

    API -- "proxy" --> GW["OpenClaw网关<br/><small>子进程 · 127.0.0.1:18789</small>"]
    GW --> DATA["ALPHACLAW_ROOT_DIR<br/><small>.openclaw/ · .env · 日志 · SQLite</small>"]

看门狗

内置的看门狗会监控网关健康状况，并在发生故障时自动恢复。

功能	详情
健康检查	定期执行openclaw health，间隔可配置
崩溃检测	监听网关退出事件
崩溃循环检测	基于阈值（默认：300秒内3次崩溃）
自动修复	运行openclaw doctor --fix --yes，重新启动网关
通知	Telegram、Discord和Slack会在崩溃、修复及恢复时发送提醒
事件日志	基于SQLite的事件历史记录，可通过API和UI访问

环境变量

变量	是否必填	描述
SETUP_PASSWORD	是	设置界面的密码
OPENCLAW_GATEWAY_TOKEN	自动	网关认证Token（未设置时自动生成）
GITHUB_TOKEN	是	用于工作区仓库的GitHub个人访问令牌
GITHUB_WORKSPACE_REPO	是	用于工作区同步的GitHub仓库（如owner/repo）
TELEGRAM_BOT_TOKEN	可选	Telegram机器人Token
DISCORD_BOT_TOKEN	可选	Discord机器人Token
SLACK_BOT_TOKEN	可选	Slack机器人Token（Socket Mode）
WATCHDOG_AUTO_REPAIR	可选	在崩溃时启用自动修复（true/false）
WATCHDOG_NOTIFICATIONS_DISABLED	可选	禁用看门狗通知（true/false）
PORT	可选	服务器端口（默认为3000）
ALPHACLAW_ROOT_DIR	可选	数据目录（默认为/data）
TRUST_PROXY_HOPS	可选	信任代理跳数，以正确获取客户端IP

安全注意事项

AlphaClaw 是一个便捷的封装工具——它有意牺牲了 OpenClaw 默认的一些强化措施，以换取更简单的部署流程。你需要了解其中的不同之处：

领域	AlphaClaw 的行为	代价
设置密码	所有网关访问都由一个 SETUP_PASSWORD 密码保护。内置了防暴力破解机制（指数退避锁定）。	比 OpenClaw 的配对码流程更简单，但密码必须足够强。
一键配对	渠道配对（Telegram/Discord/Slack）可以直接在设置界面批准，而无需使用命令行。	无需访问终端，但任何拥有设置密码的人都可以批准配对。
自动 CLI 批准	第一次 CLI 设备的配对会自动批准，这样你就可以无需第二块屏幕进行连接。后续请求则会显示在界面上。	去除了首次 CLI 连接时的手动配对步骤。
查询字符串令牌	Webhook URL 支持 ?token=<WEBHOOK_TOKEN>，适用于不支持 Authorization 头的提供商。UI 中会显示警告信息。	令牌可能会出现在服务器日志和引荐头中。如果提供商支持，请使用头部认证。
网关令牌	OPENCLAW_GATEWAY_TOKEN 会自动生成并注入环境变量，以便代理能够向网关进行身份验证。	该令牌存储在服务器的 .env 文件中——这是托管部署的标准做法，但也值得注意。

如果你需要 OpenClaw 的完整安全策略（手动配对码、不使用查询字符串令牌、不自动批准），请直接使用 OpenClaw，不要使用 AlphaClaw。

开发

npm install
npm run build:ui        # 生成设置 UI 包、Tailwind CSS 和第三方 CSS（从 Git 仓库本地运行时必需）
npm test                # 全套测试（440 个测试用例）
npm run test:watchdog   # 针对 Watchdog 的测试套件（14 个测试用例）
npm run test:watch      # 监视模式
npm run test:coverage   # 覆盖率报告

要求： Node.js ≥ 22.14.0

许可证

MIT

AlphaClaw 快速上手指南

AlphaClaw 是 OpenClaw 的终极增强外壳，提供自愈合看门狗、基于 Git 的回滚机制以及全浏览器可观测性。它旨在让你几分钟内完成部署，并无需 SSH 即可长期稳定运行 AI Agent。

环境准备

系统要求

• 操作系统：Linux (推荐) 或 Docker 环境。

  注意：目前暂不支持 macOS 本地开发，请使用 Docker 或 Linux VPS。

• 内存要求：建议至少 8 GB RAM。

  重要：若使用 Railway 等平台，请务必升级至 Hobby 计划或以上，试用版的内存限制可能导致服务崩溃。

• 运行时：Node.js 22+ (本地安装时) 或 Docker。

前置依赖

• Git：用于工作区同步和版本控制。
• GitHub Token：需要创建一个具有仓库读写权限的 Personal Access Token (PAT)。
• 部署平台账号（可选）：Railway 或 Render 账号用于一键部署。

---

安装步骤

你可以选择通过云平台一键部署，或在本地/服务器通过 Docker/NPM 安装。

方案一：云平台一键部署（推荐）

点击以下按钮之一进行部署，设置 SETUP_PASSWORD 环境变量后即可使用。

• Deploy on Railway
• Deploy to Render

Railway 用户提示：部署后请立即升级至 Hobby plan 并重新部署，以确保拥有足够的内存（8GB+）。

方案二：Docker 部署

创建 Dockerfile 并构建镜像，或直接运行以下命令（需预先准备好数据卷映射）：

FROM node:22-slim
RUN apt-get update && apt-get install -y git curl procps cron && rm -rf /var/lib/apt/lists/*
WORKDIR /app
COPY package.json ./
RUN npm install --omit=dev
ENV PATH="/app/node_modules/.bin:$PATH"
ENV ALPHACLAW_ROOT_DIR=/data
EXPOSE 3000
CMD ["alphaclaw", "start"]

运行容器：

docker run -d \
  -p 3000:3000 \
  -v alphaclaw-data:/data \
  -e SETUP_PASSWORD=你的强密码 \
  -e GITHUB_TOKEN=你的 GitHub Token \
  -e GITHUB_WORKSPACE_REPO=用户名/仓库名 \
  --name alphaclaw \
  node:22-slim alphaclaw start

(注：实际生产中建议先构建包含 alphaclaw 的自定义镜像)

方案三：NPM 本地安装

确保已安装 Node.js 22+，然后执行：

npm install @chrysb/alphaclaw
npx alphaclaw start

---

基本使用

安装完成后，所有管理操作均可通过浏览器完成，无需命令行干预。

1. 访问管理面板

打开浏览器访问 http://localhost:3000 (或你的部署域名)。 输入你在安装时设置的 SETUP_PASSWORD 登录。

2. 初始化配置向导

登录后将自动进入引导流程：

1. 模型选择：选择 AI 提供商（OpenAI, Anthropic, Gemini 等）并填入 API Key。
2. GitHub 绑定：确认工作区同步的仓库地址。
3. 渠道配对：绑定 Telegram、Discord 或 Slack 机器人（可选）。

3. 管理 Agent

在左侧边栏可以进行以下操作：

• 创建/重命名/删除 Agent。
• 查看状态：通过卡片视图监控每个 Agent 的健康状况和通道绑定。
• 文件浏览：在 Browse 标签页直接查看、编辑代码文件，支持 Diff 对比和 Git 同步，无需 SSH。

4. 监控与维护

• Watchdog (看门狗)：在 Watchdog 标签页查看实时日志、崩溃恢复记录和自动修复状态。如果网关崩溃，系统会自动尝试修复并重启。
• 定时任务：在 Cron 标签页管理定时任务，查看执行历史和资源消耗分析。

5. 常用 CLI 命令（可选）

虽然主要功能在 Web 端，你仍可使用以下命令进行特定操作：

# 手动触发 Git 同步
npx alphaclaw git-sync -m "手动提交工作区变更"

# 添加 Telegram 主题映射
npx alphaclaw telegram topic add --thread <id> --name <text>

# 查看版本
npx alphaclaw version

核心特性速览

• 自愈合：检测到网关崩溃会自动执行 openclaw doctor --fix 并重启。
• 防漂移提示：内置 AGENTS.md 和 TOOLS.md，强制 Agent 遵守提交规范和安全实践。
• 无锁定：AlphaClaw 仅是包装器，随时可移除，底层 OpenClaw 仍可独立运行。