身份认证

RawClient 构造器需要 Catalog Service 的 Base URL 和 MOI API Key。SDK 会规范化 URL、移除末尾斜杠，并在每个请求中自动发送：

moi-key: <API_KEY>

这不是 Genesis 模型 API 使用的 Authorization: Bearer。即使两个入口位于同一部署，也不要互换地址或凭据。

准备环境变量

从目标 MOI 环境的管理入口或部署管理员处取得真实值：

export MOI_BASE_URL="https://<catalog-service-host>"
export MOI_API_KEY="<MOI API Key>"

Base URL 必须包含 http:// 或 https:// 以及主机名。不要在地址中携带查询参数或片段；两套 SDK 初始化时都会去除这部分。API Key 前后的空格会被清理，空值会直接导致初始化失败。

Key 只能保存在服务端环境变量或密钥管理系统中。不要放入浏览器代码、移动端包、容器镜像或 Git 仓库，也不要输出到日志。

让 SDK 生成认证头

Python：

import os
from moi import RawClient

client = RawClient(
    os.environ["MOI_BASE_URL"],
    os.environ["MOI_API_KEY"],
)
print(client.health_check())

Go：

client, err := sdk.NewRawClient(
	os.Getenv("MOI_BASE_URL"),
	os.Getenv("MOI_API_KEY"),
)
if err != nil {
	log.Fatal(err)
}

status, err := client.HealthCheck(ctx)
if err != nil {
	log.Fatal(err)
}
fmt.Println(status)

不要通过 WithHeader / with_header 重写 moi-key。如果需要为单次请求附加业务请求 ID，使用专门选项：

from moi.options import with_request_id

catalogs = client.list_catalogs(with_request_id("catalog-list-001"))

catalogs, err := client.ListCatalogs(
	ctx,
	sdk.WithRequestID("catalog-list-001"),
)

该值作为 X-Request-ID 发送，适合与服务端日志关联；它不是认证信息。

使用不同身份

Python 的 with_special_user(api_key) 和 Go 的 WithSpecialUser(apiKey) 会基于现有 Client 创建一个使用新 Key 的 Client，并复用底层 HTTP Client。原 Client 的 Key 不会被改写：

user_client = client.with_special_user(os.environ["MOI_OTHER_API_KEY"])

userClient := client.WithSpecialUser(os.Getenv("MOI_OTHER_API_KEY"))

仅在应用确实需要代表另一个已授权身份调用时使用此能力。不要把任意终端用户输入直接当作 Key，也不要在并发请求之间修改共享 Client 的身份。Go 方法在空 Key 时会 panic，调用前必须校验配置；Python 方法会抛出 ValueError。

认证失败怎么查

按以下顺序缩小范围：

  1. Base URL 是否属于当前环境，且可以从应用网络访问。

  2. Key 是否完整、有效并属于同一环境。

  3. 调用身份是否拥有目标资源与操作权限。

  4. 是否保留了 SDK 自动生成的 moi-key，代理是否移除了自定义头。

  5. 记录 X-Request-ID 以及 SDK 错误中的 HTTP 状态、业务 code 和 request_id，但不记录 Key。

网络或非 2xx 响应会产生 HTTP 错误；HTTP 成功但响应信封中的 code 不表示成功时会产生 API 业务错误。Go SDK 对 OK 做不区分大小写的比较；Python SDK 当前要求非空 code 精确为 OK。返回与错误结构见返回结果。