401错误表明凭证链中断，需依次验证密钥是否被进程读取、.env文件格式是否合规、命令行直传是否生效、provider与密钥前缀是否匹配，并强制重载配置或清除干扰变量。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space API返回401错误，说明请求未通过身份认证，密钥未被识别、已失效或未按规范注入——不是网络不通，也不是接口地址写错，而是凭证链在某一处断开了。
先确认密钥是否真被进程读到
执行hermes config show | grep api_key，如果输出是api_key: null或api_key: ""，说明Hermes根本没加载到任何值；如果显示" sk-xxx "（两端带空格），那它会被当作非法字符串直接拒绝。
这一步必须做，否则后面所有修改都是在猜。
用.env文件注入密钥（最稳路径）
这是Hermes默认优先读取的方式，但要求严苛，差一个字符都会失败。
第一步：进入配置目录 → 执行hermes config show-path，记下输出路径（通常是~/.hermes/）→ 进入该目录：cd ~/.hermes
第二步：创建或编辑.env文件：nano .env
第三步：写入密钥行，【必须严格满足三要素】：变量名全大写+下划线、等号右侧紧贴密钥、整行无空格无引号。例如你用的是OpenRouter，就只写这一行：OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
第四步：保存退出后，立即设置文件权限，防止因权限过高被跳过读取：chmod 600 .env
第五步：验证文件内容是否干净——运行cat -A .env，输出应只有密钥行，且末尾无$符号、无^M（Windows换行符）。若有，说明编辑器用了DOS格式，得换nano或vim重写。
绕过所有配置，命令行直传密钥（即时验证法）
当你不确定.env是否生效、shell配置是否刷新、甚至怀疑文件被缓存时，这条命令能100%确保密钥进进程。
执行：OPENROUTER_API_KEY=sk-or-v1-xxx hermes start（把sk-or-v1-xxx替换成你的实际密钥）
这会绕过.env、config.yaml、环境变量全局配置三层加载逻辑，直接将密钥注入当前进程。如果这时能启动成功，说明问题一定出在配置文件或环境变量加载环节。
检查config.yaml中provider与密钥前缀是否匹配
打开~/.hermes/config.yaml，查找llm:节点下的模型设置，例如：model: deepseek/custom/main。
根据模型前缀（如deepseek/）确定应使用的密钥变量名，对照官方文档确认标准前缀映射关系——deepseek/对应DEEPSEEK_API_KEY，openrouter/对应OPENROUTER_API_KEY，拼错一个字母（比如写成DEEPSEEK_KEY）就会导致401。
若配置中存在内嵌密钥字段（如providers: deepseek: api_key: "sk-xxx"），请确保其值非空且不含多余空格；若不存在，则必须依赖外部.env文件提供对应变量。
强制重载并清除干扰变量
方法一：执行hermes config reload，强制重新解析配置，跳过初始化缓存。
方法二：临时清除可能冲突的全局环境变量，例如unset HERMES_API_KEY、unset HUGGINGFACEHUB_API_TOKEN，再重启服务。
方法三：在WSL2或Docker中运行时，常因shell配置未刷新导致.bashrc里的export未生效，此时需显式执行source ~/.bashrc后再启动hermes。
