开发者：访问令牌与 MCP

适用读者

需要用程序、AI 客户端或别的 Agent 调用某个 Agent 网址下应用的人。普通用户请从 出门也能用家里的 Agent 开始。

本页会用到几个术语：地址名（handle，网址最前面那一段）、应用（service，主人电脑上登记的一个本地端口）、宿主（运行 UUMit 电脑客户端的那台电脑）。

地址结构

用途	形式
地址主页	https://<handle>.agent.example/
路径式应用	https://<handle>.agent.example/s/<service>/
独立主机名应用	https://<service>--<handle>.agent.example/
Agent Card	https://<handle>.agent.example/.well-known/agent-card.json
验签公钥	https://agent.example/.well-known/jwks.json

内地版把域名换成 agent-cn.example。两个版本的账号与数据互不相通。Agent Card 由平台签名，调用方应使用 JWKS 验签后再信任其中的能力描述。

凭证

凭证	请求方式	适用
浏览器会话	Cookie（登录 UUMit 后自动携带）	浏览器
个人访问令牌（PAT）	Authorization: Bearer pat_…	脚本、自动化
平台 API Key	X-Api-Key + X-Platform-User-Id	接入平台的第三方 Agent
OAuth 访问令牌	Authorization: Bearer …（经同意页获得）	MCP 客户端
短期访问令牌	Authorization: Bearer aat_…，只能访问一个应用	原生客户端

网关校验后会去掉这些凭证再转发给宿主，宿主上的应用看不到你的 UUMit 凭证。调用方是否有权使用，取决于主人为该应用设置的「谁能用」与授权。

MCP 客户端接入

注意

MCP 授权在 P1 末开放，由功能开关 feature_flag.agent_address_mcp_oauth 控制；未开放时返回 FEATURE_REQUIRED。

1. 把应用的 MCP 地址（路径式或独立主机名，加上应用自己的 MCP 路径）填进客户端。

2. 客户端收到 401 后，按 WWW-Authenticate 头中的 resource_metadata 发现授权服务器，并完成注册（元数据文档或动态注册）。

3. 浏览器打开 UUMit 同意页，主人或被授权人确认后，客户端获得只对这个应用有效的访问令牌。

4. 同意随时可在「谁能用我的东西」中撤销，撤销后令牌立即失效。

原生客户端

短期访问令牌

uumit-connector access login            # 首次：保存 PAT
uumit-connector access token alice/notes
# 输出 Bearer aat_…，15 分钟有效；--raw 只输出令牌

OpenClaw 远程

uumit-connector openclaw remote alice

写入 OpenClaw 配置的 gateway.remote.url 与 edgeAuth（写入前自动备份），由 OpenClaw 在每次连接时取短期访问令牌。

本地转发

不支持自定义请求头的客户端，把应用转发到本机端口：

uumit-connector access alice/notes --listen 127.0.0.1:8080

TCP / SSH

uumit-connector access alice/ssh --listen 127.0.0.1:2222

或在 ~/.ssh/config 中：

Host alice-ssh
  ProxyCommand uumit-connector access alice/ssh --stdio

SSH 类应用默认要求二次验证。

二次验证

访问开启了「用手机确认是你本人」的应用时，可能返回 STEP_UP_REQUIRED，响应中带 challenge_id。调用方应：

1. 提示用户在手机上确认；
2. 轮询 GET /api/v1/agent-address/step-up/challenges/{challenge_id}，直到 approved 或过期；
3. 通过后用同一请求重试。

uumit-connector access token 默认等待确认（--wait-step-up 秒，0 表示不等待）。

错误与重试

• 错误响应带稳定的 code，请按 code 分支，不要解析文案。
• 4xx 是调用方问题，不要重试；5xx 可以退避重试。
• 429 按 Retry-After 秒数退避。
• 非幂等请求重试时带同一个 Idempotency-Key，网关会原样转发给宿主，由应用去重。
• 宿主离线或应用无响应返回 502 / 504 类错误，可稍后重试；ROUTE_NOT_FOUND 表示地址或应用不存在，不要重试。

完整错误码见 错误码与限流。

技能与命令行

• UUMit 技能（uumit-shared / uumit-publish）：随电脑客户端分发，让 Claude Code、Codex、OpenClaw 用本机 uumit-connector 命令行发布应用、邀请成员；让所有人都能打开前会先在对话里确认（uumit-connector skills read uumit-publish 查看全文）。
• npx @uumit-ai/uumit share <端口>：一条命令分享网页。
• npx @uumit-ai/uumit address status：查看当前账号下每个应用谁能用。