238 lines
4.9 KiB
Markdown
238 lines
4.9 KiB
Markdown
# @clawd/auth-runtime-py
|
||
|
||
Python 版本的 OpenClaw Auth Runtime。
|
||
|
||
## 全局配置
|
||
|
||
**所有 skill 共享同一份全局配置**，无需在每个 skill 中重复配置。
|
||
|
||
### 创建全局配置文件
|
||
|
||
```bash
|
||
# 复制模板
|
||
cp ~/.openclaw/.env.example ~/.openclaw/.env
|
||
|
||
# 编辑配置文件
|
||
vi ~/.openclaw/.env
|
||
```
|
||
|
||
### 配置文件内容
|
||
|
||
```bash
|
||
# ~/.openclaw/.env
|
||
|
||
# Auth Runtime 配置
|
||
CLIENT_KEY=sk_ae28fc4e.xxx
|
||
AUTH_BASE=https://api-gw-test.yuanwei-lnc.com
|
||
|
||
# Gemini API 配置（可选）
|
||
GEMINI_API_KEY=your-gemini-api-key
|
||
```
|
||
|
||
**注意**: `~/.openclaw/.env` 包含敏感信息，不要提交到 git。
|
||
|
||
---
|
||
|
||
## 安装
|
||
|
||
```bash
|
||
uv pip install /path/to/python_auth_runtime
|
||
```
|
||
|
||
---
|
||
|
||
## 使用方式
|
||
|
||
### 最简单的用法
|
||
|
||
```python
|
||
from python_auth_runtime import create_env_config, request_api_with_auto_refresh
|
||
|
||
# 自动从 ~/.openclaw/.env 加载配置
|
||
config = create_env_config()
|
||
|
||
# 调用 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"},
|
||
)
|
||
```
|
||
|
||
### 配置加载优先级
|
||
|
||
1. **环境变量**（最高优先级）
|
||
```bash
|
||
export CLIENT_KEY="override-key"
|
||
python script.py
|
||
```
|
||
|
||
2. **全局配置文件** `~/.openclaw/.env`
|
||
```bash
|
||
CLIENT_KEY=sk_ae28fc4e.xxx
|
||
```
|
||
|
||
3. **默认值**
|
||
- `AUTH_BASE`: `https://api-gw-test.yuanwei-lnc.com`
|
||
- `AUTH_CACHE_DIR`: `/tmp/skill-auth-cache`
|
||
- `AUTH_MIN_TTL_SEC`: `60`
|
||
|
||
---
|
||
|
||
## 完整示例
|
||
|
||
```python
|
||
#!/usr/bin/env python3
|
||
# your-skill/scripts/main.py
|
||
|
||
from python_auth_runtime import create_env_config, request_api_with_auto_refresh
|
||
import json
|
||
|
||
def main():
|
||
# 自动从 ~/.openclaw/.env 加载配置
|
||
config = create_env_config()
|
||
|
||
# 验证配置
|
||
if not config.client_key:
|
||
print("❌ CLIENT_KEY not found!")
|
||
print("Please create ~/.openclaw/.env with your CLIENT_KEY")
|
||
print("See: ~/.openclaw/.env.example")
|
||
return 1
|
||
|
||
# 调用 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.get("price"))
|
||
else:
|
||
print(f"❌ 失败：{response.status}")
|
||
print(response.body)
|
||
|
||
return 0
|
||
|
||
if __name__ == "__main__":
|
||
exit(main())
|
||
```
|
||
|
||
---
|
||
|
||
## API 参考
|
||
|
||
### 配置
|
||
|
||
#### `create_env_config() -> EnvConfig`
|
||
|
||
从环境变量创建配置（自动加载 `~/.openclaw/.env`）。
|
||
|
||
| 配置项 | 默认值 | 说明 |
|
||
|--------|--------|------|
|
||
| `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 请求并自动刷新令牌。
|
||
|
||
---
|
||
|
||
## 多 Agent Skill 配置
|
||
|
||
对于多 Agent skill，可以在全局配置中添加：
|
||
|
||
```bash
|
||
# ~/.openclaw/.env
|
||
|
||
# 主配置
|
||
CLIENT_KEY=sk_ae28fc4e.xxx
|
||
|
||
# Agent 特定配置
|
||
AGENT_1_CLIENT_KEY=sk_agent1.xxx
|
||
AGENT_2_CLIENT_KEY=sk_agent2.xxx
|
||
|
||
# 或者使用统一配置
|
||
# 所有 agent 共享同一个 CLIENT_KEY
|
||
```
|
||
|
||
在代码中：
|
||
|
||
```python
|
||
import os
|
||
from python_auth_runtime import create_env_config
|
||
|
||
# 主配置
|
||
config = create_env_config()
|
||
|
||
# 或者访问特定 agent 的配置
|
||
agent1_key = os.getenv("AGENT_1_CLIENT_KEY", config.client_key)
|
||
```
|
||
|
||
---
|
||
|
||
## 环境变量列表
|
||
|
||
| 变量 | 默认值 | 说明 |
|
||
|------|--------|------|
|
||
| `CLIENT_KEY` | **必需** | 客户端密钥 |
|
||
| `AUTH_BASE` | `https://api-gw-test.yuanwei-lnc.com` | 认证基础 URL |
|
||
| `AUTH_CACHE_DIR` | `/tmp/skill-auth-cache` | 缓存目录 |
|
||
| `AUTH_MIN_TTL_SEC` | `60` | 最小令牌 TTL（秒） |
|
||
| `GEMINI_API_KEY` | - | Gemini API Key（用于翻译） |
|
||
| `ECOM_BASE` | - | 1688 API 基础 URL |
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
```bash
|
||
cd /Users/xiaolongxia/Documents/ai-build-app/skills/excel-toolkit/python_auth_runtime
|
||
uv run python scripts/example_usage.py
|
||
```
|
||
|
||
---
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
python_auth_runtime/
|
||
├── src/python_auth_runtime/
|
||
│ └── __init__.py # 核心实现（自动加载全局配置）
|
||
├── scripts/
|
||
│ ├── load_env.py # .env 加载工具（可选使用）
|
||
│ └── example_usage.py # 使用示例
|
||
├── pyproject.toml
|
||
└── README.md
|
||
```
|
||
|
||
---
|
||
|
||
## 许可证
|
||
|
||
MIT
|