メインコンテンツへスキップ

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.

query() はセッションを開始するために認証設定が必要です。Personal Access Token (PAT) を使用し、環境変数で注入する方法を推奨します。スクリプト、CI、ホストアプリケーション連携に適しています。 ローカルマシンで qodercli にログイン済みの場合は、ローカルのログイン状態を再利用することもできます。

​
PAT の取得

qoder.com/account/integrations で Personal Access Token を生成します：
  1. Qoder アカウントにサインイン
  2. Account → Integrations ページを開く
  3. 新しい PAT を作成し、必要に応じて有効期限とスコープを選択
  4. 生成後、すぐにコピーしてください — ページを閉じると値を再表示できません。紛失した場合は再発行が必要です
1 つのアカウントで複数の PAT を発行できます。環境（ローカルスクリプト、CI、本番サービス）ごとに別々のトークンを発行すると、個別に失効させやすくなります。

​
推奨される使用方法

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

デフォルトの環境変数名は QODER_PERSONAL_ACCESS_TOKEN です。 
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
node agent.mjs

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?.();
}

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

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'),
  },
});
同等の明示的な記述： 
auth: {
  type: 'accessToken',
  accessToken: { envVar: 'MY_QODER_PAT' },
}
options.env と process.env の両方に同名の変数が設定されている場合、SDK は options.env の値を優先的に読み取ります。

​
PAT を直接渡す

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

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

ローカルマシンで qodercli のログインが完了している場合、SDK に CLI のローカルログイン状態を読み取らせることができます。この方法は対話型のローカル環境に適しており、ステートレスな CI での使用は推奨しません。 
import { qodercliAuth, query } from '@qoder-ai/qoder-agent-sdk';

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

​
API 概要

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

​
エラーハンドリング

​
auth 設定が未指定

query() は起動前に auth_not_configured をスローします： 
try {
  query({ prompt: 'hello' });
} catch (error) {
  if (error?.code === 'auth_not_configured') {
    console.error('Please configure options.auth');
  }
}

​
環境変数が未設定

{ envVar } を使用しているが変数が空の場合、SDK は auth_access_token_env_var_not_configured をスローします： 
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');
  }
}

​
実行中の認証失敗

リモートがトークンを拒否した場合、トークンの有効期限切れ、または CLI が認証エラーで終了した場合は、onAuthExpired を使用して再ログインまたはトークン更新フローをトリガーします： 
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 設定を渡す必要があります。

​
ベストプラクティス

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