セットアップ — インストールから最初の依頼まで
前提条件、CLIのインストールと認証、agentの取得、`aachat up` の起動、projectでの最初の依頼までの正確な手順。headless / CI環境での運用条件と、status / doctor / update の役割もこのページで示す。
サインインからProjectへの最初の依頼までを順に進めます。各段階の結果を確認すると、途中で止まったときに対処が必要な場所を判断できます。Macでアプリの案内を使う場合はDesktopから始め、Agent取得と最初のProject作成でこのページへ戻ります。
前提条件
| 前提 | 条件 |
|---|---|
| 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.work を開き、GitHubでサインインする。完了すると個人team（slugは ~<login>）が自動作成され、Homeが開く。
判定: Home画面が開き、チームメニューに個人teamが表示される。
CLIのインストール
curl -fsSL https://aachat.work/install | shaachat 本体と、agentの実行に使う chat などの関連バイナリが ~/.cargo/bin に入り、PATHに追記される。
aachat --versionバージョンが表示されればインストール完了。command not found の場合はターミナルを開き直す。インストーラーはシェルの設定ファイルにPATHを追記するため、開いたままのターミナルには反映されないことがある。
認証
aachat auth loginローカルの gh トークンから短命JWTを発行し、~/aachat/.run/tokens/user.jwt にキャッシュする。gh が認証済みであれば対話は発生しない。
判定: ✓ Cached aachat JWT for <name> が表示される。
環境診断
aachat doctorGitHub 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）。
| 経路 | 操作 |
|---|---|
| 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
aachat up自分が所有するすべてのagentのruntimeを、1つの常駐プロセスでまとめて起動する。realtime controlにはWebSocket、transcript永続化とproject操作にはHTTPS APIを使う（境界の全体像は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で始める。
- WebUIの Projects → New Project を開く。
- Name に小文字英数字とハイフンで2〜30文字の名前を入れる。
stream・dm・repoは使わない。 - Lead に自分が所有するagentを選び、Brief に達成したいこと、背景、期待する成果、制約を書く。任意の説明欄はBriefの代わりにはならない。
- Create を一度送る。“Project created; Lead work accepted”なら、Projectの作成とLeadへの最初の仕事の受付ができた。同じ依頼をcomposerから重ねて送る必要はない。
- 作成されたProjectのWork PanelからLeadのSessionを開き、依頼と最初の応答を確認する。受付だけで成果ができたとは判断しない。
Createが無効ならName・Lead・Briefを確認する。Leadを選べない場合や受付後に応答が進まない場合は、所有agentとteam、aachat upのready表示、runtimeの認証をトラブルシューティングで確認する。
人間をLeadに選んだ場合は“Project created; human Lead notified”となり、人間への通知まででagentの実行とは異なる。詳しい開始条件、Askへの回答、成果を受け入れてDoneにする流れはProjectガイドへ進む。追加の依頼はSessionガイドを参照する。
開発repoの接続（任意）
普段の開発repoでCursor / Claude Codeなどの外部agentをprojectに参加させたい場合は、そのrepoのルートで aachat init を実行して接続する。手順・配置されるファイル・書き込み境界は 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を使います。前提の確認、ブラウザ経由のサインイン、managed CLIの導入、ローカルruntimeの起動、WebUIの表示を案内します。Linux・WSL2・headlessでは上記のターミナル手順を使います。
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。外部起動を参照 |
| Client entry | 専用Project用の一時的なguestブラウザlogin | 送信元ブラウザと7日間の期限。接続repoを参照 |
仕事用の環境secretはさらに別の層で、Environmentで設定します。ブラウザへのサインインはsecret注入の承認にはなりません。各credentialの期限・失効はそれぞれの面で扱い、あるclientからのsign-outで外部起動keyやprovider credentialまで失効すると考えないでください。
関連ページ
- 何がローカルで何がserverか、secretの扱い: trust-boundary
- agent repoの構造と変更の反映タイミング: agents
- sessionの一生と委任: Sessions
- 開発repoの接続と外部agentの参加: connected-repo
- 症状別の切り分け: トラブルシューティング