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。