常见问题

没找到答案？开个 issue 问我们。

安装

系统要求是什么？

支持 Linux (x64 / arm64 / armv7 / riscv64)、macOS (Intel / Apple Silicon)、Windows、WSL2、Alpine。预编译二进制优先；如需源码编译则要求 Rust ≥ 1.75（安装器会自动装好 Rust）。

必须用 root / 管理员吗？

install.sh 当前需要 root（因为要装编译工具链）。Windows 的 install.ps1 需要管理员权限装 Build Tools。npm 方式（npm i -g）不需要 root，但系统级命令仍然会在 angles install 步骤里要求权限。

四种安装方式有什么区别？装的不一样吗？

完全一样，最终都是 ~/.local/bin/angles 这个 Rust 单二进制：

npm：打包了安装器，跨平台、国内走 npmmirror 镜像最快
curl / wget：直接拉 install.sh，最适合 Linux/macOS/WSL2 服务器
PowerShell irm：原生 Windows 首选

安装到一半中断了怎么办？

重跑同一条安装命令即可，安装器是幂等的：已装的依赖会跳过，不足的会补齐。配置文件 ~/.angles/config.json 不会被覆盖。

GitHub raw 在国内打不开 / 太慢？

用 npm 方式最稳（默认走 npmmirror）。或给_install.sh_ 换 GitHub 加速前缀，例如：

curl -fsSL https://ghfast.top/https://raw.githubusercontent.com/ZSJ305/angles-cli/main/install.sh | bash

也可在终端设代理：export https_proxy=http://127.0.0.1:7890

配置

配置文件在哪？

~/.angles/config.json（Windows: %USERPROFILE%\.angles\config.json）。想重置就删掉它，下次启动会触发 Gateway 向导。

API Key 会上传到任何服务器吗？

不会。Key 存储在本地 config.json，也可用 ANGLES_API_KEY 环境变量。所有请求直接发往你配置的模型供应商，Angles 不经过任何中转或代理服务器。

怎么重新配置（换模型 / 换语言）？

跑 angles gateway 重新进入五步 TUI 向导，任何字段都能改。或直接编辑 config.json。查看当前配置：angles config。

审批策略 untrusted / on-request / never 有什么区别？

untrusted（默认）：只读安全命令自动执行，破坏性操作问用户。on-request：agent 自行判断什么时候请示。never：全部自动执行——最快但最危险。angles-deletefile、rm -rf、git push --force 等无论哪种策略都强制确认。

模型 & Provider

支持哪些模型供应商？

OpenAI、Claude (Anthropic)、Gemini (Google)、DeepSeek、Grok (xAI)、MiniMax、OpenRouter、通义千问 Qwen、智谱 GLM、Kimi (Moonshot)、自定义。前 10 家有预置 base_url 和默认模型，自定义让你填任意端点。

能用本地 Ollama / vLLM / LM Studio 吗？

能。这些本地推理服务都提供 OpenAI 兼容端点。Gateway 中选「自定义」：

Base URL: http://localhost:11434/v1（Ollama）
API Key：随便填一个（本地通常不校验）
协议：chat
模型：填对应的模型名，如 llama3.1

Claude 和 Gemini 的协议不一样，怎么处理？

Angles 在 api.rs 中同时适配了三种协议：chat（OpenAI 兼容）、anthropic（Messages API）、gemini（原生 generateContent）。选 Claude / Gemini 时 wire_api 会自动设为对应协议，无需你手动配置。

怎么切换模型但不动其他配置？

编辑 config.json 把 model 字段改成新的模型 ID 即可，其它字段保留。或重新跑 angles gateway 只改 Step 3 模型选择那一步。

工具 & 使用

30 个工具都是什么？

分 6 组：文件创建（4）、读取搜索（5）、修改删除（7）、目录项目（5）、终端执行（3）、网络搜索（2）、Git（5）。完整速查见工具速查页，支持搜索和按类别筛选。

为什么改文件优先用 replace 不是 writefile？

angles-replace 是精准 diff 替换，意图清晰、改动最小；writefile 是全量覆盖，容易把无关内容也一起覆盖掉。系统提示里明确要求 agent 优先 replace > writefile。

怎么让 agent 执行 shell 命令？

agent 自主决定调用 angles-run，你可以直接让它「跑测试」「起服务看一下日志」之类。是否需要你确认取决于审批策略。后台任务用 angles-runbg，返回 PID，angles-kill 终止。

能联网搜索吗？

能。Gateway 第 5 步选搜索引擎：Bing / Baidu / Google / Yahoo / 自定义 URL / 关闭。agent 在需要实时信息时调用 angles-websearch，Bing 通常最稳。

会和 Codex CLI / Claude Code 冲突吗？

不会。Angles 是独立二进制 angles，配置和会话都在 ~/.angles/，与其它工具互不干扰。可以同时装多个 agentic CLI 在不同终端用。

安全 & 审批

哪些操作一定会让我确认？

无论哪种审批策略，这些始终强制确认：

angles-deletefile — 永久删除文件
angles-run 配 rm -rf / sudo / mkfs / dd 等破坏性命令
angles-run git push --force
任何修改工作区外文件的操作

agent 会不会乱删文件？

默认 untrusted 策略下不会：所有写操作要经你确认。即使切到 never，deletefile 和 rm -rf 这类仍强制确认。系统提示还明确要求 agent 不修无关 bug、不无谓改文件结构。

它会在我的项目目录外乱跑吗？

默认作用域是当前工作目录及其子树，修改工作区外文件需要确认。AGENTS.md 规范还会让 agent 遵守仓库内的特殊约束。

故障排查

对话没响应 / 报网络错？

先跑 angles doctor 诊断：

检查 config.json 是否完整
测试到 base_url 的连通性
验证 API Key 是否有效
检查每日 token 预算是否已用尽

常见根因：API Key 过期、base_url 拼错、网络代理没设、当日预算打满（等次日重置）。

提示 grep: unrecognized option -P？

你大概率在 Alpine / BusyBox 上跑 install.sh 的检测代码。BusyBox grep 不支持 PCRE（-P）。这是 install.sh 内部对 Rust 版本号解析的已知兼容问题，不影响实际功能——Rust 版本检查会退化但不会卡住安装。

Windows 上 PowerShell 提示执行策略受限？

用 irm ... | iex 形式（管道执行）可绕过执行策略；或在管理员 PowerShell 里跑 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned。

预编译二进制下不下来？

安装器会自动 fallback 到源码编译：装 Rust + cargo build --release。编译需要几分钟，但能保证成功。也可以 ANGLES_REPO=... git clone 后本地 cargo build --release 再手动 copy。

开发 & 贡献

从源码构建？

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
git clone https://github.com/ZSJ305/angles-cli.git
cd angles-cli
cargo build --release
cp target/release/angles ~/.local/bin/

交叉编译用 Makefile：make setup-arm64 && make arm64（Linux ARM64 静态二进制）等。

项目结构是怎样的？

9 个 Rust 模块：main.rs 入口、cli.rs Clap 定义、config.rs 配置、provider.rs 供应商注册表、gateway.rs TUI 向导、instructions.rs 系统提示模板、api.rs API 客户端 + 工具循环、search.rs 搜索 URL、tools.rs 30+ 工具实现。详见技术文档。

怎么贡献 / 提建议？

开源 GPL-3.0，GitHub 仓库欢迎 issue 和 PR。早期的项目，方向开放，特别欢迎：新工具想法、Provider 适配、文档改进、bug 反馈。

路线图怎么走？

v0.1 已发布（核心 CLI + 30 工具 + 11 Provider）；v0.2 规划 update/uninstall 子命令、会话持久化；v0.3 完成 Skill 系统与文档站；v0.4.1 新增 AI 操作说明生成（angles plan）与更透明的执行计划；v1.0 目标稳定 API + 完整文档站。详见主页路线图。