Grok 的 mTLS 双向认证怎么配：企业网关接入实操

2026-08-25

数据截至 2026-08，价格与限额以各官网为准。本文只讲计费与接入机制，不列具体价格数字。

一句话结论：Grok 的 mTLS 不是拿证书换掉 API Key，而是在 API Key 之上再加一层「机器身份」校验，两道校验都过了请求才走得通。官方文档把它定位成企业特性，需要先联系 support@x.ai 开通；开通之后代码侧唯一必须改的，是把基地址从 api.x.ai 换成 mtls.api.x.ai，然后给每一个请求挂上客户端证书和私钥。所有 API 路径、模型、工具、流式行为都不变。如果你的团队正好是「所有出网流量都要经自建网关」的那种合规环境，这个特性省掉的正是「怎么证明这个请求确实是从我们授权的系统发出来的」这道题。

它到底解决什么问题：不是替代 API Key

先把最容易误会的地方摆平。官方文档在示例后面专门加了一条提示：每个请求上你仍然需要一个有效的 API Key，mTLS 是额外的一层安全，不是 API Key 认证的替代品。 我见过不少团队第一反应是「上了证书就不用管密钥泄漏了」——不是这样。

官方给出的价值主张有三条，原文列得很清楚：

零信任安全：每个请求都必须用证书证明自己的身份，而不只是靠一个 API Key
对网关友好：当你的流量本来就要经过企业 API 网关、代理或服务网格时，这套机制天然契合
不需要改业务代码：启用之后你只要把客户端证书挂到请求上，既有的所有 API 能力（模型、工具、流式）行为完全一致

第三条是这个特性最实在的地方。它没有引入新的请求体字段、没有新的响应结构，改动全部落在传输层。也就是说，如果你已经跑通了常规的 Grok 接入流程，迁到 mTLS 端点基本不用动业务逻辑。

开通这一步绕不过人工

这不是一个在控制台点一下开关就能打开的特性。官方文档写明 mTLS 属于企业特性，要发邮件给 support@x.ai 申请启用，邮件里需要带三样东西：

你的 Team ID（在 xAI Console 里能查到）
你的 CA 证书，PEM 格式
你的系统将要使用的客户端证书上的 Common Name（CN）

xAI 那边完成配置后会回复确认。注意第二、三项意味着一个前提：签发客户端证书的这套 CA 得是你自己的。你要么已经有企业内部 PKI，要么得先把它搭起来。文档没有提供由 xAI 代签客户端证书的路径，也没有说明是否接受公共 CA 签发的证书——这部分官方文档里没有找到相关说明，真要用公共 CA 建议在申请邮件里直接问清楚。

另外一个容易被忽略的事实：mTLS 是配置在团队（team）层级的，不是配置在单个 API Key 上的。 官方 FAQ 里有原话——同一个团队下的所有 API Key 共享同一套 mTLS 配置。这条对组织设计有直接影响：如果你希望「生产环境强制走证书、开发环境不强制」，那就不能靠同一个团队里发两把不同的 Key 来实现，得从团队划分上想办法。团队本身怎么建、成员角色怎么分，可以看 Grok 团队管理与成员权限那篇。

换端点：真正需要改的只有基地址

配置生效后，把请求打到 https://mtls.api.x.ai，替换掉平时用的 https://api.x.ai。官方原文说这是「唯一需要的改动」。所有 API 路径——/v1/chat/completions、/v1/responses、/v1/embeddings 等等——用法完全一样。

对应到 OpenAI SDK 的写法，就是把 base_url 指成 https://mtls.api.x.ai/v1，然后在底层 HTTP 客户端上挂证书。官方给的 Python 示例是用 httpx.Client(cert=(证书路径, 私钥路径)) 构造一个 http_client 再传给 OpenAI 客户端；Node 侧则是用 https.Agent 传 cert 和 key，通过 httpAgent 交给 OpenAI 客户端。两种写法都保留了原来的 API Key 参数（Python 侧写作 api_key，Node 侧写作 apiKey，都是从环境变量里取），再次印证「证书是加法不是减法」。

curl 的形态最直白，就是加两个参数：

curl https://mtls.api.x.ai/v1/chat/completions \
  --cert /path/to/client-cert.pem \
  --key /path/to/client-key.pem \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <你的 API Key>" \
  -d '{ "messages": [{"role":"user","content":"Hello, world!"}], "model": "<模型名>", "stream": false }'

请求体和你平时写的没有任何区别，--cert 和 --key 是全部增量。

两道校验，两个错误码，别搞混

这是排查阶段最有用的一段。官方文档明确说明，开启 mTLS 后每个请求要过两道关：

证书校验：你的客户端证书会拿开通时提供的 CA 证书去验。没有有效证书的请求，被拒时返回 403 Forbidden
API Key 校验：API Key 照常校验，无效或缺失时返回 401 Unauthorized

两道都过请求才继续往下走。这个错误码分工非常好用——看到 403 就去查证书链，看到 401 就去查 Key，不用两头猜。官方 FAQ 在讲自测时又强调了一遍：如果自测请求返回 403，去检查你的证书是不是由当初提供给 xAI 的那个 CA 签发的。

顺带说一句，403 这个码在 Grok 常规调试文档里的通用解释是「向你的团队管理员申请权限」。所以在 mTLS 场景下拿到 403，除了证书问题，也别忘了排除掉「这把 Key 的 ACL 根本没授权到你要调的模型或端点」这种情况。API Key 的 ACL 类型官方列了两种：api-key:model 和 api-key:endpoint，可以精确到某个模型名或某类端点。

自测怎么做

官方给的自测方法是打一个轻量端点：带上证书和私钥去请求 /v1/api-key。这个接口返回的是这把 Key 自身的信息——名字、状态、权限、创建和修改人等。响应体里能看到 redacted_api_key、team_id、acls、api_key_disabled、api_key_blocked 这些字段。成功拿到响应，就说明证书和 Key 两边都通了。用这个端点做自测的好处是一次性验证了两道校验，而且它回给你的是这把 Key 自身的元信息而不是模型输出，字段个个都指向配置本身：team_id 能确认你打到的是不是那个配了 mTLS 的团队，acls 能确认这把 Key 被授权到了哪些模型和哪些端点，api_key_disabled 与 api_key_blocked 能确认它有没有被停用或封禁。排查配置问题时，这些信息比一句「Hello, world」的补全结果有用得多。

证书轮换：什么时候要找官方，什么时候不用

官方专门给了一张表，说明这套机制在设计上支持不停机轮换。三种情形结论完全不同：

续签客户端证书（CA 不变、CN 不变）：什么都不用做，直接开始用新证书就行
更新 CA（比如换了新的中间证书）：需要联系 support@x.ai 上传更新后的 CA 包
彻底换一家 CA：需要联系 support@x.ai 注册新的 CA 证书

这张表值得贴到你的运维手册里。它的实际含义是：日常的证书到期续签是零成本的，只要你保持 CA 和 CN 不动。 反过来，任何涉及信任锚变更的动作都需要人工介入，也就意味着有邮件往返的时间成本，得提前排期，别等旧 CA 快到期了才动手。

几个 FAQ 里已经写明、但很容易想当然的点

必须用 mTLS 端点吗？ 如果你的团队被配置成「required」，那就是必须——打到 api.x.ai 的请求会因为没有提供客户端证书而被拒。如果你确实需要一部分 API Key 在不走 mTLS 的情况下也能用，官方说法是联系支持讨论你的配置。也就是说，required 与否是有商量余地的，但官方文档给出的唯一路径是找支持沟通，文档里没有提到可以在控制台自助调整这个开关。

能和区域端点一起用吗？ 目前 mTLS 只在全局端点 mtls.api.x.ai 上提供。如果你需要 mTLS 配合区域端点，得联系 support@x.ai。这条对有数据驻留要求的团队挺关键——「合规要求走特定区域」和「合规要求走双向认证」这两件事，在当前文档口径下不能自助地同时满足。

证书格式要求？ X.509 证书，PEM 编码。开通时提供的 CA 证书和后续使用的客户端证书都必须是 PEM 编码的。

管理 API 支不支持 mTLS？ xAI 的管理 API 有自己独立的基地址，和推理 API 不是同一个域名，而 mTLS 文档只写了推理端点的替换关系。管理 API 是否也有对应的 mTLS 端点，官方文档里没有找到相关说明，需要走 support 确认。

计费、限流和它的关系

官方原文说得很干脆：证书校验和 Key 校验之外，其它所有行为——限流、计费、模型访问权限——和标准端点完全一致。所以别指望上了 mTLS 就有单独的额度池，也不用担心它会额外产生费用条目。

这意味着你原来那套成本与限流治理照搬即可：限流仍然由 Key 上的 qps、qpm、tpm 这类字段控制（具体取值以你团队的实际配置和官方文档为准），触发限流仍然是 429，退避重试的思路和标准端点没有区别。成本口径也不变，你原来按模型、按 Key、按业务线拆的那套维度可以直接沿用。单价一律以 xAI 官方定价页为准，本文不列数字。

它不解决的那部分，得靠别的机制补

mTLS 管的是「请求从哪台机器来」，管不了「这些内容会被存多久」。后者在 Grok 这边是另一套开关：默认情况下请求和响应会加密存储一段时间用于滥用审计（具体期限以官方文档为准），需要更严格的数据处理时才考虑 Zero Data Retention。官方对 ZDR 的态度其实相当克制——文档里明确写着「对大多数客户我们不建议开启 ZDR」，因为它会关掉一批依赖存储的能力，包括有状态的 Responses API、Files 与 Collections、Batch API、延迟补全、以及服务端托管的图片视频输出。这些取舍在 Grok 的数据处理与安全政策那篇里有更细的拆解。

还有两件事和 mTLS 是并行关系，别因为上了证书就松手：一是 API Key 本身的保管与轮换，官方安全 FAQ 建议把 Key 当密码级别的敏感信息对待、用环境变量或密钥管理工具存放、定期轮换，怀疑泄漏时先在控制台把 Key 禁用或删除再重建；二是审计日志，团队管理员可以在控制台查看用户与 API 服务的交互记录，支持按 Event ID、描述、用户以及时间范围筛选。证书解决的是接入侧的身份，审计日志解决的是事后追溯，两者缺一不可。密钥这块的通用做法可以看 API Key 的安全管理清单。

最后：这件事上最容易栽的坑

按官方文档的口径，最容易出问题的三个地方依次是——

第一，忘了带 API Key。文档专门用 NOTE 强调了这点，说明确实有人踩过。上了证书之后代码里如果顺手把 Authorization 头删了，你会收到 401，然后大概率会先去怀疑证书，方向就跑偏了。记住那个对应关系：403 查证书，401 查 Key。

第二，把 mTLS 当成能自助开关的功能。开通、改 CA、改 required 策略、要区域端点，这些动作全都需要发邮件走支持流程。做接入排期时，把这段往返时间算进去，别排成「今天决定明天上线」。

第三，忽略了它是团队级的。同一个团队里所有 Key 共用一套配置，你没法靠发新 Key 来给某个环境开后门。真要做环境隔离，得在团队划分这一层就规划好。这一条建议在项目立项阶段就确认，改起来比改代码贵得多。

再往下走，如果你的诉求本质上是「用云厂商的 IAM 体系来管身份，而不是自己维护证书」，那 mTLS 未必是唯一解——xAI 也在官方文档里给出了通过云平台调用 Grok 的路径，那条路上的身份认证是交给云厂商的凭据体系的，可以看通过 Google Cloud Vertex AI 调用 Grok。两条路选哪条，取决于你们的合规要求是落在「网络出口可证明」还是「身份统一纳管」上。