Rnix 快速上手指南

本指南帮助你在 15 分钟内完成 Rnix 的安装和首次运行，体验 AI 智能体操作系统的核心功能。

前置条件

Go 环境

确认已安装 Go 1.26 或更高版本：

bash

$ go version
go version go1.26.0 linux/amd64

如果未安装，请前往 Go 官方下载页面安装。

LLM 提供商

Rnix 支持多种 LLM 提供商，至少需要一个：

Claude Code CLI — npm install -g @anthropic-ai/claude-code
Cursor CLI — 需要设置 CURSOR_API_KEY 环境变量
OpenAI 兼容 API（Ollama、Groq、DeepSeek 等）— 运行 rnix init 后在 ~/.config/rnix/providers.yaml 中配置

安装 Rnix

使用 go install 一键安装：

bash

go install github.com/rnixai/rnix/cmd/rnix@latest

验证安装成功：

bash

$ rnix version
rnix v0.1.0
commit:  cd9c568
built:   2026-03-29T07:23:57Z

初始化配置

首次使用前，运行 rnix init 创建配置环境：

bash

$ rnix init
[init] created ~/.config/rnix/
[init] created .rnix/

这会创建全局配置目录 ~/.config/rnix/（包含 providers.yaml、agents/、skills/）和项目级配置目录 .rnix/。

首次运行

最简用法

向 Rnix 传递一个意图字符串，即可 Spawn 一个智能体进程来完成任务：

bash

$ rnix -i "分析 ./README.md"

首次运行时，Rnix 会自动启动一个后台 daemon 进程来管理内核和进程表。daemon 通过 Unix domain socket 与 CLI 通信，空闲 60 秒后自动退出。你也可以通过 rnix daemon status 查看状态，或 rnix daemon stop 手动停止。

你将看到类似以下的输出：

[kernel] spawning PID 1 (claude/haiku)...
[agent/1] reasoning step 1...
[agent/1] reasoning step 2...
══ Result ══════════════════════════════════════════════════════════════════════
  ## README.md 分析

  该文件是 Rnix 项目的入口说明文档，包含项目简介、安装方式和基本用法。
  结构清晰，涵盖了新用户上手所需的关键信息...
════════════════════════════════════════════════════════════════════════════════
[kernel] PID 1 exited(0) | claude/haiku | tokens: 1024 | elapsed: 5.3s

解读输出

输出行	含义
`[kernel] spawning PID 1 (claude/haiku)...`	内核正在创建智能体进程，分配 PID 1，使用 claude 提供商的 haiku 模型
`[agent/1] reasoning step 1...`	PID 1 的智能体正在执行第 1 步推理
`══ Result ══...`	双线边框内是智能体的最终输出结果
`[kernel] PID 1 exited(0)`	进程正常退出（退出码 0）
`claude/haiku`	使用的 provider/model
`tokens: 1024`	本次执行消耗的 token 数量
`elapsed: 5.3s`	总耗时

使用 Agent

Agent 定义了智能体的身份和角色。通过 --agent 参数可以使用预定义的 Agent：

bash

$ rnix -i "分析 ./cmd/rnix/main.go" --agent=code-analyst

code-analyst 是 Rnix 内置的参考 Agent，专门用于分析代码质量、识别潜在问题并提供改进建议。它引用了 code-analysis Skill，拥有访问文件系统（/dev/fs）和 Shell（/dev/shell）的权限。

选择 LLM 提供商

默认使用 Claude Code CLI（/dev/llm/claude）。通过 --provider flag 切换到 Cursor CLI：

bash

$ rnix -i "分析代码" --provider=cursor

# 或配合 --agent 使用
$ rnix -i "分析代码" --agent=code-analyst --provider=cursor

也可以在 Agent 定义中指定默认 provider（agents/*/agent.yaml）：

yaml

models:
  provider: cursor
  preferred: gpt-4

优先级：--provider CLI flag > agent.yaml models.provider > 默认 claude

你将看到类似以下的输出：

[kernel] spawning PID 1 (claude/haiku)...
[agent/1] reasoning step 1...
[agent/1] reasoning step 2...
[agent/1] reasoning step 3...
══ Result ══════════════════════════════════════════════════════════════════════
  ## 代码分析报告: cmd/rnix/main.go

  ### 总体评价
  该文件是 Rnix CLI 的入口点，结构清晰，职责明确...

  ### 发现
  - **Info** — 全局变量较多，可考虑封装到结构体中
  - **Info** — 建议为 runRoot 添加更多错误分类处理
════════════════════════════════════════════════════════════════════════════════
[kernel] PID 1 exited(0) | claude/haiku | tokens: 2340 | elapsed: 12.5s

💡 想了解 Agent 和 Skill 的设计原理？请参阅核心概念文档中的"Agent 与 Skill"章节。

strace 调试体验

strace（Agent Strace）是 Rnix 的调试工具，类似 Unix 的 strace，可以实时查看智能体进程的每一步系统调用（Syscall），帮助你理解智能体的完整执行过程。

得益于 daemon 架构，strace 支持跨终端操作——你可以在任意终端追踪任意正在运行的进程，无需在启动进程的终端中操作。

使用方法

在一个终端启动一个智能体任务：

bash

# 终端 A
$ rnix -i "分析当前项目结构并给出建议"

打开另一个终端，用 rnix ps 找到正在运行的进程 PID，然后 attach：

bash

# 终端 B
$ rnix strace 1

预期输出

[strace] attached to PID 1 (state: running)
[  0.013s] Open(flags=2, path="/dev/llm/claude") → 3    1ms  ← LLM 调用
[  0.014s] Write(fd=3, size=1234) → <nil>    5.20s  ← 慢操作
[  5.214s] Read(fd=3, length=1048576) → 892    2ms
[  5.216s] Open(flags=2, path="/dev/fs/./README.md") → 4    1ms
[  5.217s] Write(fd=4, size=56) → <nil>    0µs
[  5.217s] Read(fd=4, length=1048576) → 2048    1ms
[  5.218s] Close(fd=4) → <nil>    0µs
[  5.218s] Write(fd=3, size=3456) → <nil>    3.10s  ← 慢操作
[  8.318s] Read(fd=3, length=1048576) → 1024    2ms
[  8.320s] Close(fd=3) → <nil>    0µs
[strace] detached from PID 1 (process exited)

解读关键 Syscall

Syscall 行	含义
`Open(path="/dev/llm/claude")`	打开 LLM 推理设备
`Write(fd=3, size=1234)`	向 LLM 发送推理请求（1234 字节）
`Read(fd=3, ...)`	读取 LLM 响应
`Open(path="/dev/fs/./README.md")`	智能体请求读取文件（工具调用）
`Close(fd=4)`	关闭文件设备
`← LLM 调用`	标注涉及 `/dev/llm/` 设备的操作
`← 慢操作`	标注耗时超过 1 秒的操作（通常是 LLM 推理）

💡 <nil> 表示操作成功且无返回值（类似其他语言中的 null 或 void）。

按 Ctrl+C 可随时脱离 strace，不会影响被追踪的进程。

进程管理

Rnix 的进程在系统级别可见——与 Unix 进程一样，你可以在任意终端查看和管理所有正在运行的智能体进程，无论它们是从哪个终端启动的。

查看进程列表

bash

$ rnix ps

输出示例：

  PID   STATE     SKILL              TOKENS   ELAPSED
─────   ─────────   ───────────────   ────────   ────────
    1   running   code-analysis        456      3.2s
    2   zombie    —                    123      1.1s

1 active, 1 zombie, 2 total

使用 --json 获取 JSON 格式输出，方便脚本处理：

bash

$ rnix ps --json

输出示例：

json

{
  "ok": true,
  "data": {
    "processes": [
      {
        "pid": 1,
        "ppid": 0,
        "state": "running",
        "intent": "分析 ./README.md",
        "skills": ["code-analysis"],
        "tokens_used": 456,
        "elapsed_ms": 3200
      }
    ]
  }
}

终止进程

你可以从任意终端终止正在运行的进程：

bash

$ rnix kill 1
[kernel] PID 1: signal sent (SIGTERM)

如果没有任何 rnix 实例运行（daemon 未启动），rnix ps 会输出 "No active processes."，rnix kill 会输出标准错误提示——不会崩溃或报连接错误。

常见问题

Daemon 无法启动

如果 rnix ps 显示连接错误，daemon 可能卡住。强制重启：

bash

$ rnix daemon stop
$ rnix ps  # daemon 会在下次命令时自动重启

LLM 命令未找到

如果看到 exec: "claude": executable file not found，需要安装 Claude Code CLI：

bash

npm install -g @anthropic-ai/claude-code

/dev/shell 权限被拒绝

Skill 必须在 allowed-tools 中声明 shell 权限。检查 SKILL.md frontmatter 包含：

yaml

allowed-tools: /dev/fs /dev/shell

超时错误

LLM 调用在配置的 TimeoutMs 后超时。可通过 --max-steps 调整，或检查到 LLM 提供商的网络连接。

下一步

恭喜！你已经体验了 Rnix 的核心功能。以下资源帮助你进一步探索：

核心概念文档 — 深入理解进程、VFS、Syscall、Agent 与 Skill 的设计哲学
参考手册 — 完整的 CLI 命令参考、Syscall 签名和 Manifest 字段说明
Agent 和 Skill 扩展 — 创建自定义 Agent（~/.config/rnix/agents/ 或 .rnix/agents/）和 Skill（~/.config/rnix/skills/ 或 .rnix/skills/），扩展 Rnix 的能力边界

实战教程

想要手把手学习 Rnix 开发？查看教程目录：

编写第一个 Skill — 创建 Skill、Agent 并运行（~20 分钟）
调试第一个 bug — 使用 strace 定位和修复问题（~15 分钟）
组合多智能体工作流 — 用 Compose 编排多智能体协作（~25 分钟）

Rnix 快速上手指南 ​

前置条件 ​

Go 环境 ​

LLM 提供商 ​

安装 Rnix ​

初始化配置 ​

首次运行 ​

最简用法 ​

解读输出 ​

使用 Agent ​

选择 LLM 提供商 ​

strace 调试体验 ​

使用方法 ​

预期输出 ​

解读关键 Syscall ​

进程管理 ​

查看进程列表 ​

终止进程 ​

常见问题 ​

Daemon 无法启动 ​

LLM 命令未找到 ​

/dev/shell 权限被拒绝 ​

超时错误 ​

下一步 ​

实战教程 ​

Rnix 快速上手指南

前置条件

Go 环境

LLM 提供商

安装 Rnix

初始化配置

首次运行

最简用法

解读输出

使用 Agent

选择 LLM 提供商

strace 调试体验

使用方法

预期输出

解读关键 Syscall

进程管理

查看进程列表

终止进程

常见问题

Daemon 无法启动

LLM 命令未找到

/dev/shell 权限被拒绝

超时错误

下一步

实战教程