名称： claude-oauth-refresher
描述： 7x24 小时保持您的 Claude 访问令牌新鲜。在令牌过期前自动刷新 OAuth 令牌，从此告别身份验证失败。

claude-oauth-refresher

适用于 macOS 上 Claude Code CLI 的自动 OAuth 令牌刷新工具

通过在 OAuth 令牌过期前自动刷新，让您的 Claude 账户保持 7x24 小时登录状态。

⚠️ 系统要求

此技能仅适用于 macOS，并需要：

1. macOS（使用 Keychain 安全存储凭证）
2. 已安装 Claude Code CLI（claude 命令可用）
3. 已登录您的 Claude 账户（运行 claude 然后 login - 令牌将存储在 Keychain 中）
4. 已安装并运行 Clawdbot

不确定是否已设置完成？ 运行验证脚本：

./verify-setup.sh

功能概述

• 监控您的 Claude CLI 令牌过期时间
• 在令牌过期前自动刷新（默认：提前 30 分钟）
• 通过三种通知类型提醒您：
  • 🔄 开始："正在刷新 Claude 令牌..."
  • ✅ 成功："Claude 令牌已刷新！"
  • ❌ 失败：包含详细错误信息和故障排除步骤
• 记录所有刷新尝试，便于调试

安装

快速设置（推荐）

cd ~/clawd/skills/claude-oauth-refresher
./install.sh

此安装程序仅运行一次，并设置每 2 小时自动运行的令牌刷新任务。

安装程序将：
1. 验证您的系统是否满足要求
2. 交互式配置通知偏好
3. 自动检测您的通知目标（Telegram、Slack 等）
4. 设置 launchd 以实现自动刷新
5. 立即测试刷新功能

安装后：
- 配置更改会自动生效（刷新脚本每次运行都会读取配置）
- 编辑 claude-oauth-refresh-config.json 以更改设置
- 让 Clawdbot 为您修改设置
- 仅当需要重新安装或修复任务时才重新运行安装程序

交互式通知设置

安装过程中，系统会提示您：

配置通知：
💡 建议：首次运行时保持全部启用以验证功能。
   之后您可以通过以下方式禁用它们：
   1. 编辑 ~/clawd/claude-oauth-refresh-config.json
   2. 告诉 Clawdbot："disable Claude refresh notifications"

启用 "🔄 正在刷新令牌..." 通知？[Y/n]：
启用 "✅ 令牌已刷新！" 通知？[Y/n]：
启用 "❌ 刷新失败" 通知？[Y/n]：

建议： 初次使用时保持全部启用以验证功能，待确认一切正常后可禁用开始/成功通知。

使用 Clawdbot 管理通知

您可以让 Clawdbot 为您更改通知设置！ 无需手动编辑 JSON。

示例

禁用特定通知类型：

"disable Claude refresh start notifications"
"disable Claude refresh success notifications"
"turn off Claude token refresh start messages"

启用通知类型：

"enable Claude refresh start notifications"
"enable all Claude refresh notifications"
"turn on Claude token refresh success messages"

检查当前设置：

"show Claude refresh notification settings"
"what are my Claude token refresh notification settings?"

禁用所有通知：

"disable all Claude refresh notifications"
"turn off all Claude token notifications"

重置为默认值：

"reset Claude refresh notifications to defaults"

工作原理

Clawdbot 将：
1. 读取您的 ~/clawd/claude-oauth-refresh-config.json
2. 更新相应的通知标志
3. 保存文件
4. 确认更改

更改会立即生效于下一次刷新（无需重启任何服务）。

自动检测（智能默认值）

安装脚本会自动检测您的通知设置！

它会读取 ~/.clawdbot/clawdbot.json 以查找：
- 您启用了哪些消息通道
- 您的聊天 ID、电话号码或用户 ID
- 自动用这些值填充 claude-oauth-refresh-config.json

示例： 如果您启用了 Telegram 且聊天 ID 为 123456789，安装程序将创建：

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

要覆盖： 安装后只需编辑 claude-oauth-refresh-config.json 即可使用不同的通道或目标。

如果自动检测失败： 安装程序将提示您手动配置（请参阅下面的"查找您的目标 ID"）。

安装前测试检测：

./test-detection.sh
# 显示在不修改任何内容的情况下将自动检测到什么

查找您的目标 ID

要接收通知，您需要在 claude-oauth-refresh-config.json 中配置 notification_target。以下是各通道的查找方法：

Telegram

格式： 数字聊天 ID（例如：123456789）

如何查找：

# 方法 1：使用 Clawdbot CLI
clawdbot message telegram account list

# 方法 2：在 Telegram 上给 @userinfobot 发消息
# 发送任意消息，它会回复您的 ID

# 方法 3：检查最近的消息
clawdbot message telegram message search --limit 1 --from-me true

示例配置：

{
  "notification_channel": "telegram",
  "notification_target": "123456789"
}

Slack

格式：
- 私聊：user:U01234ABCD
- 频道：channel:C01234ABCD

如何查找：

# 列出频道
clawdbot message slack channel list

# 查找用户 ID
clawdbot message slack user list | grep "your.email@company.com"

# 或者在 Slack 中点击您的个人资料 → 更多 → 复制成员 ID

示例配置：

{
  "notification_channel": "slack",
  "notification_target": "user:U01234ABCD"
}

Discord

格式：
- 私聊：user:123456789012345678
- 频道：channel:123456789012345678

如何查找：

# 在 Discord 中启用开发者模式（设置 → 高级 → 开发者模式）
# 然后右键点击您的用户名 → 复制 ID

# 或者列出频道
clawdbot message discord channel list

示例配置：

{
  "notification_channel": "discord",
  "notification_target": "user:123456789012345678"
}

WhatsApp

格式： E.164 格式的电话号码（例如：+15551234567）

如何查找：
- 使用带国家代码的完整电话号码
- 格式：+[国家代码][号码]（无空格、破折号或括号）

示例：
- 美国：+15551234567
- 英国：+447911123456
- 澳大利亚：+61412345678

示例配置：

{
  "notification_channel": "whatsapp",
  "notification_target": "+15551234567"
}

iMessage

格式（推荐）： chat_id:123

如何查找：

# 列出最近的聊天以查找您的 chat_id
clawdbot message imessage thread list --limit 10

# 找到与您自己或首选设备的聊天

替代格式：
- 电话：+15551234567（E.164 格式）
- 邮箱：your.email@icloud.com

示例配置：

{
  "notification_channel": "imessage",
  "notification_target": "chat_id:123"
}

Signal

格式： E.164 格式的电话号码（例如：+15551234567）

如何查找：
- 使用您在 Signal 注册的电话号码
- 格式：+[国家代码][号码]（无空格、破折号或括号）

示例配置：

{
  "notification_channel": "signal",
  "notification_target": "+15551234567"
}

配置

文件： claude-oauth-refresh-config.json

{
  "refresh_buffer_minutes": 30,
  "log_file": "~/clawd/logs/claude-oauth-refresh.log",
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  },
  "notification_channel": "telegram",
  "notification_target": "YOUR_CHAT_ID"
}

选项

通知类型说明

🔄 开始 (on_start)
- 刷新过程开始时发送
- 适用于调试或了解刷新运行时间
- 建议： 验证功能正常后可禁用（可能产生较多通知）

✅ 成功 (on_success)
- 令牌成功刷新时发送
- 包含有效期信息（例如："有效期 24 小时"）
- 建议： 信任设置后可禁用（可能产生较多通知）

❌ 失败 (on_failure)
- 刷新失败时发送，包含详细的错误信息
- 根据错误类型提供故障排除步骤
- 建议： 保持启用！您需要了解失败情况。

配置示例

精简（仅失败通知）：

{
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": true
  }
}

详细（所有通知）：

{
  "notifications": {
    "on_start": true,
    "on_success": true,
    "on_failure": true
  }
}

静默（无通知）：

{
  "notifications": {
    "on_start": false,
    "on_success": false,
    "on_failure": false
  }
}

详细的失败消息

当刷新失败时，您将收到包含以下内容的详细通知：

1. 错误信息 - 出错原因
2. 详细信息 - 额外上下文（HTTP 代码、错误响应等）
3. 故障排除 - 基于错误类型的具体步骤
4. 帮助 - 查找日志和获取支持的途径

失败通知示例

❌ Claude 令牌刷新失败

错误：连接 auth.anthropic.com 网络超时
详情：连接在 30 秒后超时

故障排除：
- 检查您的互联网连接
- 验证是否可以访问 auth.anthropic.com
- 尝试手动运行：~/clawd/skills/claude-oauth-refresher/refresh-token.sh

需要帮助？联系 Clawdbot 或查看日志：
~/clawd/logs/claude-oauth-refresh.log

常见错误及解决方案

网络/超时错误

故障排除：
- 检查您的互联网连接
- 验证是否可以访问 auth.anthropic.com
- 尝试手动运行：./refresh-token.sh

无效的刷新令牌

故障排除：
- 您的刷新令牌可能已过期
- 重新认证：claude auth logout && claude auth
- 验证 Keychain 访问：security find-generic-password -s 'claude-cli-auth' -a 'default'

Keychain 访问被拒绝

故障排除：
- 检查 Keychain 权限
- 重新运行认证：claude auth
- 验证设置：./verify-setup.sh

缺少认证配置文件

故障排除：
- 运行：claude auth
- 验证文件是否存在：~/.config/claude/auth-profiles.json
- 检查文件权限：chmod 600 ~/.config/claude/auth-profiles.json

使用

检查状态

# 查看最近日志
tail -f ~/clawd/logs/claude-oauth-refresh.log

# 检查 launchd 状态
launchctl list | grep claude-oauth-refresher

# 手动刷新（用于测试）
cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

修改设置

方法 1：询问 Clawdbot（最简单）

"disable Claude refresh start notifications"
"show Claude refresh notification settings"

方法 2：编辑配置文件

nano ~/clawd/skills/claude-oauth-refresher/claude-oauth-refresh-config.json

更改会在下次刷新时自动生效（每 2 小时，或手动运行时）。

无需重启任何服务！ 刷新脚本每次运行都会读取配置文件。

故障排除

问题：verify-setup.sh 显示 Claude CLI 未找到

解决方案：

# 安装 Claude CLI
brew install claude

# 或从 https://github.com/anthropics/claude-cli 下载

问题：verify-setup.sh 显示未找到刷新令牌

解决方案：

# 使用 Claude 进行认证
claude auth

# 按照提示登录

问题：未收到通知

解决方案：
1. 检查您的 notification_target 格式是否与上述示例匹配
2. 手动测试：
bash clawdbot message [channel] send --target "[your_target]" --message "Test"
3. 检查 Clawdbot 是否运行：clawdbot gateway status
4. 验证通知设置：
bash cat ~/clawd/skills/claude-oauth-refresher/claude-oauth-refresh-config.json | jq .notifications

问题：令牌刷新失败，提示 "invalid_grant"

解决方案：

# 从头开始重新认证
claude auth logout
claude auth

# 再次测试刷新
cd ~/clawd/skills/claude-oauth-refresher
./refresh-token.sh

问题：升级后出现"找不到配置文件"

解决方案：
配置文件已从 config.json 重命名为 claude-oauth-refresh-config.json。

# 如果您有旧的 config.json，请运行安装程序进行迁移：
cd ~/clawd/skills/claude-oauth-refresher
./install.sh
# 出现提示时选择保留现有配置

问题：需要重新安装或修复任务

解决方案：

# 重新运行安装程序（可安全多次运行）
cd ~/clawd/skills/claude-oauth-refresher
./install.sh

安装程序将：
- 检测现有配置并询问是否保留
- 更新 launchd 任务
- 测试刷新功能

卸载

cd ~/clawd/skills/claude-oauth-refresher
./uninstall.sh

这将：
- 停止并卸载 launchd 服务
- 删除 plist 文件
- 可选删除日志和配置

工作原理

1. 安装程序 (install.sh) - 运行一次以设置：

   • 自动检测通知目标
   • 交互式配置通知类型
   • 创建 launchd 任务
   • 立即测试刷新功能

2. Launchd - 每 2 小时自动运行 refresh-token.sh

3. 刷新脚本 (refresh-token.sh) - 每次运行时：

   • 读取配置文件（更改自动生效！）
   • 从 ~/.config/claude/auth-profiles.json 检查令牌过期时间
   • 如果令牌在缓冲窗口内过期（默认 30 分钟）：
     • 发送开始通知（如果启用）
     • 从 Keychain 检索刷新令牌
     • 调用 OAuth 端点获取新令牌
     • 更新认证配置文件和 Keychain
     • 发送成功通知（如果启用）
   • 如果刷新失败：
     • 发送包含故障排除的详细失败通知
   • 所有活动记录到 ~/clawd/logs/claude-oauth-refresh.log

4. 配置更改 - 自动应用：

   • 随时编辑 claude-oauth-refresh-config.json
   • 让 Clawdbot 为您编辑
   • 更改在下一次刷新时生效
   • 无需重启！

安全性

• 令牌从不写入日志或配置文件
• 刷新令牌安全存储在 macOS Keychain 中
• 访问令牌缓存在 ~/.config/claude/auth-profiles.json 中（权限：600）
• 所有 HTTP 请求均使用 Claude 官方 OAuth 端点
• 配置文件为全局可读（不包含任何密钥）

支持

日志： ~/clawd/logs/claude-oauth-refresh.log

问题排查步骤：
1. 运行 ./verify-setup.sh 进行诊断
2. 检查日志获取详细错误信息
3. 测试手动刷新：`./refresh-token.sh