> ## 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()` はセッションを開始するために認証設定が必要です。Personal Access Token (PAT) を使用し、環境変数で注入する方法を推奨します。スクリプト、CI、ホストアプリケーション連携に適しています。

ローカルマシンで `qodercli` にログイン済みの場合は、ローカルのログイン状態を再利用することもできます。

<div id="pat-の取得" />

## PAT の取得

[qoder.com/account/integrations](https://qoder.com/account/integrations) で Personal Access Token を生成します：

1. Qoder アカウントにサインイン
2. **Account → Integrations** ページを開く
3. 新しい PAT を作成し、必要に応じて有効期限とスコープを選択
4. 生成後、**すぐにコピー**してください — ページを閉じると値を再表示できません。紛失した場合は再発行が必要です

> 1 つのアカウントで複数の PAT を発行できます。環境（ローカルスクリプト、CI、本番サービス）ごとに別々のトークンを発行すると、個別に失効させやすくなります。

<div id="推奨される使用方法" />

## 推奨される使用方法

<div id="デフォルト環境変数から-pat-を読み取る" />

### デフォルト環境変数から PAT を読み取る

デフォルトの環境変数名は `QODER_PERSONAL_ACCESS_TOKEN` です。

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

```js theme={null}
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the purpose of this project in one sentence.',
  options: {
    auth: accessTokenFromEnv(),
  },
});

try {
  for await (const message of q) {
    if (message.type === 'result') {
      console.log(message.subtype);
    }
  }
} finally {
  await q.close?.();
}
```

<div id="カスタム環境変数から-pat-を読み取る" />

### カスタム環境変数から PAT を読み取る

```js theme={null}
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Check whether the README contains installation steps.',
  options: {
    auth: accessTokenFromEnv('MY_QODER_PAT'),
  },
});
```

同等の明示的な記述：

```js theme={null}
auth: {
  type: 'accessToken',
  accessToken: { envVar: 'MY_QODER_PAT' },
}
```

`options.env` と `process.env` の両方に同名の変数が設定されている場合、SDK は `options.env` の値を優先的に読み取ります。

<div id="pat-を直接渡す" />

### PAT を直接渡す

ホストアプリケーションがシークレット管理サービス、ログイン状態、またはバックエンド API から PAT を取得済みの場合は、直接渡すことができます。トークンのリテラルをソースコードに書かないでください。

```js theme={null}
import { accessToken, query } from '@qoder-ai/qoder-agent-sdk';

const token = await readTokenFromSecretManager();

const q = query({
  prompt: 'List the most recently modified files.',
  options: {
    auth: accessToken(token),
  },
});
```

<div id="qodercli-のログイン状態を再利用する" />

### qodercli のログイン状態を再利用する

ローカルマシンで `qodercli` のログインが完了している場合、SDK に CLI のローカルログイン状態を読み取らせることができます。この方法は対話型のローカル環境に適しており、ステートレスな CI での使用は推奨しません。

```js theme={null}
import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

const q = query({
  prompt: 'Summarize the current workspace.',
  options: {
    auth: qodercliAuth(),
  },
});
```

<div id="api-概要" />

## API 概要

| オプション                        | 用途                                                               |
| ---------------------------- | ---------------------------------------------------------------- |
| `accessTokenFromEnv()`       | `QODER_PERSONAL_ACCESS_TOKEN` から PAT を読み取ります。                    |
| `accessTokenFromEnv(envVar)` | 指定した環境変数から PAT を読み取ります。                                          |
| `accessToken(token)`         | 呼び出し元が取得済みの PAT を使用します。                                          |
| `qodercliAuth()`             | ローカルの `qodercli` ログイン状態を再利用します。                                  |
| `onAuthExpired`              | トークン失効、認証失敗、または CLI の認証エラー終了時のコールバック。各 query セッションで最大1回トリガーされます。 |

<div id="エラーハンドリング" />

## エラーハンドリング

<div id="auth-設定が未指定" />

### auth 設定が未指定

`query()` は起動前に `auth_not_configured` をスローします：

```js theme={null}
try {
  query({ prompt: 'hello' });
} catch (error) {
  if (error?.code === 'auth_not_configured') {
    console.error('Please configure options.auth');
  }
}
```

<div id="環境変数が未設定" />

### 環境変数が未設定

`{ envVar }` を使用しているが変数が空の場合、SDK は `auth_access_token_env_var_not_configured` をスローします：

```js theme={null}
try {
  const q = query({
    prompt: 'hello',
    options: {
      auth: accessTokenFromEnv('MY_QODER_PAT'),
    },
  });

  for await (const _message of q) {
    // Initialization failures do not reach this loop.
  }
} catch (error) {
  if (error?.code === 'auth_access_token_env_var_not_configured') {
    console.error('MY_QODER_PAT is not set');
  }
}
```

<div id="実行中の認証失敗" />

### 実行中の認証失敗

リモートがトークンを拒否した場合、トークンの有効期限切れ、または CLI が認証エラーで終了した場合は、`onAuthExpired` を使用して再ログインまたはトークン更新フローをトリガーします：

```js theme={null}
const q = query({
  prompt: 'Continue with the current task.',
  options: {
    auth: accessTokenFromEnv(),
    onAuthExpired() {
      showSignInRequired();
    },
  },
});

for await (const message of q) {
  if (message.type === 'result' && message.subtype !== 'success') {
    console.error(message.errors?.join('\n') ?? message.subtype);
  }
}
```

SDK は PAT を自動更新しません。ホストアプリケーションは新しいトークンを取得した後、新しい `query()` セッションを作成し、新しい `auth` 設定を渡す必要があります。

<div id="ベストプラクティス" />

## ベストプラクティス

* 本番環境と CI では環境変数またはシークレット管理サービスを優先し、トークンをハードコードしないでください。
* トークンをログ、エラーオブジェクト、デバッグ出力に書き込まないでください。
* 自動化環境では PAT の使用を推奨し、ローカルの `qodercli` ログイン状態への依存は避けてください。
* ユーザー向けアプリケーションでは `onAuthExpired` を登録し、認証失敗を明確なログインプロンプトに変換してください。
* トークンのローテーションが必要な場合は、新しい query セッションを作成してください。認証に失敗したセッションを再利用しないでください。