自动化 on KnightLi的博客

Codex 官方文章解读：如何把 Codex 用到极致

Wed, 27 May 2026 08:21:18 +0800

多数开发者第一次使用 Codex，通常是从代码任务开始：阅读仓库、修改 diff、运行测试、打开 pull request。

这仍然是 Codex 的核心场景。但电脑上的很多工作本来就被代码和工具包围：执行 shell 命令、浏览网页、调用 API、导出文档、响应消息、触发自动化。随着这些能力逐渐接入 Codex，它就不再只是狭义的代码助手，而更像一个帮你完成电脑工作的系统。

Codex app 让这种变化变得更具体。一个 thread 可以保留上下文、调用工具、展示产物，并在多轮提示之间持续推进，而不是每次对话都重新开始。

想更充分地使用 Codex，关键是把这些能力组合起来：

持久线程，用来保存长期上下文
语音输入、steering 和 queuing，让用户仍然掌控过程
browser、computer use、MCP servers 和 connectors，让 Codex 走出仓库
thread automations 和 Goals，让任务在用户离开后继续推进
侧边栏，用来审阅代码、文档、幻灯片、网页和其他产物
共享记忆，把重要上下文写到线程之外

持久线程

Durable threads 指的是能在多次会话之间保留工作上下文的长线程。

Pinned threads 是一种很实用的入口。它适合放那些会反复回来的工作流，比如：

Chief of Staff 线程
发布线程
文档审阅线程
外部监控线程

这些不是临时聊天，而是持续存在的工作空间。Codex 可以在后续继续回到同一个线程，沿用之前的决策、偏好和背景信息，避免每次都从零重建上下文。

快捷键也让它更顺手。Command-1 到 Command-9 可以直接跳转到已保存的线程。

语音输入

语音输入的价值在于，它能捕捉还没有被整理成正式文字的想法。

Codex 内置语音输入。它特别适合那些说起来很自然、打字时却很别扭的模糊起点：

1
2
3

我记得 Slack 里好像有个叫 Ben 的人提过这个。
具体细节我不记得了。
帮我去找一下。

对于一个能搜索、整理上下文并汇报结果的 agent 来说，这通常已经足够开始。

语音也适合两三分钟的想法倾倒。会议转录、口述规划笔记、未整理的原始记录，往往比一句摘要更有用，因为它们保留了不确定性、重点和没说完的思路。

Steering 和 queuing

语音和显式控制结合起来时，会更有用。

Steering 指的是在 Codex 任务执行过程中插入新的方向，让它在当前步骤结束前改道。

例如在审阅网页时，用户可以一边在侧边栏标注，一边打断当前任务：

1
2
3

这里再小一点。
这两个元素之间的间距不对。
这句文案写错了。

Queuing 则不同。它不打断当前任务，而是把下一步工作排到队列里：

`1`	`这项工作完成后，把预览链接发给 Slack 里的 reviewer。`

Steering 改变 Codex 现在正在做什么。Queuing 改变它接下来应该做什么。两者都让用户在任务展开时仍然靠近现场。

工具和可触达范围

线程有了连续性之后，下一个问题就是：它能操作什么？

Codex 可以一层层向外扩展：

$browser：适合侧边栏里的网页检查、标注和 review
@chrome：适合依赖用户 Chrome 登录状态的浏览器工作流
@computer：适合只能通过桌面 GUI 完成的任务

MCP servers 和 connectors 把同样的思路扩展到更多工作流中。Slack、Gmail、Calendar 很重要，因为很多任务最初不是以代码形式出现，而是以消息、邮件和日程问题出现。

Skills 则适合固化重复工作。当某个流程已经被证明有用，就可以把它打包成 skill，让 Codex 下次不必重新学习这套步骤。

从任何地方继续工作

Codex mobile app 改变了用户必须坐在电脑前的时间。

一个任务可以在 Mac 上开始，因为文件、权限和本地环境都在那里；随后用户离开桌面，只用手机继续确认、补充或改方向。

这在很多小场景里很有价值：Codex 跑长任务时，用户可以离开座位；如果它需要确认，可以在外面回复；如果方向错了，也能及时 redirect。真正留在原地的是本地环境，而不是用户本人。

自动化

Automations 可以按计划运行 Codex 工作。

如果一个周期任务应该从某个 workspace 重新开始，例如日报或常规仓库检查，可以用 scheduled automation。如果调度应该回到一个已有对话，并沿用它的上下文，就更适合 thread automation。

Thread automations 更像心跳式唤醒：按固定节奏回到同一个 Codex thread。

Pinned threads 需要用户主动回来，而 thread automation 可以每几分钟或每几小时检查一次，持续运行到满足条件为止，并随时间调整节奏。

例如，一个 Chief of Staff 线程可以每 30 分钟运行一次：

1
2
3

每 30 分钟检查 Slack 和 Gmail，找出需要我注意但还没有回复的消息。
帮我判断哪些最重要。
如果有人问我问题，尽可能深入研究答案，并替我起草回复，但不要发送。

用户回来时，最耗时的上下文收集往往已经完成。真正要不要发送，仍然由人决定。

Thread automations 也适合反馈循环。它可以定期查看 pull request 评论、Google Docs 评论或 Slack 回复，在用户离开时继续推进周边工作。

比如一个动画工作流：reviewer 在 Slack 里发来视频反馈，thread automation 定时检查线程；如果有新评论，就重新渲染版本，并在同一个 Slack thread 里回复 reviewer。如果某个集成无法完成最终上传，桌面自动化还可以通过 GUI 补上最后一步。

这个循环会跨过 Slack、代码库和桌面应用，但对用户来说仍然留在同一个工作流里。

Goals

Goals 最适合那些有明确终点、并且 agent 可以持续推进的任务。

一个较弱的 goal 可能是：

`1`	`实现这个 Markdown 文件里的计划。`

更强的 goal 会有可衡量的完成标准。

例如，把一个内部工具从 Python 迁移到 Rust 时，可以先建好新目录，再把目标说清楚：新实现只有在单元测试通过后才算完成。

Goal 本质上是持续执行加验证器。用户需要定义结果、停止条件，以及判断 Codex 是否更接近目标的信号。

常见的验证器包括：

测试套件
benchmark
bug reproduction
validation matrix
必须持续通过的端到端工作流

任务可以有野心，但没有验证条件时，它更像愿望，而不是 goal。

侧边栏

侧边栏把工作产物放在生成它的对话旁边。用户不必导出文件、切换上下文，再回头描述问题。产物可能是代码，也可能是 deck、PDF、网页、表格，或者工作过程中生成的其他 artifact。

它特别适合四类工作：

检查 artifact
标注需要修改的地方
操作网页界面
审阅变更

Markdown、表格、数据表、文档和幻灯片都可以直接在侧边栏里看。用户可以检查、标注、修改，而不用把这个过程变成另一轮交接。

如果是 deck 或 PDF，它可以一直停在产生它的 thread 旁边，随时接受 review 和修复。

浏览器也是类似的工作面。Codex 可以打开渲染后的页面，检查它，响应用户在页面上的标注，并继续修复同一个对象。网页既是输出结果，也是控制表面。

这些表面尤其适合放在侧边栏里：

index.html 这种轻量静态 artifact
Storybook
Remotion Studio
浏览器幻灯片
数据分析应用

一个单独的 index.html 文件就可以成为长期存在的交互 artifact，不一定需要服务器。Thread automations 也可以定期刷新静态 artifact，让用户回来时看到新的结果。

共享记忆

长线程很有用，但重要上下文不应该只存在于对话记录里。

Shared memory 指的是把持久上下文存放在线程之外，让未来的工作可以从明确、可审阅的地方继续。

一种稳定做法是把持久线程锚定在 Obsidian vault 里。实际形态可以很简单：一组普通文件，方便检查、编辑、移动和长期保存。团队可以把它放在 cloud storage、Git、Dropbox、Google Drive 或其他同步层里。

一个 vault 可能长这样：

vault/
├── TODO.md
├── people/
├── projects/
├── agent/
└── notes/

顶层的 AGENTS.md 可以说明 Codex 应该如何维护这个工作空间：什么信息要写下来，写到哪里，什么时候不要制造噪音。

一个实用的 AGENTS.md 可以这样写：

- Treat ~/vault as durable work memory.
- Prefer canonical notes over note sprawl.
- Route TODOs, people, projects, daily summaries, and scratch notes explicitly.
- Preserve decisions, blockers, owners, dates, and useful links.
- If nothing meaningful changed, do not churn the vault.

不要照抄某个 vault 结构。更重要的是教会 agent：长期上下文应该放在哪里，哪些信息值得保留，什么时候不应该反复改动文件。

仓库存放代码。Vault 存放滚动上下文：相关人员、发生了什么、哪里卡住、谁负责、下一步是什么，以及那些如果不写下来就会在会话之间消失的细节。

Codex 也有第一方记忆能力，可以在 Settings > Personalization > Memories 中配置。它适合记录偏好、重复工作流和常见坑点，但它更适合作为显式 written context 的补充，而不是替代品。Chronicle 也在同一个方向上推进：从最近的屏幕上下文中帮助 Codex 建立记忆。

从代码向外扩展

Codex 仍然从代码开始。但代码周围的更多工作，现在也能被同一个系统触达：MCP servers、浏览器界面、桌面控制、thread automations 和可审阅 artifact。

这改变了使用 Codex 的控制方式。Steering 用来打断正在进行的工作。Queuing 用来排下一步。Thread automations 让线程在用户离开后继续活动。Goals 给长期任务加上明确终点和验证信号。

当这些能力连起来时，Codex 就能把一个工作流从指令推进到执行，再推进到 artifact review。即使任务已经离开代码仓库，它仍然可以留在同一个系统里完成。

原文链接：Getting the most out of Codex

ai-goofish-monitor：用 AI 自动盯闲鱼商品的开源监控系统

Sun, 17 May 2026 17:24:03 +0800

ai-goofish-monitor 是 Usagi-org 开源的闲鱼商品监控系统。

它的目标很明确：把闲鱼搜索、筛选、商品分析、结果记录和通知推送自动化，帮助用户从大量二手商品里更快找到符合条件的目标。项目基于 Playwright 做页面自动化，再接入支持图片输入的 AI 模型，对商品信息做进一步判断。

项目地址：https://github.com/Usagi-org/ai-goofish-monitor

先说结论

ai-goofish-monitor 更像一个“闲鱼采购情报面板”，而不是简单的关键词提醒脚本。

它有几个明显特点：

有完整 Web 管理界面，可以管理任务、账号、AI 标准、日志和结果。
支持多任务并发，每个任务可以配置关键词、价格、筛选条件和 AI Prompt。
使用 Playwright 抓取闲鱼页面，适合处理需要登录态和页面交互的场景。
使用 AI 判断商品是否符合需求，不只依赖关键词匹配。
支持 ntfy.sh、企业微信、Bark、Telegram、Webhook 等通知渠道。
支持 Cron 定时任务、多账号管理、代理轮换、失败重试和 Docker 部署。

它适合经常在闲鱼找特定商品的人，比如二手数码、摄影器材、显卡、硬盘、游戏机、乐器、家电和收藏品。但它也不是“自动捡漏神器”。闲鱼搜索结果本身会变化，账号登录态可能失效，平台风控也会影响自动化稳定性。使用时更应该把它当成辅助筛选工具，而不是完全替代人工判断。

它解决什么问题

在闲鱼上找二手商品，经常有几个痛点：

商品太多，手动翻很累。
标题和描述不规范，关键词很容易漏掉或误判。
好价格出现时间短，发现太晚就没了。
同一个商品可能有多个地区、价格、成色和卖家差异。
低价商品里混着配件、损坏品、翻新货和诱导性标题。
想持续盯多个关键词时，手动搜索很难坚持。

普通关键词提醒只能解决一部分问题。比如你搜索“ThinkPad X1”，可能会混入配件、坏屏、空盒、拆机件；你搜索“索尼 A7C”，又可能遇到镜头套装、租赁信息、标题党和价格异常。

ai-goofish-monitor 的思路是：先用自动化把候选商品抓出来，再交给 AI 按你的需求做二次判断，最后把值得关注的结果推送给你。

核心功能

项目 README 里列出的核心能力比较完整：

Web 可视化管理：任务管理、账号管理、AI 标准编辑、运行日志、结果浏览。
AI 驱动：支持自然语言创建任务，并用多模态模型分析商品。
多任务并发：不同任务可以独立配置关键词、价格、筛选条件和 AI Prompt。
高级筛选：支持包邮、新发布时间范围、省 / 市 / 区三级区域筛选。
即时通知：支持 ntfy.sh、企业微信、Bark、Telegram、Webhook 等多渠道。
定时调度：支持 Cron 配置周期性任务。
账号与代理轮换：多账号管理、任务绑定账号、代理池轮换与失败重试。
Docker 部署：支持容器化部署。

这些能力组合起来，覆盖了从“创建监控任务”到“收到命中提醒”的完整链路。

工作流是什么样

一个典型流程大概是这样：

部署服务并打开 Web UI。
导入闲鱼账号登录态。
创建监控任务。
设置关键词、价格区间、地区、新发布范围等筛选条件。
编写或让 AI 生成判断标准。
任务按实时或定时方式运行。
Playwright 打开页面并抓取商品信息。
AI 根据标题、描述、图片和 Prompt 判断是否符合需求。
命中结果写入 SQLite。
系统通过配置的通知渠道推送结果。
用户在 Web UI 里查看结果、日志和价格历史。

这个流程里，AI 的价值主要在第 8 步。它可以理解“我想要成色好、价格合理、不要配件、不要维修机、最好同城自提”这类自然语言条件，比单纯关键词规则灵活。

Docker 部署

项目推荐使用 Docker 部署：

git clone https://github.com/Usagi-org/ai-goofish-monitor && cd ai-goofish-monitor
cp .env.example .env
vim .env
docker compose up -d
docker compose logs -f app
docker compose down

默认 Web UI 地址是：

`1`	`http://127.0.0.1:8000`

官方镜像地址是：

`1`	`ghcr.io/usagi-org/ai-goofish:latest`

如果镜像访问慢，README 里也给了加速镜像示例：

1
2
3

docker pull ghcr.nju.edu.cn/usagi-org/ai-goofish:latest
docker tag ghcr.nju.edu.cn/usagi-org/ai-goofish:latest ghcr.io/usagi-org/ai-goofish:latest
docker compose up -d

Docker 镜像已内置 Chromium，不需要宿主机额外安装浏览器。默认持久化目录包括：

data/：SQLite 主存储，保存任务、结果和价格历史。
state/：登录状态 cookie 文件。
prompts/：任务提示词。
logs/：运行日志。
images/：商品图片和任务临时图片目录。

如果修改了 .env 里的 SERVER_PORT，也要同步调整 docker-compose.yaml 的端口映射。

最少配置

项目的最少配置主要围绕 AI 模型和 Web UI 登录：

OPENAI_API_KEY=your_api_key
OPENAI_BASE_URL=your_openai_compatible_base_url
OPENAI_MODEL_NAME=your_multimodal_model
WEB_USERNAME=admin
WEB_PASSWORD=change_me

其中前三项是 AI 模型接入必填项：

OPENAI_API_KEY：模型 API Key。
OPENAI_BASE_URL：OpenAI 兼容接口地址。
OPENAI_MODEL_NAME：支持图片输入的模型名称。

WEB_USERNAME 和 WEB_PASSWORD 用于 Web UI 登录。README 提到默认账号密码是 admin/admin123，生产环境必须修改。

第一次使用

第一次使用时，流程大致是：

打开 http://127.0.0.1:8000。
登录 Web UI。
进入“闲鱼账号管理”。
使用项目提供的 Chrome 扩展导出闲鱼登录态 JSON。
把登录态粘贴到系统里。
登录态文件会保存到 state/，例如 state/acc_1.json。
回到“任务管理”，创建任务并绑定账号。
运行任务并查看结果。

这里最关键的是登录态。由于闲鱼并不是开放给第三方随意抓取的标准 API，项目需要用浏览器登录状态来模拟正常页面访问。登录态失效、风控、验证码、账号异常都会影响任务运行。

AI 任务和关键词任务

项目支持两类任务创建方式。

第一类是 AI判断。

你可以填写“详细需求”，提交后系统会异步生成分析标准。适合需求比较复杂的场景，例如：

只要主机本体，不要配件。
价格明显低于市场价才提醒。
成色要好，描述里不能有进水、维修、暗病。
优先同城，能面交更好。
图片里要能看到序列号、包装或关键配件。

第二类是 关键词判断。

它更接近传统规则监控：根据关键词、价格、地区等条件直接创建任务，不经过 AI 生成流程。适合规则简单、误报可以接受的场景。

实际使用中可以混合使用：关键词负责初筛，AI 负责减少误报。

Web UI 能做什么

Web UI 是这个项目区别于普通脚本的重要部分。

任务管理页可以配置：

AI 创建任务。
关键词规则。
价格范围。
新发布范围。
区域筛选。
账号绑定。
定时规则。

账号管理页可以：

导入闲鱼账号登录态。
更新登录态。
删除账号。
为任务指定账号。
让系统自动选择账号。

结果和日志页可以：

查看命中商品。
导出结果。
查询历史记录。
查看任务运行过程。
排查登录态失效、风控和 AI 调用问题。

系统设置页可以：

查看系统状态。
编辑 Prompt。
调整代理和轮换配置。

对于长期监控来说，Web UI 很关键。否则任务一多，配置、日志、结果和通知都会变得难维护。

数据存储

项目当前在线主存储使用 SQLite，默认路径是：

`1`	`data/app.sqlite3`

Docker 默认把 SQLite 主库挂载到：

`1`	`./data:/app/data`

应用启动时会自动建库建表，并尝试从旧的 config.json、jsonl/、price_history/ 导入一次历史数据。

需要注意的是，state/、prompts/、logs/、images/ 仍然是文件系统目录，不在 SQLite 中。商品图片会临时保存到类似下面的目录：

`1`	`images/task_images_<task_name>/`

任务结束后默认会清理。

这种结构比较适合个人或小团队部署：SQLite 足够轻，迁移也简单；文件目录保留登录态、图片和日志，排查问题更直观。

通知渠道

项目支持多种通知渠道，常见配置包括：

NTFY_TOPIC_URL
GOTIFY_URL / GOTIFY_TOKEN
BARK_URL
WX_BOT_URL
TELEGRAM_BOT_TOKEN / TELEGRAM_CHAT_ID / TELEGRAM_API_BASE_URL
WEBHOOK_*

通知是这类工具的核心体验。监控系统如果只把结果写进后台，用户仍然需要反复打开页面查看；有推送之后，命中商品才能在第一时间触达。

更实用的配置方式是按商品价值分层：

普通关键词命中只写入后台。
AI 高置信度结果推送到手机。
高价值商品推送到企业微信或 Telegram。
调试阶段开启更多日志，稳定后减少噪音。

开发者运行

如果不使用 Docker，本地开发需要：

Python 3.10+
Node.js + npm
Playwright CLI
Chromium 或 Chrome / Edge 浏览器

基础命令：

1
2
3

git clone https://github.com/Usagi-org/ai-goofish-monitor
cd ai-goofish-monitor
cp .env.example .env

一键启动：

1
2

chmod +x start.sh
./start.sh

start.sh 会检查 Playwright CLI 和浏览器条件，自动安装依赖、构建前端、复制构建产物并启动后端。

手动启动后端：

`1`	`python -m src.app`

或者：

`1`	`uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload`

前端开发：

1
2
3

cd web-ui
npm install
npm run dev

测试和构建：

1
2

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 pytest
cd web-ui && npm run build

适合哪些人

ai-goofish-monitor 适合这些用户：

经常在闲鱼蹲特定型号商品的人。
想监控二手数码、摄影器材、游戏设备、硬件配件的人。
想把“关键词搜索 + 人工筛选”自动化的人。
有 OpenAI 兼容模型 API，并愿意为 AI 判断支付调用成本的人。
熟悉 Docker 或基本命令行部署的人。
需要把命中结果推送到手机、企业微信或 Telegram 的用户。

它不太适合这些情况：

完全不懂部署，只想要一个即开即用 App。
不愿意处理登录态、验证码和账号风控。
需要官方授权、强合规的数据接口。
想大规模高频抓取平台数据。
希望 AI 自动判断交易风险并替你下单。

使用风险和边界

这类工具一定要注意边界。

第一，遵守平台规则。

闲鱼有自己的服务条款、风控策略和账号安全机制。自动化访问可能触发限制。不要高频抓取，不要绕过风控，不要把它用于骚扰卖家、批量采集隐私或破坏平台秩序。

第二，保护账号登录态。

state/ 里保存的是登录状态 cookie 文件。它本质上等同于账号访问凭据，不能提交到 Git 仓库，也不要放到不可信服务器上。服务器如果暴露在公网，Web UI 必须修改默认密码，并建议放在 VPN、反向代理鉴权或内网之后。

第三，AI 判断不是事实保证。

AI 可以帮你减少误报，但不能保证商品真实、卖家可信、价格合理或交易安全。最终仍然要人工看商品详情、卖家评价、聊天记录、发货方式和支付流程。

第四，注意成本。

如果每个候选商品都交给多模态模型分析，调用成本可能很快上升。建议先用关键词、价格和区域做强筛选，再把少量候选交给 AI。

第五，注意隐私。

商品截图、聊天相关内容、账号状态和通知内容都可能包含敏感信息。通知 Webhook、日志目录和数据库都要妥善保护。

和普通脚本的差别

普通闲鱼监控脚本通常只做三件事：

搜索关键词。
判断价格。
发通知。

ai-goofish-monitor 更进一步：

用 Web UI 管理任务和账号。
用 AI Prompt 表达复杂购买标准。
用多模态模型看商品图和描述。
用 SQLite 保存结果和价格历史。
用日志页排查任务失败原因。
用代理轮换和多账号机制提高稳定性。
用定时任务支持长期运行。

也正因为功能更多，它的部署和维护成本更高。对普通用户来说，Docker 部署是最省事的方式；对开发者来说，Web UI、FastAPI、Playwright、SQLite 这套结构也比较容易二次开发。

可以怎么用

比较实用的使用方式是从小任务开始。

比如你想找一台二手相机，可以先创建一个任务：

关键词：A7C、索尼 A7C
价格范围：按市场价设置上限
区域：优先本省或同城
新发布范围：最近一天或最近几小时
AI 标准：排除单镜头、排除维修机、排除明显配件、关注快门数和成色
通知：只推送 AI 判断通过的结果

稳定运行后，再逐步增加任务数量。不要一开始就上几十个关键词、多个账号和高频 Cron。先看登录态稳定性、误报率、AI 成本和通知噪音，再调参数。

总结

ai-goofish-monitor 把闲鱼监控从“关键词脚本”推进到了“可管理的 AI 监控系统”。它用 Playwright 处理页面自动化，用 AI 处理复杂判断，用 Web UI 管理任务和结果，用 SQLite 保存数据，再通过多种通知渠道把结果推送出来。

它最适合个人或小团队做特定商品监控，尤其是二手数码、硬件、摄影器材这类价格波动大、发布时间敏感、描述噪音多的品类。

但它也需要谨慎使用：登录态要保护，默认密码要改，抓取频率要克制，AI 结果要人工复核，平台规则和隐私边界不能忽视。把它当成辅助筛选工具，它会很有价值；把它当成全自动交易系统，就容易高估它的能力。

参考链接：

goose：桌面端、CLI 和 API 一体的开源 AI Agent

Fri, 08 May 2026 13:35:45 +0800

goose 是一个运行在本机的开源 AI Agent。它不只面向代码补全，而是希望覆盖代码、研究、写作、自动化、数据分析等更广的任务。项目 README 里的定位很直接：桌面端、CLI 和 API 都提供，既可以给普通用户使用，也可以嵌入到自己的工作流里。

这个项目已经从 block/goose 迁移到 Linux Foundation 旗下的 Agentic AI Foundation（AAIF）。当前仓库是：

`1`	`https://github.com/aaif-goose/goose`

goose 主要由 Rust 和 TypeScript 编写，许可证为 Apache-2.0。GitHub 项目描述是：一个开源、可扩展的 AI agent，不只给出代码建议，还能安装、执行、编辑和测试，并可接入任意 LLM。

goose 解决什么问题

很多 AI 编程工具只停留在“给建议”或“改代码”这一层。goose 的目标更宽一些：让 AI agent 直接在你的机器上完成任务。

它可以用于：

代码修改和测试。
本地自动化任务。
资料研究和写作。
数据分析。
多步骤工作流。
通过 API 嵌入到其他系统。
通过 MCP 扩展外部工具能力。

如果你只想在编辑器里要几段代码，普通 Copilot 类工具已经够用。goose 更适合想把 AI 放进“本机任务执行链”的用户：它可以使用本地环境、连接模型 provider、调用扩展，并通过桌面端或 CLI 进入不同工作方式。

三种入口：桌面端、CLI、API

goose 的一个特点是入口比较完整。

第一种是桌面端。它支持 macOS、Linux 和 Windows，适合不想一直待在终端里的用户，也适合需要更清晰可视化交互的人。

第二种是 CLI。终端用户可以直接安装命令行工具，把 goose 放进日常开发流程里。

第三种是 API。它可以作为可嵌入的 agent runtime，让其他系统或内部工具调用 goose 的能力。

这三个入口对应不同使用习惯。个人开发机可以先从桌面端或 CLI 开始；团队内部工具、自动化平台或实验型 agent 工作流，则更适合看 API 和自定义分发能力。

安装方式

官方 README 推荐先下载桌面端：

`1`	`https://goose-docs.ai/docs/getting-started/installation`

如果只安装 CLI，可以使用官方脚本：

`1`	`curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \| bash`

GitHub Releases 也提供不同平台的构建产物。当前 latest release 信息显示，v1.33.1 发布于 2026-04-29，包含 macOS、Linux、Windows、deb、rpm、Flatpak 等资产。

安装完成后，建议先按官方 Quickstart 配置 provider，再从一个低风险目录开始测试。由于 goose 可以执行本机任务，不建议一开始就在重要生产仓库里给它过高权限。

支持的模型和 provider

goose 支持 15+ provider。README 中列出的方向包括：

Anthropic
OpenAI
Google
Ollama
OpenRouter
Azure
Bedrock
更多 OpenAI-compatible 或云端 provider

它既可以使用 API key，也可以通过 ACP 使用已有的 Claude、ChatGPT 或 Gemini 订阅。

ACP 这一点值得关注。很多用户已经有模型订阅，但不同工具要么不支持直接复用，要么配置方式很割裂。goose 通过 ACP provider 把订阅模型接入 agent 工作流，能减少“订阅在一边、自动化工具在另一边”的割裂感。

不过 provider 政策变化很快。真正使用前，仍然要确认对应服务是否允许这种接入方式、是否有额度限制、是否适合公司代码或敏感数据。

MCP 扩展能力

goose 支持通过 Model Context Protocol（MCP）连接扩展。README 提到它可以连接 70+ extensions。

MCP 的意义在于：agent 不只会“聊天”和“改文件”，还能通过标准协议接入更多工具，比如文档、数据库、浏览器、内部系统、搜索服务、设计工具或项目管理系统。

对个人用户来说，MCP 可以让 goose 连接常用工具。对团队来说，MCP 更像一个安全边界和集成标准：你可以把内部能力包装成 server，让 agent 通过明确接口访问，而不是直接把所有系统暴露给模型。

与代码助手的区别

goose 不只是代码补全工具。更准确地说，它是一个本机 agent runtime。

代码助手通常重点在：

补全代码。
解释代码。
生成函数。
在编辑器里修改局部文件。

goose 更强调：

本机任务执行。
多步骤工作流。
provider 可切换。
扩展能力。
桌面端和 CLI 并存。
API 可嵌入。
不限定在代码任务。

这也意味着它的复杂度更高。你需要考虑模型配置、权限、扩展、工作目录、日志、凭据管理等问题。它不是“越自动越好”的工具，而是更适合被认真配置和逐步引入。

自定义分发

goose 仓库提供 CUSTOM_DISTROS.md，说明可以构建自己的 goose distro，预配置 provider、extensions 和 branding。

这对团队或组织很有意义。

比如团队可以做一个内部版本：

预置公司允许的模型 provider。
默认连接内部 MCP server。
配好安全策略和日志设置。
限制不允许使用的外部服务。
使用自己的品牌和默认引导。

这样普通成员不需要从零理解所有配置，也能减少把 key、provider、扩展配错的风险。

使用建议

如果你第一次尝试 goose，可以按这个顺序来：

先安装桌面端或 CLI。
配置一个你确定可用的 provider。
在测试目录里运行简单任务。
观察它会读取哪些文件、执行哪些动作。
再接入 MCP extension。
最后再尝试复杂代码仓库或自动化工作流。

不要一开始就把 goose 放进生产仓库、给它全部权限、再让它执行模糊任务。AI agent 的能力越强，越需要明确边界。

建议保持几个习惯：

重要改动前先提交 git。
不把 API key 写进项目文件。
只在可信 workspace 里启用高权限操作。
公司代码先确认数据合规和 provider 政策。
对自动化结果保留人工 review。

适合谁用

goose 更适合这些用户：

想要桌面端和 CLI 都可用的 AI agent。
希望使用多个模型 provider。
想通过 MCP 接入更多工具。
需要把 AI agent 嵌入自动化流程。
想在代码之外处理研究、写作、数据分析等任务。
团队希望构建带预配置的内部 agent 分发版。

如果你的需求只是“在 IDE 里补全代码”，goose 可能显得重。
如果你想要一个可以长期扩展的本机 agent 平台，它的设计会更有吸引力。

小结

goose 是 AAIF/Linux Foundation 旗下的开源 AI Agent，定位比传统代码助手更广。它提供桌面端、CLI 和 API，支持 15+ provider、ACP 订阅接入和 70+ MCP extensions，适合把 AI 放进本机工作流和团队自动化体系里。

它的价值不只是“能写代码”，而是把模型、工具、扩展和执行环境放在同一个 agent 框架下。使用时要特别注意权限、凭据和数据边界：先从小任务开始，确认 provider、扩展和执行行为都符合预期，再逐步扩大使用范围。

参考资料

Claude Code Hooks Mastery：13 个 Hooks 生命周期与自动化控制入门

Fri, 01 May 2026 03:11:27 +0800

claude-code-hooks-mastery 是一个围绕 Claude Code Hooks 的学习项目。

它不是只给几个零散脚本，而是把 Claude Code 的 hooks 生命周期、配置方式、脚本写法和常见自动化场景放在一起讲清楚。对于想让 Claude Code 更可控、更像工程化助手的人来说，这类资料很值得看。

Claude Code 默认已经能读代码、改文件、跑命令。但如果你想让它在特定时机自动检查权限、拦截危险操作、注入项目规范、运行测试、提醒团队规则，单靠聊天指令就不够稳定。Hooks 的价值就在这里：把“每次都要提醒 AI 的规则”变成可执行的流程。

Hooks 解决什么问题

使用 Claude Code 一段时间后，常见痛点大概有这些：

每次新会话都要重复告诉它项目规则
担心它执行不该执行的命令
希望文件修改前后自动做检查
想在提交前自动跑格式化、测试或安全扫描
想把团队规范写成固定流程，而不是靠口头提醒
想在工具调用前后拿到上下文，做记录或拦截
希望复杂任务可以触发子代理或专门脚本处理

Hooks 就是为这些“固定时机的自动动作”准备的。

你可以把它理解成 Claude Code 工作流里的事件钩子：当会话开始、用户提交提示词、模型准备调用工具、工具调用完成、代理即将结束等节点发生时，Claude Code 可以执行你配置的脚本。

13 个 Hooks 生命周期

项目 README 的重点之一，是系统整理了 Claude Code 的 13 个 hook 事件。

这些事件覆盖了从会话开始到工具调用、从用户输入到代理结束的多个节点。按用途可以粗略分成几类：

会话启动相关：用于初始化环境、注入项目上下文
用户输入相关：用于检查提示词、补充规则、做审计
工具调用前相关：用于权限判断、命令拦截、安全检查
工具调用后相关：用于记录结果、触发格式化、运行验证
任务结束相关：用于总结、清理、通知或保存状态

这种生命周期设计让你不必把所有规则都写进一个超长提示词里。

比如，权限控制应该发生在工具调用前；格式化检查更适合发生在文件修改后；项目规范注入适合发生在会话开始或用户输入后。把规则放到正确的 hook 节点，通常比把所有内容塞进 system prompt 更可靠。

配置文件在哪里

Claude Code 的 hooks 通常通过设置文件配置。

常见位置包括：

用户级配置：~/.claude/settings.json
项目级配置：.claude/settings.json

用户级配置适合放个人偏好，比如通用安全规则、命令拦截、日志路径。

项目级配置适合放仓库相关规则，比如这个项目必须跑什么测试、哪些目录不能改、生成文件怎么处理、提交前要做哪些检查。

如果你在团队里使用 Claude Code，更推荐把项目级配置放进仓库。这样每个人打开项目时，拿到的是同一套 AI 协作约束，而不是各自凭记忆提醒。

单文件脚本为什么重要

项目里强调了 UV 单文件脚本的写法。

这类脚本的好处是部署简单。一个 Python 文件就可以声明依赖并运行，不必为了一个 hook 单独维护复杂环境。对 hooks 来说，这很合适，因为很多 hook 只是做一件小事：

检查命令是否允许执行
判断文件路径是否安全
读取项目规范并返回给 Claude
扫描输出中是否包含敏感信息
在修改后运行格式化或测试
把事件写入日志

Hook 脚本越小，越容易维护，也越不容易变成新的复杂系统。

可以做哪些自动化

claude-code-hooks-mastery 展示的方向比较多，实际工作中最常见的是下面几类。

1. 权限和安全控制

这是 hooks 最直接的用途。

比如在 Claude Code 准备执行命令之前，先检查命令内容。如果命令包含删除、重置、清空、覆盖等高风险动作，就阻止执行或要求人工确认。

类似规则还可以用于文件路径：

不允许修改生产配置
不允许写入密钥文件
不允许删除迁移脚本
不允许触碰指定目录
不允许执行未批准的网络命令

这类保护放在工具调用前，比写一句“不要做危险操作”更可靠。

2. 上下文注入

很多项目都有固定背景：

技术栈
编码规范
测试命令
分支策略
目录结构
禁止事项
生成文件处理规则

这些内容每次手动告诉 Claude Code 很麻烦，也容易漏。Hooks 可以在会话开始或用户提交提示词后，把必要上下文自动注入进去。

这相当于给 Claude Code 配一个项目级的工作说明书。它不会替代 README 或开发文档，但能让 AI 在执行任务前更快进入正确状态。

3. 修改后的验证

当 Claude Code 修改文件后，可以通过 hook 自动触发检查。

常见动作包括：

运行格式化
运行 lint
运行单元测试
检查类型错误
扫描生成文件
校验 Markdown 或 JSON 格式

这对减少低级错误很有帮助。尤其是 AI 改动多个文件时，修改后自动跑一轮轻量验证，可以更早发现问题。

不过也要注意，hook 里不适合默认塞太重的任务。每次文件改动都跑完整测试套件，可能会让体验变得很慢。更实用的做法是按文件类型、目录和任务风险选择检查范围。

4. 团队规则验证

如果团队已经有明确约定，可以把一部分约定放进 hooks。

比如：

提交信息格式
代码风格规则
禁止直接修改某些生成文件
文档必须同步更新
API 变更必须改测试
某些目录只能用指定工具生成

这会让 Claude Code 更像团队流程的一部分，而不是一个不受约束的外部助手。

当然，hooks 不应该替代 CI。它更适合做本地快速提醒和前置拦截，真正的最终验证仍然应该交给 CI、review 和测试系统。

5. 子代理和专门任务

README 里还提到子代理相关内容。

这类用法适合把复杂任务拆给更专门的流程处理。比如主会话负责理解需求，hook 或配置触发专门的检查、审计、总结、文档整理任务。

对个人用户来说，最先值得做的不是复杂代理编排，而是把重复、明确、低风险的动作交给 hooks。等规则稳定后，再考虑更复杂的自动化。

Statusline 和输出样式

项目还覆盖了状态栏和输出样式。

这部分看起来像体验细节，但对长期使用 Claude Code 很有意义。状态栏可以展示当前上下文、任务状态、环境信息或提示信息；输出样式则可以让 Claude Code 的回答更符合你的工作习惯。

如果你每天都在同一个终端里和 AI 协作，这些细节会影响效率。好的状态提示能减少误操作，也能让你更快判断当前会话是否处在正确项目、正确分支、正确环境里。

不要把 hooks 写得过重

Hooks 很强，但不适合什么都往里面塞。

比较好的规则是：

高频动作要快
安全拦截要明确
输出要短
失败原因要可读
脚本尽量单一职责
重型检查交给显式命令或 CI

如果一个 hook 每次都执行十几秒，用户很快就会想关掉它。如果一个 hook 拦截规则含糊不清，Claude Code 和用户都会难以理解下一步该怎么做。

Hooks 最适合处理那些边界清楚的事情：允许或拒绝、补充上下文、记录日志、运行轻量检查、提示下一步。

适合怎样的使用者

如果你只是偶尔让 Claude Code 改一小段代码，可能暂时不需要深入 hooks。

但如果你符合下面几种情况，就很适合研究这个项目：

高频使用 Claude Code
经常让 AI 修改真实项目代码
担心 AI 执行危险命令
想把团队规范自动注入 AI 工作流
希望修改后自动跑检查
想把重复提醒变成配置
正在搭建更稳定的 AI 编程流程

尤其是多人协作项目，hooks 的意义会更明显。它可以把一部分团队经验沉淀成脚本，而不是靠每个人临时提醒 AI。

使用时要注意

第一，先从安全类 hook 开始。

相比复杂自动化，命令拦截、路径保护、敏感文件检查更容易落地，也更能立刻降低风险。

第二，项目级规则要谨慎提交。

.claude/settings.json 会影响所有使用这个仓库的人。把规则提交前，最好确认它不会过度限制正常开发，也不会依赖只有你本机才存在的路径。

第三，hook 输出要简洁。

Claude Code 会消费这些输出。输出太长，会污染上下文；输出太模糊，又起不到指导作用。最好只返回必要判断和下一步建议。

第四，保持可调试。

Hooks 一旦变多，问题可能出在配置、脚本、权限、路径、依赖或 Claude Code 本身。给脚本留下清晰日志，会让后续排查轻松很多。

参考

disler/claude-code-hooks-mastery

最后一句

Claude Code Hooks 的价值，是把“希望 AI 每次都记住的规矩”变成真正会执行的流程。

如果你已经开始把 Claude Code 用在真实项目里，hooks 会是从“会聊天的编程助手”走向“可约束的工程协作者”的关键一步。