企业官网建设流程全解析

OpenClaw 仓库脚本实战：认证监控、手机重认证与 gh-read 只读访问

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

scripts/是 OpenClaw 仓库内为本地工作流与运维任务提供的一组辅助脚本：既包含针对远程/无头主机上Claude Code 订阅 token的监控、告警与手机重认证闭环，也包含用 GitHub App 安装令牌做只读调用、与个人登录态隔离的gh-read封装。阅读本文后，你将掌握这些脚本的定位、核心参数与完整运行方式，并能在此基础上自行新增符合仓库约定的脚本。

脚本目录定位与使用约定

官方文档（docs/help/scripts.md）开篇即明确了scripts/的定位：它存放本地工作流和运维任务的辅助脚本。当某项任务与某个脚本明确绑定时应使用脚本，否则优先使用 OpenClaw CLI。三条核心约定如下：

• 脚本是可选的：除非文档或发布检查清单（release checklist）中明确引用，否则脚本不参与核心工作流；
• 优先使用 CLI 表面：凡 CLI 已有对应能力，就优先用 CLI，例如openclaw models status --check，而不是自己造轮子；
• 假设脚本是主机相关的：在新机器上运行前，务必先通读脚本内容再执行。

也就是说，这套脚本服务于"本地/运维辅助"场景，是 CLI 的补充而非替代品。

认证监控脚本族：为无头主机上的 Claude Code token 兜底

这一组脚本（scripts/setup-auth-system.sh、scripts/claude-auth-status.sh、scripts/auth-monitor.sh、scripts/mobile-reauth.sh、scripts/termux-*.sh）是一个独立于通用模型认证的可选系统。它专门解决一个具体问题：远程/无头主机上运行的 Claude Code CLI 订阅 token 会过期，需要监控并在手机上完成重认证。

通用模型认证（API Key、OAuth、Claude CLI 复用、setup-token）见 docs/gateway/authentication.md；本文这套脚本只关注 Claude Code CLI 订阅 token 的监控与手机重认证闭环。

一次性安装：setup-auth-system.sh

scripts/setup-auth-system.sh 是整个体系的一次性初始化脚本（set -euo pipefail严格模式），运行后依次完成四步：

1. 检查当前认证状态：直接调用claude-auth-status.sh full，先看清现状；
2. 生成长效 token：推荐使用claude setup-token生成长期有效的 API token，避免每日重新认证；脚本会询问是否现在配置；
3. 配置认证监控：询问 ntfy.sh 主题（用于手机推送）和手机号（用于 OpenClaw 消息告警），然后把 systemd service 模板（scripts/systemd/openclaw-auth-monitor.service）渲染为实际路径后安装到~/.config/systemd/user/，并systemctl --user enable --now openclaw-auth-monitor.timer立即启用定时器；
4. 打印 Termux 手机端配置指引（见下文"Termux 一键认证"）。

其中 service 模板的ExecStart=@OPENCLAW_AUTH_MONITOR_PATH@占位符会在安装时被渲染为检出目录中auth-monitor.sh的绝对路径，NOTIFY_PHONE/NOTIFY_NTFY环境变量行也会按用户输入自动填充或注释掉。

状态检查：claude-auth-status.sh 的三种输出模式

scripts/claude-auth-status.sh 同时检查Claude Code与OpenClaw两边的认证状态，用法为：

scripts/claude-auth-status.sh # 默认 full scripts/claude-auth-status.sh json # 结构化 JSON scripts/claude-auth-status.sh simple # 供脚本/widget 使用的极简输出

• full（默认）：彩色终端输出，包含 Claude Code 的订阅类型（subscriptionType）、速率档位（rateLimitTier）、过期时间，以及 OpenClaw 侧使用的 Anthropic profile、过期时间、当前使用的 API key 数量，最后还会报告systemctl --user is-active openclaw的服务运行状态；
• json：通过jq -n输出{claude_code, openclaw, needs_reauth}三个字段，needs_reauth在任一状态命中EXPIRED/EXPIRING/MISSING时为true，非常适合被脚本程序化消费；
• simple：只输出OK/CLAUDE_EXPIRED/OPENCLAW_EXPIRED/CLAUDE_EXPIRING/OPENCLAW_EXPIRING之一，并带对应退出码（1 表示已过期或缺失，2 表示即将过期），专为 Termux 等外部脚本设计。

状态判定逻辑（源码见calc_status_from_expires）：以毫秒时间戳差值计算剩余小时/分钟，<= 0判定MISSING，已过期为EXPIRED，剩余不足 1 小时为EXPIRING，否则为OK。脚本优先读取openclaw models status --json的输出（USE_JSON=1），失败时才回退到直接解析~/.claude/.credentials.json与~/.openclaw/agents/main/agent/auth-profiles.json两个文件。

定时轮询：auth-monitor.sh 与 systemd 定时器

scripts/auth-monitor.sh 负责周期性检查并在 token 临近过期时发送通知，通过三个环境变量控制行为：

其运行机制与边界情况如下：

• 状态判定：读取~/.claude/.credentials.json的claudeAiOauth.expiresAt；凭据文件缺失时以high优先级告警提示运行claude setup-token；已过期时以urgent优先级提示在主机上运行mobile-reauth.sh；
• 防骚扰去抖：状态文件~/.openclaw/auth-monitor-state记录上次成功通知时间，MIN_INTERVAL=3600秒（1 小时）内最多通知一次；且只有通知确实送达（OpenClaw 或 ntfy 任一成功）才更新冷却时间；
• 通知通道：OpenClaw 通道在发送前会先以claude-auth-status.sh simple确认认证仍可用；ntfy 通道带 5 秒连接超时、15 秒总超时，并附带Title: OpenClaw Auth Alert、Priority与Tags: warning,key头。

调度方式官方推荐使用随仓库附带的 systemd 单元（scripts/systemd/openclaw-auth-monitor.service 与 scripts/systemd/openclaw-auth-monitor.timer）：Type=oneshot的服务每 30 分钟触发一次，OnBootSec=5min、OnUnitActiveSec=30min、Persistent=true（错过的周期会补跑）。脚本注释中也给出了等价的 cron 写法：*/30 * * * * /path/to/openclaw/scripts/auth-monitor.sh。

手机重认证：mobile-reauth.sh

scripts/mobile-reauth.sh 专为通过 SSH 从 Termux 使用的场景设计，把重认证流程手机化：先以claude-auth-status.sh simple判断状态（有效则直接展示 full 详情并退出），然后打印在手机上打开 Anthropic 控制台 API Keys 页面、创建/复制sk-ant-...开头 key 的分步指引，等待用户确认后运行交互式claude setup-token。认证成功后若检测到openclaw用户服务在运行，还会自动systemctl --user restart openclaw让新 token 立即生效。

Termux 一键认证：三个 Widget 脚本

仓库提供了三个面向 Termux:Widget（安卓桌面小组件）的脚本，通过OPENCLAW_SERVER环境变量（默认openclaw-host）指定主机，全部基于 SSH 执行：

• scripts/termux-quick-auth.sh：极简一键脚本，SSH 到主机执行claude-auth-status.sh simple；OK时弹 toast，EXPIRING时震动提醒，EXPIRED/MISSING时震动并直接打开 Anthropic 控制台页面，同时弹出包含后续mobile-reauth.sh命令的通知；
• scripts/termux-auth-widget.sh：功能更完整的一键脚本，通过termux-dialog弹单选/确认对话框引导"立即重认证/稍后再说"，过期时还会用am start拉起 Termux 终端供用户执行重认证命令；
• scripts/termux-sync-widget.sh：OAuth 同步小组件，SSH 执行同步逻辑后将过期时间解析为 toast，并可选重启主机上的openclaw服务。

三者分别对应setup-auth-system.sh最后一步打印的安装指引：把脚本复制到手机的~/.shortcuts/（如ClawdAuth、ClawdAuth-Full）并chmod +x后，即可从桌面小组件一键查看与恢复认证。

GitHub 只读助手：gh-read

当需要让gh使用GitHub App 安装令牌做仓库范围内的只读调用、同时把个人登录态留给写操作时，使用 scripts/gh-read（实际转发到 scripts/gh-read.ts）。

环境变量

必填：

• OPENCLAW_GH_READ_APP_ID：GitHub App 的 App ID；
• OPENCLAW_GH_READ_PRIVATE_KEY_FILE：App 私钥文件路径（源码经@openclaw/fs-safe/secret的readSecretFileSync安全读取）。

可选：

• OPENCLAW_GH_READ_INSTALLATION_ID：显式指定安装 ID，跳过基于仓库的安装查询；
• OPENCLAW_GH_READ_PERMISSIONS：逗号分隔的权限覆盖列表，用于请求比默认更小的只读权限子集。

默认申请的只读权限子集（源码DEFAULT_READ_PERMISSION_KEYS）为：actions、checks、contents、issues、metadata、pull_requests、statuses。

仓库解析顺序

当命令中未显式给出仓库时，按以下优先级解析目标仓库：

1. gh ... -R owner/repo命令行参数（源码parseRepoArg支持-R/--repo/--repo=/-Rowner四种写法）；
2. 环境变量GH_REPO；
3. git remote origin（经 scripts/lib/github-repo.ts 的resolveGitHubRepoFromOrigin解析）。

使用示例

scripts/gh-read pr view 123 scripts/gh-read run list -R openclaw/openclaw scripts/gh-read api repos/openclaw/openclaw/pulls/123

从源码结构看，gh-read整体是一个"认证替换 + 参数透传"的封装：gh-read外壳仅做exec node --import tsx "$script_dir/gh-read.ts" "$@"，而gh-read.ts负责用 GitHub App 私钥签发 JWT（createPrivateKey+createSign）、申请安装访问令牌，并把令牌注入后，将剩余参数原样转发给gh。API 请求相关实现带 30 秒默认超时（DEFAULT_GITHUB_FETCH_TIMEOUT_MS）、1 MiB 响应体上限与 4096 字符错误体截断等防护，适合在 CI 与发布流水线中安全使用。

新增脚本时的仓库约定

官方文档 docs/help/scripts.md 对新增脚本给出了两条硬性要求：

• 保持聚焦且有文档：脚本职责单一，避免大而全；
• 在相关文档中补充条目：在对应文档（不存在则新建）中添加简短说明，让脚本可被发现、可被引用。

此外，从现有脚本可以观察到的工程惯例包括：统一使用set -euo pipefail、用SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"定位自身目录以便调用兄弟脚本、输出带颜色区分状态、为所有可配置项提供环境变量默认值等——新增脚本时建议沿用这些模式。

关联文档与进一步阅读

• 通用模型认证与 setup-token 完整流程：docs/gateway/authentication.md（其中也提示：旧的auth-profiles.json/auth-state.json可通过openclaw doctor --fix导入 SQLite，token 过期时用openclaw models status定位过期 profile）；
• 测试与线上测试：文档 docs/help/testing.md、docs/help/testing-live.md。

小结

OpenClaw 的scripts/目录是一套"小而聚焦"的运维工具箱：setup-auth-system.sh+claude-auth-status.sh+auth-monitor.sh+ systemd 定时器构成了从安装、检查到主动告警的完整监控闭环；mobile-reauth.sh与三个 Termux Widget 脚本把重认证从桌面带到了手机上；gh-read则用 GitHub App 只读令牌隔离了读与写两种权限。无论你是要在无头服务器上部署 OpenClaw，还是想复用这套"监控 + 手机兜底"的模式，都可以直接按本文介绍的方式查看脚本（仓库只读，请勿修改）并参考使用。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw