Goose 桌面应用完整上手指南：从安装到跑通第一个任务

Goose 桌面应用完整上手指南：从安装到跑通第一个任务

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose

当你不想再敲命令、希望 AI 直接安装依赖、执行任务、修改文件时，Goose 桌面应用把开源 AI 代理 goose 的能力装进了图形界面。这篇指南带你完成三件事：安装 Goose Desktop、跑通第一次对话、用食谱自动化一个流程。

它解决什么问题

这一节先给你一个判断标准：Goose 桌面应用适合谁，不适合谁。

一句话定位：goose 是一个可扩展的开源 AI 代理，能对接任意 LLM 完成"安装、执行、编辑、测试"；桌面应用是它的 Electron + React 图形外壳，核心逻辑在 ui/desktop/。

不适合谁：如果你只需要纯 CLI 工作流，或者要在服务器上无头部署，直接用 goose 命令行即可，桌面应用面向本地工作站。

准备工作与安装 📦

这一节给你两条安装路径，按你的环境二选一。

系统要求

以仓库真实配置为准（见 ui/desktop/package.json 与 ui/desktop/README.md）：

• macOS / Windows / Linux 工作站，图形界面环境
• 源码构建需：Node.js^24.10.0、pnpm>=10.30.0、Hermit 依赖管理器
• Linux 打包额外需要dpkg与fakeroot（Debian/Ubuntu：sudo apt install dpkg fakeroot）
• 桌面应用版本以 ui/desktop/package.json 中version字段为准（当前为 1.48.0）

两条路径怎么选

官方安装包在 macOS 上是签名并公证的.app/.zip；Linux 支持 zip、.deb、.rpm、flatpak；Windows 走 Squirrel 安装器。产物输出目录在 ui/desktop/README.md 的 "Building for different platforms" 一节有完整表格。

源码构建步骤

git clone https://gitcode.com/GitHub_Trending/goose3/goose cd goose source ./bin/activate-hermit cd ui/desktop pnpm install pnpm run start

pnpm run start实际执行仓库根部的just run-ui，因此需要安装just命令。开发模式下界面会同时构建 SDK 并拉起内嵌的 goose CLI 二进制，通过 ACP 协议通信。

第一次运行：跑通一个真实任务

这一节以"让 Goose 在你的目录里跑一个真实任务"为主线，共 5 步。

第 1 步：进入首次引导。启动后会出现引导流程（源码在 ui/desktop/src/components/onboarding/）。这里选择模型提供方：云端 API（如 Anthropic、Google、OpenAI 等）或本地 Ollama 模型。

第 2 步：选择工作目录。界面底部控制栏有目录切换器（ui/desktop/src/components/bottom_menu/DirSwitcher.tsx），把它指向你要处理的本地项目。

第 3 步：发起会话。左侧导航进入 Chat（侧边栏含 Home、Chat、Recipes、Apps、Scheduler、Extensions、Settings 七个入口，见 documentation/docs/guides/desktop-navigation.md）。在输入框（ui/desktop/src/components/ChatInput.tsx）输入一个具体任务，例如"检查这个目录下的代码并修复 lint 错误"。

第 4 步：批准工具调用。代理开始行动后，每个敏感操作（执行命令、写文件）会弹出确认按钮（ui/desktop/src/components/ToolApprovalButtons.tsx）。逐条审核或按你的信任度放行。

第 5 步：查看执行结果。每条工具调用都有状态指示与响应内容（ui/desktop/src/components/ToolCallWithResponse.tsx），底部栏还有上下文窗口占用与费用统计（ui/desktop/src/components/bottom_menu/ContextWindowIndicator.tsx、CostTracker.tsx）。

跑完一轮，你就完成了"输入任务 → 授权 → 观察执行 → 核对结果"的完整闭环。

高频场景实战

这一节给出 3 个真实使用场景，每个都按"目标 → 关键操作 → 你会得到"展开。

场景一：多会话并行处理

目标：一个会话改代码，另一个会话查文档，互不污染上下文。

关键操作：在侧边栏打开 Sessions（ui/desktop/src/components/sessions/SessionsView.tsx），每个会话独立创建，各自的模型与目录设置互不影响；用会话列表（SessionListView.tsx）随时切回旧会话。

你会得到：并行的工作流，历史会话可回溯，上下文按会话隔离。

场景二：用食谱固化重复任务

目标：把"每周代码体检"这类多步流程变成一键操作。

关键操作：侧边栏进入 Recipes，视图代码在 ui/desktop/src/components/recipes/RecipesView.tsx。新建时用 RecipeActivityEditor.tsx 编排步骤；运行前会弹出参数输入框（ui/desktop/src/components/ParameterInputModal.tsx）让你填变量。食谱的 YAML 结构与官方文档见 documentation/docs/guides/recipes/，仓库内也有现成示例 workflow_recipes/。

你会得到：一个可重复、可分享的自动化模板，下次只需填参数。

场景三：接入 MCP 扩展

目标：让 Goose 能操作外部系统，如代码仓库、日历、浏览器。

关键操作：侧边栏进入 Extensions（ui/desktop/src/components/extensions/ExtensionsView.tsx），通过安装弹窗（ExtensionInstallModal.tsx）添加扩展；底部扩展菜单（ExtensionMenu.tsx）可快速切换当前会话启用的扩展。内置扩展源码在 crates/goose/src/，MCP 服务器示例在 examples/mcp-wiki/。

你会得到：一个带外部工具集的会话，代理可直接调用这些工具。

设置与调优

这一节是可照做的短清单，全部入口在 Settings 内（源码目录 ui/desktop/src/components/settings/）。

• 侧边栏改样式：Settings > App > Navigation，可在 Tile/List 两种样式、四个边位置、Push/Overlay 两种模式间切换，并支持拖拽排序、隐藏条目。
• 改快捷键：Settings > Keyboard，所有自定义快捷键集中在这里。
• 换模型与调参数：底部控制栏直接切换模型；深度配置在 Settings > Models。
• 控上下文：盯住底部上下文窗口指示器，接近上限时新开会话或清理旧消息。
• 收紧权限：Settings > Permission 与 Security，限制代理可执行的操作范围。
• 跑本地模型：Settings 下的 localInference 分区接 Ollama 或内置推理，适合离线场景。
• 调回答风格：Settings > response_styles，统一代理的输出语气。

故障排查清单 🩺

这一节只收录构建与运行中真实高频的 5 类问题。

写在最后：三个下一步动作

这一节给你 3 个具体动作和 3 个入口链接。

1. 打开 documentation/docs/guides/recipes/，挑一个食谱模板改造成你自己的第一个自动化流程。
2. 到 ui/desktop/src/components/settings/ 对照目录，把 Permission 与 Models 两节过一遍，按你的信任度收紧权限。
3. 阅读 ui/desktop/README.md 的 "Running with an external ACP backend" 一节，了解桌面端与 goose CLI 通过 ACP 协议通信的原理。

以上三条走完，Goose 桌面应用的核心能力你已经全部用过了。

【免费下载链接】goosean open source, extensible AI agent that goes beyond code suggestions - install, execute, edit, and test with any LLM项目地址: https://gitcode.com/GitHub_Trending/goose3/goose