401 Unauthorized响应源于API Key身份验证失败，需依次排查：一、Key填写格式与有效性；二、接口权限配置；三、Host域名匹配；四、Token有效期及刷新逻辑；五、HMAC-SHA256签名正确性。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如果您调用龙虾机器人API时收到401 Unauthorized响应，说明服务器拒绝了当前请求，核心原因是API Key未通过身份验证。以下是排查此问题的具体步骤：

一、确认API Key是否正确填写

API Key必须完整、准确地放入请求头中，任何字符缺失、多余空格或大小写错误都会导致验证失败。

1、检查请求头中Authorization字段的格式是否为Bearer <your_api_key>，注意Bearer后有一个空格。

2、复制API Key字符串，在十六进制编辑器或在线字符串分析工具中验证是否存在不可见字符（如零宽空格、BOM头）。

3、在龙虾机器人管理后台重新生成新Key，并立即用于测试，排除旧Key已被撤销或过期的可能性。

二、验证API Key是否具备对应接口权限

龙虾机器人平台对不同API Key设置了细粒度访问控制，即使Key本身有效，也可能因权限范围不匹配而被拒绝。

1、登录龙虾机器人开发者控制台，进入“API密钥管理”页面。

2、找到正在使用的Key，点击“查看权限”，确认其已勾选目标接口所属的服务模块（如“对话生成”“知识库查询”等）。

3、若权限为自定义策略，检查策略JSON中是否明确包含当前请求的HTTP方法（如POST）和路径（如/v1/chat/completions）。

三、检查请求Host与API Key绑定域名是否一致

部分龙虾机器人部署环境要求API Key仅限于特定域名调用，Host头不匹配将直接触发401响应。

1、查看请求中Host头的值，例如api.xiaolongbot.com或sandbox.xiaolongbot.com。

2、在控制台中核对该API Key的“允许调用域名”列表，确保当前Host完全匹配（含端口，如:8443需显式列出）。

3、若使用代理或CDN，确认代理层未篡改或删除原始Host头。

四、排查Token有效期与刷新机制异常

某些龙虾机器人实例采用短期有效的JWT式API Token，需定期刷新；若Token已过期但客户端未重发获取流程，将持续返回401。

1、解析当前Authorization头中的Token（取Bearer后部分），使用jwt.io等工具验证其exp字段是否已过期。

2、检查客户端代码中是否遗漏了Token自动刷新逻辑，特别是长连接或定时任务场景下Token复用超时的情况。

3、确认刷新接口（如/v1/auth/refresh）调用时携带的是原始长期有效的API Key，而非已过期的临时Token。

五、验证请求签名是否符合HMAC-SHA256规范

当龙虾机器人启用签名认证模式时，401可能源于签名计算错误，而非Key本身无效。

1、确认签名字符串拼接顺序严格遵循文档：HTTP方法 + \n + 请求路径 + \n + 请求体SHA256哈希（空体为全零32位）+ \n + 时间戳（秒级Unix时间）。

2、使用API Key的Secret部分作为HMAC密钥，以SHA256算法生成签名，并将结果转为小写十六进制字符串。

3、检查请求头中X-Lobster-Signature字段是否精确等于该签名值，且X-Lobster-Timestamp头与签名中使用的时间戳完全一致（误差超过300秒将被拒绝）。