Connection

Connection は、指定した外部ホストへの通信を許可し、必要に応じて API の認証情報を預ける設定です。 Wings が接続時に認証を付けるので、Handler のコードに鍵を書く必要はありません。 Handler から Connection の認証情報を読むこともできません。

外への fetch() には、そのホストに一致する Connection を Handler または Run に割り当てる必要があります。 Connection のないホストへの通信は、公開ページ・RSS・公開 API でも断られます。

認証のいらない公開ホストを接続する

認証情報が不要なホストには --auth none を使います。

wings connection add status-claude --host status.claude.com --auth none

トークンの入力やクリップボードの操作は不要です。秘密の値を保存せず、認証ヘッダーも追加しません。 通信できるのは完全に一致する status.claude.com だけです。サブドメインや別のホストは含みません。 利用者が選んだホスト以外に範囲を広げないため、認証なしではワイルドカードや suffix 一致を使えません。 私的な IP アドレスや内部ホストへの通信は引き続き禁止され、外への通信は HTTPS の443番ポートに限ります。 リダイレクトも、選んだ Connection の許可範囲と同じオリジンの中だけです。

次を status.js として保存し、Connection を割り当てて実行します。

export default async function () {
  const response = await fetch('https://status.claude.com/api/v2/status.json', {
    agiWings: { connection: 'status' },
  })
  if (!response.ok) throw new Error('Status request failed')
  return response.json()
}

wings run --file status.js --connection status=status-claude
wings handler deploy --name status-check --file status.js --connection status=status-claude

Console の Connection 画面でも「認証なしの Connection を追加」から名前とホストを入力できます。 作成後、Handler の Connection 設定で割り当ててください。 認証済みの API でも、同じホストの許可だけを作れます。

POST /api/v1/wings/connections
Content-Type: application/json

{"name":"status-claude","host":"status.claude.com","authType":"none"}

credential、credentials、authParam、provider、preset、config は省略します。authType: "none" と同時に指定すると拒否されます。 以前のダミーヘッダーの Connection を置き換えるときは、同じ名前で --replace を付けます。 保存していた認証情報を削除し、既存の Handler への割り当ては維持します。

1. GitHub を接続する

GitHub の API を使えるトークンをクリップボードにコピーしてから実行します。 CLI はトークンの値を表示しません。

wings connection add github-main --host api.github.com --auth bearer

2. コードを保存する

次を github-issues.js として保存します。 自分の Issue を読み、件数を返す例です。

export default async function () {
  const response = await fetch('https://api.github.com/issues', {
    headers: { 'User-Agent': 'wings-digest' },
    agiWings: { connection: 'github' },
  })
  if (!response.ok) throw new Error('GitHub request failed')
  const issues = await response.json()
  return { count: issues.length }
}

3. 登録して確認する

wings handler deploy --name github-issues --file github-issues.js --connection github=github-main
wings handler list

一覧の ID を使って実行します。

wings run <handler-id>
wings handler logs <handler-id>

count に件数が表示され、Run が成功になれば確認完了です。 認証エラーが出たら、GitHub のトークンと読み取り権限を確認してください。

Connection の指定方法

保存した Handler は、登録時に指定した Connection だけを使えます。 --connection github=github-main の左側はコードで使う名前です。 右側は登録した Connection の名前です。 Connection の名前を変えても、すでに設定した Handler からは引き続き使えます。

自分でホスト名を指定した Connection は、完全に同じホスト名だけに使えます。 api.example.com の設定は、そのサブドメインには使えません。 認証方式は none、bearer、header:<name> を選びます。 同じホストに複数の Connection を割り当てた場合は、agiWings.connection で選びます。別の Connection の認証情報で自動的に代用することはありません。

プリセットで接続する

Slack、Cloudflare、freee OAuth、Google OAuth はブラウザで接続します。 Google OAuth では --client-credentials を付けると、自分の OAuth クライアントを使えます。

Discord、Google サービスアカウント、Webull、X OAuth 1.0a は、クリップボードから認証情報を読みます。 CLI の Connection コマンドで各プリセットの指定方法を確認してください。

名前の変更と削除

wings connection list
wings connection rename github-main github-work
wings connection remove github-work

同じ名前で追加し直す場合は --replace が必要です。 Wings が用意した OAuth クライアントを使うプリセットは、--replace に対応しません。 その場合は削除してから接続し直してください。 削除や権限変更の後は、関連する Handler が動くか確認します。