WorkBuddy实操手册
WorkBuddy实操手册

Appearance

第 9 章：外部 API、密钥与权限边界 ​

本章目标 ​

掌握接入外部 API 前后的通用检查方法：先判断是否真的需要外部服务，再配置最小权限凭证，用非敏感样本测试请求、结果、日志、费用和撤销路径。具体服务、接口格式和 WorkBuddy 配置入口以当前版本为准。

适用场景 ​

  • 当前产品能力不足，需要调用组织批准的外部服务；
  • 使用自有模型或数据服务，需要配置 API 密钥；
  • 需要判断本地服务、代理服务或云端 API 的数据边界；
  • 发现密钥失效、超额、泄露或不再需要时进行处理。

前置条件 ​

  • 明确 API 的用途、输入输出、费用和数据处理政策；
  • 取得账号所有者或组织管理员授权；
  • 准备测试密钥、测试项目或低权限账号；
  • 有安全的密钥存放位置，不把密钥写进提示词、公开文档或代码仓库。

核心概念 ​

概念说明需要控制什么
EndpointAPI 请求的目标地址来源、传输方式和环境
认证凭证API Key、令牌或其他身份材料最小权限、有效期和轮换
输入输出发送给服务的数据和返回的结果敏感字段、保留期限和脱敏
配额与计费请求次数、消耗和费用限制预算、告警和停用条件
日志请求、错误和调用结果的记录是否会记录密钥或敏感内容

分步操作 ​

  1. 先判断必要性。 先查看当前 WorkBuddy 已有能力；能在本地或现有连接器完成的任务，不要为了方便新增外部 API。
  2. 确认数据边界。 列出会发送的字段、返回的字段、处理地域、保存期限和第三方访问范围。
  3. 申请最小凭证。 使用测试项目、只读权限、短有效期或可设置额度的密钥；不要复用生产主密钥。
  4. 安全配置。 使用当前产品提供的安全配置入口或组织批准的密钥管理方式。页面字段和配置位置发生变化时，以当前产品版本为准。
  5. 用脱敏样本测试。 先测试认证、超时、错误和返回格式，不把真实客户、财务或内部资料作为第一批输入。
  6. 检查日志和费用。 确认请求日志不会暴露密钥，调用量和费用在预期范围内。
  7. 逐步接入任务。 先让 API 只返回草稿或分析结果，外发、写入和自动化调用另设人工门禁。
  8. 轮换或撤销。 测试完成、人员变更或凭证疑似泄露时，立即轮换或撤销并检查残留配置。

示例 ​

接入一个组织批准的文本服务前，先写一张检查卡：

text
用途：只把脱敏的产品说明片段转换为摘要草稿。
允许数据：公开说明、已脱敏的文本片段。
禁止数据：客户信息、内部凭证、个人联系方式和未公开财务数据。
凭证：测试项目的短期低权限凭证，存放在组织批准的位置。
验收：返回格式正确、日志不含密钥、调用次数和费用在预算内。
停用：测试结束后撤销凭证，并删除未确认的临时配置。

验收方法 ​

  • API 来源、用途、权限、费用和数据处理边界已经记录；
  • 测试请求使用脱敏数据，返回结果和错误行为符合预期；
  • 密钥没有出现在提示词、日志、截图、仓库或公开产物中；
  • 额度、超时、失败和撤销路径可以验证；
  • 外部服务只生成经人工检查的草稿，不自动发布或覆盖原资料。

常见问题 ​

为什么 API Key 正确但请求仍失败？

可能是 Endpoint、权限、项目、额度、网络、请求格式或当前产品配置方式不匹配。先缩小到一条脱敏测试请求，逐项记录错误，不要反复扩大权限。

本地模型或本地服务更安全吗？

本地运行可能减少部分数据外发，但仍要检查本机访问权限、日志、端口暴露、模型来源和资源消耗。不能仅凭“本地”二字跳过安全检查。

当前版本核对：模型、API Key 与数据流 ​

WorkBuddy 个人版官方文档当前提供 头像 → 设置 → 模型 的图形化配置入口，可添加、编辑和删除自定义模型；选择标准提供商或自定义 API 后，再补全 API Key 保存配置，不需要手动编辑配置文件。

官方页面同时说明：配置参数（包括 API Key）保存在本地的 workbuddy/models.json，请求时 WorkBuddy 将输入转发给配置的第三方模型，输出由该模型返回。页面的表述是产品当前的隐私说明，不等于第三方服务的独立数据政策已被本站核验，因此仍需单独确认 Endpoint、保留、训练、地域和日志规则。页面还保留了 ~/.codebuddy/models.json 旧配置的兼容说明，不能据此推断所有版本都使用同一路径。

本地模型或自定义 API 的验收顺序建议保持不变：使用短期、低权限测试 Key；先用脱敏输入验证成功、失败、超时和撤销；检查本地文件权限与日志；最后确认密钥没有进入 Prompt、截图、仓库或公开产物。

官方文档核对示例：API Key 与自定义模型 ​

2026-06-11 更新的腾讯云 WorkBuddy/TokenHub 官方通用文档页面，当前提供了 API Key 管理、自定义模型和 Endpoint 配置的示例。该页面同时面向个人与团队使用，因此本节只作为个人/通用版的配置核对样例，不推导 WorkBuddy 企业版一定支持相同入口。

核对时可以按以下顺序操作：

  1. 先确认当前账号和项目是否有 API Key 管理权限，并使用短期、低权限、可撤销的测试凭证。
  2. 如果组织限制了可用模型，先确认允许列表，再填写当前文档展示的模型标识；不要把历史模型名写死为长期承诺。
  3. 如果需要自定义 Endpoint，逐项核对地址、模型、工具调用、图片或推理能力是否与当前产品和服务协议一致。
  4. 用脱敏样本完成一次成功、失败、超时和撤销测试，并确认日志不包含密钥。

文档中的具体 Endpoint、模型名称和字段是页面版本快照。当前产品入口、区域、模型、配额和权限变化时，以最新官方文档和组织配置为准。

可以把密钥写进自动化 Prompt 吗？

不可以。密钥应通过当前产品或组织批准的安全配置方式注入，并设置轮换、撤销和最小权限。

风险和权限边界 ​

  • 不在聊天、Prompt、截图、Markdown 或代码仓库中保存 API 密钥；
  • 不把第三方服务的默认数据保留、训练和地域政策当作已确认事实；
  • 费用、配额、外部传输和账号责任必须由授权人确认；
  • 接入配置、模型名称和 API 字段以当前产品版本为准，不承诺某个服务永久可用；
  • 发现凭证泄露或调用异常时立即停用、轮换并保留审计信息。

相关解决方案 ​

来源引用 ​

  • SRC-UPSTREAM-CH09：外部 API、模型配置和本地服务的原始资料，经删除具体密钥和平台成品后重组。
  • SRC-TENCENT-WORKBUDDY-TOKENHUB-DOC-202606：官方通用页面对 API Key、自定义模型和 Endpoint 配置的当前示例，页面更新时间 2026-06-11；按个人/通用版处理。
  • SRC-TENCENT-WORKBUDDY-PERSONAL-MODEL-20260825：WorkBuddy 个人版当前模型配置、API Key 本地保存和第三方模型数据流说明；页面未见正文发布时间，本轮只记录核对日期。

内容版本与核对日期 ​

  • 内容版本：0.3.0
  • 最后核对日期：2026-08-25
  • 适用版本状态：API 配置入口、字段和可用服务以当前产品版本与组织策略为准。
  • 来源提交版本：6b5e2403f0f2ad5d3f7ab7a67e9c4d4113583ff3

章节导航 ​

企业版指南 ​