Linux 從 0 開始

給從沒裝過 KernelHub 的 Linux。照著做，每一步都能複製、都知道成功長什麼樣：先裝 Node，再一行裝 KernelHub，登入 Runtime，配對手機，發一條真任務，看它交付。

1 · 開始之前：這台 Linux 缺什麼

一台從沒裝過 KernelHub 的 Linux（x86-64 或 arm64；桌面、伺服器、虛擬機器都行），要走到「手機上派活、這台機器上幹活」。先搞清楚它自帶什麼、缺什麼：

本頁除了裝 curl、開啟常駐會話這兩處，都不需要 sudo。如果你本來就是 root（提示符是 #），把指令前面的 sudo 去掉即可。

2 · 能上網：最短主路徑（共 15 步）

一步一行，複製即用。

第 1 步 · 確認有 curl

成功：打出 curl 的版本資訊，直接做第 2 步。全新精簡系統上可能看到（說明沒有 curl）：

bash: curl: command not found

Ubuntu / Debian 裝 curl：

Fedora / RHEL / CentOS Stream 裝 curl：

第 2 步 · 看看有沒有 Node

已經有 Node：打出版本號 —— 跳到第 3 步，第 4、5 步可以不做。全新系統上會看到（說明沒裝，照做下去）：

bash: node: command not found

第 3 步 · 把 ~/.local/bin 放進 PATH

這一行做三件事：如果 ~/.bashrc 裡還沒有，就追加一行；當前視窗立刻生效；最後列印 PATH 的第一段給你看。重複跑不會重複追加。（用 zsh 的人把兩處 ~/.bashrc 換成 ~/.zshrc。）

成功：打出來的是 /home/你的使用者名稱/.local/bin（root 是 /root/.local/bin）：

/home/kh/.local/bin

第 4 步 · 下載 Node.js，並用官方校驗和核對

當前 LTS 是 Node v24.21.0。這一行按你的 CPU（x86-64 / arm64）下載 nodejs.org 官方的 .tar.gz，再拿官方的 SHASUMS256.txt 核對：

成功：最後一行是檔名後面跟著 OK：

node-v24.21.0-linux-arm64.tar.gz: OK

最後是 FAILED：下載壞了，重跑這一行。報 curl: (6) / (7) / (28) / (35)：網路問題，重跑；還不行看第 5 節設代理。

sha256sum: WARNING: 1 computed checksum did NOT match
node-v24.21.0-linux-arm64.tar.gz: FAILED

第 5 步 · 把 Node 解到 ~/.local（不要 sudo）

成功：打出兩行版本號，一行 node、一行 npm：

v24.21.0
11.19.0

這樣裝的好處：node、npm 和之後的 icloser、claude 都在 ~/.local/bin，npm 的全域性安裝也落在 ~/.local，不需要 sudo，不會報 EACCES。官方包是給 glibc 系統（Ubuntu、Debian、Fedora 這類）的；Alpine 這類 musl 系統用發行版自己的 nodejs 包，再看第 4 節。

第 6 步 · 一行裝 KernelHub

它按順序做這些事，你不用管，看著就行：

成功時螢幕上會出現（安裝指令碼的輸出是中文的）：

  清单：stable 频道 · v1.0.2 · build 202609161352 · commit a4099c062543
下载 icloser_linux_arm64 …
✓ SHA-256 核对通过
✓ 装到 /home/kh/.local/bin/icloser
✓ 装到 /home/kh/.local/bin/kernelhub-desktop（本机管理台）
✓ icloser 1.0.2 (build 202609161352, commit a4099c062543)
装 Runtime：claude（npm install -g @anthropic-ai/claude-code）…
✓ 装好 Runtime：claude（@anthropic-ai/claude-code）
下一步：
  ① 登录 Runtime（只用一次）。装上但没登录，任务照样跑不了：
        claude
     按提示登录完，退出它即可。
  ② cd 到你的项目目录，跑：
        icloser pair

如果裡面有「这台机器上没有 npm，Runtime 没装」，說明第 4、5 步沒做或沒生效 —— KernelHub 本體已經裝好，回去裝好 Node，再把這一行跑一遍：

  清单：stable 频道 · v1.0.2 · build 202609161352 · commit a4099c062543
下载 icloser_linux_arm64 …
✓ SHA-256 核对通过
✓ 装到 /home/kh/.local/bin/icloser
  ⚠️ 管理台没下下来（kernelhub-desktop_linux_arm64）—— 只装了 CLI
✓ icloser 1.0.2 (build 202609161352, commit a4099c062543)
  ⚠️ 这台机器上没有 npm，Runtime 没装（KernelHub 本体已经装好）
     装好 Node.js（自带 npm）之后重跑一次这个安装器即可。

如果有「管理台没下下来 —— 只装了 CLI」：多半是網路抖了一下，把這一行再跑一遍即可。

第 7 步 · 核一下裝到的是哪一版

成功：一行裡同時有 1.0.2 和 202609161352：

icloser 1.0.2 (build 202609161352, commit a4099c062543)

報 icloser: command not found：第 3 步沒做；做完再試。

第 8 步 · 讓 Runtime 登入一次

先看看登入前是什麼樣。這條指令第一次輸出很長（一張矩陣加幾十行說明），只看最上面 Claude Code 那一行：登入前是「状态不明」（STARTABLE_AUTH_UNKNOWN），登入後是「✅ 可用」（AUTHENTICATED）。

这台机器上的 Runtime（14 家已注册 · 1 家装着 · 0 家可直接用 · 0 家卡在登录/凭据）
     Runtime                版本          状态           登录态 / 位置
  ⚠️ Claude Code            2.1.272     状态不明         声明了探测手段但一条都没命中，状态问不出来（不猜）
  Claude Code            STARTABLE_AUTH_UNKNOWN       起得来，但登录态问不出来：声明了探测手段但一条都没命中，状态问不出来（不猜）

然後登入。第一次執行會帶你登入，照螢幕上的提示做（沒有瀏覽器的伺服器上，按它給的辦法在你自己的電腦上完成登入）。登入完輸入 /exit 或按兩次 Ctrl + C 退出：

第一次執行 claude 的幾屏（Linux 實錄，按屏照錄要點）：

1. Welcome to Claude Code v2.1.272 / Choose the text style —— 回車（預設 Dark mode）。
2. Select login method —— 回車（選 1. Claude account with subscription）。
3. Browser didn't open? Use the url below to sign in —— 在瀏覽器裡開啟那條連結登入授權，把頁面給的授權碼粘回來，回車。
4. Login successful. Press Enter to continue… —— 回車。
5. Security notes … Press Enter to continue… —— 回車。
6. Accessing workspace … ❯ No, exit / Yes, I trust this folder —— 回車（No, exit：只是為了登入，退出即可）。

再跑一次 icloser runtimes，成功：Claude Code 那一行是可以直接用的狀態：

这台机器上的 Runtime（14 家已注册 · 1 家装着 · 1 家可直接用 · 0 家卡在登录/凭据）
     Runtime                版本          状态           登录态 / 位置
  ✅  Claude Code            2.1.272     可用           /home/kh/.local/bin/claude
  Claude Code            AUTHENTICATED                起得来、凭据也在（配置文件 /home/kh/.claude.json 里有顶层键 oauthAccount（只看键是否存在，不读值））。 …

還卡在登入上（狀態寫著 STARTABLE_NOT_AUTHED 或「状态不明」（STARTABLE_AUTH_UNKNOWN））：再敲一次 claude 登入。

第 9 步 · 建一個專案目錄並進去

已經有專案的，把路徑換成你自己的：

專案要用 git 的話，先確認裝了 git（Ubuntu / Debian 用 sudo apt-get install -y git，Fedora 用 sudo dnf install -y git）。

第 10 步 · 配對手機

它會依次做三件事：

1. 在當前目錄建工作區。
2. 問你這台機器上 Agent 可以自己做到哪一步 —— 直接回車就是第 3 檔「讀 + 寫 + 執行」，能改檔案、能跑構建和測試，多數人選它。
3. 在終端裡畫一個二維碼，下面還有一條「掃不了就手工粘這條」的連結。

這一步的螢幕 Linux 實錄裡沒有單獨留檔；權限那一問在 Mac 實錄裡是 6 檔選單、回車＝3，見 Mac 從 0 開始 第 10 步。

開啟手機上的 KernelHub App 掃這個碼。SSH 視窗太窄、碼畫不全的話，把視窗拉寬再敲下面這一行重畫。

第 11 步 · 在手機 App 裡輸入邀請碼

全新帳戶第一次 pair 時，視窗裡會有這麼一句（Mac 實錄原句，Linux 是同一套 CLI）：

  账户 7a9e5014 还没有使用权 —— 在 iPhone 或 Android 上输入一次邀请码即可，
  这台机器会自动继承（CLI 上没有激活入口）

意思是：這個帳戶還沒有使用權，啟用只能在手機上做，電腦這邊沒有入口。開啟手機上的 KernelHub App，照提示輸入邀請碼；兌換成功後，這台電腦自動繼承，不用再敲任何指令。

• 一個碼 30 天。
• 多個碼天數累計：實測剩 29 天時再兌一個碼，變成 59 天。
• 同一個碼不能兌兩次：第二次會被拒（invite_exhausted）。

沒有碼怎麼要，見使用權限與啟用。已經啟用過的帳戶，pair 時會說「使用權已繼承」，這一步跳過。

第 12 步 · 開始接活

這個視窗別關。它會一直開著，每隔幾秒去看有沒有新任務 —— 手機上發的任務就是它接的。開頭幾行會說它加入了哪個工作區、選了哪家 Runtime：

icloser · 设备 cli-fresh-ubuntu · 工作区 cc274549-d96e-44d8-a0a1-f89727078c5e
Selected Runtime: claude · 适配器 claude-code（支持会话接续、只读可强制）
  选择原因: eligible pool 里最佳可用：claude
工作目录 /home/kh/projects/my-app · 轮询 3s
等待命令中（Ctrl-C 退出）…

第 13 步 · 發一條真任務，看它交付

第 12 步那個視窗開著的時候，拿起手機：

1. 在 KernelHub App 裡選中剛配對的工作區，在輸入框裡打一句話發出去。知道檔名就寫上，比如「在 README.md 末尾加一行今天的日期，不要提交」。
2. 電腦上跑 icloser run 的視窗會滾出新的幾行 —— 說明任務被接住了。手機上的任務卡會變成即時檢視：讀了哪些檔案、跑了哪些指令、改了哪些檔案。
3. 任務缺一檔權限時，它會在動手之前停下來掛一張卡，點核准只對這一條任務生效。
4. 跑完之後，點卡片上的「改動」逐行看它改了什麼，再讀結果：做了什麼、改了什麼、有什麼沒做成。結果不滿意就點「要求修改」，讓同一條任務接著做。

成功：任務狀態是完成，「改動」裡能看到 README.md 多出的那一行，開啟電腦上的檔案也確實多了一行。

  ⓘ go：KernelHub Base（机器级，与这条任务无关）没装上 —— 不挂卡、不阻塞，这条任务照常往下跑。要补齐：在这台机器上跑 icloser env bootstrap go，或在设备权限里批 exec + web 后它会自动补上。

一條任務在第 12 步那個視窗裡交付時是這樣的（Linux 實錄）：

▶ 102f0802  新建 hello.txt，内容只写一行：hello from kernelhub。不要提交。
  ✓ 落盘核对通过（看了 2 个路径，没有越权改动）
  ⓘ 改动 1 个文件（+0 −0）
  ⓘ 已上传 1 份产物，手机上可以直接打开
✓ 完成（16s）
    我在项目根目录新建了 `hello.txt`，写入前确认过这个文件不存在。里面只有一行：
    ```
    hello from kernelhub
    ```

同一條任務的結果（CLI 裡看到的，和手機上是同一份）：

新建 hello.txt，内容只写一行：hello from kernelhub。不要提交。
  状态    done
  机器    fresh-ubuntu
  完成于  09-15 16:58
  小结    我在项目根目录新建了 `hello.txt`，写入前确认过这个文件不存在。里面只有一行：

```
hello from kernelhub
```

我没有提交，这个目录也不是 git 仓库。
  改动    改了你的文件。看改了什么：icloser task diff 102f0802

發出去一直沒人接：回去看第 12 步那個視窗還在不在；還卡著就做下一步體檢。

第 14 步 · 體檢（另開一個終端 / SSH 視窗）

  ✓ 工作目录  /home/kh/projects/my-app
  ? 常驻服务  Unknown（查不到服务状态）
  ✓ 网关连得上、令牌有效
  ✓ 读得到任务队列
      任务 2 条，其中 0 条还没人接
      执行体 fresh-ubuntu · 在轮询（0 秒前）
  ✓ 读得到本机权限
      已生效：exec read write
  ✓ 读得到 AI 团队
  本机 Runtime
      ✓ claude     /home/kh/.local/bin/claude
都正常。

這段是修復前那一版的實錄：「常駐服務」那一格在 Linux 上以前恆為 Unknown，v1.0.2 起會如實說裝沒裝、在不在跑。

服務、閘道器、佇列、權限、Runtime 一次查完。哪一項不對，它會直接說下一步該敲什麼。

第 15 步 · 關掉視窗、斷開 SSH 也要接活：裝成常駐

第 12 步那個視窗一關（或 SSH 一斷），手機上再發任務就沒人接了。有 systemd 的系統跑這一行（它讀的是配對時記下的專案目錄，在哪個目錄敲都一樣）：

✓ 已常驻 kernelhub-cli.service
  执行体   /home/kh/.local/bin/icloser run
  项目目录 /home/kh/projects/my-app
  unit     /home/kh/.config/systemd/user/kernelhub-cli.service
  日志     /home/kh/.kernelhub/daemon.log
     除非开启常驻会话：sudo loginctl enable-linger kh
     想要开机即起、与登录无关：用 root 再跑一次 icloser daemon install
  看状态：icloser daemon status

（節選：原輸出在「日誌」和「除非開啟常駐會話」之間還有一行 ⚠️，說這是 user 級常駐、你不是 root，登出之後會被收掉。）

• 你是普通使用者：它裝的是使用者級常駐，你一登出就會被 systemd 收掉。要讓它登出後也繼續跑，開啟常駐會話（需要 sudo，一台機器做一次）：

• 你是 root：它裝的是系統級常駐，開機就起，不用管登沒登入。
• 報「这台机器上没有 systemctl」（容器、精簡系統常見）：用下面這一行讓它在後台一直跑，日誌寫到 ~/icloser-run.log（機器重啟後要重新敲一次）：

之後隨時用這一行看常駐在不在：

✓ 正在跑 · pid 12860
  日志 /home/kh/.kernelhub/daemon.log

看它最近在幹什麼：

裝了常駐之後，第 12 步那個手動開的 icloser run 就可以關掉了，兩個同時開是多餘的。

3 · 本機管理台（含沒有圖形介面的伺服器）

管理台是單獨的程式，icloser run 不會帶起它。起它（這個視窗也會一直佔著）：

在這台機器自己的瀏覽器裡開啟 http://127.0.0.1:18092。它只綁在本機迴環地址，別的機器直接夠不著 —— 這是故意的。

伺服器沒有瀏覽器？在你自己的電腦上開一個 SSH 隧道（把使用者名稱和伺服器地址換掉；這個視窗開著別關），然後在自己電腦的瀏覽器裡開啟 http://127.0.0.1:18092：

看管理台現在在不在跑、地址是什麼：

4 · Node 的另一種裝法：發行版自帶的包

也可以用發行版的包管理器裝 nodejs 和 npm。兩件事要知道：版本常常偏舊；而且裝在系統目錄，之後 npm install -g 常會報 EACCES（權限不夠） —— 包括 KernelHub 安裝指令碼替你裝 claude 那一步。

別用 sudo 硬裝，把 npm 的全域性目錄改到 ~/.local 就好（先做第 2 節第 3 步）：

成功：打出 /home/你的使用者名稱/.local。然後把第 6 步的安裝指令再跑一遍。

5 · 再裝別的 Runtime、網路被堵

再裝別的 Runtime（不用重跑整個安裝）

預設只裝了 claude。能用 npm 裝的有：claude、codex、qwen、codebuddy、opencode、kimi、mimo、pi。下面這一行裝的是 codex，換成其中任意一個即可：

或者用安裝指令指定（同樣把 codex 換成你要的）：

裝完同樣要登入一次（敲它的名字，比如 codex）。Google 這一家是 agy（Antigravity），不走 npm，要從 Google 官方渠道裝。

設代理（只對當前這個視窗生效）

把 埠 換成你自己的代理地址和埠，最後那段是自證：

成功：打出 install -> HTTP 200。打不出就是代理不對，先別往下走。通了之後，第 2 節的指令照常在這個視窗裡跑。

npm 換映象

會回顯映象地址。registry.npmmirror.com 是常見的公共映象，換別的就把地址替換掉。

換 KernelHub 自己的下載源 / 不裝 Runtime

公司內網有映象時（映象要照原樣映象官方目錄，SHA-256 仍然會核；安裝指令碼本身仍從 icloser.xyz 取）：

一個 Runtime 都不裝（只要 CLI）：

6 · 自己核一遍檔案對不對

打出來的串和下表比，按你的 CPU 看對應的行：

KernelHub 那幾行與發佈清單 stable.json 逐字一致；Node 那兩行來自 nodejs.org 的 SHASUMS256.txt。安裝指令碼本身已經替你核過一遍，這裡是給想親眼看的人。

7 · 常見報錯：症狀 → 原因 → 那一行指令

8 · 解除安裝 / 清乾淨

① 裝過常駐的，先卸常駐：

② 先看清楚要刪什麼（只列，不刪）：

③ 刪資料目錄。三個目錄分別是配置與任務台帳、身份憑據、受保護的根目錄，三個都刪掉才算清乾淨。刪了就要重新配對：

④ 刪程式本體：

~/.bashrc 裡那行 PATH 可以留著（Node 也在那個目錄裡）。Node 和各家 Runtime 是你自己裝的：按本頁裝的 Node 在 ~/.local 下，不要了就刪掉 ~/.local/bin/node、~/.local/bin/npm、~/.local/bin/npx 和 ~/.local/lib/node_modules。