Agent Space API Key失效会导致任务卡死、流式响应中断、工具调用失败甚至整个Agent会话崩溃，必须立即定位是密钥本身问题还是配置加载异常；通过curl健康检查、平台密钥状态核验、清除YAML空格与不可见字符、环境变量排查及强制使用.env文件等五步完成精准诊断与修复。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space API Key失效会导致任务卡死、流式响应中断、工具调用失败甚至整个Agent会话崩溃，必须立即定位是密钥本身问题还是配置加载异常。
确认API Key是否真实失效
打开终端，执行：
curl -I -H "Authorization: Bearer sk-xxxxxxxx" https://your-agentspace-domain/v1/health
观察响应头：若返回 HTTP/2 200，说明密钥仍有效，问题出在Agent Space自身配置或网络层；若返回 401 Unauthorized，则密钥已失效或被撤销。
登录对应平台（如OpenRouter、DashScope、OpenAI）的API密钥管理页，查找当前密钥条目，确认状态为Active且Expiration时间晚于2026年9月5日。如果显示Revoked或已过期，必须点击Regenerate生成新密钥。
这一步不能跳过——有些平台（如Anthropic）会在密钥创建7天后自动设为“待撤销”，表面显示Active但实际已无法认证。
清除配置中隐藏空格与格式错误
执行 hermes config show | grep api_key 查看当前生效值。【若输出中key两端可见空格（如" sk-xxx "），或含^M、$等不可见字符，说明YAML解析器已拒绝加载】
运行 hermes config edit 进入编辑模式，手动删除 api_key 字段值前后所有空白字符、换行符和中文标点，确保其严格形如：
api_key: sk-xxx
（冒号后仅一个英文空格，无引号，无缩进，无任何额外符号）
保存退出后再次执行 hermes config show 验证，确认输出为纯密钥字符串，无任何包裹或空白。
绕过配置文件直连测试
方法一：命令行显式注入
AGENTSPACE_API_KEY="sk-xxxxxxxx" agentspace run --test
方法二：使用curl直连下游模型服务（以OpenRouter为例）：
curl -X POST https://openrouter.ai/api/v1/chat/completions \
-H "Authorization: Bearer sk-xxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"model":"google/gemma-2-9b-it","messages":[{"role":"user","content":"hi"}]}'
如果该请求成功返回JSON，说明密钥本身有效，问题锁定在Agent Space的配置加载逻辑或Base URL拼接错误上。
为项目需求设计最小有效的子代理团队与协作计划。当用户明确要求代理（agents）、子代理（subagents）、委派（delegation）、并行协作（parallel work）、团队组成（team composition），或希望获得低风险的多代理执行方案时使用；不要仅因用户要求构建、调试或编辑而使用。
检查环境变量覆盖与冲突
第一步：确认当前shell中变量已导出
env | grep -i "agentspace_api\|agent_api"
第二步：排查拼写错误的干扰变量
执行 unset AGENT_API_KEY AGENTSPACE_APIKEY（注意下划线缺失或大小写错误的变体），再重新 export AGENTSPACE_API_KEY="sk-xxxxxxxx"
第三步：验证进程内是否可见
AGENTSPACE_API_KEY="sk-xxxxxxxx" agentspace config show | grep api_key
【若此处仍显示 from environment 或为空，说明Agent Space未按预期读取该变量，需改用 .env 文件方式】
强制使用 .env 文件加载密钥
① 创建标准路径并进入：
mkdir -p ~/.agentspace && cd ~/.agentspace
② 新建 .env 文件：
nano ~/.agentspace/.env
③ 写入唯一一行（无空格、无注释、无引号）：
AGENTSPACE_API_KEY=sk-xxxxxxxx
④ 设置严格权限防止加载失败：
chmod 600 ~/.agentspace/.env
⑤ 验证内容纯净性：
cat -A ~/.agentspace/.env
输出应仅显示 AGENTSPACE_API_KEY=sk-xxxxxxxx$，不含 ^M 或多余 $ 符号。
重启Agent Space服务，此时将优先从该文件加载密钥，彻底绕过shell环境变量不确定性。
