什么是Setup Agent
Setup Agent 是 Karma 体系里的初始化能力，作用并不是执行业务动作，而是先把环境和身份凭据准备好。按照说明，它适合在用户第一次使用任何 Karma 技能前运行；当用户提出“设置代理”“配置 API 密钥”“连接 Karma”或“登录”等需求时，也应优先走这一步。它的核心任务很明确：检查本地是否已经存在 KARMA_API_KEY，如果没有，就引导用户通过快速生成、邮箱验证或直接填写现有密钥三种方式完成接入，再把配置写入当前环境并做一次可用性校验。
从流程设计看，这个工具更像一个把“登录、发 key、保存 key、验证连通性”串成闭环的接入向导。所谓快速开始，主打的是无需邮箱、无需登录、也不要求已有账号，调用注册接口后即可得到一个 API key；另一条路径则面向已有 Karma 账户或希望通过邮箱完成身份确认的用户，先发送验证码，再验证后生成 key。对于已经持有密钥的人，它也支持直接录入并跳过前置认证。这些路径最终都会回到同一个目标：把可用的 API key 放到正确的位置，保证后续技能可以直接调用。
证据包里还体现出它对开发者工作流的细节考虑。保存密钥前需要先征得用户同意；若用户允许，工具会根据本机使用的是 zsh 还是 bash，把 KARMA_API_KEY 写入对应 shell 配置文件，并避免重复追加；如果用户不希望持久化，则只在当前会话中导出变量。除此之外，还可以按需设置 KARMA_API_URL，默认走生产环境，本地开发时可切换到本地地址。最后通过查询 agent 信息接口验证配置是否生效，只要返回里包含钱包地址和可用动作列表，就说明代理已经就绪，可以继续使用后续的项目管理或资金机会检索等技能。
核心功能特点
- 提供三种接入路径：无需账号的快速生成、邮箱验证码登录、直接使用已有 API 密钥
- 在保存凭据前先征求用户许可，可写入 shell 配置长期生效，也可只在当前终端会话临时设置
- 会自动检查本地是否已存在 KARMA_API_KEY，避免重复配置，并在已有配置时直接进入验证环节
- 支持按 zsh 或 bash 的常见环境写入变量，同时要求已有旧值时进行替换而不是不断追加重复项
- 内置配置校验流程，通过查询 agent 信息确认密钥有效且代理已可调用后续技能
- 覆盖常见异常情况，包括验证码失效、已有活跃密钥、请求过多、无效或被撤销的 key，以及 API 地址配置错误
适用场景
它最适合出现在所有 Karma 能力的入口位置。比如团队刚准备在终端里使用 Karma 的项目管理、里程碑创建或资金机会搜索能力时，第一步往往不是直接调用业务动作，而是先确认本机有没有可用的 API key、环境变量是否已经设好、接口地址是否正确。Setup Agent 正是用来处理这类“开场工作”的：把容易遗漏的身份配置、变量写入和连接验证一次做完，减少后续技能在调用时才报错的情况。
对于首次接触 Karma 的用户，这个工具尤其有价值。有人只是想马上试用，不愿先注册账号，那么快速开始路径可以立即生成密钥；有人已经有 Karma 账户，希望把代理和既有身份体系关联起来，则可以走邮箱验证流程；还有一些用户本来就从别处拿到了 key，只需要规范地写入环境即可。它并不强迫所有人走同一条路，而是根据当前状态分流处理，这让接入门槛明显降低，也更符合实际开发中的多种起点。
在本地开发和团队协作场景下，它也很实用。开发者经常需要在生产默认地址和本地调试地址之间切换，Setup Agent 允许显式设置 API URL；而当多人共用一套文档或脚本时，统一的验证步骤还能帮助快速确认“问题到底出在密钥、接口还是环境变量”。再加上它对错误码和典型故障给出了明确处理方向，例如验证码过期、请求频率受限、旧 key 已失效或本地地址不可达，因此它不仅是一次性的登录辅助工具，也适合作为 Karma 相关能力的标准接入检查环节。