Agent 集成：作用域密钥 axn_* 与最小权限实践
让 AI Agent 安全管理你的资源：作用域令牌按最小权限发放、凭据只走环境注入、工具调用面对齐错误契约、审计留痕。附完整的接入五步与一个「内容助理 Agent」的权限设计实例。
Agent 是新时代的运维实习生：能干、不知疲倦、但给的权限必须像对实习生一样抠。本篇讲怎么让 Agent 安全地管理你的站内资源：作用域密钥的发放纪律、凭据注入方式、工具面设计与审计闭环——五步接入，每步可验证。本文属于开发者中心栏目；接口全貌先读API 参考总览。
第一步：作用域令牌——最小权限不是口号
本站管理 API 支持三类钥匙（主密钥/会话/作用域令牌），Agent 只用第三类：axn_* 作用域令牌——按 scope 词表（articles/markets/courses/settings/tokens/ops/ugc 等）授权，可单独吊销、互不牵连。发放纪律三条：
- 一个 Agent 一把钥匙：多个 Agent 共用令牌 = 审计失效 + 吊销连坐；
- scope 按任务白名单：内容助理只给 articles，行情机器人只给 markets——「顺手给全权限」是事故的首付款；
- 生命周期有人管：令牌写进台账（谁、什么 scope、何时发、何时轮换），90 天轮换是合理默认。
# 用主密钥（环境变量注入，勿入命令行历史）签发一把文章域令牌：
curl -s -X POST https://axionserve-portal.aeronest-global.workers.dev/api/admin/tokens -H "Authorization: Bearer $AX_MASTER" -H "Content-Type: application/json" -d '{"name":"content-agent","scopes":"articles"}'
# 响应含明文令牌（仅此一次显示）→ 立即写入 Agent 运行环境的 secret 存储
# 验证作用域边界（拿文章令牌碰设置 → 应 403）：
curl -s -o /dev/null -w "%{http_code}\n" -H "Authorization: Bearer $AXN_CONTENT" https://axionserve-portal.aeronest-global.workers.dev/api/admin/settings # 期望 403第二步：凭据注入——Agent 拿钥匙的正确姿势
- 环境变量或平台 secret 存储：令牌在运行时注入进程环境，不进代码仓库、不进日志、不进提示词——三条红线对 Agent 比对人更重要，因为 Agent 的对话记录与工具调用日志会被系统性留存；
- 提示词里永远只有引用：系统提示写「用环境变量 AXN_CONTENT 里的令牌调用」，不写令牌值本身——防提示注入攻击的第一道墙（Agent 被诱导输出上下文时，值不在上下文里）；
- 怀疑即轮换：日志里出现过令牌明文、Agent 行为异常、第三方工具接触过环境——三种情况都立即吊销重发，成本是五分钟，不做的成本无上限。
第三步：工具面设计——让 Agent 的每个动作可预期
把 API 包装成 Agent 工具（function calling / MCP tool 的描述层）时的四个设计点：
- 描述里写边界：工具描述明确「这个工具会发布内容到生产」——让模型的规划层知道动作的重量级；
- 写操作加确认层：发布/删除类工具走「先草稿后发布」两段式，或加人工确认参数——本站内容治理的 R5 纪律（AI 内容一律 draft 待人工审批）就是这一层的制度化；
- 错误契约直通模型：把 {error, code, requestId} 信封原样回传给模型——code 是机器可读的，模型能按 40xxx（改参数重试）与 403xx（权限不足，别重试）正确分支；
- 速率自觉：工具描述里写明限速（写操作 60 req/min 量级、批间隔 ≥2s），让 Agent 的规划自带节流。
第四步：审计闭环——每个动作都能回放
本站管理端写操作全部落审计日志（actor/IP/动作/对象），Agent 接入后的对账节奏：每日看异常动作（非工作时间的写操作、高频失败）、每周对台账（令牌使用与预期任务是否吻合）、每月轮换。Agent 侧同样留档：工具调用记录（哪个模型、什么输入、调了什么、返回什么）与站内审计对得上，事故回溯才是双向的。审计数据的最低保留期建议 90 天（与本站管理端审计保留策略同量级）；对账发现的三类异常要立即处置：越权尝试（scope 设计有漏）、高频失败（工具描述或参数映射有问题）、非任务时段活动（令牌可能外流）——第三类直接触发轮换。
第五步：实例——内容助理 Agent 的权限设计
| 任务 | 工具 | 所需 scope | 护栏 |
|---|---|---|---|
| 起草文章 | POST articles（status=draft） | articles | 只产 draft，发布走人工 |
| 体检字数/图/表 | GET admin articles（stats 字段） | articles | 只读 |
| 修订内容 | PUT articles/{slug} | articles | 已发布条目禁改（先转 draft） |
| 行情建档 | POST markets（null 语义） | markets | 无实测数据必须置 null |
| 发布上线 | —（不给） | — | 人工保留的最后一环 |
这张表就是最小权限的具象：Agent 拿到完成任务的刚好权限，发布权永远在人手里——本门户自己的内容生产就按这张表运转（46+ 篇草稿全部待人工审批，即本栏目的现场证据）。
接入验证清单
# 五连验证（接入完成后逐条跑；PORTAL=门户 API 域名，令牌走环境变量）
# ① 作用域生效：越权访问 → 期望 403
curl -s -o /dev/null -w "%{http_code}
" -H "Authorization: Bearer $AXN_CONTENT" $PORTAL/api/admin/settings
# ② 错误契约：坏参数 → 期望 40xxx 信封带 requestId
curl -s -X POST $PORTAL/api/admin/articles -H "Authorization: Bearer $AXN_CONTENT" -H "Content-Type: application/json" -d '{"slug":"x"}'
# ③ 限速：快速连发写请求观察 429 与退避
for i in 1 2 3; do curl -s -o /dev/null -w "%{http_code} " -X POST $PORTAL/api/admin/articles -H "Authorization: Bearer $AXN_CONTENT" -d '{}'; done; echo
# ④ 审计：管理端审计日志里能看到 Agent 的每次写操作（actor 与 IP 对得上）
curl -s -H "Authorization: Bearer $AX_MASTER" "$PORTAL/api/admin/audit?limit=5"
# ⑤ 吊销：控制台吊销旧令牌后 → 期望 401，Agent 应报告而非静默失败
curl -s -o /dev/null -w "%{http_code}
" -H "Authorization: Bearer $AXN_OLD_REVOKED" $PORTAL/api/admin/articles?limit=1相关文档：API 参考总览 · Webhook 与事件 · SDK 与库。Agent 安全的攻击面全景（提示注入/凭据/最小权限）在AI 与 Agent 安全（安全批次）；趋势背景见未来 Web 与 Agent；栏目首页回开发者中心。