
easy-agent
终端里的可控编码助手,权限沙箱齐全,代码好读好改
项目预览
项目数据
项目介绍
Star 增长趋势
本站每日记录该项目 GitHub 星标变化,观测越久曲线越完整
数据来源:GitHub API 逐日快照 · 收录于 2026-10-04 · 当前星标 ★ 1031
使用教程
环境要求
- Node.js 22 或更高版本
- npm 包管理器
- 至少一个受支持模型提供商的凭据(Anthropic / OpenAI 兼容 / Gemini / 本地模型)
- 可选:macOS 或 Linux 环境可使用官方安装脚本(脚本本身不安装 Node.js)
安装与启动步骤
-
1全局安装 eagent
通过 npm 全局安装 eagent 包,--ignore-scripts 会跳过包的生命周期脚本,安装后同时提供 eagent 和 easy-agent 两个命令。
npm install -g --ignore-scripts eagent -
2确认安装成功
运行版本命令,能打印出版本号说明可执行文件已进入 PATH;若提示找不到命令,检查 npm 全局 bin 目录是否在 PATH 中。
eagent --version -
3临时免安装试用
不想全局安装时可用 npx 直接拉取最新版本运行,适合快速体验;正式使用仍建议全局安装。
npx --yes eagent@latest -
4或用官方安装脚本
macOS/Linux 上可执行安装脚本,它会检查 Node.js、以 --ignore-scripts 方式安装同一个 npm 包并验证 eagent 是否在 PATH 上。
curl -fsSL https://raw.githubusercontent.com/ConardLi/easy-agent/main/install.sh | sh -
5设置模型凭据
使用原生 Anthropic 模型时只需设置环境变量即可,token 替换为你自己的真实凭据;可选再用 ANTHROPIC_MODEL 指定默认模型名。
export ANTHROPIC_AUTH_TOKEN="your-token" export ANTHROPIC_MODEL="claude-sonnet-4-20250514" -
6进入项目并启动
切换到你的代码仓库目录后直接运行 eagent 进入交互式 REPL;首次在该目录使用时会询问是否信任此文件夹,信任后才应用项目级配置。
cd your-project eagent -
7命令行无头调用
把任务作为 prompt 传入即可无头执行,适合放进 CI 或 shell 脚本;加 --output-format json 可输出机器可读结果,也可用管道传入内容。
eagent -p "summarize this repo" --output-format json git diff | eagent -p "review this patch" -
8配置多模型档案
在 settings.json 中定义命名模型档案,支持 openai-chat、gemini 等协议与本地模型地址,之后用 --model 或 REPL 内 /model 切换。
{ "defaultModel": "gpt", "models": { "gpt": { "protocol": "openai-chat", "model": "gpt-5.1", "baseURL": "https://api.openai.com/v1", "apiKey": "${OPENAI_API_KEY}" }, "gemini": { "protocol": "gemini", "model": "gemini-2.5-pro", "apiKey": "${GEMINI_API_KEY}" }, "ollama": { "protocol": "openai-chat", "model": "qwen2.5-coder", "baseURL": "http://localhost:11434/v1" } } }
关键配置
| 配置项 | 必填 | 说明 | 示例 |
|---|---|---|---|
ANTHROPIC_AUTH_TOKEN | 是 | Anthropic API token 或兼容网关 token,使用原生 Anthropic 模型时必需 | your-token |
ANTHROPIC_MODEL | 否 | 原生 Anthropic 的默认模型名 | claude-sonnet-4-20250514 |
defaultModel | 否 | settings.json 中默认使用的模型档案名 | gpt |
models.<name>.protocol | 是 | 模型协议类型,如 openai-chat 或 gemini | openai-chat |
models.<name>.baseURL | 否 | 兼容接口或本地模型的服务地址 | http://localhost:11434/v1 |
models.<name>.apiKey | 否 | 该档案的密钥,可引用环境变量占位符 | ${OPENAI_API_KEY} |
如何确认成功
运行 eagent --version 能打印版本号;进入 REPL 后执行 /doctor 和 /config list 可检查配置与运行时健康状态。
常见问题
Q:第一次在某个目录运行 eagent 时提示是否信任文件夹,会影响什么?
A:只有信任该目录后,项目级与本地级 settings.json(以及项目 .env)才会被应用;未信任时不会读取这些项目配置。
Q:配置文件优先级是怎么排的?
A:从低到高依次是:用户级 ~/.easy-agent/settings.json、项目级 settings.json、本地 settings.local.json、命令行参数,最高为托管策略文件。项目 .env 在项目与本地设置之后生效。
Q:如何临时切换模型而不用改默认配置?
A:启动时用 eagent --model gpt 指定档案,或进入 REPL 后用 /model gpt 切换;原生 Anthropic 模型也可直接用 ANTHROPIC_MODEL 环境变量。
Q:卸载后我的配置和会话会丢吗?
A:不会。npm uninstall -g eagent 只会移除包本身,~/.easy-agent/ 下的用户配置与会话会被有意保留。
Q:支持本地模型吗?
A:支持。在 settings.json 里以 openai-chat 协议新增一个档案,把 baseURL 指向本地服务(例如 http://localhost:11434/v1)即可。
注意事项
- 安装命令带有 --ignore-scripts,不会执行包的安装脚本,属于项目有意设计的安全行为。
- 凭据建议通过环境变量注入,配置里可用 ${OPENAI_API_KEY} 这类占位符引用,不要在 settings.json 中硬编码明文密钥。
- 在 REPL 中可用 Ctrl+D 退出,输入 /help 查看全部命令与快捷键。
- 除 Anthropic 外还支持 OpenAI 兼容接口、Gemini 与本地模型,模型层不绑定单一厂商。
核心亮点
- 分层可读的代码结构,便于二次开发和定制
- 权限规则加 OS 沙箱双重防护,执行命令更安全可控
- 模型无关,支持 Anthropic、OpenAI 兼容、Gemini 与本地模型
不足之处
- 项目处于成长期,生态与插件数量相对有限
- 文档与社区案例仍在完善,上手深度定制需读源码
适用场景
- 在终端中让 Agent 自动读写代码、跑测试并提交修改
- 团队基于它定制内部编码助手,接入私有模型和内部工具
- 需要严格权限与沙箱隔离的受控开发环境
替代项目
OpenHands、Aider、Cline
同类项目推荐
dyad
开源
本地运行,用对话打造全栈应用,数据不出门
Local, open-source AI app builder for power users ✨ v0 / Lovable / Replit / Bolt al···
tlm
开源
在终端里用本地大模型,随时提问,数据不出本机。
Local CLI Copilot, powered by Ollama.
yume
开源
给 Claude Code 套上原生桌面壳,看得见的 AI 编码流
Native desktop UI for Claude Code with orchestration, streaming, background agents, ···
Waza
开源
把工程习惯变成 AI 能直接执行的技能
Engineering habits you already know, turned into skills AI assistants like Claude Co···
dora
开源
让 AI 代理像专家一样快速定位代码,告别低效 grep。
CLI built for AI agents to help navigate codebases better. An alternative to grep/fi···
cc-switch
开源
一个桌面窗口,统管所有 AI 编程代理,随切随用
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode,DeepS···
cmux
开源
垂直标签+通知,让多个AI编程代理并行不打架
Open source Ghostty-based macOS terminal with vertical tabs and notifications for AI···
ryugi
开源
给编码代理配技能包和可视化工作台
Ryugi (ryoo-ghee) — artifacts for coding agents: artboards of mockups, design docs,···
replica-skill
开源
逆向拆解竞品,自动重建并修 bug,克隆应用一条龙
Eleven free Claude skills that clone any app: reverse-engineer it, rebuild it, test ···