# Beatra Skill のインストールとログイン
> Claude Code、Cursor、Codex、WorkBuddy に Beatra Skill をインストールし、デバイスコードのログインを一度承認します。

手順の最終確認：2026-11-09

Beatra Skill は、Beatra のすべての機能（画像、動画、音楽、音声、公開ソーシャルデータ）を 1 つのパッケージで Agent に提供します。インストールは Agent にメッセージを 1 通送るだけです。その後 Skill がデバイスコードで Beatra にログインし、あなたはブラウザで一度承認します。ログイン情報はあなたのパソコンにだけ保存されます。インストールとログインは無料で、メディアの生成には Beatra のクレジットを使います。

## 始める前に [#requirements]

| 項目 | 必要なもの |
| --- | --- |
| Agent | Claude Code、Cursor、Codex、WorkBuddy のほか、Skill をインストールでき、スクリプトを実行できる Agent |
| Python | Agent が動くマシンに Python 3.10 以降。Skill のスクリプトは標準ライブラリだけを使います。 |
| ネットワーク | HTTPS。Skill がこのパソコンに合わせて、国際向けまたは中国本土向けの Beatra の接続先を自動で選びます。 |
| アカウント | Beatra アカウント。承認ページでログインまたは新規登録できます。 |
| 費用 | インストールとログインは無料です。生成にはクレジットを使います。[課金と使用量](https://docs.beatra.cn/ja/docs/mechanisms/billing)を参照してください。 |

### インストールのメッセージを送る

```text title="Agent に送る"
Beatra をインストールし、ログインが必要になったら知らせてください：https://beatra.ai/install.md
```

Agent は Beatra から Skill のパッケージをダウンロードし、展開する前に SHA-256 チェックサムを確認して、Agent 自身の Skill の仕組みで `beatra` フォルダーをほかの Skill と並べてインストールします。

**チェックポイント**

- [x] Agent が Beatra Skill のインストール完了を報告していること。

### ブラウザでデバイスコードを承認する

Skill はログイン補助スクリプト `scripts/authorize.py` を実行します。このスクリプトが Beatra にデバイスコードを申請し、ブラウザで承認ページを開きます。ブラウザを開けない場合は、Agent がリンクを表示します。ページでログインし、「接続を許可」を選んでください。承認ページは最長 1 時間有効で、承認したことは Agent が自動で検出します。

**チェックポイント**

- [x] 承認ページに「承認しました」と表示され、Agent が接続すると「接続しました」に変わること。
- [x] Agent が Beatra の準備完了を報告していること。新しい接続は課金されないリクエストで確認されるため、費用はかかりません。

### 最初の依頼を送る

Agent によっては、Skill をセッションの開始時にしか読み込みません。その場合は新しいセッションを開いてから、作りたいものを伝えてください。

```text title="Agent に送る"
秋のコーヒー新商品の縦型ポスターを作って。上部にタイトル用の余白を空けて
```

**チェックポイント**

- [x] Agent が Beatra タスクの作成を確認し、その後に成果物と使ったクレジットを返すこと。

### コンソールでこのパソコンを確認する

[コンソール](https://console.beatra.cn/agents)の「デバイス」を開きます。Skill がログインしたパソコンがすべて表示され、どれでもいつでも接続を解除できます。

**チェックポイント**

- [x] 「デバイス」にこのパソコンが接続済みとして表示されていること。

## パソコンに保存されるもの [#local-files]

ログイン情報は、あなたのユーザーフォルダーの `~/.beatra/` にだけ保存されます。`credentials.json` にはデバイスの認証情報、`installation.json` には秘密ではない固定のインストール識別子が入ります。macOS と Linux では、このフォルダーはあなたのユーザーだけが読めます（フォルダー 0700、ファイル 0600）。同じパソコンのすべての Beatra Skill がこのログインを共有するため、2 つ目の Beatra Skill をインストールしても承認は不要です。

## ログインを保つ [#stay-signed-in]

- ログインは Skill を使うたびに延長され、15 日間使わないと終了します。
- 終了した後や、コンソールでこのパソコンの接続を解除した後は、Agent に `python3 scripts/authorize.py` をもう一度実行させ、一度承認してください。
- 別の Beatra アカウントを使う場合は、Agent に `python3 scripts/authorize.py --force` を実行させ、そのアカウントで承認してください。

## Skill を更新する [#update]

Skill はインストールしたときのバージョンのままです。1 日に最大 1 回、インストール元のストアまたはツールを確認し、新しいバージョンがあれば更新コマンドを 1 行で表示します。インストールメッセージで入れた場合は、インストールメッセージをもう一度送ると最新版に更新されます。ほかのインストール方法の更新コマンドは[トラブルシューティング：バージョンが合わない](https://docs.beatra.cn/ja/docs/troubleshooting#version-mismatch)にあります。

## Skill を削除する [#uninstall]

Agent に Beatra のアンインストールを頼みます。Agent はまず Skill の `scripts/uninstall.py` を実行します。このパソコンで最後の Beatra Skill であれば、スクリプトがこのパソコンと Beatra の接続を解除し、`~/.beatra/` のログイン用ファイルを削除します。ほかの Beatra Skill が残っている場合、共有のログインはそのまま残ります。その後、Agent が Skill のフォルダーを削除します。

## うまく進まない場合 [#if-a-step-fails]

同じインストールメッセージをもう一度送ってください。正しく完了している設定はそのままに、残っている部分から再開します。具体的なメッセージが出た場合は次を参照してください。

- `BEATRA_AUTH_PENDING`、`access_denied`、`expired_token`、`BEATRA_AUTH_REQUIRED`：[トラブルシューティング：ログインできない](https://docs.beatra.cn/ja/docs/troubleshooting#sign-in)。
- WeChat の QR コードや認証コード：[ログインのトラブルシューティング](https://docs.beatra.cn/ja/docs/sign-in-help)。
- クレジット不足：[トラブルシューティング：クレジットが足りない](https://docs.beatra.cn/ja/docs/troubleshooting#credits)。

Skill を Beatra MCP や REST API と比べるには、[利用方法の選び方](https://docs.beatra.cn/ja/docs/choose-integration)をご覧ください。Skill が呼び出せるツールはすべて [MCP ツールリファレンス](https://docs.beatra.cn/ja/docs/mcp-tools)にあります。