Agent-cli（gcli）

终端里的自主 AI 编码助理：一句话让它读改文件、执行命令、搜代码、多步推理，自己把任务做完——构建在 AgentOS 微内核之上（进程化 Agent、计量上下文、快照/回放、会话持久化），配一层尽可能强的终端 UX。支持任意 OpenAI /Anthropic 兼容 /v1 端点（Guangnao / OpenAI / Anthropic / Gemini / DeepSeek / 自建网关等）。

npm i -g @guangnao/agent-cli
gcli

装好直接敲 gcli，首次运行会弹引导帮你选端点 / 填 Key / 选模型，然后就能用。

安装

npm i -g @guangnao/agent-cli      # 全局安装，得到 gcli 命令（别名 agent-cli）

要求 Node ≥ 20.12。零运行时依赖（内核与 UI 已全部打包进单文件），安装很快。

🪟 Windows 建议用 Windows Terminal（或 VSCode 内置终端）—— 它字体全、真彩色 + 真 emoji，观感与 macOS 一致。传统 cmd.exe / PowerShell 旧窗口(conhost)字体有限,gcli 会自动降级字形(彩色 emoji→ASCII、⏺→● 等)保证不糊、不错位,但精致程度不如现代终端。装 Windows Terminal 后用它打开再跑 gcli 即可。

快速开始

方式一：首启引导（推荐） —— 直接运行，按提示选即可：

gcli
# → 选服务商（Guangnao / Claude·订阅 / Codex·订阅 / DeepSeek / OpenAI / Anthropic / Gemini / Custom）
#   普通服务商：贴 Key → 自动列模型并选 → 进入交互
#   订阅直连：选 Claude·订阅 / Codex·订阅 → 复用本机 CLI 登录、零 Key → 直接进入

🆕 订阅直连（零 API key） —— 选 「Claude · 订阅 (claude CLI)」 或 「Codex · 订阅 (codex CLI)」：复用你本机 claude / codex CLI 的既有登录，gcli 在进程内拉起 代理读其订阅凭证、字节级转发（Claude 走原生 /v1/messages，保留原生 tool_use），无需任何 API key，选完直接可用。 前提：本机已用 claude（或设 CLAUDE_CODE_OAUTH_TOKEN）/ codex login 登录过；模型从真实订阅目录自动挑，随后可用 /models 切换。

选 Custom 可接任意自建端点：先选协议（OpenAI 兼容 / Anthropic 兼容）→ 填 baseURL + Key + 模型即可。

配置存到 ~/.agentos/config.json，下次直接进，无需重填。

方式二：环境变量 —— 适合脚本 / CI / 固定配置（环境变量优先于已保存配置）：

# 任意 OpenAI 兼容端点：
export LLM_PROVIDER="openai"                       # 服务商 id
export LLM_BASE_URL="https://api.openai.com/v1"    # 任意 OpenAI 兼容 /v1 端点
export LLM_API_KEY="sk-..."                         # API Key
export LLM_MODEL="<模型名>"                          # 可选，默认按服务商自动选
gcli

也认各服务商专属 Key（任填其一即可）：GAPI_API_KEY（Guangnao）·DEEPSEEK_API_KEY·OPENAI_API_KEY·ANTHROPIC_API_KEY·GEMINI_API_KEY。其它可选：LLM_CHEAP_MODEL（子代理 / 廉价档模型）。

Guangnao·Gmodel 端点一把 Key 通所有模型（api.guangnao.com，推荐）。

用法

gcli                          # 交互式常驻：像结对一样持续对话
gcli "给这个项目补单元测试"      # 一次性跑完该任务后打印结果退出
gcli version                  # 显示版本（亦可 -v / --version）

交互态里直接说需求即可——它会读代码、搜仓库、改文件、跑测试验证，一步步把事做完。改文件 / 执行命令默认弹审批，看彩色 diff 再放行。 它还会读项目里的 CLAUDE.md / AGENTS.md 与 package.json 脚本，按本项目约定写代码、用对的命令做校验。

会话内斜杠命令

交互态输入 / 会弹出可上下选择的命令菜单。完整清单：

| 命令 | 作用 | |---|---| | /help | 全部命令与快捷键 | | /mode <arg> | 权限模式：confirm（逐项确认）/ auto-edits（自动改文件）/ auto（全自动） | | /new | 开新会话 | | /sessions /resume <id> | 选历史会话恢复接着聊 | | /clear | 清屏（历史保留） | | /models | 上下选 / 切换服务商与模型 | | /login | 重新连接 / 换服务商（重跑引导，含 Claude·订阅 / Codex·订阅 直连） | | /config <arg> | 配置重置——清除已保存的 Key 并退出 | | /theme | 切主题强调色 | | /notify | 开关「失焦时任务完成」提醒 | | /verbose | 切换工具展示繁简：默认所有工具都显示但折叠成一行；静默模式再隐藏「读取」与「成功命令」 | | /voice | 语音输入（或按 F5）：录音 → 转写 → 落进输入框 | | /skills | 查看可复用技能包（Skills） | | /personas /specialize <域> | 切专家人格 / 从记忆里铸一个领域人格 | | /memory | 查看蒸馏出的项目长期经验 | | /forget [N\|all] | 纠错:删掉一条错的/过时的长期教训(不再被召回);无参列出、N 删第 N 条、all 清空 | | /cwd <path> | 切本会话工作目录（-g 设全局默认） | | /expand <id> | 展开被折叠的工具组，如 /expand #e1（大段内容进可滚动阅读层） | | /rewind [N] | 无参列出各轮快照；/rewind N 回到第 N 轮之前：还原文件改动 + 对话（每轮开跑前自动打 git-tree 快照） | | /update | 立即查 npm 有无新版（每小时自动查、下次启动生效） | | /version | 显示版本 |

快捷键

| 按键 | 作用 | |------|------| | @path | 把文件内容内联进消息 | | !cmd | 直接执行 shell 命令（不走 agent、不耗 token），如 !git status | | Enter | 发送；有 ▸ next 建议时 1..N 选一个、空回车弹多选一次排好几个 | | 粘贴 / 拖入图片 | → [Image #N]（送视觉模型识图） | | ↑↓ | 历史 | | ⌘V | 粘贴 | | F5 | 语音 | | Ctrl+O | 折叠计划 | | Ctrl+C | 打断 / 退出 |

核心能力

• 自主编码 Agent：读文件 / 改代码 / 跑命令 / 搜代码多步自主推进，一口气把任务做完；先想透根因再下手（修因不修表）、按工匠标准写最小正确改动，收尾先自审 diff 再跑校验到绿才算完。
• 主动澄清（不瞎猜）：遇到真正该你拍板的分歧——多种合理设计、需求含糊、不可逆选择——它会弹窗让你定（单选 / 多选 / 表单），拿到答案再继续，而不是替你猜一个就跑。
• 下一步建议：一轮结束后按需给出可选的后续动作，输入 1..N 选一个，或空回车弹多选、一次排好几个接连执行。
• 降噪的工具展示：文件读写 / 命令 / 调研默认折叠成一行结论（如 Explored · 363 lines · 15.1k chars），点它或 /expand #eN 展开；大段内容进可滚动全屏阅读层（↑↓/滚轮翻、c 全复制、拖选复制、esc 关闭）。失败命令与文件 diff 始终显示；/verbose 切繁简。
• 并行子代理：面大的调研一条指令并行派多个只读子代理分头摸清（最多 5 个并行、其余排队），实时泳道看进度，再综合动手。
• 视觉 / 多模态：直接把截图 / 报错图贴进终端（或拖入）识图，按 OpenAI image_url 标准送视觉模型——图片仅当次有效，不重复占上下文烧 token。
• 语音输入：按 F5 录音 → 本地转写成文字落进输入框（macOS 原生设备端识别；其它系统用 whisper.cpp 回退）。
• 自学进化：跑通的可复用流程沉淀成技能（Skills，可 /名 直呼）；项目级长期记忆跨会话记住约定与坑，越用越准。
• 流式渲染：旁白 / 工具卡片 / diff / 命令输出实时打字机式呈现，markdown 边出边渲染。
• 会话持久化 + 回退：完整历史本地留存，/resume 接着上次聊；上下文超限自动压缩，长任务不撑爆。每轮开跑前自动给工作树打 git-tree 快照，/rewind N 一键把文件改动 + 对话都回退到某轮之前（含 shell 写的文件，不碰你的真实 git index）。
• MCP：放个 mcp.json 即接入 MCP 工具（同名内置工具优先，保安全边界）。

安全

• 默认 HITL 审批：改文件 / 执行命令前弹确认，看彩色 diff 再放行。
• /mode 可升到 auto-edits（自动改文件）或 auto（全自动）；但内置安全网始终在线——毁灭性命令（rm -rf、写敏感文件等）即使全自动也硬拦，危险但偶有正当用途的操作强制人工确认。

配置与环境变量

• 配置文件：~/.agentos/config.json（用 AGENTOS_CONFIG 改路径）。环境变量永远优先于已保存配置。
• 连接：LLM_PROVIDER · LLM_BASE_URL · LLM_API_KEY（或各服务商专属 Key）· LLM_MODEL · LLM_CHEAP_MODEL。
• 订阅直连：选 Claude·订阅 / Codex·订阅 后，配置里记 localProxy: claude|codex；每次启动 gcli 进程内拉起本地代理、baseUrl 动态指向它（无需手填）。凭证来源：Claude 读 ~/.claude 登录或 CLAUDE_CODE_OAUTH_TOKEN；Codex 读 ~/.codex/auth.json（codex login）。
• 目录：AGENTOS_SESSIONS_DIR（会话）· AGENTOS_SKILLS_DIR（技能）· AGENTOS_MCP_CONFIG（MCP 配置）。
• 语音回退（非 macOS）：REC_BIN（sox/ffmpeg）· WHISPER_BIN · WHISPER_MODEL。

更新

/update                              # 交互态里立即查一次，有新版即后台安装、下次启动生效
npm i -g @guangnao/agent-cli@latest  # 或直接强制更新到最新

许可

MIT。