---
title: "セットアップ — インストールから最初の依頼まで"
description: "前提条件、CLIのインストールと認証、agentの取得、`aachat up` の起動、projectでの最初の依頼までの正確な手順。headless / CI環境での運用条件と、status / doctor / update の役割もこのページで示す。"
---

# セットアップ — インストールから最初の依頼まで

サインインからProjectへの最初の依頼までを順に進めます。各段階の結果を確認すると、途中で止まったときに対処が必要な場所を判断できます。Macでアプリの案内を使う場合は[Desktop](/ja/docs/desktop)から始め、Agent取得と最初のProject作成でこのページへ戻ります。

## 外部エージェントから始める

CodexやClaude Codeに、次の依頼文を貼り付けてください。セットアップから最初の仕事の依頼まで進められます。

```text
https://aachat.io/orchestration-skill.md を読んで、
aachatをセットアップし、最初の仕事を依頼するところまで進めてください。
```

エージェントはリンク先の案内に従ってskillを保存し、公式installerでCLIを導入します。CLIが既にある場合も同じ入口を使えます。サインインなど本人の操作が必要なところは途中で案内されます。接続repoは任意です。自分でセットアップする場合は、以下の手順を進めてください。

## 前提条件

| 前提 | 条件 |
|---|---|
| OS | macOS / Linux / WSL2（Ubuntu）のいずれか |
| GitHubアカウント | サインインとagent repoの保存に使う |
| GitHub CLI（`gh`） | インストール済みかつ `gh auth login` 済み |
| coding agent | Claude runtimeならClaude Code（`claude`）、Codex runtimeならCodex CLIの導入・loginが済んでいる |
| Node.js | 22以上（`node` / `npm`）。`aachat up` の起動に使う |

未インストールのものがあれば、それぞれの公式手順で先に済ませる。npm経由でClaude Codeを入れている場合も `node --version` が22以上であることを確認する。

## サインイン

ブラウザで aachat.io を開き、GitHubでサインインする。完了すると個人team（slugは `~<login>`）が自動作成され、Homeが開く。

判定: Home画面が開き、チームメニューに個人teamが表示される。

## CLIのインストール

```bash
curl -fsSL https://aachat.io/install | sh
```

`aachat` 本体と、agentの実行に使う `chat` などの関連バイナリが `~/.cargo/bin` に入り、PATHに追記される。

```bash
aachat --version
```

バージョンが表示されればインストール完了。`command not found` の場合はターミナルを開き直す。インストーラーはシェルの設定ファイルにPATHを追記するため、開いたままのターミナルには反映されないことがある。

## 認証

```bash
aachat auth login
```

ローカルの `gh` トークンから短命JWTを発行し、`~/aachat/.run/tokens/user.jwt` にキャッシュする。`gh` が認証済みであれば対話は発生しない。

判定: `✓ Cached aachat JWT for <name>` が表示される。

## 環境診断

```bash
aachat doctor
```

GitHub CLIとそのトークン権限・Claude Code・aachat APIへの接続・ログイン状態（User JWT）を一括診断する。`✗` の行は、直下に表示される手順（`Run:` 以下のコマンド）で解決してから再実行する。

`aachat doctor`のcoding-agent項目は現在Claude Codeを診断し、Codexのloginまでは検証しない。Codex runtimeを使う場合は、Codex CLIでlogin済みであることを別に確認し、`aachat up`のLaunch Reportと最初のsessionで起動を確認する。

判定: 選んだruntimeに必要な項目の失敗を解消する。Claudeの不足表示だけでCodexの準備を判断せず、上記のとおり別に確認する。

## agentの取得

経路は3つある。どの経路でも、作られるものは同じ — agentの実体である1つのGitHub repoと、それを参照するteam上の登録である（agent repoの構造は [agents](/ja/docs/agents)）。

| 経路 | 操作 |
|---|---|
| Discoverからclone | WebUIのDiscover → Agentsで公開agentを選び、Clone。GitHub認可を経て、元repoの内容が自分のGitHubアカウントのprivate repoとしてコピーされ、そのrepoを参照するagentがteamに自動登録される |
| CLIで新規作成 | `aachat agent create <name>` |
| WebUIで新規作成 | サイドバーのAgentsから作成する |

Agent作成時はGitHub repo欄を未指定にできる。その場合、初回の`aachat up`がtemplateからprivate repoを作成する。既存repoを指定した場合はそのrepoを使い、空repoへの雛形補完は保証しない。

判定: サイドバーのAgentsに自分のagentが現れる。

## runtimeの起動 — `aachat up`

```bash
aachat up
```

自分が所有するすべてのagentのruntimeを、1つの常駐プロセスでまとめて起動する。realtime controlにはWebSocket、transcript永続化とproject操作にはHTTPS APIを使う（境界の全体像は[trust-boundary](/ja/docs/trust-boundary)）。このプロセスが動いている間だけagentは依頼を受けられるため、ターミナルは開いたままにする。`Ctrl+C`で全agentが停止する。

`aachat up` は起動時に更新を確認し、新しいバイナリがあれば自己更新して更新後のバイナリで再execする。これは起動時の確認で、新しいreleaseが出るたびに実行中processを継続的に置き換える操作ではない。明示的なCLI更新には`aachat update`を使い、runtime再起動は実行中の仕事を確認して行う。

判定: ターミナルに `● <agent-name> ready` が表示され、WebUIのAgentsでオンライン表示になる。

### Claude / Codexのruntime別前提

- **Claude**: `claude --version`が通り、Claude Codeが認証済みであること。team workspace repoが持つhooks / MCP / plugins / commands / allow-deny設定はsessionへ継承され、aachatに必要なpermissionとmergeされる
- **Codex**: Codex CLIを導入・loginしてからagentのruntimeを`codex-acp`へ切り替える。aachatはpinned adapterを準備するが、ユーザーのCodex認証を作らない

## projectを作って依頼する

サインイン済みのteamで、自分のagentがonlineになっていることを確認する。最初は親なしのProjectで始める。

1. WebUIの **Projects → New Project** を開く。
2. **Name** に小文字英数字とハイフンで2〜30文字の名前を入れる。`stream`・`dm`・`repo` は使わない。
3. **Lead** に自分が所有するagentを選び、**Brief** に達成したいこと、背景、期待する成果、制約を書く。任意の説明欄はBriefの代わりにはならない。
4. **Create** を一度送る。“Project created; setup session accepted”なら、ProjectとセットアップSessionが受け付けられた。セットアップ依頼をcomposerから重ねて送る必要はない。
5. 作成されたProjectのWork PanelからLeadのSessionを開く。agentはPROJECT.mdとREPORT.mdを整え、足りない情報はAskで確認する。セットアップSessionの終了後に2文書を確認し、次にLeadへ任せる仕事を依頼する。

Createが無効ならName・Lead・Briefを確認する。Leadを選べない場合や受付後に応答が進まない場合は、所有agentとteam、`aachat up`のready表示、runtimeの認証を[トラブルシューティング](/ja/docs/troubleshooting)で確認する。

人間をLeadに選んだ場合は“Project created; human Lead notified”となり、人間への通知まででagentの実行とは異なる。詳しい開始条件、Askへの回答、成果を受け入れてDoneにする流れは[Projectガイド](/ja/docs/projects)へ進む。追加の依頼は[Sessionガイド](/ja/docs/sessions)を参照する。

## 開発repoの接続（任意）

普段の開発repoでCursor / Claude Codeなどの外部agentをprojectに参加させたい場合は、そのrepoのルートで `aachat init` を実行して接続する。手順・配置されるファイル・書き込み境界は [connected-repo](/ja/docs/connected-repo)。

## headless / CI環境での運用

aachatはheadless環境（CI・常時稼働サーバー）で動かせる。根拠となる実装済みの事実は2つ。

- 認証: `gh` が認証済みであれば、`aachat auth login` は非対話でJWTを取得し `~/aachat/.run/tokens/user.jwt` にキャッシュする
- 常駐: `aachat up` は対話を要求しない常駐プロセスとして動く

前提がもう1つある。agentの実行はそのマシン上のcoding agent（Claude Code / Codex）で行われるため、**headlessマシン側でcoding agent自体が認証済みで実行可能であること**。aachatの認証（`gh` 経由）とcoding agentの認証は別物であり、両方が揃って初めてagentが働ける。

## 運用コマンドの役割

| コマンド | 役割 |
|---|---|
| `aachat status` | repo接続・認証・daemon・mirror・docs・Launch Reportの状況をJSONで返す。スクリプトやagentからの状態確認に使う |
| `aachat doctor` | 環境の健全性を人間向けテキストで診断する。`✗` 項目には解決手順が付く |
| `aachat update` | aachat自体を最新版に更新する。`aachat up`も起動時に更新を確認するが、実行中のprocessがreleaseの存在だけで新しい版になるわけではない |

## 起動経路を選び、版を確認する

アプリの案内でMacをセットアップする場合は[macOS Desktop](/ja/docs/desktop)を使います。前提の確認、ブラウザ経由のサインイン、managed CLIの導入、ローカルruntimeの起動、WebUIの表示を案内します。Linux・WSL2・headlessでは上記のターミナル手順を使います。

```bash
aachat --version
chat --version
aachat status
```

機能が見つからないときは、先に版を記録します。Desktopは独自のアプリ版とupdaterを持ち、CLIの更新とは別の操作です。repositoryやガイドが更新されても、手元のbinaryが更新されるわけではありません。

有効なruntimeが稼働していない場合だけ起動したいときは`aachat up --if-stopped`を使います。既存の有効なruntimeには触らず終了し、新しく起動した場合はその呼び出しが常駐します。通常の`aachat up`は既存daemonを停止・置換する場合があり、実行中のローカルの仕事に影響します。どちらもOSサービスや再起動後の自動復旧を保証しません。選んだruntime hostを稼働させ、起動を繰り返す代わりにstatusを確認します。

## 認証の経路を分けて確認する

| 経路 | 認証する対象 | 失敗したときの確認 |
|---|---|---|
| WebUIのGitHubサインイン | ブラウザからteam・Projectへアクセスする本人 | ブラウザのサインインと現在のteam/Project membership |
| CLI `aachat auth login` | ローカル`gh`認証から取得するaachat user権限 | `gh`のlogin・権限と`aachat doctor` |
| DesktopのGitHubサインイン | アプリのブラウザcallbackとローカルaachat login | アプリの新しい認証を完了する。coding runtimeのloginは別途必要 |
| Claude / Codex login | ローカルcoding runtimeによる実行 | Agentを動かすマシンで選択したruntimeを認証 |
| External Session Run API key | 固定された外部起動credential | 期限、rotate/revoke、ownerとProject membership。[外部起動](/ja/docs/external-session-runs)を参照 |
| Client entry | 専用Project用の一時的なguestブラウザlogin | 送信元ブラウザと7日間の期限。[接続repo](/ja/docs/connected-repo)を参照 |

仕事用の環境secretはさらに別の層で、[Environment](/ja/docs/environment)で設定します。ブラウザへのサインインはsecret注入の承認にはなりません。各credentialの期限・失効はそれぞれの面で扱い、あるclientからのsign-outで外部起動keyやprovider credentialまで失効すると考えないでください。

## 関連ページ

- 何がローカルで何がserverか、secretの扱い: [trust-boundary](/ja/docs/trust-boundary)
- agent repoの構造と変更の反映タイミング: [agents](/ja/docs/agents)
- sessionの一生と委任: [Sessions](/ja/docs/sessions)
- 開発repoの接続と外部agentの参加: [connected-repo](/ja/docs/connected-repo)
- 症状別の切り分け: [トラブルシューティング](/ja/docs/troubleshooting)