401错误表明身份认证失败，需依次确认：Token是否启用且为智能体专用、Authorization头是否严格按“Bearer + 空格 + 64位Token”格式、请求URL是否为https://www.php.cn/link/8eb6c13d87ba59b39ba6d8f03f47dcbd/openapi/v1/agent/chat/completions、Content-Type是否缺失或重复设置Header。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
腾讯混元API调用返回401错误，说明服务端拒绝了你的身份认证请求，常见于API Key无效、过期、权限不足或未正确传递。这一步必须先确认凭证本身是否真实可用，而不是直接检查代码逻辑。
确认API Key是否已正确生成并启用
登录腾讯混元开放平台→进入「我的应用」→找到对应智能体→点击「API凭证」→查看「Token」状态是否为「已启用」。
如果状态是「已禁用」或「已过期」，点击右侧「重置」按钮生成新Token；【重置后旧Key立即失效，所有正在运行的服务将立刻中断】。
注意：Token不是API Key，混元当前不使用OpenAI风格的sk-xxx密钥，而是平台生成的长字符串Token，长度通常为64位十六进制字符。
检查请求头Authorization字段构造是否合规
方法一：使用Bearer前缀 + 空格 + 完整Token字符串（无引号、无换行、无前后空格）。
错误示例：Authorization: Bearer "abc123"（带英文双引号）、Authorization: bearer abc123（小写bearer）、Authorization: Bearer abc123\n（末尾含不可见换行）都会导致401。
正确写法：Authorization: Bearer abc123def456...（全大写Bearer，后接一个空格，再紧贴Token，中间无任何分隔符）。
验证请求URL与base_url是否匹配混元v1规范
第一步：确认你调用的是混元官方支持的API地址：https://www.php.cn/link/8eb6c13d87ba59b39ba6d8f03f47dcbd/openapi/v1/agent/chat/completions。
第二步：检查是否误用了OpenAI兼容路径（如/v1/chat/completions）——混元的Agent接口【不兼容OpenAI标准路径，必须用/openapi/v1/agent/前缀】。
第三步：确认域名没有拼错，例如把open.hunyuan.tencent.com写成api.hunyuan.tencent.com或漏掉open.前缀，这类错误返回也是401而非404。
排查Token是否被错误用于非Agent接口
方法一：你正在调用的是智能体（Agent）能力，就必须使用「智能体Token」，不能复用「模型直连API Key」或「百炼/通义千问迁移用的Key」。
方法二：如果你在调试中混用了不同环境的凭证（比如测试环境Token用于生产调用），也会触发鉴权失败。每个智能体Token仅对该智能体ID唯一有效。
这一步操作起来很简单，回到平台页面，点开目标智能体→「API凭证」→复制最上方显示的Token，不要从历史记录或笔记里翻旧值。
检查HTTP客户端是否自动添加了干扰Header
① 使用curl时，避免用-H "Authorization: ..."和-H "Content-Type: ..."分开写却漏掉其中一项；401常伴随Content-Type缺失（应为application/json）而被统一拦截。
② 使用Python requests时，不要同时设置headers={'Authorization': '...'}和auth=xxx参数——后者会覆盖前者，导致Authorization被丢弃。
③ Postman用户注意：如果在「Authorization」标签页选择「Bearer Token」模式，就不要再手动在Headers里重复填写Authorization字段，否则会发送两遍，服务端可能因格式冲突拒收。
