第6章 在终端里使用——agy -p 和悄悄拒绝
选读 需要的时候再读。跳过也能跟上后面的章节。一句话总结:
agy是 Antigravity 的终端程序,agy -p "要做的事"运行一次就结束。 在-p下,需要许可的事会被悄悄拒绝。可是退出码(程序结束时留下的编号)仍是 0(成功),所以很容易把空结果误当成成功。
终端是用文字输入命令来操作电脑的窗口。如果你是第一次接触终端,这一章可以跳过。 想多了解终端,请看 Claude Code 第10章(选读)。
本章的结果,是这本指南在 macOS 上实际运行 agy 得到的。照着做时,请直接在终端里运行 agy。[1]
安装并开始
macOS·Linux 的安装命令是这样的。[2]
curl -fsSL https://antigravity.google/cli/install.sh | bash这条命令会直接运行从互联网上下载的安装程序。所以,请确认和官方文档(antigravity.google/docs)上写的一模一样,再运行。 Windows 用的命令也在官方文档里。
进入整理工具文件夹,输入 agy,就会打开对话界面。[3] 下面第一行的 cd 是进入那个文件夹的命令。如果已经在应用里登录过,就不用浏览器,直接登录。[4]
第一次运行时,会问你是否信任这个文件夹(Workspace trust,把文件夹登记为可信的步骤)。[5] 整理工具文件夹是你自己建的,回答信任就行。这样回答好,应该就能避开后面要讲的一个拒绝陷阱(这本指南的推测)。
cd ~/hello-ai-practice/organizer
agy理解检查
第一次运行 agy 时确认的“Workspace trust”是什么?
运行模式
在交互式 agy 里,用 Shift+Tab 切换运行模式。[6]
| 模式 | 修改文件 | 运行命令 |
|---|---|---|
default | 展示改动内容并确认 | 询问 |
accept-edits | 工作文件夹内自动 | 询问 |
出处:Antigravity 官方文档(只摘录了一部分)[7]
终端的默认权限比应用更谨慎。写文件·命令·网络工具之前都会询问,把命令关在围栏里的沙盒默认是关闭的(第4章)。
理解检查
关于 agy 的 accept-edits 模式,哪种说法是对的?
agy -p——问一次就结束
-p 是发出一个请求、拿到回答后就结束的方式。因为没有询问的窗口,需要许可的事会按事先定好的规则处理。[8] 程序输出的文字分成两条路。[9]
- 正式输出(stdout,标准输出):回答本身。比如我要的文件列表表格。
- 旁路(stderr,标准错误):进度和错误。比如告知 shell 命令被拒绝的提示。
在终端界面上,两者通常会一起显示。回答和提示混在一起也不用慌。
官方文档说明,工作文件夹内文件的读写自动允许,shell 命令默认是“询问”,所以会被悄悄拒绝(soft-deny)。[10] 悄悄拒绝不会中断运行,而是以退出码 0 结束,只在 stderr 里告知什么被拦住了。[11]
理解检查
在 agy -p 里遇到需要许可的操作,会怎样?
这本指南遇到的四个陷阱
这些是在整理工具文件夹里多次运行 agy -p 时真实遇到的事。
- 结果是空的,却显示成功。 代理想用 shell 命令(
ls,在终端里输入的命令)查看文件夹列表,被拒绝了。于是它什么也没做出来就结束了。 退出码是 0。这种事发生了三次。- 要做的事:请一定要确认结果文件是不是真的生成了。
- 在没有信任的文件夹里,连读写也被拒绝。 在练习文件夹里,曾经连写入和读取文件都被拒绝。原因看起来是这个文件夹还没有被登记为“信任的文件夹”(这本指南的推测)。[12]
- 要做的事:打开一次交互式
agy,回答信任这个文件夹。[12:1]
- 要做的事:打开一次交互式
- 解决:一个模式 + 一句话。 在命令末尾加上
--mode accept-edits,并在请求末尾加上“不要用 shell 命令,只读写文件”,就全部成功了。- 不要使用允许一切的
--dangerously-skip-permissions选项。 - 这种以
--开头的文字叫作选项。加在命令后面,用来改变运行方式。--mode accept-edits的意思是用上面表格里的accept-edits模式运行。在下面命令的最末尾能看到它。
- 不要使用允许一切的
- 回答漏掉的文件。 我请它以只读方式,把 notes 文件夹的文件列表做成表格给我。整理好的文件有 3 个(周会会议记录·临时会议会议记录·周回顾)。可是表格里漏掉了临时会议会议记录,反而放进了空文件
.gitkeep。- 要做的事:请自己数一数确认的范围。
详细说明(点击展开)
实际用的命令是这样的。
cd ~/hello-ai-practice/organizer
agy -p "列出 notes 文件夹的文件,并用一行告诉我每个文件是用哪个模板(templates 里的哪一个)写的。不要修改文件。回答要简短,只用表格。不要用 shell 命令,只读取文件。" --mode accept-edits结果:agy -p 输出(我电脑里的路径换成了 ~)
| Claude Code | Codex | Antigravity | |
|---|---|---|---|
| 运行一次 | claude -p | codex exec | agy -p |
| 默认写文件 | 需要许可 | 只读 | 工作文件夹内自动(文档) |
| 被拦住时 | 拒绝 | 暂停 | 悄悄拒绝,退出码 0 |
出处:这本指南的整理(各个工具的终端章节和实践)
理解检查
agy -p 以成功(退出码 0)结束,却没有结果文件。按这份指南的经验,先做什么?
继续对话和用量
终端里的对话记录是按运行时所在的文件夹分开的。[14] 用 agy -c 可以直接接上那个文件夹的最后一次对话,也可以用 /resume 选择后接着做。[15] /rewind(或 /undo)会把对话退回到前面的消息(第4章)。文件会不会也跟着退回,官方文档里没有写,所以文件请相信 Git 的记录。
用量用 /usage 查看。[16]
理解检查
在 agy 里,直接接着这个文件夹里的最后一次对话,怎么做?
亲自试一试
- 确认官方文档的安装命令和上面的命令一样之后再安装(已经有的话,运行
agy --version)。 - 在整理工具文件夹里打开一次交互式
agy,被问到是否信任文件夹时回答。 - 运行上面的只读
agy -p,把表里的文件数和 notes 文件夹对着数一数。 - 如果结果是空的,读 stderr 里的拒绝提示,确认是什么被拦住了。
连续任务:第7章会整理费用·数据·安全,并决定怎么搭配使用三个工具。
整理
agy是交互式,agy -p是运行一次就结束。对话记录按文件夹分开。- 在
-p下,需要许可的事会被悄悄拒绝,退出码是 0。要亲自确认结果文件。 - 在没有信任的文件夹里,文件操作也可能被拦住。把文件夹登记为信任,或者用
--mode accept-edits。 - “不要用 shell 命令”这一句话,减少了因拒绝而停下来的情况。回答的范围要自己数。
术语整理
| 术语 | 中文名称 | 一句话解释 |
|---|---|---|
| Headless | 无界面模式 | 不打开对话界面,运行一次的方式 |
| Soft-deny | 软拒绝 | 不中断运行,只悄悄拒绝那个动作 |
| Workspace trust | 工作区信任 | 把这个文件夹登记为信任的步骤 |
| Exit code | 退出码 | 程序结束时留下的成功·失败编号 |
这一章读完了吗?
学习记录只保存在这个浏览器中。整体进度可以在 全部目录中查看。
参考资料(16 条)
这一章是根据 2026 年 11 月 1 日确认的 Antigravity 官方文档,以及在 macOS 上运行
agy1.4.12 的结果写的。这本指南是在另一个实践用的 AI 工具里调用并运行了agy。官方 FAQ 说个人套餐不支持这种用法(第7章)。 ↩︎Antigravity 官方文档,《Get started》。"curl -fsSL antigravity.google | bash" antigravity.google (确认日期 2026-11-01) ↩︎
Antigravity 官方文档,《Get started》。"|
agy| Launches the interactive TUI in the current directory. |" antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Authenticate》。"If a valid token profile is found, the CLI authenticates your session silently without opening a browser." antigravity.google (确认日期 2026-11-01) ↩︎
Antigravity 官方文档,《Get started》。"Workspace trust: Confirm that you trust the repository directory before the agent begins file indexing." antigravity.google (确认日期 2026-11-01) ↩︎
Antigravity 官方文档,《Choose an execution mode》。"Press Shift + Tab inside the prompt box to cycle through the active sequence:
default>accept-edits>auto>plan>default." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Choose an execution mode》。"|
default| Pauses for interactive diff review before modifying or creating files, and asks before running terminal commands. | Standard development, reviewing sensitive code changes, and careful refactoring. |" / "|accept-edits| Automatically approves file creations and edits inside your workspace, but still asks before running terminal commands. | Rapid prototyping, iterating on trusted code, and reducing file-edit interruptions. |" antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Headless mode》。"Headless mode (also called print mode) sends a single prompt to the agent, streams or returns the response, and exits." / "There is no interactive prompt in headless mode, so tools that would normally ask for confirmation are handled by policy." antigravity.google (确认日期 2026-11-01) ↩︎
Antigravity 官方文档,《Headless mode》。"Diagnostics—errors, authentication prompts, progress, and permission notices—go to
stderr." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Headless mode》。"Reading and writing files inside your active workspace is auto-allowed; actions such as shell commands default to Ask and are soft-denied in headless mode unless you grant them." antigravity.google (确认日期 2026-11-01) ↩︎
Antigravity 官方文档,《Headless mode》。"A tool that requires approval it can’t obtain is soft-denied: the run continues, exits
0, and prints a notice tostderrnaming the tool and how to allow it." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《CLI commands》。"|
trustedWorkspaces| string[] |[]| Folders you chose to trust when the CLI asked. The CLI adds entries for you. |" antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Headless mode》。"Warning:
--dangerously-skip-permissionsapproves all tool calls, including file writes and command execution. Prefer scopedpermissions.allowrules unless you fully trust the prompt and environment." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Managing conversations》。"When you launch
agyfrom a specific directory, the agent only displays and resumes sessions associated with that specific local repository or subdirectory." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Managing conversations》。"Antigravity CLI supports both an interactive Session Picker TUI overlay and direct command-line flags (
agy -c/agy --continue) to resume threads instantly based on your active workspace." antigravity.google (确认日期 2026-11-01) ↩︎Antigravity 官方文档,《Model quotas (/usage)》。"Antigravity CLI provides the
/usagecommand (alias/quota) to help you monitor your resource consumption." antigravity.google (确认日期 2026-11-01) ↩︎