===============================================================
 案内役の指示書 ── ここから先は、あなた（チャットAI）への指示です
===============================================================

あなたは、これから AI エージェント専用の小さなサーバを1台立ち上げようとしている人の、
案内役（ナビゲーター）です。この指示書のあとに、手順書の全文が入っています。

■ 相手のこと
  - エンジニアではありません。Linux を触ったことがないかもしれません
  - 手元の PC は Windows を想定しています
  - 手順書を自分で読む時間がないので、あなたに案内を頼んでいます

■ あなたの進め方（ここが最も大事です）

  1. 🔴 一度に案内するのは「1工程だけ」。先の話をしないでください
       まとめて説明すると、必ずどこかで迷子になります。
       いま何をしていて、次に何をするかだけを言ってください

  2. 🔴 次に進む前に、必ず「終わりの印」を確認する
       各章の末尾に「✅ ここまで出来たら」があります。
       そこに書かれた確認を1つずつ聞いて、**相手が「できた」と言うまで次に進まない**でください
       「たぶんできた」で進めると、あとで必ず戻ることになります

  3. 🔴 戻せない操作は、必ず本人に押してもらう
       ディスクを消す／BIOS（起動前の設定画面）を変える／再起動する／
       アカウントを作る・認証する、といった操作は、
       **「これから○○します。よろしいですか」と先に確認してから**進めてください
       あなたが代わりに判断してはいけません

  4. 手順書に無いことを、想像で足さない
       手順書に書いていないことを聞かれたら、
       「手順書には書かれていません」と正直に言ってください。
       それらしい手順を作らないでください。**間違った手順は、事故になります**

  5. 用語は、初めて出すときに言い換える
       例：「BIOS（パソコンの電源を入れた直後に出る、起動前の設定画面）」
       専門用語をそのまま使わないでください

  6. 詰まったら、画面を見せてもらう
       「その画面のスクリーンショットを貼ってください」と頼んでください。
       文字で説明してもらうより、はるかに早く分かります

  7. 最初に「先に埋める表」を一緒に埋める
       手順書の 2章に、機械ごとに変わる値（ユーザー名・IP など）を集めた表があります。
       **本文には決め打ちの値が出てきません。**
       進みながら分かった値を、その表に書き留めるよう促してください

  8. 時間の話をしない
       所要時間は人によって何倍も変わります。「あと○分です」とは言わないでください。
       「終わりの印」で進み具合を伝えてください

■ 最初のひとこと（これから始めるとき）

  相手に、まずこう伝えてください。

    - 全部で11の工程があること
    - 7番目まで行けば一区切りで、そこで「話しかけたら返事が来る」ようになること
    - 機械が届く前にできることが2つあること
    - いま、どこから始めたいか（機械はもう手元にあるか）

■ 工程の全体（相手に見せてよい地図）

  機械が届く前   ① 入口をつくる（チャットの Bot）
                ② インストール用の USB をつくる
  機械が届いた日 ③ 箱を建てる（OS を入れる）
                ④ 別の PC から入れるようにする
                ⑤ 右腕を入れる
                ⑥ 配管をつなぐ
              ★ ⑦ 第1関門 ── 話しかけたら返事が来る
  後日でよい     ⑧ 外から届くようにする
                ⑨ 出口を置く　⑩ 控えを置く　★ ⑪ 合格判定

===============================================================
 ここから下が、手順書の全文です
===============================================================


===============================================================
【00_setup_intro.md】
===============================================================

# 導入編 — はじめに（読む順はここ）

!!! success "この手順書を上から通すと、**こうなります**"
    スマホの Discord に、こう書くだけで仕事が返ってくる机が出来ます。

    ```
    あなた   このサーバのCPUとメモリとディスクを調べて、表にして教えて
    右腕     承知しました。
             | 項目 | 値 |
             |---|---|
             | CPU | AMD Ryzen 5 7640HS（6コア12スレッド） |
             | メモリ | 15Gi（うち空き 13Gi） |
             | ディスク | 476G（使用 12G） |
    ```

    **24時間そこに居ます。**あなたが寝ている間も止まりません。
    書かせたものは Wiki に置かれ、原稿は Git に控えが残ります。

    → **[1. これが終わると、何ができるか](01_what_you_get.md)** から読んでください。

---

## 誰のための手順書か

**自分の手で、AI エージェント専用の小さなサーバを1台立ち上げたい方**のためのものです。
Linux を触ったことが無くても通るように書いてあります。手元の PC は **Windows** を前提にしています。

書いた人がそばに居なくても、この1本で最後まで行けることを目標にしています。

---

## 読む順（全14章・3つの区切り）

**一気に通す必要はありません。**機械が届く前にできる章が2つあり、
10章まで行けば一区切りです。残りは別の日でも、別の場所からでもできます。

| いつ | 章 |
|---|---|
| **① 機械が届く前** | [4. 入口をつくる（Discord の Bot）](04_discord_bot.md) ／ [5. USB インストーラをつくる](05_usb.md) |
| **② 機械が届いた日** | [6. 箱を建てる](06_ubuntu.md) → [7. SSH](07_ssh.md) → [8. Claude Code](08_claude.md) → [9. xangi](09_xangi.md) |
| **★ 一区切り** | ✅ **[10. 第1関門 — Discord から話しかける](10_first_talk.md)** |
| **③ 後日でよい** | [11. 外から届く](11_tailscale.md) → [12. 出口（Wiki）](12_wiki.md) → [13. 控え（Git）](13_git.md) → [14. 合格判定と引き渡し](14_handover.md) |

!!! success "🤝 各工程に「サポート役」を付けられます"
    4章〜9章の冒頭に、**その工程まるごとをチャットAI（ChatGPT・Claude など）に渡すためのファイル**を置いてあります。
    作業を始める前にそれを渡しておくと、**詰まった画面のスクリーンショットを貼るだけ**で、
    どこで止まっているかを見てくれます。**一人で進むための仕掛けです。**

!!! note "所要時間は書いていません"
    **かかる時間は、慣れによって何倍も変わります。**時間で追うと、遅れているように感じて雑になります。
    各章の末尾にある**「✅ ここまで出来たら」の印**で進み具合を見てください。

**先に [2. 先に埋める表](02_values.md) を開いて、手元に置いてください。**
この手順書は、機械ごとに変わる値（ユーザー名・IP など）を**すべてその1枚に集めて**あります。
本文には決め打ちの値が出てきません。全体の順序は [3. 工程表](03_flow.md) にあります。

詰まったときは **[詰まったら（全部まとめ）](90_troubleshooting.md)**。
通した記録は **[📓 記録場](log/index.md)** に書き足してください。

---

## この手順書の約束

| # | 約束 | なぜ |
|---|---|---|
| 1 | **書いた人がいなくても通ります** | そばに人がいる前提、電話で補う前提では書いていません |
| 2 | **機種と環境を決め打ちしません** | 埋める値は [2章の表](02_values.md) 1枚に集めてあります |
| 3 | **詰まる場所が先に書いてあります** | 各章の末尾と [90章](90_troubleshooting.md) に「詰まったら」があります |
| 4 | **価値が先、土台が後** | 何ができるようになるかを [1章](01_what_you_get.md) で見てから、手順に入ります |
| 5 | **通した人が書き足せます** | [記録場](log/index.md) があります。**詰まったことを書いてください。**次の人が助かります |

!!! note "実際に通した記録から起こしています"
    この手順書は机上の設計ではなく、**ある導入案件で1台を実機で立ち上げた記録**
    （PC 調達 → Ubuntu → SSH → Claude Code → xangi → Discord Bot → Tailscale）を土台にしています。

    ただし **12章（出口 Wiki）と13章（控え Git）は、まだ実機で通していません。**
    そのことは各章に明記してあります。**通っていない手順を、通ったことにはしません。**

---

## どんな機械が要るか

特別なものは要りません。**24時間つけっぱなしにできる小さな PC が1台**あれば足ります。

| 要件 | 目安 | なぜ |
|---|---|---|
| **有線 LAN が挿せる** | 1口あれば十分 | 24時間動かす機械は、有線のほうが確実に安定します |
| **メモリ** | 16GB あれば余裕 | 考えるのはクラウド側の AI なので、大きな性能は要りません |
| **SSD** | 256GB 以上 | 成果物とログの置き場です |
| **静かで、置き場所がある** | — | 鍵のかかる部屋か、人目のある場所に置きます（[6章](06_ubuntu.md)で理由を書きます） |

この手順書を書くときに想定した機械は **GMKtec NucBox M6 Ultra**（AMD Ryzen 5 7640HS・16GB DDR5・
512GB SSD・有線 2.5GbE が2口・79,999円）です。**同等のミニPC なら、どれでも同じように通ります。**

ノートPC でも建てられますが、**蓋を閉じても眠らないようにする設定**が別に要ります。
この手順書はミニPC を前提にしているので、その章はありません。

!!! warning "🔴 3つだけ、機種によって違います（現物で確かめてください）"
    推測で書かないと決めたので、そこは**候補を並べて、確かめる手順**にしてあります。

    | | 何が機種で違うか | どこで確かめるか |
    |---|---|---|
    | 1 | **BIOS（起動前の設定画面）の入り方**が `Delete` か `F7` か | [6章](06_ubuntu.md) |
    | 2 | **最初から入っている OS** が何か | [6章](06_ubuntu.md) |
    | 3 | **停電のあと、自動で電源が入るか**（BIOS に項目があるか） | [6章](06_ubuntu.md) |

    確かめた結果は [2章の表](02_values.md) と [初回の記録用紙](log/first_setup.md) に書いてください。

---

## この手順書が扱う範囲 —— 採用と研修は分けています

| | 何を | 終点 | |
|---|---|---|---|
| **採用編** | 機器のセットアップ。箱を建て、入口・出口・控えを置く | **Discord から右腕に話しかけられる**ところまで | 🔴 **これがこの手順書** |
| **研修編** | 右腕の育て方。実際の仕事を渡す。丸投げ→スキル→システム化 | 右腕が実際の仕事を1つ片づける | ⚪ 別に作ります |

**スターターキットの4つ**で言うと、こう割れます。

| | | |
|---|---|---|
| **採用編で建てる** | **1 仕事の道具** | 入口 Discord ／ 出口 Wiki ／ 控え Git |
| **採用編で建てる** | **4 置き場所** | 24時間動く箱 |
| 研修編の話 | 2 仕事の型 | ワークフロー・役割分担・手順書・チェックリスト |
| 研修編の話 | 3 台帳 | |

!!! note "2つは仕事の質が違うので、1本に混ぜません"
    **Discord で話せるようになるまで**と、**右腕が仕事を1つ片づけるまで**では、仕事の質が変わります。
    前者は機器のセットアップ＝**採用**。後者は右腕の育て方＝**研修**です。

    採用は「技術か、仕事か」で線を引いています。**機械・回線・アカウント・道具立てまでが採用。**
    そこに**どんな仕事を、どういう順番で渡すか**は、研修の話になります。

---

## この手順書で決めていること

議論の余地はありますが、この手順書では次の形で書いています。**変えて構いません。**

| | 決めていること | 変える場合 |
|---|---|---|
| **入口** | **Discord を推奨。**スマホから呼べて、案件ごとに部屋を分けられて、無料だからです | Slack・ChatWork でも同じことができます。Bot の作り方だけ変わります |
| **道具** | **xangi**（Discord と AI をつなぐ配管） | 固定ではありません。同種の道具に置き換えられます |
| **控え** | **構造**（Wiki の作り・設定・手順書）は GitHub のプライベートリポジトリ | **コンテンツ**（成果物・日々のデータ）は、すでに使っているストレージでも構いません |


===============================================================
【01_what_you_get.md】
===============================================================

# 1. これが終わると、何ができるか

この手順を終えると、**あなた専用のデジタル新人**ができます。この手順書では、これを**「右腕」**と呼びます。スマホの Discord から頼めます。返事を Wiki に残せます。壊しても Git の履歴から戻せます。

## ① スマホから調査を頼めます

```text
あなた
このサーバのCPUとメモリとディスクを調べて、表にして教えて

右腕
| 項目 | 調査結果 |
|---|---|
| CPU | AMD Ryzen 5 7640HS（6コア12スレッド） |
| メモリ | 15Gi（うち空き 13Gi） |
| ディスク | 476G（使用 12G） |
```

数字を調べるために、サーバの前へ行く必要はありません。Discord が仕事を頼む窓口になります。

## ② 会話を、読めるページとして残せます

```text
あなた
いまの話、wiki に書いておいて

右腕
書きました。
http://<Tailscale IP>:8080/

あなた
（ブラウザで、見出しと表のあるページを読む）
```

Discord の会話は流れていきます。Wiki に置けば、後からブラウザで探して読めます。

## ③ 夜に頼み、朝に読めます

```text
あなた（夜）
この資料を調べて、明日の朝に読める比較表を作っておいて

右腕（夜のうち）
調査を始めます。

あなた（朝）
比較表を読みました。次は候補を3つに絞ってください
```

ミニPC は24時間動きます。あなたが寝ている間も止まりません。再起動した後も、人がサービスを起動し直さずに仕事を受けられる状態まで確認します。

## 入口・出口・控え

この3つが「仕事の道具」です。右腕が仕事をするための口、棚、安全装置に当たります。

| 呼び方 | 道具 | 担うこと | 無いと起きること |
|---|---|---|---|
| 入口 | Discord | 指示を出し、結果の通知を受けます。スマホから呼べます | パソコンの前でしか頼めません |
| 出口 | Wiki | 成果物を置きます。人がブラウザで読めます | 答えがチャットの流れに埋もれます |
| 控え | Git | 原稿と履歴を持ちます。壊れたら戻せます | 上書き事故が致命傷になります |

## 3つの区切り

| いつ | やること | 終わったと言える印 |
|---|---|---|
| ① 機械が届く前 | Discord の Bot、USB づくり | Bot がサーバに入り、USB が1本できる |
| ② 機械が届いた日 | Ubuntu、SSH、Claude Code、xangi | **Discord で話しかけると返事が来る** |
| ③ 後日でよい | 外からの接続、出口 Wiki、控え Git | 事務所の外からでも同じことができる |

**かかる時間は、慣れによって何倍も変わります。**この手順書に所要時間は書いていません。
上の「印」が出てから次へ進んでください。

## お金

| | |
|---|---|
| **機械** | 24時間つけっぱなしにできるミニPC が1台（[はじめに](index.md)に要件があります） |
| **AI** | 🔴 **Claude か ChatGPT の、どちらかの有料プランが要ります。**（Claude Pro / Max、または ChatGPT Plus / Pro など）**API キーは要りません。両方は要りません** |
| **入口・出口・控え** | Discord・Wiki・GitHub とも、この使い方なら無料の範囲で足ります |
| **外から繋ぐ** | Tailscale は**登録に使うメールで無料か有料かが変わります**。[11章](11_tailscale.md)で選びます |

ここまでが**採用**です。実際の仕事を渡す**研修編**は、この続きに別で作ります。

次は [2. 先に埋める表](02_values.md) です。**印刷するか、画面で開いたまま**先へ進んでください。


===============================================================
【02_values.md】
===============================================================

# 2. 先に埋める表（この手順書で使う値）

このページを印刷するか、画面で開いたまま進めてください。値が分かった時点で書き足します。以降の `<ユーザー名>` や `<LAN内IP>` は、この表の値に読み替えてください。

## この手順で使う値

| 項目 | あなたが書く値 | どこで分かるか |
|---|---|---|
| ユーザー名（`whoami` の出力） | `________________` | 7章 |
| LAN内IP（`hostname -I`） | `________________` | 7章 |
| Tailscale IP（`tailscale ip -4`） | `________________` | 11章 |
| サーバ名（`tailscale status` の左端） | `________________` | 11章 |
| Discord サーバ名・チャンネル名 | `________________` | 4章 |
| Discord のチャンネルID | `________________` | 4章 |
| （Slack の場合）自分のユーザーID `U…` | `________________` | 4b章 |
| （Slack の場合）チャンネルID `C…` | `________________` | 4b章 |
| 自分の Discord ユーザーID | `________________` | 4章 |
| Wi-Fi の SSID | `________________` | 6章 |
| Wi-Fi のパスワード | `________________` | 6章 |
| Wiki の URL | `________________` | 12章 |
| GitHub のリポジトリ名 | `________________` | 13章 |
| BIOS に入るキー（🔴 現物で確定） | `________________` | 6章 |
| 停電後の自動起動の項目名（🔴 現物で確定。無ければ「無し」） | `________________` | 6章 |

!!! danger "Bot トークンだけは別扱いです"
    **トークンだけは、この表にも、チャットにも、メールにも書かないでください。**
    置き場所は**サーバの中の `.env` ファイル1か所だけ**です。手元では Windows のメモ帳に一時的に置き、`.env` に入れたら消してください。

ユーザー名と表示名は別です。必ず `whoami` の出力を使います。IP が複数出た場合は、有線 LAN に付いた同じ網の値を使います。

## 用意するもの

| 用意するもの | 条件・使い道 |
|---|---|
| ミニPC 本体 | 届いてから始めます |
| 電源 | 本体に付属するもの |
| USB メモリ | 16GB 以上。中身を全消去してよいもの |
| LAN ケーブル | 有線接続に使います。Wi-Fi で運用する場合は不要です |
| モニタ（HDMI）・USB キーボード・USB マウス、または KVM 切替器 | **最初のセットアップだけ必要**です。詳しくは[6章の KVM の説明](06_ubuntu.md#kvm)を見ます |
| Windows PC | USB 作成と、その後の SSH に使います |
| スマホ | Discord と別ネットワーク試験に使います |

想定機種（GMKtec NucBox M6 Ultra）では、有線が2口あります。**どちらか1口**に LAN ケーブルを挿します。1口しかない機種でも構いません。メモリ増設や2台目の SSD は、この採用編では触りません。

## 値の扱い

| 値 | 人に見せてよいか | 注意 |
|---|---|---|
| ユーザー名・IP・サーバ名 | 関係者内なら可 | 公開ページには載せません |
| Discord のID | 関係者内なら可 | 数字を取り違えないようにします |
| パスワード | 不可 | 紙など安全な場所に控えます |
| Bot トークン | 不可 | `.env` 以外から消します |

!!! warning "🔴 現物が届いたら確かめること"
    BIOS に入るキーと、停電後の自動起動の項目名は未確認です。[6章](06_ubuntu.md)で確かめて、
    この表と [初回の記録用紙](log/first_setup.md) に書いてください。

次は [3. 工程表](03_flow.md) です。


===============================================================
【03_flow.md】
===============================================================

# 3. 工程表（どの順でやるか）

!!! tip "機械の到着を待たずに、いま出来ることが2つあります"
    [4章の Discord Bot](04_discord_bot.md) と [5章の USB](05_usb.md) は、ミニPC が届く前に終えられます。
    ここを先に済ませておくと、機械が届いた日は**箱を建てることだけ**に集中できます。

```mermaid
flowchart TB
    subgraph S1["① 機械が届く前"]
        direction LR
        C4["4章<br>Discord の入口"] --> C5["5章<br>USB インストーラ"]
    end
    subgraph S2["② 機械が届いた日"]
        direction LR
        C6["6章<br>Ubuntu"] --> C7["7章<br>SSH"] --> C8["8章<br>Claude Code"] --> C9["9章<br>xangi"]
    end
    M["★ 10章 第1関門<br>Discord から話しかけられる<br><small>ここで一区切りにしてよい</small>"]
    subgraph S3["③ 後日でよい"]
        direction LR
        C11["11章<br>Tailscale"] --> C12["12章<br>出口 Wiki"] --> C13["13章<br>控え Git"] --> C14["14章<br>引き渡し"]
    end
    S1 --> S2 --> M --> S3
    style M fill:#e8590c,color:#fff,stroke:#e8590c
```

## 工程と、終わりの印

**「だいたい出来た」で次へ進まないでください。**各工程には、**目で見て分かる終わりの印**を置いてあります。
それが出てから次へ行きます。

| いつ | 章 | やること | 終わりの印 |
|---|---:|---|---|
| ① 届く前 | 4 | Discord の入口をつくる | Bot がサーバのメンバー一覧に出て、値が4つそろう |
| ① 届く前 | 5 | USB インストーラをつくる | Ubuntu を書き込んだ USB が1本できる |
| ② 届いた日 | 6 | 箱を建てる（BIOS → Ubuntu） | Ubuntu が起動し、端末で更新が終わる |
| ② 届いた日 | 7 | 別の PC から入れるようにする | 別の PC から `uptime` が返る |
| ② 届いた日 | 8 | 右腕を入れる | `claude --version` が返り、ログインできる |
| ② 届いた日 | 9 | 配管をつなぐ | Discord の Bot がオンラインになる |
| ★ | 10 | **第1関門** | **再起動しても、手で何も起動せずに返事が来る** |
| ③ 後日 | 11 | 外から届くようにする | 別回線から SSH で入れる |
| ③ 後日 | 12 | 出口を置く | 別回線から Wiki が開く |
| ③ 後日 | 13 | 控えを置く | 別の場所へ複製して、中身が一致する |
| ③ 後日 | 14 | 合格判定と引き渡し | チェック表が埋まる |

!!! note "所要時間は書いていません"
    **かかる時間は、慣れによって何倍も変わります。**1時間で 10章まで行く人もいれば、
    6章で半日止まる人もいます。**時間で追うと、遅れているように感じて雑になります。**

    代わりに、上の**「終わりの印」で進み具合を見てください。**印が出ていないのに次へ進むと、
    あとの章で原因が分からなくなります。

    区切りは3つです。**①が終わったら一度休む。②の終わり（10章）で一区切り。③は別の日でよい。**

## 機械が届いた日の進め方

最初に [記録用紙](log/first_setup.md) を開きます。BIOS、初期 OS、停電復帰は**現物を見て**書きます。推測では埋めません。

作業中に止まったら、章末の表と [詰まったら](90_troubleshooting.md) を見ます。
それでも載っていない症状なら、**その場で工夫せず**記録場へ残します。

次は [4. 入口をつくる](04_discord_bot.md) です。


===============================================================
【04_discord_bot.md】
===============================================================

# 4. 入口をつくる（Discord の Bot）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_04_discord.txt](assets/support_04_discord.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】4. 入口をつくる（Discord の Bot）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 4. 入口をつくる（Discord の Bot）

    この章はミニPCが無くてもできます。Windows PC のブラウザと Discord を使います。

    !!! tip "すでに Slack を仕事で使っているなら → [4b. 入口を Slack にする場合](04b_slack.md)"
        入口は**どちらか片方だけ**でよく、両方は要りません。
        **相手が日常で使っているもの**に合わせるのが原則です。この章は Discord の手順です。

    ```mermaid
    flowchart LR
        A["① アカウントと<br>サーバ"] --> B["② アプリ"]
        B --> C["③ トークン<br>一度しか見えない"]
        C --> D["④ MESSAGE CONTENT<br>INTENT をON"]
        D --> E["⑤ Botを招待"]
        E --> F["⑥ 2つのID"]
    ```

    ## ① Discord のアカウント、サーバ、チャンネル

    <https://discord.com/> でアカウントを作ります。左側の `+` から「サーバを追加」→「オリジナルの作成」→「自分と友達のため」と進みます。分かりやすいサーバ名とチャンネル名を付け、[2章の表](02_values.md)に書きます。

    ## ② アプリを作る

    <https://discord.com/developers/applications> を開きます。右上の「New Application」を押します。名前を入れ、規約にチェックし、「Create」を押します。

    ## ③ Bot トークンを取り出す

    左の「Bot」を開きます。「Reset Token」→「Yes, do it!」→「Copy」と進みます。

    !!! danger "トークンは一度しか見えません"
        Windows のメモ帳に一時的に貼ります。チャット、メール、Wiki、2章の表には貼りません。9章でサーバの `.env` に入れたら、メモ帳から消します。忘れた場合は Reset Token で再発行でき、古いものは無効になります。

    ## ④ MESSAGE CONTENT INTENT を ON

    同じ Bot 画面の「Privileged Gateway Intents」まで下へ動かします。

    | 項目 | 設定 |
    |---|---|
    | Presence Intent（プレゼンス。オンライン状態） | 任意 |
    | Server Members Intent（サーバメンバー情報） | 任意 |
    | **Message Content Intent（メッセージ本文）** | **ON（必須）** |

    最後に「Save Changes」を押します。ここが OFF だと、Bot はオンラインでもメッセージの中身を読めず、返事をしません。もっとも多いつまずきです。

    ## ⑤ Bot をサーバに招待

    左の「OAuth2」→「OAuth2 URL Generator」を開きます。

    SCOPES（機能の範囲）は2つ選びます。

    | 英語表示 | 日本語での意味 |
    |---|---|
    | `bot` | Bot をサーバに追加します |
    | `applications.commands` | スラッシュコマンドを使えるようにします |

    BOT PERMISSIONS（Bot の権限）は8つ選びます。

    | # | 日本語表示 | 英語表示 | なぜ要るか |
    |---:|---|---|---|
    | 1 | チャンネルを見る | View Channels | これが無いとチャンネルが見えないためです |
    | 2 | メッセージを送る | Send Messages | 返事をするためです |
    | 3 | **Threadsでメッセージを送る** | **Send Messages in Threads** | スレッドを1件の仕事として使うためです |
    | 4 | **スレッドを管理** | **Manage Threads** | スレッド内の `Close` ボタンで、押した人を退出させるためです |
    | 5 | メッセージ履歴を読む | Read Message History | 前の会話を踏まえて答えるためです |
    | 6 | ファイルを添付 | Attach Files | 作った資料や画像を返すためです |
    | 7 | **リアクションを付ける** | **Add Reactions** | 受け取った合図を絵文字で返すためです |
    | 8 | **スラッシュコマンドを使用** | **Use Slash Commands** | `/` で始まるコマンドを使うためです |

    下に出る「GENERATED URL」をコピーしてブラウザで開きます。①のサーバを選び、認証します。メンバー一覧に Bot が出れば成功です。まだオフラインで正常です。9章で xangi とつながるとオンラインになります。

    !!! warning "後から権限を足した場合は、もう一度認可します"
        URL Generator でチェックを入れただけでは、すでに入っている Bot の権限は変わりません。生成した URL を開き、もう一度認可します。または、サーバ設定の Bot ロールか、対象チャンネルの権限へ直接反映します。

    ## ⑥ ユーザーIDとチャンネルID

    Discord の歯車から「ユーザー設定」→「詳細設定」→「開発者モード」を ON にします。

    | 取る値 | 操作 |
    |---|---|
    | 自分のユーザーID | 自分の名前を右クリック。スマホは長押し。「ユーザーIDをコピー」 |
    | チャンネルID | 対象チャンネルを右クリック。「チャンネルIDをコピー」 |

    どちらも18〜19桁の数字です。[2章の表](02_values.md)に書きます。ユーザーIDは、誰の指示を受けるかを制限するために必要です。

    ## 手元に残る4つ

    | # | 名前 | 置き場所 |
    |---:|---|---|
    | 1 | Bot トークン | Windows メモ帳へ一時保存。最終的には `.env` だけ |
    | 2 | 自分のユーザーID | 2章の表 |
    | 3 | チャンネルID | 2章の表 |
    | 4 | サーバ名・チャンネル名 | 2章の表 |

    ## ✅ ここまで出来たら

    Bot がサーバのメンバー一覧に現れ、上の4つがそろえば合格です。Bot はオフラインのままで構いません。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | Bot はオンラインなのに無反応 | MESSAGE CONTENT INTENT が ON か確認します |
    | 後から権限を足したのに反応しない | 生成した招待 URL で、もう一度認可したか確認します |
    | IDをコピーする項目がない | 開発者モードが ON か確認します |
    | トークンを忘れた | Reset Token で再発行します。古いトークンは無効です |

    次は [5. USB インストーラをつくる](05_usb.md) です。
    ````
<!-- SUPPORT:END -->
この章はミニPCが無くてもできます。Windows PC のブラウザと Discord を使います。

!!! tip "すでに Slack を仕事で使っているなら → [4b. 入口を Slack にする場合](04b_slack.md)"
    入口は**どちらか片方だけ**でよく、両方は要りません。
    **相手が日常で使っているもの**に合わせるのが原則です。この章は Discord の手順です。

```mermaid
flowchart LR
    A["① アカウントと<br>サーバ"] --> B["② アプリ"]
    B --> C["③ トークン<br>一度しか見えない"]
    C --> D["④ MESSAGE CONTENT<br>INTENT をON"]
    D --> E["⑤ Botを招待"]
    E --> F["⑥ 2つのID"]
```

## ① Discord のアカウント、サーバ、チャンネル

<https://discord.com/> でアカウントを作ります。左側の `+` から「サーバを追加」→「オリジナルの作成」→「自分と友達のため」と進みます。分かりやすいサーバ名とチャンネル名を付け、[2章の表](02_values.md)に書きます。

## ② アプリを作る

<https://discord.com/developers/applications> を開きます。右上の「New Application」を押します。名前を入れ、規約にチェックし、「Create」を押します。

## ③ Bot トークンを取り出す

左の「Bot」を開きます。「Reset Token」→「Yes, do it!」→「Copy」と進みます。

!!! danger "トークンは一度しか見えません"
    Windows のメモ帳に一時的に貼ります。チャット、メール、Wiki、2章の表には貼りません。9章でサーバの `.env` に入れたら、メモ帳から消します。忘れた場合は Reset Token で再発行でき、古いものは無効になります。

## ④ MESSAGE CONTENT INTENT を ON

同じ Bot 画面の「Privileged Gateway Intents」まで下へ動かします。

| 項目 | 設定 |
|---|---|
| Presence Intent（プレゼンス。オンライン状態） | 任意 |
| Server Members Intent（サーバメンバー情報） | 任意 |
| **Message Content Intent（メッセージ本文）** | **ON（必須）** |

最後に「Save Changes」を押します。ここが OFF だと、Bot はオンラインでもメッセージの中身を読めず、返事をしません。もっとも多いつまずきです。

## ⑤ Bot をサーバに招待

左の「OAuth2」→「OAuth2 URL Generator」を開きます。

SCOPES（機能の範囲）は2つ選びます。

| 英語表示 | 日本語での意味 |
|---|---|
| `bot` | Bot をサーバに追加します |
| `applications.commands` | スラッシュコマンドを使えるようにします |

BOT PERMISSIONS（Bot の権限）は8つ選びます。

| # | 日本語表示 | 英語表示 | なぜ要るか |
|---:|---|---|---|
| 1 | チャンネルを見る | View Channels | これが無いとチャンネルが見えないためです |
| 2 | メッセージを送る | Send Messages | 返事をするためです |
| 3 | **Threadsでメッセージを送る** | **Send Messages in Threads** | スレッドを1件の仕事として使うためです |
| 4 | **スレッドを管理** | **Manage Threads** | スレッド内の `Close` ボタンで、押した人を退出させるためです |
| 5 | メッセージ履歴を読む | Read Message History | 前の会話を踏まえて答えるためです |
| 6 | ファイルを添付 | Attach Files | 作った資料や画像を返すためです |
| 7 | **リアクションを付ける** | **Add Reactions** | 受け取った合図を絵文字で返すためです |
| 8 | **スラッシュコマンドを使用** | **Use Slash Commands** | `/` で始まるコマンドを使うためです |

下に出る「GENERATED URL」をコピーしてブラウザで開きます。①のサーバを選び、認証します。メンバー一覧に Bot が出れば成功です。まだオフラインで正常です。9章で xangi とつながるとオンラインになります。

!!! warning "後から権限を足した場合は、もう一度認可します"
    URL Generator でチェックを入れただけでは、すでに入っている Bot の権限は変わりません。生成した URL を開き、もう一度認可します。または、サーバ設定の Bot ロールか、対象チャンネルの権限へ直接反映します。

## ⑥ ユーザーIDとチャンネルID

Discord の歯車から「ユーザー設定」→「詳細設定」→「開発者モード」を ON にします。

| 取る値 | 操作 |
|---|---|
| 自分のユーザーID | 自分の名前を右クリック。スマホは長押し。「ユーザーIDをコピー」 |
| チャンネルID | 対象チャンネルを右クリック。「チャンネルIDをコピー」 |

どちらも18〜19桁の数字です。[2章の表](02_values.md)に書きます。ユーザーIDは、誰の指示を受けるかを制限するために必要です。

## 手元に残る4つ

| # | 名前 | 置き場所 |
|---:|---|---|
| 1 | Bot トークン | Windows メモ帳へ一時保存。最終的には `.env` だけ |
| 2 | 自分のユーザーID | 2章の表 |
| 3 | チャンネルID | 2章の表 |
| 4 | サーバ名・チャンネル名 | 2章の表 |

## ✅ ここまで出来たら

Bot がサーバのメンバー一覧に現れ、上の4つがそろえば合格です。Bot はオフラインのままで構いません。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| Bot はオンラインなのに無反応 | MESSAGE CONTENT INTENT が ON か確認します |
| 後から権限を足したのに反応しない | 生成した招待 URL で、もう一度認可したか確認します |
| IDをコピーする項目がない | 開発者モードが ON か確認します |
| トークンを忘れた | Reset Token で再発行します。古いトークンは無効です |

次は [5. USB インストーラをつくる](05_usb.md) です。


===============================================================
【04b_slack.md】
===============================================================

# 4b. 入口を Slack にする場合

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_04b_slack.txt](assets/support_04b_slack.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】4b. 入口を Slack にする場合

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 4b. 入口を Slack にする場合

    !!! info "この章は、Slack を使う方だけ読んでください"
        [4章](04_discord_bot.md)の Discord の代わりに、**Slack を入口にする**手順です。
        どちらか**片方だけ**でよく、両方は要りません。

        **すでに Slack を仕事で使っている**なら、こちらの方が自然です。
        新しいアプリを増やさずに済み、いつも見ている画面から右腕に話しかけられます。

    !!! success "✅ この手順は 2026-09-09 に実機で1回通りました"
        実際に1台のミニPC で、Slack から右腕に話しかけられるところまで確認しています。
        そのとき詰まったのは**次の3つだけ**でした。どれも下に書いてあります。

        | | 詰まったところ |
        |---|---|
        | 1 | `.env` の見本の文字（`your-bot-token` など）を**消し切っていなかった** |
        | 2 | `#` を消したあと、**行頭に空白が残っていた** |
        | 3 | 直したのに**古いログを見ていて**、直っていないと思い込んだ |

        ただし、通したのは**この1台だけ**です。画面の文言はバージョンで変わることがあります。
        詰まったところは[記録場](log/index.md)に書き足してください。

    !!! success "Slack は「Socket Mode」で繋ぎます — 外から届く住所が要りません"
        サーバ側から Slack へ**繋ぎに行く**方式なので、**家や事務所のネットワークに穴を開ける必要がありません。**
        ルータの設定も、固定の住所も要らない、ということです。

    ## ① Slack アプリを作る（Manifest を貼るのが最短です）

    <https://api.slack.com/apps> を開き、Slack にログインします。

    1. **Create New App** → **From an app manifest** を選ぶ
    2. ワークスペースを選ぶ
    3. 形式は **YAML** を選び、下の内容を**まるごと貼り付ける**
    4. **Next** → **Create**

    ??? note "📋 貼り付ける Manifest（クリックで開く）"

        ```yaml
        display_information:
          name: xangi
          description: AI CLI assistant for Slack
          background_color: '#2f3136'
        features:
          bot_user:
            display_name: xangi
            always_online: false
        oauth_config:
          scopes:
            bot:
              - app_mentions:read
              - channels:history
              - channels:read
              - chat:write
              - files:read
              - files:write
              - groups:history
              - groups:read
              - im:history
              - im:read
              - im:write
              - reactions:read
              - reactions:write
        settings:
          event_subscriptions:
            bot_events:
              - app_mention
              - message.channels
              - message.groups
              - message.im
          interactivity:
            is_enabled: true
          org_deploy_enabled: false
          socket_mode_enabled: true
          token_rotation_enabled: false
        ```

    **これで、権限もイベントも Socket Mode も、まとめて設定されます。**
    手で1つずつ入れる方法もありますが、**取りこぼしが起きやすい**のでこちらを推します。

    ## ② App-Level Token（`xapp-` で始まる方）を作る

    Manifest を使っても、**この鍵だけは手で作ります。**

    1. 左メニュー **Basic Information** → 下の方の **App-Level Tokens** → **Generate Token and Scopes**
    2. Token Name … `xangi-socket`（何でも構いません）
    3. **Add Scope** → **`connections:write`** を選ぶ
    4. **Generate** → 表示された **`xapp-...` をコピー**

    ## ③ ワークスペースに入れて、Bot Token（`xoxb-` で始まる方）を取る

    1. 左メニュー **Install App** → **Install to Workspace**
    2. 権限を確認して **許可する**
    3. 表示された **Bot User OAuth Token（`xoxb-...`）をコピー**

    !!! danger "🔴 2つのトークンは、チャットにもメールにも貼らないでください"
        置き場所は**サーバの中の `.env` ファイル1か所だけ**です（[9章](09_xangi.md)）。
        手元では Windows のメモ帳に一時的に置き、`.env` に入れたら消してください。
        漏れてしまったときは、**同じ画面から作り直せます**（古い方は無効になります）。

    ## ④ 自分のユーザーID と、チャンネルID を控える

    | 取る値 | 操作 |
    |---|---|
    | **自分のユーザーID**（`U` で始まる） | 自分のプロフィールを開く → **︙**（その他）→ **メンバーIDをコピー** |
    | **チャンネルID**（`C` で始まる） | チャンネル名を右クリック → **リンクをコピー**。URL の末尾（`.../archives/C01234567` の `C01234567`）がID |

    どちらも [2章の表](02_values.md) に書いてください。
    ユーザーIDは、**誰の指示なら受けるか**を決めるために使います。

    ## ⑤ 🔴 Bot をチャンネルに招待する

    **ここを忘れると、何を書いても反応しません。**使いたいチャンネルで、こう打ちます。

    ```text
    /invite @xangi
    ```

    ## 手元に残る4つ

    [9章](09_xangi.md)で使います。**メモ帳に並べておいてください。**

    | # | 名前 | 見た目 | 置き場所 |
    |---:|---|---|---|
    | 1 | **Bot Token** | `xoxb-...` | 🔴 メモ帳に一時保存 → 最終的には `.env` だけ |
    | 2 | **App Token** | `xapp-...` | 🔴 同上 |
    | 3 | 自分のユーザーID | `U` で始まる | 2章の表 |
    | 4 | チャンネルID | `C` で始まる | 2章の表 |

    ## ✅ ここまで出来たら

    Slack のメンバー一覧に Bot が現れ、上の4つがそろえば合格です。
    **Bot はまだ反応しません。**サーバ側の設定（[9章](09_xangi.md)）が済むと動きます。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | 🔴 **ログに `invalid_auth` と出る** | **Bot Token（`xoxb-`）が違います。**下の「鍵が本物か確かめる」を実行してください。`xoxb-` と `xapp-` を**入れ違いに入れている**のが最も多い原因です |
    | **メンションしても無反応** | 🔴 ⑤の `/invite @xangi` を、そのチャンネルでやったか |
    | 権限を足したのに変わらない | **Install App から入れ直す**必要があります（権限の変更は再インストールで反映されます） |
    | `xapp-` のトークンが見つからない | **Basic Information** の下の方の **App-Level Tokens** です。OAuth の画面にはありません |
    | DM で反応しない | Manifest を使わず手で設定した場合、`im:history` `im:read` と `message.im` が要ります |
    | IDをコピーする項目がない | プロフィールの **︙**（その他）の中にあります |

    ## 🔑 鍵が本物か、その場で確かめる

    `.env` に入れたあと（[9章](09_xangi.md)）、Slack 本体に直接聞けます。**トークンは画面に出ません。**

    ```bash
    # どちらの鍵がどこに入っているか（先頭9文字だけ表示）
    grep -E "^SLACK_(BOT|APP)_TOKEN" ~/xangi/.env | sed -E 's/=(.{9}).*/=\1…/'
    ```

    ```bash
    # Bot Token が本物か
    curl -s -H "Authorization: Bearer $(grep '^SLACK_BOT_TOKEN=' ~/xangi/.env | cut -d= -f2-)" \
      https://slack.com/api/auth.test
    ```

    | 返ってくるもの | 意味 |
    |---|---|
    | `{"ok":true,"team":...}` | ✅ Bot Token は正常です |
    | `{"ok":false,"error":"invalid_auth"}` | 🔴 **Bot Token が違います。**取り直してください |

    ```bash
    # App Token が本物か
    curl -s -X POST -H "Authorization: Bearer $(grep '^SLACK_APP_TOKEN=' ~/xangi/.env | cut -d= -f2-)" \
      https://slack.com/api/apps.connections.open
    ```

    !!! danger "🔴 取り違えやすいもの"
        **Bot Token は `xoxb-` で始まります。**`api.slack.com/apps` → **OAuth & Permissions** の一番上、
        **Bot User OAuth Token** です。

        同じ画面の周りにある **Signing Secret** や **Client Secret** を入れると、
        このエラー（`invalid_auth`）になります。**`xoxb-` で始まっていない時点で間違いです。**

    次は [5. USB インストーラをつくる](05_usb.md) です。
    （サーバ側で Slack を繋ぐ設定は [9章](09_xangi.md) で行います。）
    ````
<!-- SUPPORT:END -->
!!! info "この章は、Slack を使う方だけ読んでください"
    [4章](04_discord_bot.md)の Discord の代わりに、**Slack を入口にする**手順です。
    どちらか**片方だけ**でよく、両方は要りません。

    **すでに Slack を仕事で使っている**なら、こちらの方が自然です。
    新しいアプリを増やさずに済み、いつも見ている画面から右腕に話しかけられます。

!!! success "✅ この手順は 2026-09-09 に実機で1回通りました"
    実際に1台のミニPC で、Slack から右腕に話しかけられるところまで確認しています。
    そのとき詰まったのは**次の3つだけ**でした。どれも下に書いてあります。

    | | 詰まったところ |
    |---|---|
    | 1 | `.env` の見本の文字（`your-bot-token` など）を**消し切っていなかった** |
    | 2 | `#` を消したあと、**行頭に空白が残っていた** |
    | 3 | 直したのに**古いログを見ていて**、直っていないと思い込んだ |

    ただし、通したのは**この1台だけ**です。画面の文言はバージョンで変わることがあります。
    詰まったところは[記録場](log/index.md)に書き足してください。

!!! success "Slack は「Socket Mode」で繋ぎます — 外から届く住所が要りません"
    サーバ側から Slack へ**繋ぎに行く**方式なので、**家や事務所のネットワークに穴を開ける必要がありません。**
    ルータの設定も、固定の住所も要らない、ということです。

## ① Slack アプリを作る（Manifest を貼るのが最短です）

<https://api.slack.com/apps> を開き、Slack にログインします。

1. **Create New App** → **From an app manifest** を選ぶ
2. ワークスペースを選ぶ
3. 形式は **YAML** を選び、下の内容を**まるごと貼り付ける**
4. **Next** → **Create**

??? note "📋 貼り付ける Manifest（クリックで開く）"

    ```yaml
    display_information:
      name: xangi
      description: AI CLI assistant for Slack
      background_color: '#2f3136'
    features:
      bot_user:
        display_name: xangi
        always_online: false
    oauth_config:
      scopes:
        bot:
          - app_mentions:read
          - channels:history
          - channels:read
          - chat:write
          - files:read
          - files:write
          - groups:history
          - groups:read
          - im:history
          - im:read
          - im:write
          - reactions:read
          - reactions:write
    settings:
      event_subscriptions:
        bot_events:
          - app_mention
          - message.channels
          - message.groups
          - message.im
      interactivity:
        is_enabled: true
      org_deploy_enabled: false
      socket_mode_enabled: true
      token_rotation_enabled: false
    ```

**これで、権限もイベントも Socket Mode も、まとめて設定されます。**
手で1つずつ入れる方法もありますが、**取りこぼしが起きやすい**のでこちらを推します。

## ② App-Level Token（`xapp-` で始まる方）を作る

Manifest を使っても、**この鍵だけは手で作ります。**

1. 左メニュー **Basic Information** → 下の方の **App-Level Tokens** → **Generate Token and Scopes**
2. Token Name … `xangi-socket`（何でも構いません）
3. **Add Scope** → **`connections:write`** を選ぶ
4. **Generate** → 表示された **`xapp-...` をコピー**

## ③ ワークスペースに入れて、Bot Token（`xoxb-` で始まる方）を取る

1. 左メニュー **Install App** → **Install to Workspace**
2. 権限を確認して **許可する**
3. 表示された **Bot User OAuth Token（`xoxb-...`）をコピー**

!!! danger "🔴 2つのトークンは、チャットにもメールにも貼らないでください"
    置き場所は**サーバの中の `.env` ファイル1か所だけ**です（[9章](09_xangi.md)）。
    手元では Windows のメモ帳に一時的に置き、`.env` に入れたら消してください。
    漏れてしまったときは、**同じ画面から作り直せます**（古い方は無効になります）。

## ④ 自分のユーザーID と、チャンネルID を控える

| 取る値 | 操作 |
|---|---|
| **自分のユーザーID**（`U` で始まる） | 自分のプロフィールを開く → **︙**（その他）→ **メンバーIDをコピー** |
| **チャンネルID**（`C` で始まる） | チャンネル名を右クリック → **リンクをコピー**。URL の末尾（`.../archives/C01234567` の `C01234567`）がID |

どちらも [2章の表](02_values.md) に書いてください。
ユーザーIDは、**誰の指示なら受けるか**を決めるために使います。

## ⑤ 🔴 Bot をチャンネルに招待する

**ここを忘れると、何を書いても反応しません。**使いたいチャンネルで、こう打ちます。

```text
/invite @xangi
```

## 手元に残る4つ

[9章](09_xangi.md)で使います。**メモ帳に並べておいてください。**

| # | 名前 | 見た目 | 置き場所 |
|---:|---|---|---|
| 1 | **Bot Token** | `xoxb-...` | 🔴 メモ帳に一時保存 → 最終的には `.env` だけ |
| 2 | **App Token** | `xapp-...` | 🔴 同上 |
| 3 | 自分のユーザーID | `U` で始まる | 2章の表 |
| 4 | チャンネルID | `C` で始まる | 2章の表 |

## ✅ ここまで出来たら

Slack のメンバー一覧に Bot が現れ、上の4つがそろえば合格です。
**Bot はまだ反応しません。**サーバ側の設定（[9章](09_xangi.md)）が済むと動きます。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| 🔴 **ログに `invalid_auth` と出る** | **Bot Token（`xoxb-`）が違います。**下の「鍵が本物か確かめる」を実行してください。`xoxb-` と `xapp-` を**入れ違いに入れている**のが最も多い原因です |
| **メンションしても無反応** | 🔴 ⑤の `/invite @xangi` を、そのチャンネルでやったか |
| 権限を足したのに変わらない | **Install App から入れ直す**必要があります（権限の変更は再インストールで反映されます） |
| `xapp-` のトークンが見つからない | **Basic Information** の下の方の **App-Level Tokens** です。OAuth の画面にはありません |
| DM で反応しない | Manifest を使わず手で設定した場合、`im:history` `im:read` と `message.im` が要ります |
| IDをコピーする項目がない | プロフィールの **︙**（その他）の中にあります |

## 🔑 鍵が本物か、その場で確かめる

`.env` に入れたあと（[9章](09_xangi.md)）、Slack 本体に直接聞けます。**トークンは画面に出ません。**

```bash
# どちらの鍵がどこに入っているか（先頭9文字だけ表示）
grep -E "^SLACK_(BOT|APP)_TOKEN" ~/xangi/.env | sed -E 's/=(.{9}).*/=\1…/'
```

```bash
# Bot Token が本物か
curl -s -H "Authorization: Bearer $(grep '^SLACK_BOT_TOKEN=' ~/xangi/.env | cut -d= -f2-)" \
  https://slack.com/api/auth.test
```

| 返ってくるもの | 意味 |
|---|---|
| `{"ok":true,"team":...}` | ✅ Bot Token は正常です |
| `{"ok":false,"error":"invalid_auth"}` | 🔴 **Bot Token が違います。**取り直してください |

```bash
# App Token が本物か
curl -s -X POST -H "Authorization: Bearer $(grep '^SLACK_APP_TOKEN=' ~/xangi/.env | cut -d= -f2-)" \
  https://slack.com/api/apps.connections.open
```

!!! danger "🔴 取り違えやすいもの"
    **Bot Token は `xoxb-` で始まります。**`api.slack.com/apps` → **OAuth & Permissions** の一番上、
    **Bot User OAuth Token** です。

    同じ画面の周りにある **Signing Secret** や **Client Secret** を入れると、
    このエラー（`invalid_auth`）になります。**`xoxb-` で始まっていない時点で間違いです。**

次は [5. USB インストーラをつくる](05_usb.md) です。
（サーバ側で Slack を繋ぐ設定は [9章](09_xangi.md) で行います。）


===============================================================
【05_usb.md】
===============================================================

# 5. USB インストーラをつくる（Windows）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_05_usb.txt](assets/support_05_usb.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】5. USB インストーラをつくる（Windows）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 5. USB インストーラをつくる（Windows）

    ミニPCが届く前にできます。Windows PC と、中身を消してよい16GB以上の USB メモリを使います。ISO のダウンロードに時間がかかるので、先に始めておくと楽です。

    ## Ubuntu を取得する

    [Ubuntu Desktop のダウンロードページ](https://ubuntu.com/download/desktop)から、**Desktop 24.04 LTS** の amd64 用 ISO を取得します。Server 版ではありません。Desktop 版なら、初回ログインを画面で行えます。

    **24.04 LTS を推します。**LTS は長期サポート版のことで、この手順書の既定です。
    より新しい版でも通ると思われますが、**画面の文言が変わることがあります。**新しい版を使う場合は、
    違ったところを[記録場](log/index.md)に書き足してください。

    ISO は約6GBです。そのため、USB メモリは16GB以上を使います。

    !!! danger "USB の中身はすべて消えます"
        別の用途で使っている USB は使わないでください。残したいファイルが1つでもある場合は、ここで止めます。

    ## Rufus で書き込む

    Rufus は、USB メモリに起動用のディスクを書き込む Windows 用の道具です。
    [Rufus 公式（日本語）](https://rufus.ie/ja/)から入手します。画面の写真もあります。インストール不要で、落としたファイルをそのまま実行できます。

    [Ubuntu 公式の手順（英語・画面写真つき）](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows)には、1手ずつ写真が載っています。英語ですが、ブラウザの翻訳で足ります。初めてで不安なときは、画面を見比べながら進めてください。

    !!! note "この章の画面写真について"
        **この章は画面写真がまだありません。** 実際に作ったときの画面を[記録場](log/index.md)に貼っていただけると、次の人が助かります。

    Rufus を Windows PC で起動します。**画面で触るのは4か所だけです。**

    | 欄の名前 | 選ぶもの | 触らない理由・補足 |
    |---|---|---|
    | デバイス | 今挿した16GB以上の USB | 名前と容量を確認します |
    | ブートの種類 | 「選択」を押し、ダウンロードした Ubuntu Desktop の ISO | ISO は起動用ディスクのファイルです |
    | パーティション構成／ターゲットシステム | **既定のまま触りません** | ISO に合わせて Rufus が選ぶためです |
    | スタート | 押して書き込みを始めます | 聞かれたら `ISO イメージモード` を選びます |

    !!! danger "Windows の内蔵ディスクを選ばないでください"
        USB の名前と容量をよく見ます。Windows PC の内蔵ディスクを選ぶと、Windows や大切なファイルを消す危険があります。

    完了表示が出たら、Windows の取り外し操作をして USB を抜きます。

    ## この USB は何度でも使えます

    作った USB は、Ubuntu を読み出すだけの道具です。インストール先の情報は USB に書き込まれません。何台にでも、何度でも使えます。

    作り直すのは、別の用途で上書きしたとき、壊れて認識しないとき、別の Ubuntu 版へ替えるときです。

    ## ✅ ここまで出来たら

    Ubuntu Desktop 24.04 LTS を書いた16GB以上の USB が1本できれば合格です。ラベルなどで Ubuntu 用だと分かるようにします。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | ISO が USB に入らない | USB が16GB以上か確認します |
    | 書き込み方法を聞かれた | ISO イメージモードを選びます |
    | USB を選ぶのが怖い | 容量を見て、別用途の USB でないことを確認します |

    次は、機械が届いた日に [6. 箱を建てる](06_ubuntu.md) へ進みます。

    ## 🟡 この手順書の未確認事項

    より新しい版を使った場合の画面の違いは、想定機種では未確認です。
    ````
<!-- SUPPORT:END -->
ミニPCが届く前にできます。Windows PC と、中身を消してよい16GB以上の USB メモリを使います。ISO のダウンロードに時間がかかるので、先に始めておくと楽です。

## Ubuntu を取得する

[Ubuntu Desktop のダウンロードページ](https://ubuntu.com/download/desktop)から、**Desktop 24.04 LTS** の amd64 用 ISO を取得します。Server 版ではありません。Desktop 版なら、初回ログインを画面で行えます。

**24.04 LTS を推します。**LTS は長期サポート版のことで、この手順書の既定です。
より新しい版でも通ると思われますが、**画面の文言が変わることがあります。**新しい版を使う場合は、
違ったところを[記録場](log/index.md)に書き足してください。

ISO は約6GBです。そのため、USB メモリは16GB以上を使います。

!!! danger "USB の中身はすべて消えます"
    別の用途で使っている USB は使わないでください。残したいファイルが1つでもある場合は、ここで止めます。

## Rufus で書き込む

Rufus は、USB メモリに起動用のディスクを書き込む Windows 用の道具です。
[Rufus 公式（日本語）](https://rufus.ie/ja/)から入手します。画面の写真もあります。インストール不要で、落としたファイルをそのまま実行できます。

[Ubuntu 公式の手順（英語・画面写真つき）](https://ubuntu.com/tutorials/create-a-usb-stick-on-windows)には、1手ずつ写真が載っています。英語ですが、ブラウザの翻訳で足ります。初めてで不安なときは、画面を見比べながら進めてください。

!!! note "この章の画面写真について"
    **この章は画面写真がまだありません。** 実際に作ったときの画面を[記録場](log/index.md)に貼っていただけると、次の人が助かります。

Rufus を Windows PC で起動します。**画面で触るのは4か所だけです。**

| 欄の名前 | 選ぶもの | 触らない理由・補足 |
|---|---|---|
| デバイス | 今挿した16GB以上の USB | 名前と容量を確認します |
| ブートの種類 | 「選択」を押し、ダウンロードした Ubuntu Desktop の ISO | ISO は起動用ディスクのファイルです |
| パーティション構成／ターゲットシステム | **既定のまま触りません** | ISO に合わせて Rufus が選ぶためです |
| スタート | 押して書き込みを始めます | 聞かれたら `ISO イメージモード` を選びます |

!!! danger "Windows の内蔵ディスクを選ばないでください"
    USB の名前と容量をよく見ます。Windows PC の内蔵ディスクを選ぶと、Windows や大切なファイルを消す危険があります。

完了表示が出たら、Windows の取り外し操作をして USB を抜きます。

## この USB は何度でも使えます

作った USB は、Ubuntu を読み出すだけの道具です。インストール先の情報は USB に書き込まれません。何台にでも、何度でも使えます。

作り直すのは、別の用途で上書きしたとき、壊れて認識しないとき、別の Ubuntu 版へ替えるときです。

## ✅ ここまで出来たら

Ubuntu Desktop 24.04 LTS を書いた16GB以上の USB が1本できれば合格です。ラベルなどで Ubuntu 用だと分かるようにします。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| ISO が USB に入らない | USB が16GB以上か確認します |
| 書き込み方法を聞かれた | ISO イメージモードを選びます |
| USB を選ぶのが怖い | 容量を見て、別用途の USB でないことを確認します |

次は、機械が届いた日に [6. 箱を建てる](06_ubuntu.md) へ進みます。

## 🟡 この手順書の未確認事項

より新しい版を使った場合の画面の違いは、想定機種では未確認です。


===============================================================
【06_ubuntu.md】
===============================================================

# 6. 箱を建てる（BIOS → Ubuntu）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_06_ubuntu.txt](assets/support_06_ubuntu.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】6. 箱を建てる（BIOS → Ubuntu）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 6. 箱を建てる（BIOS → Ubuntu）

    ミニPCには、画面もキーボードも付いていません。最初のセットアップの間だけ、操作する道具をつなぎます。5章で作った USB も挿します。

    ## 最初だけ KVM をつなぐ { #kvm }

    KVM は、Keyboard / Video / Mouse の頭文字です。ここでは「キーボード・画面・マウス」のことです。最初は、モニタ（HDMI）・USB キーボード・USB マウスが必要です。

    | やり方 | 中身 |
    |---|---|
    | テレビ／モニタを借りる | HDMI が挿さるテレビで構いません。USB キーボードとマウスを直挿しします |
    | いま使っている PC の周辺機器を一時的に付け替える | モニタのケーブルを挿し替えます |
    | **KVM 切替器を使う** | 1組のキーボード・画面・マウスを、ボタンで2台に切り替える箱です。数千円です |

    **[7章](07_ssh.md)で別の PC から SSH で入れたら、その時点で外して構いません。** 以降は画面もキーボードも要りません。この状態をヘッドレス（画面やキーボードを常時つながない運用）と言います。**これが今日いちばんの区切りです。**

    ## ネットワークを選ぶ

    | 選び方 | 向いている場面 |
    |---|---|
    | 有線 LAN | 24時間動かすなら、こちらが安定します |
    | Wi-Fi | LAN ケーブルを引けないなど、置き場所の都合があるときに使います |

    有線を使う場合は、LAN ケーブルを先につなぎます。Wi-Fi を使う場合は、SSID（Wi-Fi の名前）とパスワードを[2章の表](02_values.md)に控えます。

    ## 1. BIOS を開く

    BIOS（起動前の設定画面）を開きます。

    !!! warning "🔴 現物で確かめる"
        BIOS のキーは未確認です。`Delete` が第一候補です。入れなければ `F7`（起動メニュー）、`Esc`、`F2` の順で試します。電源を入れる**前**からキーを押しっぱなしにします。確定したキーを[記録用紙](log/first_setup.md)へ書きます。

    BIOS に入れたら、次を探します。項目は「Security」「Boot」「Advanced」の中にあることがあります。

    | 項目 | 設定 | なぜ |
    |---|---|---|
    | Secure Boot | Disabled | Ubuntu の導入で余計な壁を作らないためです |
    | Fast Boot | Disabled | USB を見つけて起動できるようにします |
    | Boot 順 | USB を先頭 | USB のインストーラから起動します |

    !!! warning "🔴 現物で確かめる"
        `Restore on AC Power Loss` 相当の項目を探します。あれば `Power On` にします。無ければ、記録場に「無かった」と書きます。項目名を推測しません。

    「Save & Exit」で保存して抜けます。

    ## 2. 初期 OS を確認する

    !!! warning "🔴 現物で確かめる"
        初期 OS は未確認です。Windows が入っている可能性はありますが、断定しません。中に必要なファイルが無いことと、初期 OS を消してよいことを確認してから進みます。確認結果を記録用紙へ書きます。

    ## 3. Ubuntu を入れる

    USB から起動し、次の順で選びます。

    | 画面 | 選ぶもの |
    |---|---|
    | 最初 | Try or Install Ubuntu |
    | 言語 | 日本語 |
    | 操作 | Install Ubuntu |
    | キーボード | Japanese |
    | ネットワーク | 有線 LAN、または下の手順で Wi-Fi |
    | インストールの種類 | ディスクを削除して Ubuntu をインストール |

    「ディスクを削除」は、SSD の中身を消します。初期 OS と必要ファイルを確認していなければ、進めません。

    ### Wi-Fi でつなぐ場合 { #wifi }

    Wi-Fi は、インストール中のネットワーク画面でつなぐのが一番確実です。一覧から[2章](02_values.md)に控えた SSID を選び、パスワードを入れます。

    Ubuntu の導入後に設定する場合は、端末で次を実行します。

    ```bash
    nmcli device wifi list  # ← SSIDが見えるか
    sudo nmcli device wifi connect "SSID名" password "パスワード"
    sudo nmcli connection modify "SSID名" connection.autoconnect yes connection.permissions ""
    ```

    最後の1行は、Wi-Fi を機械全体の設定にします。これが無いと、再起動後に誰かがログインするまでつながらず、SSH が通らないことがあります。Wi-Fi が一覧に出ない場合は[付録A](99_appendix.md#appendix-a)で切り分けます。

    ## 4. ユーザーを作る

    「名前」は人に見せる表示名です。「ユーザー名」は SSH で入るときにも使う名前です。**2つは別物です。** ユーザー名は英小文字で始めます。大文字は使えません。パスワードは安全な場所へメモします。

    「自動的にログインする」を ON にします。20〜30分待ちます。再起動の指示が出たら USB を抜きます。

    !!! note "自動ログインを ON にする理由と代償"
        無人で再起動した後も、画面側の動作環境を上げるためです。その代わり、**物理的に触れる人は誰でも中に入れます。** 置き場所が鍵です。鍵のかかる部屋か、人目のある管理された場所に置きます。

    ### Windows と違うところ { #win-diff }

    ??? warning "🔴 ここから先は、Windows と操作の作法が違います（開いて一読してください）"

        いちばん多いつまずきが **コピーと貼り付け**です。

        | やりたいこと | Windows のアプリ | **Ubuntu の端末** |
        |---|---|---|
        | コピー | `Ctrl` + `C` | **`Ctrl` + `Shift` + `C`** |
        | 貼り付け | `Ctrl` + `V` | **`Ctrl` + `Shift` + `V`** |

        🔴 **端末で `Ctrl` + `C` を押すと、コピーではなく「いま動いているものを止める」になります。**
        **`Shift` を足す**、と覚えてください。**右クリックでも貼り付けられます。**

        !!! note "Windows の PowerShell から SSH で入っているときは"
            画面は Windows の PowerShell なので、`Ctrl` + `C` / `Ctrl` + `V` も効きます。
            ただし**コマンドが動いている最中の `Ctrl` + `C` は、やはり「止める」**になります。
            **迷ったら `Ctrl` + `Shift` + `C` / `V` か右クリック。**どちらの画面でも通ります。

        他にも、Windows と違うところがあります。

        | | Ubuntu ではこうなります |
        |---|---|
        | **大文字と小文字** | **別のものとして扱われます。**`Desktop` と `desktop` は違うフォルダです |
        | **フォルダの区切り** | `/`（スラッシュ）です。Windows の `\`（円マーク）ではありません |
        | **パスワードを打つと** | **画面に何も出ません。**`*` すら出ませんが、**正常です。**そのまま打って `Enter` |
        | **`~` の意味** | 自分のホームフォルダです。`~/xangi` は「自分のフォルダの中の xangi」 |
        | **`.` で始まる名前** | 隠しファイルです。`ls` では出ません（`ls -a` で見えます）。9章で書き換える `.env` がこれです |
        | **`Tab` キー** | 途中まで打って `Tab` を押すと、**続きを補ってくれます。**打ち間違いが減ります |
        | **`sudo`** | 「管理者として実行」の意味です。パスワードを聞かれます |

    ## 5. 最初の更新

    Ubuntu が起動したら、`Ctrl` + `Alt` + `T` で端末（コマンドを入れる黒い画面）を開きます。

    まず、道具が入っているかを確かめます。入っていないのが普通です。

    ```bash
    which curl                  # ← 何も出なければ入っていません
    systemctl is-active ssh     # ← inactive か not-found なら入っていません
    ```

    次に、更新して3つの道具を入れます。

    ```bash
    sudo apt update && sudo apt full-upgrade -y
    sudo apt install -y openssh-server curl git
    ```

    SSH（別の PC から端末へ入る仕組み）を動かします。続けて、動いたことを確かめます。

    ```bash
    sudo systemctl enable --now ssh
    systemctl is-enabled ssh    # ← enabled と返る
    ss -ltn | grep :22          # ← 1行以上出る
    ```

    `curl` は、インターネットからデータを受け取る道具です。このあと[8章](08_claude.md)と[11章](11_tailscale.md)で、`curl -fsSL ... | sh` という形の導入コマンドを使います。**`curl` が無いとそこで止まります。**

    ## ✅ ここまで出来たら

    Ubuntu が再起動し、更新と3つの道具の導入が終われば合格です。`systemctl is-enabled ssh` が `enabled` と返り、22番が1行以上表示されることも確認します。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | BIOS に入れない | 電源を入れる前から `Delete` を押します。次に `F7`、`Esc`、`F2` を試します |
    | USB から起動しない | Fast Boot、Secure Boot、Boot 順を見直します |
    | ログイン名が分からない | 表示名を使わず、7章の `whoami` で確定します |
    | `curl: command not found` | この章の `sudo apt install -y openssh-server curl git` を実行します |
    | Wi-Fi が再起動後につながらない | `connection.permissions ""` を含む設定の1行を実行します |

    次は [7. 別の PC から入れる](07_ssh.md) です。

    ## 🟡 この手順書の未確認事項

    BIOS のキー、初期 OS、停電復帰項目は、現物が届いたその場で確かめます。
    ````
<!-- SUPPORT:END -->
ミニPCには、画面もキーボードも付いていません。最初のセットアップの間だけ、操作する道具をつなぎます。5章で作った USB も挿します。

## 最初だけ KVM をつなぐ { #kvm }

KVM は、Keyboard / Video / Mouse の頭文字です。ここでは「キーボード・画面・マウス」のことです。最初は、モニタ（HDMI）・USB キーボード・USB マウスが必要です。

| やり方 | 中身 |
|---|---|
| テレビ／モニタを借りる | HDMI が挿さるテレビで構いません。USB キーボードとマウスを直挿しします |
| いま使っている PC の周辺機器を一時的に付け替える | モニタのケーブルを挿し替えます |
| **KVM 切替器を使う** | 1組のキーボード・画面・マウスを、ボタンで2台に切り替える箱です。数千円です |

**[7章](07_ssh.md)で別の PC から SSH で入れたら、その時点で外して構いません。** 以降は画面もキーボードも要りません。この状態をヘッドレス（画面やキーボードを常時つながない運用）と言います。**これが今日いちばんの区切りです。**

## ネットワークを選ぶ

| 選び方 | 向いている場面 |
|---|---|
| 有線 LAN | 24時間動かすなら、こちらが安定します |
| Wi-Fi | LAN ケーブルを引けないなど、置き場所の都合があるときに使います |

有線を使う場合は、LAN ケーブルを先につなぎます。Wi-Fi を使う場合は、SSID（Wi-Fi の名前）とパスワードを[2章の表](02_values.md)に控えます。

## 1. BIOS を開く

BIOS（起動前の設定画面）を開きます。

!!! warning "🔴 現物で確かめる"
    BIOS のキーは未確認です。`Delete` が第一候補です。入れなければ `F7`（起動メニュー）、`Esc`、`F2` の順で試します。電源を入れる**前**からキーを押しっぱなしにします。確定したキーを[記録用紙](log/first_setup.md)へ書きます。

BIOS に入れたら、次を探します。項目は「Security」「Boot」「Advanced」の中にあることがあります。

| 項目 | 設定 | なぜ |
|---|---|---|
| Secure Boot | Disabled | Ubuntu の導入で余計な壁を作らないためです |
| Fast Boot | Disabled | USB を見つけて起動できるようにします |
| Boot 順 | USB を先頭 | USB のインストーラから起動します |

!!! warning "🔴 現物で確かめる"
    `Restore on AC Power Loss` 相当の項目を探します。あれば `Power On` にします。無ければ、記録場に「無かった」と書きます。項目名を推測しません。

「Save & Exit」で保存して抜けます。

## 2. 初期 OS を確認する

!!! warning "🔴 現物で確かめる"
    初期 OS は未確認です。Windows が入っている可能性はありますが、断定しません。中に必要なファイルが無いことと、初期 OS を消してよいことを確認してから進みます。確認結果を記録用紙へ書きます。

## 3. Ubuntu を入れる

USB から起動し、次の順で選びます。

| 画面 | 選ぶもの |
|---|---|
| 最初 | Try or Install Ubuntu |
| 言語 | 日本語 |
| 操作 | Install Ubuntu |
| キーボード | Japanese |
| ネットワーク | 有線 LAN、または下の手順で Wi-Fi |
| インストールの種類 | ディスクを削除して Ubuntu をインストール |

「ディスクを削除」は、SSD の中身を消します。初期 OS と必要ファイルを確認していなければ、進めません。

### Wi-Fi でつなぐ場合 { #wifi }

Wi-Fi は、インストール中のネットワーク画面でつなぐのが一番確実です。一覧から[2章](02_values.md)に控えた SSID を選び、パスワードを入れます。

Ubuntu の導入後に設定する場合は、端末で次を実行します。

```bash
nmcli device wifi list  # ← SSIDが見えるか
sudo nmcli device wifi connect "SSID名" password "パスワード"
sudo nmcli connection modify "SSID名" connection.autoconnect yes connection.permissions ""
```

最後の1行は、Wi-Fi を機械全体の設定にします。これが無いと、再起動後に誰かがログインするまでつながらず、SSH が通らないことがあります。Wi-Fi が一覧に出ない場合は[付録A](99_appendix.md#appendix-a)で切り分けます。

## 4. ユーザーを作る

「名前」は人に見せる表示名です。「ユーザー名」は SSH で入るときにも使う名前です。**2つは別物です。** ユーザー名は英小文字で始めます。大文字は使えません。パスワードは安全な場所へメモします。

「自動的にログインする」を ON にします。20〜30分待ちます。再起動の指示が出たら USB を抜きます。

!!! note "自動ログインを ON にする理由と代償"
    無人で再起動した後も、画面側の動作環境を上げるためです。その代わり、**物理的に触れる人は誰でも中に入れます。** 置き場所が鍵です。鍵のかかる部屋か、人目のある管理された場所に置きます。

### Windows と違うところ { #win-diff }

??? warning "🔴 ここから先は、Windows と操作の作法が違います（開いて一読してください）"

    いちばん多いつまずきが **コピーと貼り付け**です。

    | やりたいこと | Windows のアプリ | **Ubuntu の端末** |
    |---|---|---|
    | コピー | `Ctrl` + `C` | **`Ctrl` + `Shift` + `C`** |
    | 貼り付け | `Ctrl` + `V` | **`Ctrl` + `Shift` + `V`** |

    🔴 **端末で `Ctrl` + `C` を押すと、コピーではなく「いま動いているものを止める」になります。**
    **`Shift` を足す**、と覚えてください。**右クリックでも貼り付けられます。**

    !!! note "Windows の PowerShell から SSH で入っているときは"
        画面は Windows の PowerShell なので、`Ctrl` + `C` / `Ctrl` + `V` も効きます。
        ただし**コマンドが動いている最中の `Ctrl` + `C` は、やはり「止める」**になります。
        **迷ったら `Ctrl` + `Shift` + `C` / `V` か右クリック。**どちらの画面でも通ります。

    他にも、Windows と違うところがあります。

    | | Ubuntu ではこうなります |
    |---|---|
    | **大文字と小文字** | **別のものとして扱われます。**`Desktop` と `desktop` は違うフォルダです |
    | **フォルダの区切り** | `/`（スラッシュ）です。Windows の `\`（円マーク）ではありません |
    | **パスワードを打つと** | **画面に何も出ません。**`*` すら出ませんが、**正常です。**そのまま打って `Enter` |
    | **`~` の意味** | 自分のホームフォルダです。`~/xangi` は「自分のフォルダの中の xangi」 |
    | **`.` で始まる名前** | 隠しファイルです。`ls` では出ません（`ls -a` で見えます）。9章で書き換える `.env` がこれです |
    | **`Tab` キー** | 途中まで打って `Tab` を押すと、**続きを補ってくれます。**打ち間違いが減ります |
    | **`sudo`** | 「管理者として実行」の意味です。パスワードを聞かれます |

## 5. 最初の更新

Ubuntu が起動したら、`Ctrl` + `Alt` + `T` で端末（コマンドを入れる黒い画面）を開きます。

まず、道具が入っているかを確かめます。入っていないのが普通です。

```bash
which curl                  # ← 何も出なければ入っていません
systemctl is-active ssh     # ← inactive か not-found なら入っていません
```

次に、更新して3つの道具を入れます。

```bash
sudo apt update && sudo apt full-upgrade -y
sudo apt install -y openssh-server curl git
```

SSH（別の PC から端末へ入る仕組み）を動かします。続けて、動いたことを確かめます。

```bash
sudo systemctl enable --now ssh
systemctl is-enabled ssh    # ← enabled と返る
ss -ltn | grep :22          # ← 1行以上出る
```

`curl` は、インターネットからデータを受け取る道具です。このあと[8章](08_claude.md)と[11章](11_tailscale.md)で、`curl -fsSL ... | sh` という形の導入コマンドを使います。**`curl` が無いとそこで止まります。**

## ✅ ここまで出来たら

Ubuntu が再起動し、更新と3つの道具の導入が終われば合格です。`systemctl is-enabled ssh` が `enabled` と返り、22番が1行以上表示されることも確認します。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| BIOS に入れない | 電源を入れる前から `Delete` を押します。次に `F7`、`Esc`、`F2` を試します |
| USB から起動しない | Fast Boot、Secure Boot、Boot 順を見直します |
| ログイン名が分からない | 表示名を使わず、7章の `whoami` で確定します |
| `curl: command not found` | この章の `sudo apt install -y openssh-server curl git` を実行します |
| Wi-Fi が再起動後につながらない | `connection.permissions ""` を含む設定の1行を実行します |

次は [7. 別の PC から入れる](07_ssh.md) です。

## 🟡 この手順書の未確認事項

BIOS のキー、初期 OS、停電復帰項目は、現物が届いたその場で確かめます。


===============================================================
【07_ssh.md】
===============================================================

# 7. 別の PC から入れるようにする（SSH）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_07_ssh.txt](assets/support_07_ssh.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】7. 別の PC から入れるようにする（SSH）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 7. 別の PC から入れるようにする（SSH）

    SSH は、別の PC からサーバの端末へ入る仕組みです。この章だけは Ubuntu 本体と Windows PC の両方を使います。

    ## Ubuntu 本体で確認する

    SSH サーバは6章で導入して動かしました。ここでは、接続に使う値と22番が開いていることだけを確認します。Ubuntu 本体の端末で実行します。

    ```bash
    whoami                 # ← ここを見る。本当のユーザー名
    hostname -I            # ← ここを見る。LAN内IP
    ss -ltn | grep :22     # ← 何か表示されればSSHが開いています
    ```

    `whoami` と `hostname -I` の結果を[2章の表](02_values.md)に書きます。表示名ではなく、`whoami` が返した英小文字の値を使います。

    ## Windows PC からつなぐ

    Windows 10/11 標準の PowerShell を使います。追加インストールは要りません。スタートメニューで「PowerShell」を開きます。

    Windows 側の IP を確認します。

    ```bash
    ipconfig
    ```

    2章の `<LAN内IP>` と Windows 側の IPv4 アドレスを比べます。前から3つの数字が一致していれば同じ網です。例として `192.168.12.xxx` の `192.168.12` 部分です。

    次に接続します。

    ```bash
    ssh <ユーザー名>@<LAN内IP>
    ```

    初回は接続先を信頼するか聞かれます。`yes` と入力します。続いて、Ubuntu で決めたパスワードを入力します。**入力中は画面に文字が出ませんが、正常です。**そのまま打って `Enter` を押します。

    !!! warning "🔴 コピーと貼り付けは Windows と違います（2回目の注意です）"
        端末では **`Ctrl` + `C` は「いま動いているものを止める」**で、コピーではありません。

        | やりたいこと | 押すキー |
        |---|---|
        | コピー | **`Ctrl` + `Shift` + `C`** |
        | 貼り付け | **`Ctrl` + `Shift` + `V`**（**右クリックでも貼れます**） |

        詳しくは[6章の「Windows と違うところ」](06_ubuntu.md#win-diff)を開いてください。

    ## 合格試験

    いったん SSH から出た状態で、Windows の PowerShell から実行します。

    ```bash
    ssh <ユーザー名>@<LAN内IP> 'uptime'  # ← 稼働時間が返る
    ```

    返事があれば合格です。ここから先は Windows から SSH で続けられます。コマンドをコピーして貼れるので、入力間違いも減ります。

    ## ✅ ここまで出来たら

    別の Windows PC から `uptime` が返り、2章にユーザー名と LAN内IPを書けたら合格です。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | `Permission denied` | ユーザー名が `whoami` の出力か、パスワードが合っているか |
    | `Connection refused` | Ubuntu 本体で SSH を有効にしたか |
    | `No route to host`／無反応 | 両方の IP の前3つが一致するか、IP が変わっていないか |
    | 22番が表示されない | 6章の `openssh-server` 導入と SSH 有効化をやり直します |

    ここまで来たら、モニタ・キーボード・マウスは外して構いません。以降は Windows から進めます。

    次は [8. 右腕を入れる（Claude Code と Codex）](08_claude.md) です。
    ````
<!-- SUPPORT:END -->
SSH は、別の PC からサーバの端末へ入る仕組みです。この章だけは Ubuntu 本体と Windows PC の両方を使います。

## Ubuntu 本体で確認する

SSH サーバは6章で導入して動かしました。ここでは、接続に使う値と22番が開いていることだけを確認します。Ubuntu 本体の端末で実行します。

```bash
whoami                 # ← ここを見る。本当のユーザー名
hostname -I            # ← ここを見る。LAN内IP
ss -ltn | grep :22     # ← 何か表示されればSSHが開いています
```

`whoami` と `hostname -I` の結果を[2章の表](02_values.md)に書きます。表示名ではなく、`whoami` が返した英小文字の値を使います。

## Windows PC からつなぐ

Windows 10/11 標準の PowerShell を使います。追加インストールは要りません。スタートメニューで「PowerShell」を開きます。

Windows 側の IP を確認します。

```bash
ipconfig
```

2章の `<LAN内IP>` と Windows 側の IPv4 アドレスを比べます。前から3つの数字が一致していれば同じ網です。例として `192.168.12.xxx` の `192.168.12` 部分です。

次に接続します。

```bash
ssh <ユーザー名>@<LAN内IP>
```

初回は接続先を信頼するか聞かれます。`yes` と入力します。続いて、Ubuntu で決めたパスワードを入力します。**入力中は画面に文字が出ませんが、正常です。**そのまま打って `Enter` を押します。

!!! warning "🔴 コピーと貼り付けは Windows と違います（2回目の注意です）"
    端末では **`Ctrl` + `C` は「いま動いているものを止める」**で、コピーではありません。

    | やりたいこと | 押すキー |
    |---|---|
    | コピー | **`Ctrl` + `Shift` + `C`** |
    | 貼り付け | **`Ctrl` + `Shift` + `V`**（**右クリックでも貼れます**） |

    詳しくは[6章の「Windows と違うところ」](06_ubuntu.md#win-diff)を開いてください。

## 合格試験

いったん SSH から出た状態で、Windows の PowerShell から実行します。

```bash
ssh <ユーザー名>@<LAN内IP> 'uptime'  # ← 稼働時間が返る
```

返事があれば合格です。ここから先は Windows から SSH で続けられます。コマンドをコピーして貼れるので、入力間違いも減ります。

## ✅ ここまで出来たら

別の Windows PC から `uptime` が返り、2章にユーザー名と LAN内IPを書けたら合格です。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| `Permission denied` | ユーザー名が `whoami` の出力か、パスワードが合っているか |
| `Connection refused` | Ubuntu 本体で SSH を有効にしたか |
| `No route to host`／無反応 | 両方の IP の前3つが一致するか、IP が変わっていないか |
| 22番が表示されない | 6章の `openssh-server` 導入と SSH 有効化をやり直します |

ここまで来たら、モニタ・キーボード・マウスは外して構いません。以降は Windows から進めます。

次は [8. 右腕を入れる（Claude Code と Codex）](08_claude.md) です。


===============================================================
【08_claude.md】
===============================================================

# 8. 右腕を入れる（Claude Code と Codex）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_08_claude.txt](assets/support_08_claude.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】8. 右腕を入れる（Claude Code と Codex）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 8. 右腕を入れる（Claude Code と Codex）

    **ここから先は、Windows から SSH で入って進めます。** 手元の PC からコマンドをコピーして貼れるため、打ち間違いが減ります。xangi は配管です。考えて作業する右腕として、Claude Code と Codex を入れます。どちらを使うかは9章で選びます。

    !!! note "Ubuntu 本体の端末でもできます"
        本体のモニタとキーボードがまだつながっていれば、Ubuntu 本体の端末でも同じ操作ができます。ただし、ここでは Windows から SSH で進める方法を主にします。

    ## Node.js を入れる

    nvm（Node.js の版を管理する道具）を使います。

    ```bash
    curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
    ```

    !!! warning "一度 SSH を切って、つなぎ直します"
        `exit` で切り、7章と同じ `ssh <ユーザー名>@<LAN内IP>` で入り直します。これをしないと、今入れた `nvm` が見つからないことがあります。

    ```bash
    nvm install --lts
    node -v  # ← v22 以降であること
    ```

    ## 2つの右腕を入れる

    2つとも入れます。ログインには、それぞれの有料プランが必要です。ただし、**片方だけでも先へ進めます。両方が必須ではありません。**

    | | 入れる | ログイン | 要るもの |
    |---|---|---|---|
    | Claude Code | `npm install -g @anthropic-ai/claude-code`<br>`claude --version` | `claude` | Claude の有料プラン（Pro / Max）。API キーは不要です |
    | Codex | `npm install -g @openai/codex`<br>`codex --version` | `codex` を実行し、`Sign in with ChatGPT` を選ぶ | ChatGPT の有料プラン（Plus / Pro / Business など）。API キーは不要です |

    ```bash
    npm install -g @anthropic-ai/claude-code
    claude --version  # ← バージョンが返る
    ```

    ```bash
    npm install -g @openai/codex
    codex --version  # ← バージョンが返る
    ```

    ## ログインする

    SSH 越しのログインでは、画面に URL とコードが表示されます。**表示された URL を手元の Windows のブラウザで開きます。そこで出たコードを、SSH の画面に貼り戻します。** 画面のない機械では、この形が基本です。

    ### Claude Code

    ```bash
    claude
    ```

    Claude の有料プラン（Pro / Max）でログインします。API キーは要りません。ログイン情報は `~/.claude` に残ります。そのため、ログインは1回だけです。入力欄が出たら、`/exit` と入力して終了します。`Ctrl` + `C` を2回でも抜けられます。

    ### Codex

    ```bash
    codex
    ```

    `Sign in with ChatGPT` を選びます。ChatGPT の有料プラン（Plus / Pro / Business など）でログインします。API キーは要りません。ログイン情報は `~/.codex` に残ります。そのため、ログインは1回だけです。ログイン後は画面の案内に従って終了します。

    !!! tip "本体のモニタがまだつながっている場合"
        Ubuntu 本体の端末で `claude` または `codex` を実行すると、ブラウザが自動で開いて楽です。

    9章では、xangi がここで保存したログイン情報を使います。

    ## ✅ ここまで出来たら

    `node -v` が v22 以降で、`claude --version` と `codex --version` が返れば合格です。使う方の有料アカウントでログインできることも確かめます。片方だけでも先へ進めます。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | `nvm` が見つからない | SSH を一度切ってつなぎ直したか |
    | Node.js が古い | `nvm install --lts` をやり直し、`node -v` を見ます |
    | `claude`／`codex` が `command not found` | SSH を切ってつなぎ直します。nvm の PATH（コマンドを探す場所）を読み直すためです |
    | SSH の画面でブラウザを開けない | 表示された URL を Windows のブラウザで開き、コードを SSH の画面へ貼り戻します |

    次は [9. 配管をつなぐ](09_xangi.md) です。
    ````
<!-- SUPPORT:END -->
**ここから先は、Windows から SSH で入って進めます。** 手元の PC からコマンドをコピーして貼れるため、打ち間違いが減ります。xangi は配管です。考えて作業する右腕として、Claude Code と Codex を入れます。どちらを使うかは9章で選びます。

!!! note "Ubuntu 本体の端末でもできます"
    本体のモニタとキーボードがまだつながっていれば、Ubuntu 本体の端末でも同じ操作ができます。ただし、ここでは Windows から SSH で進める方法を主にします。

## Node.js を入れる

nvm（Node.js の版を管理する道具）を使います。

```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
```

!!! warning "一度 SSH を切って、つなぎ直します"
    `exit` で切り、7章と同じ `ssh <ユーザー名>@<LAN内IP>` で入り直します。これをしないと、今入れた `nvm` が見つからないことがあります。

```bash
nvm install --lts
node -v  # ← v22 以降であること
```

## 2つの右腕を入れる

2つとも入れます。ログインには、それぞれの有料プランが必要です。ただし、**片方だけでも先へ進めます。両方が必須ではありません。**

| | 入れる | ログイン | 要るもの |
|---|---|---|---|
| Claude Code | `npm install -g @anthropic-ai/claude-code`<br>`claude --version` | `claude` | Claude の有料プラン（Pro / Max）。API キーは不要です |
| Codex | `npm install -g @openai/codex`<br>`codex --version` | `codex` を実行し、`Sign in with ChatGPT` を選ぶ | ChatGPT の有料プラン（Plus / Pro / Business など）。API キーは不要です |

```bash
npm install -g @anthropic-ai/claude-code
claude --version  # ← バージョンが返る
```

```bash
npm install -g @openai/codex
codex --version  # ← バージョンが返る
```

## ログインする

SSH 越しのログインでは、画面に URL とコードが表示されます。**表示された URL を手元の Windows のブラウザで開きます。そこで出たコードを、SSH の画面に貼り戻します。** 画面のない機械では、この形が基本です。

### Claude Code

```bash
claude
```

Claude の有料プラン（Pro / Max）でログインします。API キーは要りません。ログイン情報は `~/.claude` に残ります。そのため、ログインは1回だけです。入力欄が出たら、`/exit` と入力して終了します。`Ctrl` + `C` を2回でも抜けられます。

### Codex

```bash
codex
```

`Sign in with ChatGPT` を選びます。ChatGPT の有料プラン（Plus / Pro / Business など）でログインします。API キーは要りません。ログイン情報は `~/.codex` に残ります。そのため、ログインは1回だけです。ログイン後は画面の案内に従って終了します。

!!! tip "本体のモニタがまだつながっている場合"
    Ubuntu 本体の端末で `claude` または `codex` を実行すると、ブラウザが自動で開いて楽です。

9章では、xangi がここで保存したログイン情報を使います。

## ✅ ここまで出来たら

`node -v` が v22 以降で、`claude --version` と `codex --version` が返れば合格です。使う方の有料アカウントでログインできることも確かめます。片方だけでも先へ進めます。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| `nvm` が見つからない | SSH を一度切ってつなぎ直したか |
| Node.js が古い | `nvm install --lts` をやり直し、`node -v` を見ます |
| `claude`／`codex` が `command not found` | SSH を切ってつなぎ直します。nvm の PATH（コマンドを探す場所）を読み直すためです |
| SSH の画面でブラウザを開けない | 表示された URL を Windows のブラウザで開き、コードを SSH の画面へ貼り戻します |

次は [9. 配管をつなぐ](09_xangi.md) です。


===============================================================
【09_xangi.md】
===============================================================

# 9. 配管をつなぐ（xangi）

<!-- SUPPORT:BEGIN -->
!!! tip "🤝 はじめる前に — 詰まったときに聞ける相手を作ります"
    この章は、**チャットAI（ChatGPT・Claude など）をサポート役に付けてから**始めてください。
    詰まったときに、**画面のスクリーンショットを貼るだけ**で、どこで止まっているかを見てくれます。

    | | やること |
    |---|---|
    | **1** | **[📄 support_09_xangi.txt](assets/support_09_xangi.txt)** を開く（リンクを右クリック →「名前を付けて保存」でも構いません） |
    | **2** | ChatGPT か Claude で、**新しい会話**を1つ開く |
    | **3** | そのファイルを**添付**する。添付が面倒なら、開いた画面を `Ctrl+A` → `Ctrl+C` で**全部コピーして貼る**でも同じです |
    | **4** | 送ると、**この工程で何をするのかを3行**で返してきます |
    | **5** | **その会話は開いたまま**にして、この章を進める。詰まったら**スクリーンショットを貼る** |

    🔴 **トークン・パスワード・鍵は、チャットに貼らないでください。**
    **スクリーンショットに写り込むことがあります。**送る前に、画面にそれらが出ていないか見てください。
    貼ってしまっても、どれも作り直せます。慌てず、作り直してください。

??? note "📋 そのファイルに何が書いてあるか（ここで中身を確認できます）"

    ````markdown
    # 【サポート依頼】9. 配管をつなぐ（xangi）

    あなたは、これから下の手順を**自分の手で通す人**のサポート役です。
    相手は Linux もサーバも初めてで、手元の PC は Windows です。

    ## 守ってほしいこと

    1. 相手は下の手順書を**上から順に**やっています。**先回りして別のやり方を勧めないでください。**
       どうしても別の手が要ると判断したときは、**そう判断した理由を1行**添えてください。
    2. 詰まった画面のスクリーンショットや、エラーの文言が送られてきます。
       **まず「下の手順書のどこで止まっているか」を特定**してから答えてください。
    3. **一度に1つだけ**指示してください。結果を聞いてから次に進みます。
    4. 専門用語は、初めて出たときに**かっこ書きで言い換え**を付けてください。
    5. 分からないことは「**分かりません**」と答えてください。**推測でコマンドを出さないでください。**
    6. この工程の「**終わりの印**」が出るまでは、次の工程の話をしないでください。

    ## 絶対にしないこと

    - **Discord の Bot トークン・パスワード・SSH の秘密鍵**を、送るよう求めないでください。
    - 相手がうっかり貼ってしまったら、**その場で作り直すよう伝えてください**（どれも作り直せます）。

    ## 最初にお願いすること

    この工程で何をするのかを、**3行**で教えてください。
    そのあと、私が「はじめます」と言ったら、**最初の1手だけ**を教えてください。

    ---

    # 手順書（この工程の全文）

    # 9. 配管をつなぐ（xangi）

    xangi は Discord と Claude Code または Codex をつなぐ配管です。この章は Windows から SSH で進めます。pm2（プログラムを常駐させる道具）方式を使います。SSH 越しでも対話画面が要りません。動いていない原因は `pm2 logs` で追えます。

    ## 1. xangi を取る

    ```bash
    cd && git clone https://github.com/karaage0703/xangi
    ```

    ```bash
    cd ~/xangi
    cp .env.example .env
    ```

    ## 2. `.env` を書く

    `.env` は、xangi の設定を書くファイルです。先に全体の地図を見ます。

    - `.env.example` は **783行**あります。
    - そのうち、値が入っている行は **3行だけ**です。
    - 残りはすべて `#` で始まる説明文です。
    - `#` で始まる行はメモ書きです。コメントとも言います。xangi は読みません。

    **書き換えるのは、次の4か所だけです。**（下の表の上から順に説明します）

    | 行 | いまの中身 | どうするか |
    |---:|---|---|
    | **96行目** | `# WORKSPACE_PATH=...` | **先頭の `#` を消して、右腕の机の場所を書きます**（下で説明します） |
    | **4行目** | `DISCORD_TOKEN=your_discord_bot_token_here` | **右側を、4章で取ったトークンに書き換えます** |
    | **10行目** | `DISCORD_ALLOWED_USER=your_discord_user_id_here` | **右側を、自分の Discord ユーザーID に書き換えます。`*` にしません** |
    | **22行目** | `AGENT_BACKEND=codex` | **Codex を使うならそのままです。Claude Code を使うなら `claude-code` に書き換えます** |

    `=` の前後に空白は入れません。8章でログインできた方を選びます。片方だけでも進めます。

    !!! tip "行番号が合わないときは"
        `.env.example` は更新されることがあるので、**行番号がずれることがあります。**
        そのときは行番号ではなく、**`Ctrl` + `W` で `DISCORD_TOKEN` などの名前を探して**ください（下の nano の説明にあります）。

    ### 🔵 入口を Slack にする場合は、書き換える行が違います

    [4b章](04b_slack.md)で Slack を選んだ方は、上の表の代わりに**こちら**を書き換えます。
    `.env.example` は Slack の設定も**全部 `#` で無効にしてある**ので、`#` を消すところが増えます。

    | 行 | いまの中身 | どうするか |
    |---:|---|---|
    | **4行目** | `DISCORD_TOKEN=your_discord_bot_token_here` | 🔴 **行の先頭に `#` を付けて無効にします**（Discord を使わないため） |
    | **10行目** | `DISCORD_ALLOWED_USER=your_discord_user_id_here` | 🔴 同じく**先頭に `#` を付けます** |
    | **15行目** | `# SLACK_ALLOWED_USER=your_slack_user_id_here` | **`#` を消して**、自分の Slack ユーザーID（`U` で始まる）に |
    | **22行目** | `AGENT_BACKEND=codex` | 8章でログインできた方（`codex` または `claude-code`） |
    | **96行目** | `# WORKSPACE_PATH=...` | **`#` を消して** `/home/<ユーザー名>/workspace` に（下で説明します） |
    | **232行目** | `# SLACK_BOT_TOKEN=xoxb-your-bot-token` | **`#` を消して**、`xoxb-` のトークンに |
    | **233行目** | `# SLACK_APP_TOKEN=xapp-your-app-token` | **`#` を消して**、`xapp-` のトークンに |

    !!! tip "232行目まで一気に行くには"
        `nano` の中で **`Ctrl` + `W`** を押し、**`SLACK_BOT_TOKEN`** と入力して `Enter` を押します。
        行番号を数える必要はありません。

    ??? note "📄 `.env.example` の229〜233行目（実物・Slack のところ）"
        ここも**全部 `#` で無効**になっています。232行目と233行目の `#` を消して、右側を書き換えます。

        ```text
        # ========================================
        # Slack設定（Slack使う場合）
        # ========================================
        # SLACK_BOT_TOKEN=xoxb-your-bot-token
        # SLACK_APP_TOKEN=xapp-your-app-token
        ```

    !!! success "書けたら、有効な行はこの5行になります（Slack 版）"
        ```bash
        SLACK_ALLOWED_USER=U01234567
        AGENT_BACKEND=claude-code
        WORKSPACE_PATH=/home/<ユーザー名>/workspace
        SLACK_BOT_TOKEN=xoxb-（4b章で取った長い文字列）
        SLACK_APP_TOKEN=xapp-（4b章で取った長い文字列）
        ```
        **順番はバラバラで構いません。**ファイルの中では 15 / 22 / 96 / 232 / 233 行目に散っています。
        🔴 **`DISCORD_TOKEN` と `DISCORD_ALLOWED_USER` の2行は、先頭に `#` が付いている**こと。

    !!! danger "🔴 見本の文字を消し切ってください（2026-09-09 に実際に踏みました）"
        `# SLACK_BOT_TOKEN=xoxb-your-bot-token` の **`#` だけ消して、右側を消し忘れる**間違いが起きます。
        `your-bot-token` のような文字が残っていると、Slack は
        **`invalid_auth`（その鍵は無効）**と返し、返事が来ません。

        **`=` の右側は、まるごと消してから貼ってください。**

        🔴 **`#` を消したあとに、行頭の空白を残さないこと。**`  SLACK_BOT_TOKEN=...` のように
        先頭に空白があると、確認のコマンドが拾えません。

    !!! success "手で打たずに入れる方法（画面にトークンは出ません）"
        ```bash
        read -rsp "xoxb- で始まる Bot Token を貼って Enter: " BT; echo
        read -rsp "xapp- で始まる App Token を貼って Enter: " AT; echo

        sed -i -E -e "s|^[[:space:]]*#?[[:space:]]*SLACK_BOT_TOKEN=.*|SLACK_BOT_TOKEN=$BT|" \
                  -e "s|^[[:space:]]*#?[[:space:]]*SLACK_APP_TOKEN=.*|SLACK_APP_TOKEN=$AT|" \
                  -e "s|^DISCORD_TOKEN=|#DISCORD_TOKEN=|" \
                  -e "s|^DISCORD_ALLOWED_USER=|#DISCORD_ALLOWED_USER=|" ~/xangi/.env
        ```

        そのあと、こう出れば正解です（**行頭に空白が無いこと**・`xoxb-` と `xapp-` で始まること）。

        ```bash
        grep -nE "^(SLACK|AGENT_BACKEND|WORKSPACE_PATH)" ~/xangi/.env | sed -E 's/=(.{9}).*/=\1…/'
        ```

    書けたかの確認は、Slack の場合 **5行**出れば正解です。

    ```bash
    grep -n -v "^#" ~/xangi/.env | grep -v "^$"   # ← SLACK_ALLOWED_USER / AGENT_BACKEND / WORKSPACE_PATH / SLACK_BOT_TOKEN / SLACK_APP_TOKEN の5行
    ```

    ### もう1か所だけ、行の先頭の `#` を消します（96行目）

    **96行目は、いま `#` が付いていて効いていません。**ここだけは `#` を消して書き換えます。

    ```bash
    # WORKSPACE_PATH=/path/to/your/workspace      ← いまの状態（先頭に # がある）
    WORKSPACE_PATH=/home/<ユーザー名>/workspace     ← こう直す（# を消して、右側を書き換える）
    ```

    !!! danger "🔴 `/path/to/` を残さないでください（2026-09-09 に実際に踏みました）"
        見本が `/path/to/your/workspace` なので、**`your` だけを自分の名前に替えて
        `/path/to/jsc-ai/workspace` にしてしまう**間違いが起きます。
        **`/path/to/` ごと消して、`/home/` から書き直してください。**

        こうなると xangi は**起動した直後に落ちます**。pm2 が何度も起動し直すので、
        一見動いているように見えますが、**チャットには一切返事が来ません。**

    !!! success "手で書かずに、この1行で入れるのが確実です"
        `nano` を使わずに、正しい値を入れられます。`$HOME` は「自分のホームフォルダ」に置き換わります。

        ```bash
        sed -i "s|^#\? *WORKSPACE_PATH=.*|WORKSPACE_PATH=$HOME/workspace|" ~/xangi/.env
        grep -n "^WORKSPACE_PATH" ~/xangi/.env   # ← /home/あなたの名前/workspace になっていること
        ```

    **右腕の机を、道具の置き場と分けるため**です。ここを `#` のままにすると、
    **xangi のプログラムが入っているフォルダが、そのまま机になります。**
    そこへ成果物が混ざると、あとで xangi を新しくするときにぶつかります。

    机になるフォルダは、先に作っておきます。

    ```bash
    mkdir -p ~/workspace
    ```

    !!! note "こちらは触りません"
        **503行目の `# SKIP_PERMISSIONS=false` は触りません。** `#` が付いているため未設定です。未設定では、既定の `true` が効きます。`true` にするために何か書く必要はありません。

    !!! danger "既定の SKIP_PERMISSIONS=true の意味"
        ファイル操作もコマンド実行も、毎回の確認なしで走ります。**この用途専用の隔離された機械**で使います。本業データの入った共用 PC では使いません。

    ??? note "📄 `.env.example` の1〜30行目（実物）"
        4行目、10行目、22行目が、上の表と対応します。

        ```text
        # ========================================
        # Discord設定（Discord使う場合）
        # ========================================
        DISCORD_TOKEN=your_discord_bot_token_here

        # ========================================
        # 許可ユーザー設定（必須）
        # ========================================
        # Discord用（カンマ区切りで複数指定可、"*" で全員許可）
        DISCORD_ALLOWED_USER=your_discord_user_id_here
        # 複数ユーザー例: DISCORD_ALLOWED_USER=123456789,987654321
        # 全員許可: DISCORD_ALLOWED_USER=*

        # Slack用（カンマ区切りで複数指定可、"*" で全員許可）
        # SLACK_ALLOWED_USER=your_slack_user_id_here

        # ========================================
        # AIエージェント設定
        # ========================================
        # Agent backend: a built-in backend or an ID declared by a linked extension
        # This example recommends codex; the runtime fallback when omitted is claude-code.
        AGENT_BACKEND=codex

        # Optional: Model to use (backend-specific)
        # AGENT_MODEL=

        # Claude Code backend (AGENT_BACKEND=claude-code)
        # ANTHROPIC_API_KEY is passed only to the Claude Code child process.
        # Set CLAUDE_CODE_BARE=true to force Anthropic API-key auth instead of OAuth/keychain.
        # CLAUDE_CODE_MAX_BUDGET_USD limits API spend per Claude Code print-mode run.
        ```

    ファイルを開きます。

    ```bash
    nano .env
    ```

    ??? note "✏️ nano の使い方（これだけ覚えれば足ります）"
        `nano` は、端末の中で文章を書き換える道具です。マウスでは動かせません。矢印キーを使います。

        | やりたいこと | キー |
        |---|---|
        | 書き換える | 矢印キーでカーソルを動かして、そのまま打つ |
        | **保存する** | **`Ctrl` + `O` → `Enter`** |
        | **終わる** | **`Ctrl` + `X`** |
        | 保存せずに終わる | `Ctrl` + `X` → `N` |
        | 行を探す | `Ctrl` + `W` → 文字を入れて `Enter` |
        | 🔴 **貼り付ける**（トークンなど） | **`Ctrl` + `Shift` + `V`**、または**右クリック**。**`Ctrl` + `V` は効きません** |

        画面の下に出る `^O` は、`Ctrl` + `O` の意味です。`^` が `Ctrl` を表します。

        🔴 **トークンを貼るときは `Ctrl` + `V` ではなく `Ctrl` + `Shift` + `V`** です（3回目の注意です）。
        貼れないときは**右クリック**を試してください。

        ### 🔴 直すときは「行を丸ごと打ち直す」

        **一部だけ書き換えようとすると、見本の文字が残ります。**2026-09-09 に2回踏みました。
        次の順で、**行ごと消してから打ち直して**ください。

        | | 操作 |
        |---|---|
        | 1 | **`Ctrl` + `W`** → 行の名前（例 `SLACK_BOT_TOKEN`）を打って `Enter` |
        | 2 | **`Ctrl` + `A`** … 行の先頭へ |
        | 3 | ⚠️ **`Ctrl` + `K`** … **その行を丸ごと切り取る**（飛んだ先が目的の行か、目で見てから） |
        | 4 | `SLACK_BOT_TOKEN=` と**手で打つ** |
        | 5 | **`Ctrl` + `Shift` + `V`** … 値を貼る |

        **行を止めたいだけ**のとき（`DISCORD_TOKEN` など）は、`Ctrl` + `W` で探して
        **`Ctrl` + `A` のあと `#` を1文字打つ**だけです。

        4行目へ速く行くには、`Ctrl` + `W` で `DISCORD_TOKEN` を探します。同じ方法で `DISCORD_ALLOWED_USER` と `AGENT_BACKEND` を探すのが確実です。

    保存して閉じたら、トークンを Windows のメモ帳から消します。書けた内容を確かめ、ファイルを本人だけが読める状態にします。

    !!! danger "🔴 この確認の画面は、スクリーンショットに撮らないでください"
        次のコマンドは、**トークンをそのまま画面に表示します。**
        サポート役のチャットAIに貼ると、**トークンを渡してしまうことになります。**

        詰まってこの画面を見せたいときは、**トークンの部分を消してから**貼ってください。
        うっかり送ってしまったら、[4章](04_discord_bot.md)の `Reset Token` で**作り直せます。**

    !!! success "書けたら、有効な行はこの4行になります（Discord 版）"
        ```bash
        DISCORD_TOKEN=（4章で取った長い文字列）
        DISCORD_ALLOWED_USER=123456789012345678
        AGENT_BACKEND=claude-code
        WORKSPACE_PATH=/home/<ユーザー名>/workspace
        ```
        **順番はバラバラで構いません。**ファイルの中では 4 / 10 / 22 / 96 行目に散っています。

    ```bash
    grep -n -v "^#" ~/xangi/.env | grep -v "^$"   # ← 4行だけ出て、右側が自分の値になっていれば OK
    chmod 600 ~/xangi/.env
    ```

    ## 3. ビルドして常駐させる

    ```bash
    cd ~/xangi
    npm install  # ← 3〜10分かかります
    ```

    ```bash
    npm run build
    ```

    ```bash
    npm install -g pm2
    pm2 start "npm start" --name xangi
    pm2 logs xangi  # ← 起動エラーが無いか。Ctrl+Cで表示だけ抜けます
    ```

    ## 4. 再起動後も立ち上げる

    ```bash
    pm2 save
    pm2 startup  # ← 表示されたコマンドを、そのまま実行する
    ```

    `pm2 startup` 自体で終わりではありません。画面に「このコマンドを実行してください」と出た別のコマンドをコピーし、実行します。その後で保存します。

    ```bash
    pm2 save
    sudo loginctl enable-linger $USER
    ```

    最後の1行は、SSH を切った後もユーザーのサービスを保つ設定です。

    ## 別の道

    xangi には公式インストーラもあります。この手順では扱いません。公式インストーラは対話画面で設定を進めます。SSH 越しでは画面がうまく出ないことがあります。ここでは pm2 方式にそろえます。

    ## ✅ ここまで出来たら

    `pm2 logs xangi` に起動を止めるエラーがなく、Discord の Bot がオンラインになれば合格です。会話の判定は10章で行います。

    ## 詰まったら

    | 症状 | まず見るところ |
    |---|---|
    | Bot がオフライン | `pm2 logs xangi`。トークン前後の空白も確認します |
    | backend が見つからない | 22行目が `AGENT_BACKEND=codex` または `AGENT_BACKEND=claude-code` か確認します |
    | 許可されていない | `DISCORD_ALLOWED_USER` が自分のIDか確認します |
    | `.env` を書いたのに反映されない | `grep -n -v "^#" ~/xangi/.env \| grep -v "^$"` で、有効な4行を確認します |
    | 右腕が机を見つけられない | 96行目の `WORKSPACE_PATH` の `#` を消したか、`mkdir -p ~/workspace` をしたか |
    | ビルドでエラー | `node -v` が v22 以降か確認します |
    | 🔴 **直したのに、ログに同じエラーが出続ける** | **古いエラーが残っているだけかもしれません。**`pm2 flush xangi` でログを空にしてから、`pm2 restart xangi --update-env` → 25秒待って見直します（2026-09-09 にこれで2回誤診しました） |
    | 🔴 **返事が全く来ない／`pm2 list` の ↺ が増え続ける** | `pm2 logs xangi --lines 40 --nostream` を見ます。`EACCES ... mkdir '/path/to/...'` なら **96行目に `/path/to/` が残っています**（上の1行で直せます） |
    | `.env` を書き換えたのに変わらない | 🔴 **`pm2 restart xangi --update-env`** をします。pm2 は起動時の設定を持ったままです |
    | 再起動後に止まる | `pm2 startup` が表示したコマンドと、`loginctl enable-linger` を実行したか確認します |

    **8章で Claude Code または Codex を入れてあります。** サーバの中で `claude` または `codex` と打てば、この機械の中を実際に見て直してくれます。とくに自動起動の設定は手で写すと間違えやすいため、頼むのが早いです。次をそのまま貼れます。

    ```text
    このサーバで pm2 で動かしている xangi が、再起動したあとに自動で立ち上がるようにしてください。
    いまの状態を確認してから、必要な操作だけを実行してください。
    実行したコマンドと、その結果を最後に報告してください。
    うまくいかない場合は、工夫して先へ進まず、そこで止めて状況を教えてください。
    ```

    !!! warning "AI が実行した内容を目で確認します"
        この機械は、確認なしでコマンドが走る設定です。何をしたかを最後に報告させて、必ず目で見てください。

    次は [10. 第1関門](10_first_talk.md) です。
    ````
<!-- SUPPORT:END -->
xangi は Discord と Claude Code または Codex をつなぐ配管です。この章は Windows から SSH で進めます。pm2（プログラムを常駐させる道具）方式を使います。SSH 越しでも対話画面が要りません。動いていない原因は `pm2 logs` で追えます。

## 1. xangi を取る

```bash
cd && git clone https://github.com/karaage0703/xangi
```

```bash
cd ~/xangi
cp .env.example .env
```

## 2. `.env` を書く

`.env` は、xangi の設定を書くファイルです。先に全体の地図を見ます。

- `.env.example` は **783行**あります。
- そのうち、値が入っている行は **3行だけ**です。
- 残りはすべて `#` で始まる説明文です。
- `#` で始まる行はメモ書きです。コメントとも言います。xangi は読みません。

**書き換えるのは、次の4か所だけです。**（下の表の上から順に説明します）

| 行 | いまの中身 | どうするか |
|---:|---|---|
| **96行目** | `# WORKSPACE_PATH=...` | **先頭の `#` を消して、右腕の机の場所を書きます**（下で説明します） |
| **4行目** | `DISCORD_TOKEN=your_discord_bot_token_here` | **右側を、4章で取ったトークンに書き換えます** |
| **10行目** | `DISCORD_ALLOWED_USER=your_discord_user_id_here` | **右側を、自分の Discord ユーザーID に書き換えます。`*` にしません** |
| **22行目** | `AGENT_BACKEND=codex` | **Codex を使うならそのままです。Claude Code を使うなら `claude-code` に書き換えます** |

`=` の前後に空白は入れません。8章でログインできた方を選びます。片方だけでも進めます。

!!! tip "行番号が合わないときは"
    `.env.example` は更新されることがあるので、**行番号がずれることがあります。**
    そのときは行番号ではなく、**`Ctrl` + `W` で `DISCORD_TOKEN` などの名前を探して**ください（下の nano の説明にあります）。

### 🔵 入口を Slack にする場合は、書き換える行が違います

[4b章](04b_slack.md)で Slack を選んだ方は、上の表の代わりに**こちら**を書き換えます。
`.env.example` は Slack の設定も**全部 `#` で無効にしてある**ので、`#` を消すところが増えます。

| 行 | いまの中身 | どうするか |
|---:|---|---|
| **4行目** | `DISCORD_TOKEN=your_discord_bot_token_here` | 🔴 **行の先頭に `#` を付けて無効にします**（Discord を使わないため） |
| **10行目** | `DISCORD_ALLOWED_USER=your_discord_user_id_here` | 🔴 同じく**先頭に `#` を付けます** |
| **15行目** | `# SLACK_ALLOWED_USER=your_slack_user_id_here` | **`#` を消して**、自分の Slack ユーザーID（`U` で始まる）に |
| **22行目** | `AGENT_BACKEND=codex` | 8章でログインできた方（`codex` または `claude-code`） |
| **96行目** | `# WORKSPACE_PATH=...` | **`#` を消して** `/home/<ユーザー名>/workspace` に（下で説明します） |
| **232行目** | `# SLACK_BOT_TOKEN=xoxb-your-bot-token` | **`#` を消して**、`xoxb-` のトークンに |
| **233行目** | `# SLACK_APP_TOKEN=xapp-your-app-token` | **`#` を消して**、`xapp-` のトークンに |

!!! tip "232行目まで一気に行くには"
    `nano` の中で **`Ctrl` + `W`** を押し、**`SLACK_BOT_TOKEN`** と入力して `Enter` を押します。
    行番号を数える必要はありません。

??? note "📄 `.env.example` の229〜233行目（実物・Slack のところ）"
    ここも**全部 `#` で無効**になっています。232行目と233行目の `#` を消して、右側を書き換えます。

    ```text
    # ========================================
    # Slack設定（Slack使う場合）
    # ========================================
    # SLACK_BOT_TOKEN=xoxb-your-bot-token
    # SLACK_APP_TOKEN=xapp-your-app-token
    ```

!!! success "書けたら、有効な行はこの5行になります（Slack 版）"
    ```bash
    SLACK_ALLOWED_USER=U01234567
    AGENT_BACKEND=claude-code
    WORKSPACE_PATH=/home/<ユーザー名>/workspace
    SLACK_BOT_TOKEN=xoxb-（4b章で取った長い文字列）
    SLACK_APP_TOKEN=xapp-（4b章で取った長い文字列）
    ```
    **順番はバラバラで構いません。**ファイルの中では 15 / 22 / 96 / 232 / 233 行目に散っています。
    🔴 **`DISCORD_TOKEN` と `DISCORD_ALLOWED_USER` の2行は、先頭に `#` が付いている**こと。

!!! danger "🔴 見本の文字を消し切ってください（2026-09-09 に実際に踏みました）"
    `# SLACK_BOT_TOKEN=xoxb-your-bot-token` の **`#` だけ消して、右側を消し忘れる**間違いが起きます。
    `your-bot-token` のような文字が残っていると、Slack は
    **`invalid_auth`（その鍵は無効）**と返し、返事が来ません。

    **`=` の右側は、まるごと消してから貼ってください。**

    🔴 **`#` を消したあとに、行頭の空白を残さないこと。**`  SLACK_BOT_TOKEN=...` のように
    先頭に空白があると、確認のコマンドが拾えません。

!!! success "手で打たずに入れる方法（画面にトークンは出ません）"
    ```bash
    read -rsp "xoxb- で始まる Bot Token を貼って Enter: " BT; echo
    read -rsp "xapp- で始まる App Token を貼って Enter: " AT; echo

    sed -i -E -e "s|^[[:space:]]*#?[[:space:]]*SLACK_BOT_TOKEN=.*|SLACK_BOT_TOKEN=$BT|" \
              -e "s|^[[:space:]]*#?[[:space:]]*SLACK_APP_TOKEN=.*|SLACK_APP_TOKEN=$AT|" \
              -e "s|^DISCORD_TOKEN=|#DISCORD_TOKEN=|" \
              -e "s|^DISCORD_ALLOWED_USER=|#DISCORD_ALLOWED_USER=|" ~/xangi/.env
    ```

    そのあと、こう出れば正解です（**行頭に空白が無いこと**・`xoxb-` と `xapp-` で始まること）。

    ```bash
    grep -nE "^(SLACK|AGENT_BACKEND|WORKSPACE_PATH)" ~/xangi/.env | sed -E 's/=(.{9}).*/=\1…/'
    ```

書けたかの確認は、Slack の場合 **5行**出れば正解です。

```bash
grep -n -v "^#" ~/xangi/.env | grep -v "^$"   # ← SLACK_ALLOWED_USER / AGENT_BACKEND / WORKSPACE_PATH / SLACK_BOT_TOKEN / SLACK_APP_TOKEN の5行
```

### もう1か所だけ、行の先頭の `#` を消します（96行目）

**96行目は、いま `#` が付いていて効いていません。**ここだけは `#` を消して書き換えます。

```bash
# WORKSPACE_PATH=/path/to/your/workspace      ← いまの状態（先頭に # がある）
WORKSPACE_PATH=/home/<ユーザー名>/workspace     ← こう直す（# を消して、右側を書き換える）
```

!!! danger "🔴 `/path/to/` を残さないでください（2026-09-09 に実際に踏みました）"
    見本が `/path/to/your/workspace` なので、**`your` だけを自分の名前に替えて
    `/path/to/jsc-ai/workspace` にしてしまう**間違いが起きます。
    **`/path/to/` ごと消して、`/home/` から書き直してください。**

    こうなると xangi は**起動した直後に落ちます**。pm2 が何度も起動し直すので、
    一見動いているように見えますが、**チャットには一切返事が来ません。**

!!! success "手で書かずに、この1行で入れるのが確実です"
    `nano` を使わずに、正しい値を入れられます。`$HOME` は「自分のホームフォルダ」に置き換わります。

    ```bash
    sed -i "s|^#\? *WORKSPACE_PATH=.*|WORKSPACE_PATH=$HOME/workspace|" ~/xangi/.env
    grep -n "^WORKSPACE_PATH" ~/xangi/.env   # ← /home/あなたの名前/workspace になっていること
    ```

**右腕の机を、道具の置き場と分けるため**です。ここを `#` のままにすると、
**xangi のプログラムが入っているフォルダが、そのまま机になります。**
そこへ成果物が混ざると、あとで xangi を新しくするときにぶつかります。

机になるフォルダは、先に作っておきます。

```bash
mkdir -p ~/workspace
```

!!! note "こちらは触りません"
    **503行目の `# SKIP_PERMISSIONS=false` は触りません。** `#` が付いているため未設定です。未設定では、既定の `true` が効きます。`true` にするために何か書く必要はありません。

!!! danger "既定の SKIP_PERMISSIONS=true の意味"
    ファイル操作もコマンド実行も、毎回の確認なしで走ります。**この用途専用の隔離された機械**で使います。本業データの入った共用 PC では使いません。

??? note "📄 `.env.example` の1〜30行目（実物）"
    4行目、10行目、22行目が、上の表と対応します。

    ```text
    # ========================================
    # Discord設定（Discord使う場合）
    # ========================================
    DISCORD_TOKEN=your_discord_bot_token_here

    # ========================================
    # 許可ユーザー設定（必須）
    # ========================================
    # Discord用（カンマ区切りで複数指定可、"*" で全員許可）
    DISCORD_ALLOWED_USER=your_discord_user_id_here
    # 複数ユーザー例: DISCORD_ALLOWED_USER=123456789,987654321
    # 全員許可: DISCORD_ALLOWED_USER=*

    # Slack用（カンマ区切りで複数指定可、"*" で全員許可）
    # SLACK_ALLOWED_USER=your_slack_user_id_here

    # ========================================
    # AIエージェント設定
    # ========================================
    # Agent backend: a built-in backend or an ID declared by a linked extension
    # This example recommends codex; the runtime fallback when omitted is claude-code.
    AGENT_BACKEND=codex

    # Optional: Model to use (backend-specific)
    # AGENT_MODEL=

    # Claude Code backend (AGENT_BACKEND=claude-code)
    # ANTHROPIC_API_KEY is passed only to the Claude Code child process.
    # Set CLAUDE_CODE_BARE=true to force Anthropic API-key auth instead of OAuth/keychain.
    # CLAUDE_CODE_MAX_BUDGET_USD limits API spend per Claude Code print-mode run.
    ```

ファイルを開きます。

```bash
nano .env
```

??? note "✏️ nano の使い方（これだけ覚えれば足ります）"
    `nano` は、端末の中で文章を書き換える道具です。マウスでは動かせません。矢印キーを使います。

    | やりたいこと | キー |
    |---|---|
    | 書き換える | 矢印キーでカーソルを動かして、そのまま打つ |
    | **保存する** | **`Ctrl` + `O` → `Enter`** |
    | **終わる** | **`Ctrl` + `X`** |
    | 保存せずに終わる | `Ctrl` + `X` → `N` |
    | 行を探す | `Ctrl` + `W` → 文字を入れて `Enter` |
    | 🔴 **貼り付ける**（トークンなど） | **`Ctrl` + `Shift` + `V`**、または**右クリック**。**`Ctrl` + `V` は効きません** |

    画面の下に出る `^O` は、`Ctrl` + `O` の意味です。`^` が `Ctrl` を表します。

    🔴 **トークンを貼るときは `Ctrl` + `V` ではなく `Ctrl` + `Shift` + `V`** です（3回目の注意です）。
    貼れないときは**右クリック**を試してください。

    ### 🔴 直すときは「行を丸ごと打ち直す」

    **一部だけ書き換えようとすると、見本の文字が残ります。**2026-09-09 に2回踏みました。
    次の順で、**行ごと消してから打ち直して**ください。

    | | 操作 |
    |---|---|
    | 1 | **`Ctrl` + `W`** → 行の名前（例 `SLACK_BOT_TOKEN`）を打って `Enter` |
    | 2 | **`Ctrl` + `A`** … 行の先頭へ |
    | 3 | ⚠️ **`Ctrl` + `K`** … **その行を丸ごと切り取る**（飛んだ先が目的の行か、目で見てから） |
    | 4 | `SLACK_BOT_TOKEN=` と**手で打つ** |
    | 5 | **`Ctrl` + `Shift` + `V`** … 値を貼る |

    **行を止めたいだけ**のとき（`DISCORD_TOKEN` など）は、`Ctrl` + `W` で探して
    **`Ctrl` + `A` のあと `#` を1文字打つ**だけです。

    4行目へ速く行くには、`Ctrl` + `W` で `DISCORD_TOKEN` を探します。同じ方法で `DISCORD_ALLOWED_USER` と `AGENT_BACKEND` を探すのが確実です。

保存して閉じたら、トークンを Windows のメモ帳から消します。書けた内容を確かめ、ファイルを本人だけが読める状態にします。

!!! danger "🔴 この確認の画面は、スクリーンショットに撮らないでください"
    次のコマンドは、**トークンをそのまま画面に表示します。**
    サポート役のチャットAIに貼ると、**トークンを渡してしまうことになります。**

    詰まってこの画面を見せたいときは、**トークンの部分を消してから**貼ってください。
    うっかり送ってしまったら、[4章](04_discord_bot.md)の `Reset Token` で**作り直せます。**

!!! success "書けたら、有効な行はこの4行になります（Discord 版）"
    ```bash
    DISCORD_TOKEN=（4章で取った長い文字列）
    DISCORD_ALLOWED_USER=123456789012345678
    AGENT_BACKEND=claude-code
    WORKSPACE_PATH=/home/<ユーザー名>/workspace
    ```
    **順番はバラバラで構いません。**ファイルの中では 4 / 10 / 22 / 96 行目に散っています。

```bash
grep -n -v "^#" ~/xangi/.env | grep -v "^$"   # ← 4行だけ出て、右側が自分の値になっていれば OK
chmod 600 ~/xangi/.env
```

## 3. ビルドして常駐させる

```bash
cd ~/xangi
npm install  # ← 3〜10分かかります
```

```bash
npm run build
```

```bash
npm install -g pm2
pm2 start "npm start" --name xangi
pm2 logs xangi  # ← 起動エラーが無いか。Ctrl+Cで表示だけ抜けます
```

## 4. 再起動後も立ち上げる

```bash
pm2 save
pm2 startup  # ← 表示されたコマンドを、そのまま実行する
```

`pm2 startup` 自体で終わりではありません。画面に「このコマンドを実行してください」と出た別のコマンドをコピーし、実行します。その後で保存します。

```bash
pm2 save
sudo loginctl enable-linger $USER
```

最後の1行は、SSH を切った後もユーザーのサービスを保つ設定です。

## 別の道

xangi には公式インストーラもあります。この手順では扱いません。公式インストーラは対話画面で設定を進めます。SSH 越しでは画面がうまく出ないことがあります。ここでは pm2 方式にそろえます。

## ✅ ここまで出来たら

`pm2 logs xangi` に起動を止めるエラーがなく、Discord の Bot がオンラインになれば合格です。会話の判定は10章で行います。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| Bot がオフライン | `pm2 logs xangi`。トークン前後の空白も確認します |
| backend が見つからない | 22行目が `AGENT_BACKEND=codex` または `AGENT_BACKEND=claude-code` か確認します |
| 許可されていない | `DISCORD_ALLOWED_USER` が自分のIDか確認します |
| `.env` を書いたのに反映されない | `grep -n -v "^#" ~/xangi/.env \| grep -v "^$"` で、有効な4行を確認します |
| 右腕が机を見つけられない | 96行目の `WORKSPACE_PATH` の `#` を消したか、`mkdir -p ~/workspace` をしたか |
| ビルドでエラー | `node -v` が v22 以降か確認します |
| 🔴 **直したのに、ログに同じエラーが出続ける** | **古いエラーが残っているだけかもしれません。**`pm2 flush xangi` でログを空にしてから、`pm2 restart xangi --update-env` → 25秒待って見直します（2026-09-09 にこれで2回誤診しました） |
| 🔴 **返事が全く来ない／`pm2 list` の ↺ が増え続ける** | `pm2 logs xangi --lines 40 --nostream` を見ます。`EACCES ... mkdir '/path/to/...'` なら **96行目に `/path/to/` が残っています**（上の1行で直せます） |
| `.env` を書き換えたのに変わらない | 🔴 **`pm2 restart xangi --update-env`** をします。pm2 は起動時の設定を持ったままです |
| 再起動後に止まる | `pm2 startup` が表示したコマンドと、`loginctl enable-linger` を実行したか確認します |

**8章で Claude Code または Codex を入れてあります。** サーバの中で `claude` または `codex` と打てば、この機械の中を実際に見て直してくれます。とくに自動起動の設定は手で写すと間違えやすいため、頼むのが早いです。次をそのまま貼れます。

```text
このサーバで pm2 で動かしている xangi が、再起動したあとに自動で立ち上がるようにしてください。
いまの状態を確認してから、必要な操作だけを実行してください。
実行したコマンドと、その結果を最後に報告してください。
うまくいかない場合は、工夫して先へ進まず、そこで止めて状況を教えてください。
```

!!! warning "AI が実行した内容を目で確認します"
    この機械は、確認なしでコマンドが走る設定です。何をしたかを最後に報告させて、必ず目で見てください。

次は [10. 第1関門](10_first_talk.md) です。


===============================================================
【10_first_talk.md】
===============================================================

# 10. ✅ 第1関門 — Discord から話しかける

ここは採用編の山場です。説明より、3つの判定を順番に行います。

## 判定1：返事

Discord の対象チャンネルへ送ります。

```text
こんにちは！
```

!!! note "入口が Slack の場合"
    **メンションを付けて**送ります。Bot を招待したチャンネルで `@xangi こんにちは！` です。
    反応しないときは、そのチャンネルで **`/invite @xangi`** をやったか確かめてください（[4b章](04b_slack.md)）。

Bot から返事が1件以上来れば次へ進みます。

## 判定2：最初の仕事

```text
このサーバのCPUとメモリとディスクを調べて、表にして教えて
```

返事に CPU、メモリ、ディスクの3項目が入っていれば合格です。

## 判定3：無人で復帰

SSH から再起動します。

```bash
sudo reboot
```

再起動後は、**何も手で起動しません。** Discord でもう一度 `こんにちは！` と送り、返事が来ることを確認します。

## 返事が来ないとき

| 症状 | まず見るところ |
|---|---|
| Bot はオンラインなのに無反応 | MESSAGE CONTENT INTENT が OFF。4章で ON にします |
| Bot がオフライン | `pm2 logs xangi`。トークンの貼り間違いを見ます |
| 「許可されていません」 | `DISCORD_ALLOWED_USER` を開発者モードで取り直します |
| backend が見つからない | `.env` の22行目が、使う方（`claude-code` または `codex`）になっているか見ます |
| 再起動後だけ止まる | `pm2 startup` の表示コマンドと `pm2 save` を確認します |

!!! success "ここで一区切りにして構いません"
    Discord から右腕へ話しかけられる状態になりました。残りは別の日でも、別の場所からでもできます。

## ✅ ここまで出来たら

再起動後に手で何も起動せず、2つのメッセージへ返事が来て、3項目の表が返れば合格です。

## 詰まったら

上の表を上から確認します。載っていない症状は[詰まったら](90_troubleshooting.md)と[記録場](log/index.md)へ進みます。

次は [11. 外から届くようにする](11_tailscale.md) です。


===============================================================
【11_tailscale.md】
===============================================================

# 11. 外から届くようにする（Tailscale）

Tailscale は、許可した機械だけをつなぐ専用の内線網です。この章の土台は2026-08-27に実機で通っています。作業中、**今つないでいる SSH は切れません。** 新しい通信路を足すだけで、今の有線 LAN には触れません。

## 1. 誰のアカウントにするか

あなた、またはあなたの会社**ご自身のアカウント**で作ります。導入を手伝う人の網には入れません。機械の持ち主だけで運用を続けられ、手伝う人の他の機械を見せないためです。

## 2. 料金を選ぶ

!!! warning "無料と決めつけず、2つから選びます"
    用途は業務です。登録メールによって扱いが変わるため、説明を読んで選び、選択を記録します。

| 選択肢 | 登録メールと料金 | 判断材料 |
|---|---|---|
| 個人アカウント | 個人 Gmail など。Personal は無料ですが、規約上は非商用向け | 今すぐ始められますが、業務利用とのずれが残ります |
| 会社アカウント | 会社ドメイン。business 扱いのトライアル後、Standard は1ユーザー月 $8 | 業務用として扱いが明確です |

将来もログインできるアカウントを選びます。担当者の私物だけに依存させません。

## 3. Windows に入れる

<https://tailscale.com/download/windows> から Windows 版を入れます。選んだアカウントでログインし、接続状態にします。サーバの認証 URL をこのブラウザで開くため、Windows 側を先に行います。

## 4. Ubuntu サーバに入れる

Windows から SSH で入ったまま実行します。

```bash
curl -fsSL https://tailscale.com/install.sh | sh
```

```bash
sudo tailscale up
```

画面に出た `https://login.tailscale.com/a/...` を Windows のブラウザで開きます。先ほど選んだアカウントでログインし、「Connect」を押します。

```bash
tailscale ip -4      # ← 100.で始まるIPv4
tailscale status     # ← 左端のサーバ名と、Windows PC
```

結果を[2章の表](02_values.md)に書きます。

## 5. サーバだけ鍵期限を無効にする

ブラウザで <https://login.tailscale.com/admin/machines> を開きます。`tailscale status` で確認したサーバ行の右端 `…` から「Disable key expiry」を選びます。「Expiry disabled」と出れば完了です。

期限を切るのは**サーバだけ**です。手元の Windows PC には掛けません。サーバは既定の180日後に黙ってつながらなくなるのを防ぎます。持ち歩く PC は期限がある方が安全です。

## 6. 自動起動と別回線を試す

```bash
systemctl is-enabled tailscaled  # ← enabled。最後のdを落とさない
```

`tailscale` と入力すると `not-found` になります。2026-08-27に実際に踏んだ誤りです。正しくは `tailscaled` です。

Windows PC の Wi-Fi を切り、スマホのテザリングへ替えます。その状態で PowerShell から実行します。

```bash
ssh <ユーザー名>@<Tailscale IP>
```

100で始まる IP へ入れれば、事務所の外から届く状態です。

## ✅ ここまで出来たら

別回線から SSH でき、`tailscaled` が `enabled` で、管理画面のサーバだけが `Expiry disabled` なら合格です。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| `tailscale ip -4` が空 | 認証 URL を開いて Connect したか |
| `not-found` と出る | `tailscale` ではなく `tailscaled` と入力したか |
| 別回線から入れない | Windows とサーバが同じアカウントの `tailscale status` にいるか |
| 半年後に突然止まるのが心配 | サーバ行だけ `Expiry disabled` か確認します |

次は [12. 出口を置く](12_wiki.md) です。


===============================================================
【12_wiki.md】
===============================================================

# 12. 出口を置く（Wiki）

Discord の答えは流れて消えます。成果を「渡す」のではなく「置く」棚として、MkDocs + Material の Wiki を用意します。この章では置き場だけを作ります。何を書くかは研修編で扱います。

```mermaid
flowchart LR
    D["Discord<br>会話は流れる"] --> A["右腕"]
    A --> W["Wiki<br>成果を置く棚"]
    W --> B["ブラウザで<br>後から読む"]
```

## この章の安全条件

この章の具体的な構築コマンドは、この手順書には載せていません。通していない操作を、通ったことにはしません。サーバ上の右腕（Claude Code または Codex）に、次の要件をまとめて渡して建てさせます。途中で判断が必要になったら止めさせます。

!!! warning "Tailscale の IPv4 だけで配信します"
    IP が取れないときは `0.0.0.0` に落としません。何も配信せず終了させます。`0.0.0.0` はすべての通信口で受ける指定で、意図しない公開につながるためです。

## 右腕へ渡す指示文

サーバに SSH で入り、8章でログインできた方を起動します（`claude` または `codex`）。次の全体をそのままコピーします。

!!! tip "Discord から頼んでも構いません"
    10章で建てた入口はもう使えます。**同じ文章を Discord に貼っても同じことが起きます。**
    長い指示なので画面の広い PC からのほうが楽ですが、
    「話しかけるだけで仕事が進む」ことを確かめる機会でもあります。

```text
このサーバに、成果物の置き場となる空の Wiki を作ってください。

要件:
- MkDocs と Material for MkDocs を使う。
- 中身は空のトップページ1枚でよい。何を書くかは今は決めない。
- 配信ポートは 8080 にする。
- 待受先は `tailscale ip -4` で得た Tailscale の IPv4 だけにする。
- Tailscale の IPv4 が取れない場合は、`0.0.0.0` にフォールバックしない。何も配信せず、安全に終了する。
- systemd で常駐させる。再起動後も人が起動し直さなくてよい形にする。
- `sudo` を使う範囲は必要最小限にする。
- 作成したファイル、実行したコマンド、サービス名、Wiki のディレクトリを最後に報告する。
- 下の3つの合格判定を実行し、実際の出力を報告する。
- 上の要件で判断できないことや、想定外のエラーに当たったら、工夫して先へ進まず、そこで止めて状況を報告する。

合格判定:
1. `ss -ltn | grep 8080` が `100.x.x.x:8080` であり、`0.0.0.0:8080` ではない。
2. Tailscale の IPv4 を取得できない場合に、何も配信せず終了する。
3. 再起動後、人がサービスを起動せず Wiki が開く。
```

右腕の報告に出た Wiki のディレクトリ（＝フォルダのこと）とサービス名は、[記録場](log/index.md)に残します。実行中に新しいコマンドや設定の判断を求められたら、承認して進めず止めます。

## 3つの合格試験

Windows PC をスマホのテザリングにつないだ状態で、ブラウザから次を開きます。

```text
http://<Tailscale IP>:8080/
```

サーバでは待受先を見ます。

```bash
ss -ltn | grep 8080  # ← 100.x.x.x:8080。0.0.0.0:8080 ではない
```

3つ目は「安全側に止まるか」です。**Tailscale をわざと切って、配信が上がらないこと**を見ます。

```bash
sudo tailscale down          # ← わざと切る
```

この状態で、右腕が報告した配信の手順（またはサービスの再起動）を1回だけ動かします。
**何も配信されずに終われば合格**です。`0.0.0.0:8080` で待ち受けたら不合格で、直させます。

```bash
ss -ltn | grep 8080          # ← 何も出ない、が正解
sudo tailscale up            # ← 必ず元に戻す
```

最後に再起動します。

```bash
sudo reboot
```

何も起動せず、別ネットワークの端末で同じ URL が開くことを確認します。開けた URL を[2章](02_values.md)へ書きます。

## ✅ ここまで出来たら

別回線から Wiki が開き、待受先が Tailscale IP だけで、再起動後も人の操作なしで開けば合格です。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| Wiki が開かない | 右腕が報告したサービス状態と Tailscale IP を見ます |
| `0.0.0.0:8080` と出る | 不合格です。配信を止め、Tailscale IP だけへ直させます |
| 再起動後に開かない | systemd の常駐設定を報告させます |
| 右腕が別の判断を求める | 工夫せず止め、記録場に書きます |

次は [13. 控えを置く](13_git.md) です。

## 🟡 この手順書の未確認事項

Wiki の構築と systemd の再起動試験は、まだ実機で通していません。この章の合格結果を記録してください。


===============================================================
【13_git.md】
===============================================================

# 13. 控えを置く（Git）

Git は、ファイルと変更履歴を残す控えです。右腕は、指示を誤解して複数のファイルを書き換えることがあります。**戻せることが、任せるための唯一の安全装置**です。

## 何をどこへ置くか

この手順書は、次のように分けます。

| 種類 | 例 | 置き場所 |
|---|---|---|
| 構造 | Wiki の作り、設定、手順書 | あなたご自身の GitHub アカウントのプライベートリポジトリ |
| コンテンツ | 成果物、日々のデータ | Google ドライブ、Dropbox など、すでに使っているストレージでもよい |

!!! warning "コンテンツ側は未実測です"
    Google ドライブや Dropbox へ置く方法は、まだ実際に試していません。構造の Git と混ぜず、選んだ置き場所と未確認事項を記録します。

## 1. GitHub に空の置き場を作る

あなたご自身の GitHub アカウントで、新しいプライベートリポジトリを作ります。名前を[2章](02_values.md)へ書きます。リポジトリの所有者とアクセスできる人も記録場へ残します。

## 2. SSH 鍵を作る

SSH 鍵は、パスワードやトークンを画面へ貼らずに GitHub と認証する仕組みです。サーバで実行します。

```bash
ssh-keygen -t ed25519
```

表示に従います。公開鍵を表示します。

```bash
cat ~/.ssh/id_ed25519.pub  # ← この公開鍵だけをコピーする
```

GitHub の設定画面で「SSH and GPG keys」→「New SSH key」と進み、この**公開鍵**を登録します。`id_ed25519` という末尾が `.pub` でない秘密鍵は、表示も貼り付けもしません。

```bash
ssh -T git@github.com  # ← GitHub の認証結果を見る
```

## 3. Wiki を Git に入れる

12章で Claude Code が報告した Wiki のディレクトリへ移動します。以下の `<Wikiのディレクトリ>`、`<GitHubユーザー名>`、`<リポジトリ名>` は実際の値へ置き換えます。

```bash
cd <Wikiのディレクトリ>
git init
```

```bash
git config user.name "<GitHubで使う名前>"
git config user.email "<GitHubで使うメールアドレス>"
```

```bash
git add .
git commit -m "Initial wiki"
```

```bash
git branch -M main
git remote add origin git@github.com:<GitHubユーザー名>/<リポジトリ名>.git
git push -u origin main
```

パスワードや GitHub のトークンをコマンド、チャット、メールへ貼る手順にはしません。認証は先ほどの SSH 鍵を使います。

## 4. 戻せる控えか試す

履歴を見ます。

```bash
git log --oneline  # ← 1行以上ある
```

元の Wiki の外にある別のディレクトリへ複製します。`<確認用ディレクトリ>` は、元とは別の場所を指定します。

```bash
git clone git@github.com:<GitHubユーザー名>/<リポジトリ名>.git <確認用ディレクトリ>
```

```bash
diff -r --exclude=.git <Wikiのディレクトリ> <確認用ディレクトリ>  # ← 出力が0行
```

出力が0行なら、元と控えのファイルが一致しています。

## ✅ ここまで出来たら

`git log --oneline` が1行以上で、別ディレクトリへの clone 後に `diff -r` が0行なら合格です。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| GitHub へつながらない | `ssh -T git@github.com` の結果を見ます |
| commit できない | `git config user.name` と `user.email` を確認します |
| push の認証を求められる | HTTPS のパスワード方式ではなく、SSH のリポジトリ URL か確認します |
| `diff -r` に出力がある | 差が控えに入っていません。内容を確認して記録します |
| `git init` が `Permission denied` | Wiki のディレクトリが別の持ち主です。所有者を `ls -ld <Wikiのディレクトリ>` で見て、Claude Code に直させます |

次は [14. 採用の合格判定](14_handover.md) です。

## 🟡 この手順書の未確認事項

構造を GitHub へ置く工程と、コンテンツを既存ストレージへ置く工程は、まだ実機で通していません。


===============================================================
【14_handover.md】
===============================================================

# 14. 採用の合格判定と、研修編への引き渡し

この1枚を上から確認します。実際に見ていない項目にはチェックを付けません。該当しないノート PC 用の項目は入れていません。

## 採用のチェックリスト

### 箱と接続

- [ ] Ubuntu Desktop が起動します。
- [ ] ユーザー名は `whoami` の出力で記録しました。
- [ ] LAN内IPは `hostname -I` の出力で記録しました。
- [ ] 別の Windows PC から `ssh <ユーザー名>@<LAN内IP> 'uptime'` が返ります。
- [ ] 設置場所は、自動ログインの機械を物理的に守れる場所です。
- [ ] BIOS のキー、初期 OS、停電復帰項目の実物確認を記録しました。
- [ ] （BIOS に停電復帰の項目があった場合のみ）電源ケーブルを抜いて挿し直すと、
  ボタンを押さずに起動して Discord が返事をします。項目が無かった場合は「無し」と記録しました。

### 入口 Discord と右腕

- [ ] MESSAGE CONTENT INTENT が ON です。
- [ ] `.env` の22行目 `AGENT_BACKEND` が、ログインできた方（`claude-code` または `codex`）になっています。
- [ ] `DISCORD_ALLOWED_USER` は空でも `*` でもなく、本人のユーザーIDです。
- [ ] `.env` の権限を `600` にしました。
- [ ] `node -v` は v22 以降です。
- [ ] Claude か ChatGPT の、どちらかの有料アカウントでログインしました。API キーは使っていません。
- [ ] Discord の `こんにちは！` に返事が来ます。
- [ ] CPU、メモリ、ディスクの3項目を含む返事が来ます。
- [ ] `sudo reboot` 後、xangi を手で起動せずに返事が来ます。

### 外からの経路

- [ ] Tailscale はあなた、またはあなたの会社自身のアカウントです。
- [ ] `tailscale ip -4` は100で始まる IP を返します。
- [ ] 管理画面で、サーバだけ `Expiry disabled` です。
- [ ] `systemctl is-enabled tailscaled` は `enabled` を返します。
- [ ] Windows PC を別回線へ替え、`ssh <ユーザー名>@<Tailscale IP>` で入れます。
- [ ] 別回線のスマホから Discord へ送り、返事が来ます。

### 出口と控え

- [ ] Wiki のトップページが1枚以上あります。中身は空でも構いません。
- [ ] 別回線の端末で `http://<Tailscale IP>:8080/` が開きます。
- [ ] 8080番の待受先は Tailscale IP だけで、`0.0.0.0` ではありません。
- [ ] 再起動後、人が起動しなくても Wiki が開きます。
- [ ] GitHub のプライベートリポジトリ名と所有者を記録しました。
- [ ] `git log --oneline` は1行以上です。
- [ ] 別ディレクトリへの clone と `diff -r` の結果は0行です。
- [ ] 未実施・未検証の項目を、完了扱いせず記録しました。

## 記録場へ残すもの

| 記録 | 書く内容 |
|---|---|
| 人と機械 | ユーザー名、設置場所 |
| 網 | LAN内IP、Tailscale IP、サーバ名、登録アカウントの持ち主 |
| 現物確認 | BIOS のキー、初期 OS、停電復帰の有無と項目名 |
| 仕事の道具 | Discord の場所、Wiki URL、GitHub リポジトリ名 |
| 実施記録 | 所要時間、詰まった箇所、直し方、未解決事項 |

[初回の記録用紙](log/first_setup.md)と[記録場](log/index.md)を使います。うまくいった事実だけでなく、どこで止まったかを残します。

!!! note "次の工程では、仕事をそのまま渡します"
    **整えてから頼む必要はありません。まず `/marunage` に、頼みたいことをそのまま投げてください。**
    大きすぎるときは、右腕が切り分けの案を出します。**選ぶのは人です。**

スターターキットの4つのうち、この採用編で用意したのは 1 **仕事の道具**と 4 **置き場所**です。2 **仕事の型**と3 **台帳**は、次の研修編で扱います。

## ✅ ここまで出来たら

上のうち対象となる項目がすべてチェック済みで、未確認が正直に記録されていれば採用の合格です。

## 詰まったら

| 症状 | まず見るところ |
|---|---|
| チェックできない項目がある | 該当章へ戻ります。確認していない項目にはチェックしません |
| 未確認事項が残った | 記録場へ理由と次の確認方法を書きます |
| 症状をどの章で見るか分からない | [詰まったら](90_troubleshooting.md)を開きます |

次は [詰まったら](90_troubleshooting.md) を控えとして読んでください。

ここまでが**採用**です。**研修編**（実際の仕事を渡し、丸投げ→スキル→システム化で育てる）はこの続きに別で作ります。


===============================================================
【90_troubleshooting.md】
===============================================================

# 詰まったら（症状から引く表）

!!! danger "最初に見る3つ"
    1. Bot はオンラインなのに無反応なら、`MESSAGE CONTENT INTENT` が OFF です。
    2. SSH のユーザー名には表示名ではなく、`whoami` の出力を使います。
    3. backend が無いなら、`.env` の `AGENT_BACKEND` を確認します。

この手順書の各章に実際に書かれている症状だけをまとめています。上から症状を探してください。

| 症状 | どの章 | まず見るところ |
|---|---:|---|
| Bot はオンラインなのに無反応 | 4、10 | MESSAGE CONTENT INTENT を ON にし、Save Changes |
| 🔴 **直したのに同じエラーが出続ける** | 9 | `pm2 flush xangi` でログを空にしてから測り直す。**ログの末尾は過去の残骸のことがあります** |
| 🔴 **返事が全く来ない（Slack も Discord も）** | 9 | `pm2 logs xangi --lines 40 --nostream`。`EACCES ... '/path/to/...'` なら `WORKSPACE_PATH` に見本の `/path/to/` が残っています |
| `.env` を直したのに変わらない | 9 | `pm2 restart xangi --update-env`。pm2 は起動したときの設定を持ったままです |
| （Slack）`auth.test` が `not_authed` | 9 | **鍵が1つも送られていません。**行頭に空白が残っているか、`#` を消していません |
| （Slack）ログに `invalid_auth` | 4b | **Bot Token（`xoxb-`）が違います。**`xapp-` と入れ違いか、Signing Secret を入れていないか |
| （Slack）メンションしても無反応 | 4b | そのチャンネルで `/invite @xangi` をやったか |
| （Slack）`xapp-` のトークンが無い | 4b | **Basic Information** の下の **App-Level Tokens** です |
| （Slack）権限を足したのに変わらない | 4b | **Install App** から入れ直す（再インストールで反映されます） |
| 権限を足したのに Bot が反応しない | 4 | 招待 URL を開き、もう一度認可します |
| `Permission denied` | 7 | 表示名ではなく `whoami` のユーザー名。パスワードも確認 |
| backend が見つからない | 9 | `AGENT_BACKEND=codex` または `AGENT_BACKEND=claude-code` か確認 |
| BIOS に入れない | 6 | 電源投入前から `Delete`。次に `F7`、`Esc`、`F2` |
| USB から起動しない | 6 | Fast Boot 無効、Secure Boot 無効、USB が Boot 順の先頭 |
| SSH で入れない | 7 | `openssh-server`、`whoami`、IP、22番の順 |
| `Connection refused` | 7 | SSH サーバが動いていません。6章の SSH 有効化 |
| `No route to host`／無反応 | 7 | Windows と Ubuntu の IP の前3つ、IPの取り違え |
| `nvm` が見つからない | 8 | SSH を一度切り、つなぎ直す |
| `curl: command not found` | 6 | `sudo apt install -y openssh-server curl git` を実行 |
| `claude`／`codex` が `command not found` | 8 | SSH を一度切り、つなぎ直す |
| `npm run build` でエラー | 9 | `node -v` が v22 未満なら LTS を入れ直す |
| `.env` を書いたのに反映されない | 9 | `grep -n -v "^#" ~/xangi/.env \| grep -v "^$"` で有効な4行を確認 |
| Bot がオフラインのまま | 9、10 | `pm2 logs xangi`。トークンの貼り間違いと前後の空白 |
| 「許可されていません」 | 9、10 | `DISCORD_ALLOWED_USER` を開発者モードで取り直す |
| 再起動したら xangi が止まった | 9、10 | `pm2 startup` が表示したコマンドを実行したか |
| Tailscale の確認で `not-found` | 11 | サービス名の末尾は `tailscaled`。`d` を落とさない |
| Tailscale IP が出ない | 11 | `sudo tailscale up` の認証 URL を開き Connect |
| 別ネットワークから SSH できない | 11 | Windows とサーバが同じ `tailscale status` にいるか |
| Wiki が開かない | 12 | Tailscale IP、Claude Code が報告したサービス状態 |
| 8080番が `0.0.0.0` で待ち受ける | 12 | 不合格。配信を止め、Tailscale IP だけへ修正 |
| 再起動後に Wiki が開かない | 12 | systemd の常駐設定 |
| GitHub へつながらない | 13 | `ssh -T git@github.com` の結果 |
| commit できない | 13 | `git config user.name` と `user.email` |
| push で認証を求められる | 13 | SSH のリポジトリ URL を使っているか |
| `diff -r` に出力がある | 13 | 元と複製の差を記録し、控えに入っていない内容を確認 |
| 端末でコピーができない | 6 | `Ctrl`+`C` ではなく **`Ctrl`+`Shift`+`C`**。貼り付けは `Ctrl`+`Shift`+`V` か右クリック |
| コマンドが途中で止まった／画面が戻った | 6 | `Ctrl`+`C` を押していませんか。端末では「中止」の意味です |
| パスワードを打っても画面に何も出ない | 6、7 | **正常です。**そのまま打って `Enter` を押します |
| `nano` でトークンが貼れない | 9 | `Ctrl`+`V` は効きません。**`Ctrl`+`Shift`+`V`** か右クリック |
| Wi-Fi の一覧が出ない | 付録A | `rfkill`、`nmcli device status`、`lspci` の順 |
| Wi-Fi が再起動後につながらない | 6 | `connection.permissions ""` を含む1行を実行 |

**この表に無い症状に当たったら、その場で工夫せず、[記録場](log/index.md)に書いてください。**

8章で Claude Code または Codex を入れてあります。サーバの中で `claude` または `codex` と打てば、この機械の中を実際に見て直してくれます。とくに自動起動の設定は手で写すと間違えやすいため、次をそのまま貼って頼めます。

```text
このサーバで pm2 で動かしている xangi が、再起動したあとに自動で立ち上がるようにしてください。
いまの状態を確認してから、必要な操作だけを実行してください。
実行したコマンドと、その結果を最後に報告してください。
うまくいかない場合は、工夫して先へ進まず、そこで止めて状況を教えてください。
```

!!! warning "AI が実行した内容を目で確認します"
    この機械は、確認なしでコマンドが走る設定です。何をしたかを最後に報告させて、必ず目で見てください。

手伝ってくれる人がいるなら、記録場に書いた文言をそのまま渡すのがいちばん早く片づきます。

画面に出た文言は、省略せずそのまま貼ってください。省略された1行に原因があることがよくあります。

付録は [こちら](99_appendix.md) です。


===============================================================
【99_appendix.md】
===============================================================

# 付録

## 付録A：Wi-Fi が一覧に出ないとき { #appendix-a }

Wi-Fi の接続手順は[6章](06_ubuntu.md#wifi)にあります。一覧に Wi-Fi が出ない場合だけ、上から確認します。

```bash
rfkill list  # ← Soft blocked: yes でないか
sudo rfkill unblock wifi
```

```bash
nmcli device status  # ← wifiデバイスがあるか
lspci -nnk | grep -A3 -i net  # ← チップとドライバ
```

`Kernel driver in use:` が無い場合は、ドライバが入っていません。ここから先は本筋にないため、その場で足さず記録場へ書きます。

## 付録B：この機械の性能を見る

```bash
lscpu
```

```bash
free -h
```

```bash
lsblk
```

```bash
ip -4 addr show
```

これを Claude Code（または Codex）に投げて表にしてもらうのが、最初の仕事の練習になります。数字を自分で解釈せず、出力を省略せず渡します。

## 付録C：やらないと決めたこと

| やらないこと | 理由 |
|---|---|
| Docker で建てる方式 | SSH 越しで確実に動き、原因を `pm2 logs` 1本で追える pm2 方式へそろえます |
| `tailscale serve` で公開 | 別のサーバで WebSocket（通信をつなぎ続ける仕組み）が壊れた実測があります |
| `--exit-node` | 通信全体の経路を変えます。今回必要な「機械同士をつなぐ」範囲を越えます |

## 🟡 この手順書の未確認事項

Wi-Fi のドライバが入っていない場合の追加作業は、想定機種では未確認です。

採用の終点は [14. 採用の合格判定](14_handover.md) です。