ralph-claude-code

让 Claude Code 自动干活，干完就停，不空转。

ralph-claude-code 是一个为 Claude Code 设计的自主 AI 开发循环工具，它通过智能退出检测机制，让 AI 能在完成开发任务后自动停止，避免无限循环。该项目解决了 AI 编程助手在复杂任务中容易陷入重复或过度执行的问题，核心能力包括：自动检测任务完成状态、控制 AI 的执行循环、支持与 Claude Code CLI 无缝集成。它用 Shell 脚本实现，轻量且易于部署，适合希望提升 AI 编码效率的开发者。

开源 free 智能体

访问官网 ↗ GitHub ↗ 文档 ↗

GitHub 星标 ★ 9643

维护状态活跃

是否开源是

定价模式 free

项目数据

分类智能体

开发团队frankbria

所属国家

官网地址

GitHubhttps://github.com/frankbria/ralph-claude-code

定价模式free

价格说明MIT 许可证开源，完全免费，无付费版本。

访问状态

是否开源是

开源协议MIT

主要语言Shell

技术栈/模型ai,ai-agent,ai-agents,ai-development,ai-development-tools,claude-code,claude-code-cli,development-tools,development-workflow

GitHub 星标★ 9643

30天Star增速

HF 下载量

上线时间2025-08-27 00:00:00

最近更新2026-09-22 00:00:00

维护状态活跃

中文支持

访问方式

移动端支持

综合评分

收录时间2026-08-09

浏览次数3

使用教程

难度：入门约 10 分钟部署方式：命令行工具 8 步

环境要求

Git（用于克隆仓库）
Shell 环境（macOS / Linux / WSL 等可执行 bash 的系统）
使用 --monitor 需先安装 tmux
macOS 需安装 GNU coreutils（提供 gtimeout）
已安装并可用的 Claude Code CLI
可选：Docker（仅使用 Docker 沙箱时需要）；Python/pip（仅使用 E2B 沙箱时需要）

安装与启动步骤

1克隆仓库

把 ralph-claude-code 源码克隆到本地并进入目录，这是安装前的准备动作。
```
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
```
2全局安装 Ralph

运行安装脚本，把 ralph、ralph-setup、ralph-enable 等命令加入 PATH，全系统只需执行一次。
```
./install.sh
```
3初始化项目

进入你的项目目录，用 ralph-setup 创建 Ralph 项目骨架；之后可用 ralph-enable 与 ralph-import 导入 PRD。
```
cd /your/project
ralph-setup my-project
ralph-enable
ralph-import prd.md
```
4运行开发循环

在任意已初始化项目中执行，推荐配合 tmux 集成监控，实时查看循环与用量。
```
ralph --monitor
```
5构建 Docker 沙箱

可选。在源码目录构建镜像，让 Claude 在隔离容器内改文件，Ralph 循环仍跑在宿主机。
```
docker build -t ralph-sandbox .
```
6使用 Docker 沙箱

可选。指定镜像、内存、CPU 与网络；项目目录以读写方式挂载到 /workspace。
```
ralph --sandbox docker --sandbox-image node:20 --sandbox-memory 8g --sandbox-cpus 4
```
7配置 E2B 沙箱

可选。安装 E2B Python SDK 并设置 API Key，即可用云端沙箱执行。
```
pip install e2b
export E2B_API_KEY="e2b_xxxxxxxx"
```
8macOS 补齐 coreutils

macOS 缺少 timeout，安装 GNU coreutils 后 Ralph 会自动改用 gtimeout，无需额外配置。
```
brew install coreutils
gtimeout --version
```

关键配置

配置项	必填	说明	示例
`PROJECT_NAME`	否	Ralph 项目名称，写入项目根目录的 .ralphrc	`PROJECT_NAME="my-project"`
`PROJECT_TYPE`	否	项目类型，用于让 Claude 理解技术栈	`PROJECT_TYPE="typescript"`
`MAX_CALLS_PER_HOUR`	否	每小时最大 Claude 调用次数，默认 100，每小时重置	`100`
`MAX_TOKENS_PER_HOUR`	否	每小时累计 token 上限，默认 0 表示禁用	`0`
`SANDBOX_PROVIDER`	否	沙箱提供方，可在 .ralphrc 中设置（CLI 参数优先）	`docker`
`SANDBOX_DOCKER_IMAGE`	否	沙箱使用的 Docker 镜像，需镜像内可调用 claude	`node:20`

如何确认成功

安装后新开终端执行 ralph --status，能显示本小时已用的调用次数与 token 数即表示可用。

常见问题

Q：如何避免 Claude 无限循环或超额调用 API？

A：Ralph 内置双条件退出闸门（完成指标 + 显式 EXIT_SIGNAL）、按小时重置的速率限制与断路器。可用 ralph --status 查看本小时调用与 token 用量。

Q：调用次数限制怎么调？token 限制为什么默认是 0？

A：两者均每小时重置。MAX_CALLS_PER_HOUR 默认 100；MAX_TOKENS_PER_HOUR 默认 0（禁用）。单次调用可能消耗 10 万以上 token，需要控成本时再开启它。

Q：macOS 上提示找不到 timeout 命令怎么办？

A：安装 GNU coreutils：brew install coreutils。Ralph 会自动检测并使用 gtimeout，装好后无需任何额外配置。

Q：如何完全卸载 Ralph？

A：在仓库中执行 ./uninstall.sh（或 ./install.sh uninstall）；若已删除仓库，可运行 curl -sL https://raw.githubusercontent.com/frankbria/ralph-claude-code/main/uninstall.sh | bash。

Q：--sandbox-network none 会有什么影响？

A：该参数实现完全网络隔离，会同时阻断 Claude API，仅适用于镜像自带鉴权或代理的场景，否则 Claude 无法工作。

注意事项

安装是全局一次性动作，之后可在任意目录直接使用 ralph 等命令。
安装完成后可以删除克隆下来的仓库，不影响使用。
执行 npm install 与 npm test 可跑测试（需先 npm install -g bats bats-support bats-assert）。
沙箱只隔离 Claude 的执行，Ralph 的循环、限流与监控仍在宿主机上运行。

核心亮点

智能退出检测：精准识别任务完成点，避免 AI 无限循环，节省时间和 token。
无缝集成：直接与 Claude Code CLI 配合，安装简单，不改变原有工作流。
轻量级：纯 Shell 实现，依赖少，易于定制和扩展。

不足之处

功能相对单一，仅聚焦于循环控制，不提供任务规划或代码审查等高级功能。
文档/社区待观察：项目较新，社区资源和最佳实践尚不丰富。

适用场景

自动化代码生成：让 AI 自主完成整个功能模块的开发，无需人工干预。
批量任务处理：对多个小任务进行连续自动化处理，提升效率。
CI/CD 集成：在持续集成流程中，用 AI 自动修复或生成代码。

替代项目

Claude Code、Aider、OpenHands

项目介绍

ralph-claude-code 是智能体领域的开源项目，由 frankbria 开发，2025 年首次发布。

在全站 13,014 个收录项目中，它的 GitHub 星标数（9,643）位列前 6%，在智能体分类的 2,499 个项目里位列前 6%。

近 44 天，它的 GitHub 星标从 9,596 增加到 9,643，净增 47。

项目目前处于活跃维护状态，最近一次代码更新于 2026-09-22。MIT 许可证开源，完全免费，无付费版本。

它主要面向的使用场景是：自动化代码生成：让AI自主完成整个功能模块的开发，无需人工干预。同类可对比的替代方案包括 Claude Code、Aider、OpenHands。

上一篇：hermes-studio

下一篇：Bindu