agentcloud

AgentCloud（AI Agent 云存储）— 一键注册 Agent，上传/下载文件，创建分享链接，查询用量。支持 Hermes Agent 和 OpenClaw 用户直接使用。

AgentCloud Skill

为 AI Agent 打造的云存储服务。让你的 Agent 拥有专属文件存储空间，支持跨 Agent 文件传输和分享。

快速开始

一键注册 Agent（无需手机/邮箱，无需先注册人类账号）

只需一个命令，Agent 就能获得专属存储空间：

bash

curl -X POST https://api.traceclaw.cn/api/v1/agents/register/open \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent"}'

# 返回示例
# {
#   "agent_id": "agt_xxxxx",
#   "api_key": "avk_yyyyy",   # ← 保存好！只返回一次
#   "name": "my-agent",
#   "plan": "free",
#   "total_storage_mb": 30
# }

⚠️ api_key 只返回一次，请妥善保存。如果丢失，可在 Dashboard 重置。

设置 API Key

bash

# 保存到环境变量（推荐）
export AGENTCLOUD_KEY="avk_yyyyy"

# 或直接写在请求头中
# X-Agent-Key: avk_yyyyy

API 概览

所有请求都通过 https://api.traceclaw.cn/api/v1 访问。

方法	路径	认证	说明
POST	/agents/register/open	无（开放注册，限频3次/小时/IP）	注册新 Agent
GET	/agents/me	X-Agent-Key	查询本 Agent 信息
POST	/agents/{id}/reset-key	X-Agent-Key	重置 API Key
DELETE	/agents/{id}	X-Agent-Key	删除 Agent
POST	/files/upload	X-Agent-Key	上传文件
GET	/files/download/{id}	X-Agent-Key	下载文件
GET	/files	X-Agent-Key	文件列表
DELETE	/files/{id}	X-Agent-Key	删除文件
POST	/files/{id}/share	X-Agent-Key	创建分享链接
GET	/files/shared/{token}	无需认证	通过分享链接下载

认证方式：Agent 使用 X-Agent-Key 请求头，值为注册时获得的 avk_xxx API Key。

Python 使用示例

安装依赖

bash

pip install requests

注册 Agent

python

import requests

BASE = "https://api.traceclaw.cn/api/v1"

# 注册（无需任何认证）
r = requests.post(f"{BASE}/agents/register/open", json={"name": "my-agent"})
data = r.json()

api_key = data["api_key"]  # 保存好！
agent_id = data["agent_id"]
print(f"注册成功！Agent ID: {agent_id}")

上传文件

python

API_KEY = "avk_xxxxx"  # 注册时获得的 Key

with open("report.pdf", "rb") as f:
    r = requests.post(
        f"{BASE}/files/upload",
        files={"file": ("report.pdf", f, "application/pdf")},
        headers={"X-Agent-Key": API_KEY}
    )
file_id = r.json()["file_id"]
print(f"上传成功！File ID: {file_id}")

下载文件

python

r = requests.get(
    f"{BASE}/files/download/{file_id}",
    headers={"X-Agent-Key": API_KEY}
)
with open("downloaded.pdf", "wb") as f:
    f.write(r.content)

创建分享链接（给其他 Agent）

python

# 生成 1 小时有效分享链接
r = requests.post(
    f"{BASE}/files/{file_id}/share",
    json={"expires_in": 3600},
    headers={"X-Agent-Key": API_KEY}
)
share_token = r.json()["share_token"]
share_url = f"https://api.traceclaw.cn/api/v1/files/shared/{share_token}"
print(f"分享链接: {share_url}")

# 对方无需认证即可下载
r = requests.get(share_url)
with open("shared_file.pdf", "wb") as f:
    f.write(r.content)

查看文件列表

python

r = requests.get(
    f"{BASE}/files",
    headers={"X-Agent-Key": API_KEY}
)
files = r.json()
for f in files:
    print(f"{f['filename']} — {f['file_size']} bytes")

查询 Agent 信息

python

r = requests.get(
    f"{BASE}/agents/me",
    headers={"X-Agent-Key": API_KEY}
)
print(r.json())
# {
#   "agent_id": "agt_xxx",
#   "name": "my-agent",
#   "total_storage_mb": 30,
#   "used_storage_mb": 1.2,
#   "subscription_end": null
# }

curl 一行命令版

bash

# 注册
curl -s -X POST https://api.traceclaw.cn/api/v1/agents/register/open \
  -H "Content-Type: application/json" \
  -d '{"name":"my-agent"}'

# 上传文件
curl -s -X POST https://api.traceclaw.cn/api/v1/files/upload \
  -H "X-Agent-Key: avk_xxxxx" \
  -F "file=@myfile.pdf"

# 下载文件
curl -s -o output.pdf \
  https://api.traceclaw.cn/api/v1/files/download/{file_id} \
  -H "X-Agent-Key: avk_xxxxx"

# 创建分享链接
curl -s -X POST https://api.traceclaw.cn/api/v1/files/{file_id}/share \
  -H "X-Agent-Key: avk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"expires_in": 3600}'

# 查看文件列表
curl -s https://api.traceclaw.cn/api/v1/files \
  -H "X-Agent-Key: avk_xxxxx" | jq .

Web 管理后台

注册后可通过浏览器管理文件：

• 首页: https://agentcloud.traceclaw.cn
• 登录: https://agentcloud.traceclaw.cn/login
• 控制台: https://agentcloud.traceclaw.cn/dashboard

登录后可查看存储使用量、管理上传的文件、查看 API Key。

套餐说明

AgentCloud 采用会员制：

套餐	价格	存储空间
🆓 免费	¥0	30 MB
⭐ VIP	¥6/月	600 MB
💎 SVIP	¥30/月	3.2 GB
👑 SVIP+	¥128/月	15 GB

注册即送免费额度，可通过 Web 后台充值升级。

OpenClaw / OpenCode 用户使用

安装方式

OpenClaw/OpenCode 不支持 hermes skills install，但支持本地 skill 目录发现。有两种方式让 skill 生效：

方式一：直接克隆仓库用 CLI 脚本

bash

git clone https://github.com/jiangzh0202/agentcloud-skill.git ~/agentcloud-skill
cd ~/agentcloud-skill
pip install requests
python3 scripts/agentcloud.py register
python3 scripts/agentcloud.py me

方式二：让 OpenClaw 自动发现 SKILL.md

bash

# 全局安装（所有项目生效）
mkdir -p ~/.config/opencode/skills/agentcloud
cp ~/agentcloud-skill/SKILL.md ~/.config/opencode/skills/agentcloud/

# 或项目级安装（仅当前项目生效）
mkdir -p .opencode/skills/agentcloud
cp ~/agentcloud-skill/SKILL.md .opencode/skills/agentcloud/

OpenClaw/OpenCode 会自动从 ~/.config/opencode/skills/、.opencode/skills/、.claude/skills/、.agents/skills/ 目录加载 skill。安装后 Agent 在对话中可自动发现并使用。

在代码中调用 API

python

# OpenClaw 脚本示例
import requests

# 注册（开放注册，无需任何前置条件）
r = requests.post("https://api.traceclaw.cn/api/v1/agents", json={
    "name": context.agent.name  # 使用 Agent 自身名称
})
config = r.json()
context.memory.set("agentcloud_key", config["api_key"])

# 上传文件
r = requests.post(
    "https://api.traceclaw.cn/api/v1/files/upload",
    files={"file": open("/tmp/result.txt", "rb")},
    headers={"X-Agent-Key": config["api_key"]}
)
file_id = r.json()["file_id"]

助手脚本

本技能附带了一个 Python 助手脚本 agentcloud.py，提供更便捷的接口：

bash

# 一键注册
python3 agentcloud.py register

# 上传文件
python3 agentcloud.py upload myfile.pdf

# 下载文件
python3 agentcloud.py download <file_id> -o output.pdf

# 查看文件列表
python3 agentcloud.py list

# 分享文件
python3 agentcloud.py share <file_id> --expires 3600

详细用法见脚本文件。

注意事项

1. API Key 安全：avk_xxx 是 Agent 的唯一凭证，不要泄露
2. 文件大小限制：单文件最大 500MB（Nginx 限制）
3. 存储限制：免费用户 30MB，超出后上传会被拒绝
4. 分享过期：分享链接默认 24 小时有效，可自定义过期时间
5. 跨 Agent 传输：A Agent 创建分享链接 → B Agent 用链接下载，无需 B 有 API Key

服务状态

• API: https://api.traceclaw.cn/health
• 网站: https://agentcloud.traceclaw.cn
• 服务条款: 使用即表示同意合理使用，禁止存储违法内容