5.0 KiB

Raw Blame History

OpenClaw Auth Runtime Python 实现

基于 ~/clawd/skills/_shared/auth-runtime 的 TypeScript 实现，提供 Python 版本的客户端密钥认证。

功能特性

✅ 使用 CLIENT_KEY 获取访问令牌
✅ 支持令牌缓存（可配置 TTL）
✅ 自动刷新过期令牌
✅ 401/403 自动重试
✅ 从 .env 文件自动加载配置

快速开始

1. 配置环境变量

在 .env 文件中设置 CLIENT_KEY：

# 从 ~/clawd/skills/_shared 获取 CLIENT_KEY
CLIENT_KEY=your-client-key-here

2. 获取访问令牌

from auth_runtime import create_env_config, get_access_token

# 创建配置（自动从环境变量加载）
config = create_env_config()

# 获取访问令牌（带缓存）
token = get_access_token(dry_run=False, config=config)

3. 发送 API 请求

from auth_runtime import request_api_with_auto_refresh

# 发送请求（自动处理令牌刷新）
response = request_api_with_auto_refresh(
    method="POST",
    url="https://api-gw-test.yuanwei-lnc.com/your-api-endpoint",
    dry_run=False,
    config=config,
    body={"key": "value"},
)

print(f"状态码：{response.status}")
print(f"响应体：{response.body}")

API 参考

配置

`create_env_config() -> EnvConfig`

从环境变量创建配置：

环境变量	默认值	说明
`AUTH_BASE`	`https://api-gw-test.yuanwei-lnc.com`	认证基础 URL
`CLIENT_KEY`	必需	客户端密钥
`AUTH_CACHE_DIR`	`/tmp/skill-auth-cache`	缓存目录
`AUTH_MIN_TTL_SEC`	`60`	最小令牌 TTL（秒）

令牌管理

`get_access_token(dry_run, config) -> str`

获取访问令牌（带缓存）：

检查缓存
如果缓存有效，返回缓存令牌
否则请求新令牌并缓存

`refresh_access_token(dry_run, config) -> str`

刷新访问令牌（绕过缓存）

API 请求

`request_api(method, url, auth_token, body) -> ApiResponse`

发送 HTTP 请求

`request_api_with_auto_refresh(method, url, dry_run, config, body) -> ApiResponse`

发送 API 请求并自动刷新令牌：

使用当前令牌发送请求
如果是 401/403 错误，刷新令牌并重试一次

便捷函数

`load_client_key_from_env(env_path) -> str`

从 .env 文件加载 CLIENT_KEY

优先级：

环境变量 CLIENT_KEY
.env 文件中的 CLIENT_KEY
抛出异常

使用示例

示例 1: 简单的 API 调用

from auth_runtime import create_env_config, request_api_with_auto_refresh

config = create_env_config()

response = request_api_with_auto_refresh(
    method="POST",
    url=f"{config.auth_base}/your-endpoint",
    dry_run=False,
    config=config,
    body={"url": "https://example.com"},
)

if response.status == 200:
    print("成功:", response.body)
else:
    print("失败:", response.status, response.body)

示例 2: 结合 Excel 翻译使用

from auth_runtime import create_env_config, request_api_with_auto_refresh
import json

config = create_env_config()

# 调用 1688 API 获取商品详情
response = request_api_with_auto_refresh(
    method="POST",
    url=f"{config.auth_base}/ecom/tasks/scrape",
    dry_run=False,
    config=config,
    body={"url": "https://detail.1688.com/offer/123.html"},
)

if response.status == 200:
    data = json.loads(response.body)
    print("商品价格:", data["price"])

缓存机制

令牌缓存位置：/tmp/skill-auth-cache/token_<hash>.json

缓存文件内容：

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": 1234567890.123,
  "expires_in": 900
}

缓存策略：

令牌在过期前 AUTH_MIN_TTL_SEC 秒内视为无效
默认最小 TTL 为 60 秒
缓存文件自动创建和删除

错误处理

常见错误

错误	原因	解决方案
`CLIENT_KEY is required`	未设置 CLIENT_KEY	在 .env 文件或环境变量中设置
`Auth session request failed`	认证请求失败	检查 CLIENT_KEY 是否有效
`Missing accessToken`	认证响应缺少令牌	检查认证服务是否正常

自动重试

以下情况会自动刷新令牌并重试一次：

HTTP 401 Unauthorized
HTTP 403 Forbidden
响应体包含 "expired"、"unauthorized" 等标记

测试

运行测试脚本：

cd /Users/xiaolongxia/Documents/ai-build-app/skills/excel-toolkit
uv run python scripts/test_auth.py

与 TypeScript 版本的差异

特性	TypeScript	Python
HTTP 客户端	原生 fetch	requests
缓存文件	Bun/Node fs	pathlib
环境变量	process.env	os.getenv
类型系统	TypeScript	dataclass

功能完全对等，可以互换使用。

获取 CLIENT_KEY

CLIENT_KEY 存储在 ~/clawd/skills/_shared 目录中。

查看相关文档：

~/clawd/skills/_shared/AUTH_RUNTIME_IMPLEMENTATION.md
~/clawd/skills/_shared/auth-runtime/README.md

许可证

与 OpenClaw 项目保持一致。

5.0 KiB Raw Blame History Unescape Escape