Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

第四章：安装与初始化——五分钟让 Ralph 就位

📌 本章李明轩在做什么：在前面"主角故事"那一篇里，他决定把 Ralph 引入自己的自媒体工作流。这一章，我们陪他——也陪你——把 Ralph 装到电脑上。

准备工作

在安装 Ralph 之前，先确认你有以下前提条件：

操作系统要求

Ralph 目前支持：

  • macOS（推荐）
  • Linux（完全支持）
  • Windows with WSL2（通过 Windows 子系统运行）

Windows 用户注意：Ralph 需要 Unix 系统调用，不能在原生 Windows 上运行。你需要先安装 WSL2（Windows Subsystem for Linux 2），然后在 WSL2 环境里安装 Ralph。微软的官方文档有详细的 WSL2 安装指南。

需要预先安装的工具

1. 一个 AI 后端（二选一或多选）

最简单的选择是 Claude Code（Anthropic 的 CLI 工具）：

# 安装 Node.js（如果还没有）：去 nodejs.org 下载安装包

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 验证安装（会要求你登录 Anthropic 账户）
claude --version

或者使用 Kiro（速度更快，需要 AWS 账户）：

# 前往 kiro.dev 按照指引安装

本书后续的示例默认使用 Claude Code 作为后端。

2. Git（大多数 Mac/Linux 系统已预装）：

git --version
# 如果没有，macOS 用户：xcode-select --install
# Ubuntu/Debian：sudo apt-get install git

安装 Ralph

Ralph 提供三种安装方式，任选其一：

方式一：通过 npm 安装（推荐）

npm install -g @ralph-orchestrator/ralph-cli

安装完成后验证：

ralph --version
# 应该输出类似：ralph 2.9.x

方式二：通过 Cargo 安装（适合 Rust 用户）

如果你的电脑安装了 Rust 工具链：

cargo install ralph-cli

方式三：下载预编译二进制（最快）

前往 GitHub Releases 页面，下载适合你系统的二进制文件，解压后放到 PATH 路径里。

# 解压后
chmod +x ralph
sudo mv ralph /usr/local/bin/

运行健康检查

安装完成后，先运行 Ralph 的诊断命令，确保环境配置正确：

ralph doctor

这个命令会检查：

  • Ralph 是否正确安装
  • AI 后端（如 Claude Code）是否可以调用
  • 当前目录是否是 Git 仓库

示例输出（一切正常时）：

Doctor checks for ralph.yml

  OK   config         Configuration valid
  OK   hats           No custom hats configured (solo mode)
  OK   backend:claude claude CLI available (claude)
  OK   hooks          Hooks disabled (skipping)
  OK   telegram       RObot disabled (skipping)
  OK   git            Git repository detected
  OK   paths          Workspace paths accessible
  OK   tools          Required tools available (git)
  OK   specs          No spec files found (skipping)

Result: PASS

只需看最后一行 Result: PASS/FAIL 就知道结论；上方 WARN/FAIL 行会告诉你具体哪一项需要处理。如果看到 FAIL，按提示修复再继续下一步。

在项目里初始化 Ralph

进入你想要用 Ralph 管理的项目目录（如果是新项目，先创建一个目录）：

# 新项目
mkdir my-awesome-project
cd my-awesome-project
git init

# 或者进入已有的项目
cd /path/to/your/project

然后运行初始化命令：

ralph init --backend claude

这个命令只做一件事：在当前目录生成默认的 ralph.yml 配置文件。

your-project/
└── ralph.yml                  ← Ralph 配置文件

📖 名词解释 · YAML

YAML（发音 /ˈjæməl/）是一种给人类读写的配置文件格式，用缩进表达层级，不需要大括号和引号。比 JSON 更适合写配置（更易读、能写注释），Ralph 的 ralph.yml、帽子配置（第六章会讲）都用 YAML。

阅读技巧：看到冒号就是"键 = 值"，看到减号开头就是列表项，缩进表示"属于上一层"。

进一步学习：维基百科：YAML

其它 Ralph 工作目录（.ralph/agent/memories.md、.ralph/agent/tasks.jsonl、.ralph/events-*.jsonl 等）不会立即生成，而是在第一次运行 ralph run 或 ralph tools memory add 等命令时按需自动创建。如果你希望把 Ralph 的工作状态从 Git 仓库里排除，可以手动在 .gitignore 里加一行 .ralph/。

了解默认配置文件

打开生成的 ralph.yml，你会看到类似这样的内容：

# Ralph Orchestrator Configuration
# Generated by: ralph init --backend claude

cli:
  backend: "claude"                    # AI 后端选择

event_loop:
  prompt_file: "PROMPT.md"             # 默认提示词文件
  completion_promise: "LOOP_COMPLETE"  # 循环结束信号
  max_iterations: 100                  # 最多迭代次数
  # max_runtime_seconds: 14400         # 最长运行时间（秒），默认 4 小时

文件末尾还有一段被注释掉的可选配置（core.scratchpad、core.specs_dir、自定义帽子示例等），需要时再解开注释修改。

现阶段你不需要修改这个文件。我们会在第十四章详细介绍每个配置项的含义和用法。

使用预设（Preset）快速开始

Ralph 内置了多个预设工作流（Presets），这些是专家配置好的帽子组合，开箱即用：

预设名称适用场景
code-assist从任务描述或规格文档实现代码功能
pdd-to-code-assist从模糊想法出发，经过设计到代码的完整流程
review代码审查工作流
debug调试工作流
research自动研究某个主题
autoresearch更深度的自动研究

要使用预设，推荐用 -H builtin:<预设名>（-H 是 --hats 的缩写），Ralph 会从安装包自带的内置预设中直接加载：

# 使用内置的代码辅助预设
ralph run -H builtin:code-assist --prompt "添加用户登录功能"

如果你想对内置预设做定制（例如修改某个帽子的指令），可以先把上游仓库 https://github.com/mikeyobrien/ralph-orchestrator/tree/main/presets 里对应的 .yml 文件下载到本地（例如放到 presets/ 目录），然后用 -H 指向这个本地副本（-H 既接受 builtin:<name>，也接受本地文件路径或 URL）：

ralph run -H presets/code-assist.yml --prompt "添加用户登录功能"

这种"下载-改-指路径"的做法适合团队沉淀自己的标准流程；新手入门时用 -H builtin:xxx 即可。

注意：旧版本里曾经流行 ralph run --config presets/code-assist.yml 这种用 --config 加载预设的写法，新版本里 --config / -c 只用于加载主配置（如 ralph.yml），预设统一走 -H。如果你看到老教程仍是 --config，请改成 -H。

注意：旧版的 ralph init --preset 写法已经移除，请使用上面任一种方式在 ralph run 时指定预设。

设置你的第一个别名（可选但推荐）

为了日常使用方便，你可以在 shell 配置文件里添加一些别名：

# 在 ~/.bashrc 或 ~/.zshrc 里添加：

# 快速运行代码辅助
alias rchat='ralph run -H ~/.ralph/presets/code-assist.yml'

# 快速规划功能
alias rplan='ralph plan'

# 查看循环状态
alias rls='ralph loops'

验证安装

让我们用一个极简的测试确认 Ralph 工作正常：

# 进入一个有 git 的目录
cd /tmp && mkdir ralph-test && cd ralph-test && git init

# 初始化 Ralph
ralph init --backend claude

# 运行 preflight 检查
ralph preflight

如果 preflight 输出没有错误，说明 Ralph 已经完全就绪。

常见安装问题

问：运行 ralph 提示"command not found"

检查 npm 的全局安装路径是否在你的 PATH 里：

npm config get prefix
# 如果输出 /home/user/.npm-global，确保 /home/user/.npm-global/bin 在 PATH 里

问：ralph doctor 提示 claude 后端不可用

确保 Claude Code 已经安装并登录：

claude --version
claude login  # 如果没有登录

问：在 macOS 上提示权限问题

sudo npm install -g @ralph-orchestrator/ralph-cli

或者先配置 npm 不需要 sudo 的全局安装路径（推荐）。

本章小结

  • Ralph 支持 macOS、Linux 和 WSL2（Windows）
  • 通过 npm、Cargo 或二进制包安装
  • ralph init 在项目里创建工作空间和配置文件
  • 内置多个预设工作流，开箱即用
  • 遇到问题先运行 ralph doctor 诊断

下一章，我们陪李明轩跑通他的第一个 Ralph 任务——让 AI 写出"明轩说"工具箱的第一个命令。你也会亲身感受一次"让 AI 自己跑完"的体验。