> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK 认证

`query()` 和 `QoderSDKClient` 通过 SDK 启动 `qodercli` 时需要认证配置。推荐在脚本、CI 和宿主应用中使用 Personal Access Token (PAT)，并通过环境变量注入。

如果你已经在本机通过 `qodercli` 登录，也可以复用本机登录态。

<div id="获取-pat" />

<div id="获取pat" />

## 获取 PAT

到 [qoder.com/account/integrations](https://qoder.com/account/integrations) 生成一个 Personal Access Token：

1. 登录 Qoder 账号
2. 打开 **Account → Integrations** 页面
3. 创建新的 PAT，按需选择有效期和权限范围
4. 生成后**立即复制**——页面关闭后无法再次查看，丢失只能重新生成

> 同一个账号可以生成多个 PAT，建议给不同环境（本地脚本、CI、生产服务）发独立的 token，方便单独吊销。

<div id="从默认环境变量读取-pat" />

<div id="从默认环境变量读取pat" />

## 从默认环境变量读取 PAT

默认环境变量名是 `QODER_PERSONAL_ACCESS_TOKEN`。

```bash theme={null}
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
```

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env, query

options = QoderAgentOptions(auth=access_token_from_env())

async for message in query(
    prompt="用一句话总结当前目录的项目用途。",
    options=options,
):
    print(message)
```

<div id="从自定义环境变量读取-pat" />

<div id="从自定义环境变量读取pat" />

## 从自定义环境变量读取 PAT

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

options = QoderAgentOptions(auth=access_token_from_env("MY_QODER_PAT"))
```

如果同时设置了 `options.env` 和进程环境变量中的同名变量，SDK 会优先读取 `options.env` 中的值。

<div id="直接传入-pat" />

<div id="直接传入pat" />

## 直接传入 PAT

宿主应用已经从密钥管理服务、登录态或后端接口拿到 PAT 时，可以直接传入。不要把 token 字面量写进源码。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token

token = read_token_from_secret_manager()
options = QoderAgentOptions(auth=access_token(token))
```

<div id="复用-qodercli-登录态" />

<div id="复用qodercli登录态" />

## 复用 qodercli 登录态

本机已通过 `qodercli` 完成登录时，可以让 SDK 交给 CLI 读取本地登录态。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())
```

<div id="认证失败回调" />

## 认证失败回调

远端拒绝 token、token 过期或 CLI 以认证错误退出时，可以使用 `on_auth_expired` 触发重新登录或换 token 流程。每个 SDK 会话最多触发一次。

```python theme={null}
from qoder_agent_sdk import QoderAgentOptions, access_token_from_env

def show_sign_in_required() -> None:
    print("认证已失效，请重新登录。")

options = QoderAgentOptions(
    auth=access_token_from_env(),
    on_auth_expired=show_sign_in_required,
)
```

SDK 不会自动刷新 PAT。拿到新 token 后应创建新的会话并传入新的 `auth` 配置。

<div id="错误" />

## 错误

* 缺少认证配置：`AuthNotConfiguredError`，`code == "auth_not_configured"`。
* 环境变量未设置：`AuthAccessTokenEnvVarError`，`code == "auth_access_token_env_var_not_configured"`。

<div id="最佳实践" />

## 最佳实践

* 生产和 CI 中优先使用环境变量或密钥管理服务，不要硬编码 token。
* 不要把 token 写入日志、错误对象或测试快照。
* 自动化环境中建议使用 PAT，不建议依赖本机 `qodercli` 登录态。
* 用户可见应用建议注册 `on_auth_expired`，把认证失败转成明确的登录提示。