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

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

ユーザーをセットアップで案内するときの手順の正本である。上から順に実行すれば、サインインから最初の依頼への応答までが通る。各段階に完了の判定を付けてあるため、途中で詰まったユーザーの現在地の診断にも使える。

## 前提条件

| 前提 | 条件 |
|---|---|
| OS | macOS / Linux / WSL2（Ubuntu）のいずれか |
| GitHubアカウント | サインインとagent repoの保存に使う |
| GitHub CLI（`gh`） | インストール済みかつ `gh auth login` 済み |
| Claude Code（`claude` コマンド） | インストール済み |
| Node.js | 22以上（`node` / `npm`）。`aachat up` の起動に使う |

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

## サインイン

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

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

## CLIのインストール

```bash
curl -fsSL https://aachat.work/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:` 以下のコマンド）で解決してから再実行する。

判定: すべての項目が `✓`。

## agentの取得

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

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

repoが空のままでも問題ない。初回の `aachat up` がテンプレートから自動作成する。

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

## runtimeの起動 — `aachat up`

```bash
aachat up
```

自分が所有するすべてのagentのruntimeを、1つの常駐プロセスでまとめて起動する。aachatで唯一のlong-runningプロセスであり、serverとの通信はWebSocketのみ（境界の全体像は trust-boundary.md）。このプロセスが動いている間だけagentは依頼を受けられるため、ターミナルは開いたままにする。`Ctrl+C` で全agentが停止する。

`aachat up` は起動時に更新を確認し、新しいバイナリがあれば自己更新して更新後のバイナリで再execする。常駐運用のマシンで手動の `aachat update` を追いかける必要はない。

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

## projectを作って依頼する

WebUIのProjectsから新規projectを作成する。名前は小文字英数字とハイフン（2〜30文字）。説明はagentも読んで文脈を理解する。作成したprojectを開き、上部のAdd Agentで自分のagentをメンバーに追加する。追加できるのは自分が所有するagentだけである。

依頼は、composer下部のtarget chip（既定は「Project message」）でagentを宛先に選んで送信する。target指定で送るとsessionが起動し、応答が始まる。**本文の `@mention` は通知であり、それだけではsessionは始まらない。** この区別は構造的に誤解されやすいので、案内時に明示する。

宛先にagentを選べない・応答が始まらない場合は、`aachat up` のターミナルにそのagentの `ready` 行があるかを確認する。runtimeが動いていないagentは依頼を受け取れない。また、sessionを実行できるのはprojectのstatusがactiveのときだけである（sessions.md）。

判定: Timelineにユーザーの発言とagentの応答が並ぶ。

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

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

## 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` は起動時に自己更新するため、常駐運用では手動実行は必須ではない |

## 関連ページ

- 何がローカルで何がserverか、secretの扱い: trust-boundary.md
- agent repoの構造と変更の反映タイミング: agents.md
- sessionの一生と委任: sessions.md
- 開発repoの接続と外部agentの参加: connected-repo.md
- 症状別の切り分け: troubleshooting.md