401错误表明身份校验失败，主因是凭证缺失、过期或格式不合法；需检查Authorization头是否为“Bearer sk-xxx”（含空格）、环境变量是否生效、密钥是否在秘塔平台过期（默认90天），并排除中间件覆盖或企业网关需刷新token等情况。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
秘塔AI搜索API返回401错误时，你正在调用https://metaso.cn/api/mcp却收到“Unauthorized”响应，这说明请求未通过身份校验，不是网络不通或参数错位的问题，而是凭证缺失、过期或格式不合法导致的权限拦截。
确认API密钥是否已正确配置
打开你的MCP客户端配置文件（如config.json或环境变量配置），检查mcpServers.metaso.headers.Authorization字段值是否为Bearer sk-xxx格式。【必须以Bearer 开头且后接一个空格，缺空格或写成Bearer:sk-xxx都会触发401】。
这一步操作起来很简单，直接在编辑器里搜Authorization就能定位到。
若使用环境变量（如METASO_API_KEY），请确认该变量已在当前Shell会话中生效：执行echo $METASO_API_KEY应输出完整密钥字符串，而非空值或undefined。
验证密钥是否已过期或被撤销
登录 https://www.php.cn/link/a1f326958470b4c96e94f95ba7610faf → 查看密钥列表中的「状态」列。若显示「已禁用」或「已过期」，说明该密钥不可再用。
注意：秘塔API密钥默认有效期为90天，且不支持手动续期；一旦过期，旧密钥将永久失效，无法恢复。
点击「创建新密钥」生成替代密钥，并立即更新配置文件或环境变量——旧密钥即使未显式禁用，只要超过90天也自动失效。
排查请求头是否被中间件覆盖
方法一：用curl直连验证基础可用性
执行以下命令（将sk-xxx替换成你的实际密钥）：curl -X POST https://metaso.cn/api/mcp -H "Authorization: Bearer sk-xxx" -H "Content-Type: application/json" -d '{"tool":"metaso_web_search","q":"test"}'
若返回200，说明密钥本身有效，问题出在你的客户端代码中；若仍返回401，则密钥无效或网络代理篡改了请求头。
方法二：检查SDK或HTTP库是否自动添加冲突头
某些HTTP客户端（如Python的requests）在启用认证时会自动注入Authorization头，若你手动再设一次，可能造成重复或覆盖。【务必只保留一处Authorization设置，且确保它未被auth=()等参数二次覆盖】。
强制刷新Token缓存（仅限企业版网关用户）
第一步：确认你是否接入的是企业版专属网关（URL形如https://<em>your-company</em>.metaso-api.com）；
第二步：若确认是企业网关，执行curl -X POST https://<em>your-company</em>.metaso-api.com/v1/auth/refresh -H "Authorization: Bearer sk-xxx"；
第三步：捕获返回的new_token字段值，将其作为后续所有请求的Authorization头新值。
企业网关不复用个人密钥的长期Token机制，每次调用前需先换取短期访问令牌，否则一律返回401。
