Palm Agent 接入指南
给 AI Agent 颁发「真人认领」的身份凭证；并让 Agent 的每一次危险操作，都必须再回到真人手上刷一次掌。
概述
本文档帮助第三方业务方将自己的 AI Agent 接入 Palm，主要解决两件事：
-
Agent 身份 — 让一台 Agent（脚本 / 机器人 / 自动化进程）以「某个真人」的身份运行。真人通过 PalmxApp 扫码刷掌后，Agent 获得一对 Ed25519 密钥的「认领凭证」，业务方据此知道「这台 Agent 背后是我系统里的哪个用户」。
-
操作级 Step-up 核验 — 身份对了 ≠ 这一笔操作真人同意了。Agent 发起高危操作（转账、提现、删除等）时，业务方调用 Step-up 接口，要求真人在 PalmxApp 上当场刷掌确认，确认通过后业务方拿到一张 Assertion JWT 作为放行凭证。
与 OAuth 接入的关系：OAuth 验证的是「人类用户」，Agent 验证的是「代表人类的 AI」。两条链路接口独立（
/x/agent/*vs/x/oauth/*），可单独接入。
角色与前置
| 角色 | 身份 / 鉴权 | 职责 |
|---|---|---|
| Agent 客户端 | app_id（公开）+ 本地 Ed25519 私钥自签 | 生成密钥、发起注册、对每次业务请求签名 |
| 业务方后端 | api_key（product_code='agent' 应用） | 换取 open_id、验签、发起 Step-up |
| 真人 owner | PalmxApp 登录态 | 扫码刷掌确认授权、管理 / 吊销 Agent |
接入前置：
- 在 Palm 控制台创建一个
product_code='agent'的应用，拿到app_id（公开）和api_key（业务方后端密钥，env-only 保存，切勿下发到 Agent 客户端）。 - 用户须事先用 Palm 在你的系统登录 / 绑过号，即你的系统里已存在
open_id ↔ 本地账号的映射。Agent 是「代表一个已存在账号」行事，无此绑定则授权无法完成。
接口域名： https://open.palmoa.youtu.qq.com
| 调用方 | 网关前缀 |
|---|---|
| Agent 客户端（无 api_key） | /palm/openai/x/agent/... |
| 业务方后端（api_key） | /palm/openai/x/agent/...，带 Authorization: Bearer <api_key> |
| PalmxApp（真人登录态） | /palm/openconsole/x/agent/... |
业务方接口入参不需要传
app_id—— 网关从 api_key 自动注入（oc_appid），服务端用(oc_appid, device_id)定位 Agent，并强制校验「你只能操作自己 app 下的 Agent」。
全链路总览
[授权阶段]
┌─ Agent 客户端 ──────────────────────────────────────────────┐
│ 1. 本地生成 Ed25519 密钥对（私钥永不出本机） │
│ 2. 自签调 register/init → 拿 registration_url + session_id │
└──────────────────────────────────────────────────────────────┘
│ 把 registration_url 交给真人打开
↓
┌─ 真人 / PalmxApp ───────────────────────────────────────────┐
│ 3. 浏览器打开 url → PalmxApp 扫码 → 刷掌确认 + 选授权时长 │
│ 服务端单事务：t_agent=active + 绑定 owner + 生成一次性 code │
└──────────────────────────────────────────────────────────────┘
↓
┌─ Agent 客户端 ──────────────────────────────────────────────┐
│ 4. 用 session_id 轮询 register/status → 拿 status + 一次性 code│
│ （拿到的是 code，不是 open_id） │
└──────────────────────────────────────────────────────────────┘
│ 把 code 交给业务方
↓
┌─ 业务方后端（api_key）─────────────────────────────────────┐
│ 5. code/exchange → 拿 (device_id, open_id) │
│ 6. 用 open_id 查本地账号绑定：命中→授权完成；未命中→失败 │
└──────────────────────────────────────────────────────────────┘
[每次业务请求]
7. Agent 用私钥对「canonical 串(含 body_hash+ts+nonce)」签名，带 device_id 发给业务方
8. 业务方按 (open_id, device_id) 拉公钥缓存（TTL≤15min），本地验签 + 校 ts + nonce 去重
[高危操作 —— 必须真人当场刷掌]
9. 业务方对高危动作调 stepup/create → 真人 PalmxApp 刷掌 → 服务端签 Assertion JWT
10. 业务方 stepup/query 拿 JWT → 验签 + 重算 action_detail_hash + jti 去重 → 才执行
接入分为三个阶段，请继续阅读后续文档：