Appearance
第 9 章：外部 API、密钥与权限边界
本章目标
掌握接入外部 API 前后的通用检查方法：先判断是否真的需要外部服务，再配置最小权限凭证，用非敏感样本测试请求、结果、日志、费用和撤销路径。具体服务、接口格式和 WorkBuddy 配置入口以当前版本为准。
适用场景
- 当前产品能力不足，需要调用组织批准的外部服务；
- 使用自有模型或数据服务，需要配置 API 密钥；
- 需要判断本地服务、代理服务或云端 API 的数据边界；
- 发现密钥失效、超额、泄露或不再需要时进行处理。
前置条件
- 明确 API 的用途、输入输出、费用和数据处理政策；
- 取得账号所有者或组织管理员授权；
- 准备测试密钥、测试项目或低权限账号；
- 有安全的密钥存放位置，不把密钥写进提示词、公开文档或代码仓库。
核心概念
| 概念 | 说明 | 需要控制什么 |
|---|---|---|
| Endpoint | API 请求的目标地址 | 来源、传输方式和环境 |
| 认证凭证 | API Key、令牌或其他身份材料 | 最小权限、有效期和轮换 |
| 输入输出 | 发送给服务的数据和返回的结果 | 敏感字段、保留期限和脱敏 |
| 配额与计费 | 请求次数、消耗和费用限制 | 预算、告警和停用条件 |
| 日志 | 请求、错误和调用结果的记录 | 是否会记录密钥或敏感内容 |
分步操作
- 先判断必要性。 先查看当前 WorkBuddy 已有能力；能在本地或现有连接器完成的任务，不要为了方便新增外部 API。
- 确认数据边界。 列出会发送的字段、返回的字段、处理地域、保存期限和第三方访问范围。
- 申请最小凭证。 使用测试项目、只读权限、短有效期或可设置额度的密钥；不要复用生产主密钥。
- 安全配置。 使用当前产品提供的安全配置入口或组织批准的密钥管理方式。页面字段和配置位置发生变化时，以当前产品版本为准。
- 用脱敏样本测试。 先测试认证、超时、错误和返回格式，不把真实客户、财务或内部资料作为第一批输入。
- 检查日志和费用。 确认请求日志不会暴露密钥，调用量和费用在预期范围内。
- 逐步接入任务。 先让 API 只返回草稿或分析结果，外发、写入和自动化调用另设人工门禁。
- 轮换或撤销。 测试完成、人员变更或凭证疑似泄露时，立即轮换或撤销并检查残留配置。
示例
接入一个组织批准的文本服务前，先写一张检查卡：
text
用途：只把脱敏的产品说明片段转换为摘要草稿。
允许数据：公开说明、已脱敏的文本片段。
禁止数据：客户信息、内部凭证、个人联系方式和未公开财务数据。
凭证：测试项目的短期低权限凭证，存放在组织批准的位置。
验收：返回格式正确、日志不含密钥、调用次数和费用在预算内。
停用：测试结束后撤销凭证，并删除未确认的临时配置。验收方法
- API 来源、用途、权限、费用和数据处理边界已经记录；
- 测试请求使用脱敏数据，返回结果和错误行为符合预期；
- 密钥没有出现在提示词、日志、截图、仓库或公开产物中；
- 额度、超时、失败和撤销路径可以验证；
- 外部服务只生成经人工检查的草稿，不自动发布或覆盖原资料。
常见问题
为什么 API Key 正确但请求仍失败？
可能是 Endpoint、权限、项目、额度、网络、请求格式或当前产品配置方式不匹配。先缩小到一条脱敏测试请求，逐项记录错误，不要反复扩大权限。
本地模型或本地服务更安全吗？
本地运行可能减少部分数据外发，但仍要检查本机访问权限、日志、端口暴露、模型来源和资源消耗。不能仅凭“本地”二字跳过安全检查。
可以把密钥写进自动化 Prompt 吗？
不可以。密钥应通过当前产品或组织批准的安全配置方式注入，并设置轮换、撤销和最小权限。
风险和权限边界
- 不在聊天、Prompt、截图、Markdown 或代码仓库中保存 API 密钥；
- 不把第三方服务的默认数据保留、训练和地域政策当作已确认事实；
- 费用、配额、外部传输和账号责任必须由授权人确认；
- 接入配置、模型名称和 API 字段以当前产品版本为准，不承诺某个服务永久可用；
- 发现凭证泄露或调用异常时立即停用、轮换并保留审计信息。
相关解决方案
来源引用
- SRC-UPSTREAM-CH09：外部 API、模型配置和本地服务的原始资料，经删除具体密钥和平台成品后重组。
内容版本与核对日期
- 内容版本：
0.1.0 - 最后核对日期：
2026-08-05 - 适用版本状态：API 配置入口、字段和可用服务以当前产品版本与组织策略为准。
- 来源提交版本：
6b5e2403f0f2ad5d3f7ab7a67e9c4d4113583ff3
章节导航
- 上一篇： 第 8 章：小程序、IM 助手与移动办公
- 下一篇： 第 10 章：自动化任务入门