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

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() と QoderSDKClient は、SDK から qodercli を起動する際に認証設定が必要です。スクリプト、CI、ホストアプリケーションでは、Personal Access Token (PAT) を環境変数で注入する方法を推奨します。 ローカルマシンで 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>"

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)

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

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 の値を優先的に読み取ります。

​
PAT を直接渡す

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

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

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

ローカルマシンで qodercli のログインが完了している場合、SDK に CLI のローカルログイン状態を読み取らせることができます。 
from qoder_agent_sdk import QoderAgentOptions, qodercli_auth

options = QoderAgentOptions(auth=qodercli_auth())

​
認証失敗コールバック

リモートがトークンを拒否した場合、トークンの有効期限切れ、または CLI が認証エラーで終了した場合は、on_auth_expired を使って再ログインまたはトークン更新フローをトリガーできます。各 SDK セッションで最大 1 回トリガーされます。 
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 を自動更新しません。新しいトークンを取得した後は、新しいセッションを作成し、新しい auth 設定を渡す必要があります。

​
エラー

  • 認証設定が未指定: AuthNotConfiguredError、code == "auth_not_configured"。
  • 環境変数が未設定: AuthAccessTokenEnvVarError、code == "auth_access_token_env_var_not_configured"。

​
ベストプラクティス

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