goose 安装与自定义 Provider 配置

goose 是跑在你电脑上的通用 AI 助手。除了代码，它也能做检索、写作、自动化和数据整理。你可以用桌面版、终端或接口来使用它，桌面版和终端版共用同一套模型配置。它适合处理重复的编码工作，也能连接 GitHub、数据库和文件。

安装前准备

goose 提供 Desktop 和 CLI 两种安装方式。Desktop 是带窗口的桌面版，CLI 是在终端中输入命令使用的版本。两边共用核心配置，包括 Provider 和模型。Provider 可以理解为“告诉 goose 使用哪个模型服务”的连接配置。

想要窗口

goose Desktop

macOS 下载 zip
或 brew cask
Linux 用安装包

只要终端

goose CLI

download_cli.sh
或 Homebrew CLI
然后 goose session

Windows

先选环境

Git Bash 或 MSYS2
也可以用 PowerShell
命令找不到就加 PATH

macOS 可以用下载或 Homebrew。Linux 桌面版用发行版安装包。Windows 先看官方给出的终端环境。

开始前准备好当前模型列表里的模型 ID。模型 ID 就是模型服务用来识别具体模型的名称，使用时需要完整复制。

安装并首次启动

想要窗口

macOS 官方给出两条安装路径：

从安装页下载。页面上有 macOS Silicon 和 macOS Intel。下载后解压 zip，运行里面的程序。
或者使用 Homebrew：

brew install --cask block-goose

它下载的是同一个应用，并可以顺带处理更新。

如果是 Apple Mac M3，打开后没有窗口，检查 ~/.config 是否可读写。goose 要用这个目录写日志。

Linux 桌面版从安装页下载。官方列出 DEB（Ubuntu/Debian）、RPM（RHEL/Fedora）和 Flatpak。Debian 或 Ubuntu 的步骤是：下载 DEB，进入保存它的目录，执行 sudo dpkg -i (filename).deb，再从应用菜单打开 goose。把 (filename) 换成实际文件名。

Windows 桌面版从安装页下载，解压 zip，运行里面的程序。

只要终端

macOS 和 Linux 执行：

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

不想在安装过程中做交互配置时，在前面加上 CONFIGURE=false：

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

macOS 还可以执行：

brew install block-goose-cli

更新已安装的 CLI 用：

goose update

Windows 官方要求下面三种环境之一：Git Bash（随 Git for Windows 提供，官方标成推荐）、MSYS2，或 Windows 10/11 自带的 PowerShell。Git Bash 和 MSYS2 用上面同一条 download_cli.sh。PowerShell 则先下载脚本再运行：

Invoke-WebRequest -Uri "https://raw.githubusercontent.com/aaif-goose/goose/main/download_cli.ps1" -OutFile "download_cli.ps1"
.\download_cli.ps1

如果提示 goose 不在 PATH 里，按安装页把 ~/.local/bin 或 %USERPROFILE%\.local\bin 加进当前 shell 的配置，然后重开终端。PATH 是终端查找程序位置的一组目录，没加进去时，程序已经安装也可能无法直接输入名称运行。

2026-10-09 的 CLI 版本是 1.54.0。安装脚本默认把程序放到 ~/.local/bin。环境变量 GOOSE_BIN_DIR 可以改这个目录。改了之后，脚本不会自动写入 shell 配置，终端会提示该目录不在 PATH 里。把那个目录加进 PATH，或用完整路径运行。

第一次使用时，goose 会让你配置 Provider。可以先跳过自带供应商，按下一节添加自定义 Provider。终端里进入你要工作的目录，运行：

goose session

从 OmniProxy 取得连接参数

从你自己的 OmniProxy 准备地址、密钥和模型名。自定义 Provider 的官方示例把 base_url 写到 /v1/chat/completions，所以这里也按这个写法：

API URL:  https://your-omniproxy-origin.example/v1/chat/completions
API Key:  <YOUR_OMNIPROXY_API_KEY>
Models:   从 OmniProxy 当前模型列表复制，多个用英文逗号分开

模型名从 OmniProxy 当前列表整段复制，斜杠也保留。2026-10-09 供应商文档里的两个对照 ID 是 Grok 的 grok-4.7，以及 OpenAI 文档中的 gpt-6-luna。gpt-6-luna 支持 Chat Completions；函数调用在 Chat Completions 里只在 reasoning_effort 为 none 时支持。列表里没有的名字不要照抄。

填写工具配置

自定义 Provider 使用 OpenAI、Anthropic 或 Ollama 兼容格式。兼容格式可以理解为：工具按照某种通用接口发送请求。接 OmniProxy 时选 OpenAI Compatible。

桌面版

点左上角按钮打开侧边栏。
点 Settings。
点 Models。
点 Configure providers。
点窗口底部的 Add Custom Provider。
Provider Type 选 OpenAI Compatible。Display Name 可以写成 OmniProxy。API URL 填写上一节的地址。需要密钥时勾选要求 API Key，并填入 OmniProxy 的密钥。Available Models 填写模型名，多个用英文逗号分开。
点 Create Provider。

桌面版目前不能在这个窗口里定义自定义请求头。需要请求头时，创建后再改配置文件。

终端

运行：

goose configure

选择 Custom Providers，再选择 Add A Custom Provider。API Type 选 OpenAI Compatible，然后按提示填写名称、API URL、是否需要密钥、模型名和是否支持流式响应。

Windows 上手动配置时，如果钥匙串报错，安装页的说明是：提示是否存入 keyring 时选择不存，改用环境变量。然后重新运行 goose configure。钥匙串是系统用来保存密钥的小型安全存储。

配置文件

官方给出的目录是：

macOS 和 Linux：~/.config/goose/custom_providers/
Windows：%APPDATA%\Block\goose\config\custom_providers\

文件可以仿照官方示例。把名称、地址和模型换成你的，密钥放在 api_key_env 指定的环境变量里，不要把真实密钥写进文件：

{
  "name": "omniproxy",
  "engine": "openai",
  "display_name": "OmniProxy",
  "api_key_env": "OMNIPROXY_API_KEY",
  "base_url": "https://your-omniproxy-origin.example/v1/chat/completions",
  "models": [
    { "name": "grok-4.7", "context_limit": 128000 },
    { "name": "gpt-6-luna", "context_limit": 128000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

context_limit 按官方示例保留一个数字。实际上下文以模型和 OmniProxy 为准，不要把这个示例数字当成该模型的官方上限。使用前执行：

export OMNIPROXY_API_KEY="<YOUR_OMNIPROXY_API_KEY>"

进入工作目录后：

goose session --provider omniproxy --model grok-4.7

--model 换成列表里的完整 ID。goose session 没有 start 子命令。--provider 和 --model 也可以写成环境变量 GOOSE_PROVIDER、GOOSE_MODEL。网关不校验密钥时，OMNIPROXY_API_KEY 仍要有值，可以是一串只在本机使用的占位字符。2026-10-09 这样读到了文件。

窗口

Settings

侧边栏 Settings
Models 页
Add Custom Provider

终端

goose configure

选 Custom Providers
再选添加
类型选 OpenAI Compatible

文件

custom_providers

macOS 与 Linux 在 ~/.config
Windows 在 APPDATA
base_url 按官方示例

三条路写的是同一类配置。Provider 类型选 OpenAI Compatible。

验证一个真实任务

进入一个有普通文件的目录，运行上一节的 goose session。让它读出你指定的文件的第一行。它需要给出文件内容，而不是只显示配置已保存。

要读文件或执行命令，会话里需要 Developer 扩展。Developer 扩展可以理解为让 goose 处理本地文件和命令的工具模块。默认配置一般会带上。如果它回答自己没有文件工具，在命令里加上：

--with-builtin developer

不要同时加上 --no-profile，那个参数会关掉默认扩展。

2026-10-09 用 goose 1.54.0 读到了指定文件的第一行。第一次回复可能要一分钟左右。

然后在 OmniProxy 的调用记录里确认来源和模型名。

启动

能进入会话

goose session
Provider 是刚加的
模型名在列表里

任务

它真的做了

例如列出当前目录
看它的回复
不要只看保存成功

记录

网关看得到

地址以文档示例为准
密钥不写进仓库
模型 ID 与列表一致

保存 Provider 之后，还要用一次真实会话确认。

常见错误

找不到 goose 命令：按安装页把安装目录加入 PATH，然后重开终端。
M3 桌面版没有窗口：检查 ~/.config 的读写权限。
钥匙串失败：不要存入 keyring，改用环境变量。
模型不在列表里：桌面版可以选 Use custom model 手写模型名。goose configure 不能输入自定义模型名；终端要改用桌面版，或直接改配置里的 GOOSE_MODEL。
地址连不上：确认 API URL 与官方示例一样写到 /v1/chat/completions，并且 OmniProxy 正在运行。
它说读不了文件：加上 Developer 扩展，并且不要使用 --no-profile。
返回 unsupported Responses role: system：地址通常没错。换模型列表里的另一个完整 ID。

官方参考

安装见 Install goose。自定义 Provider 见 goose providers。举例用的模型 ID 见 xAI 模型页和 GPT-6 Luna。

用你自己的 OmniProxy 配置替换每个占位符。不要发布真实密钥。

保存成功或 HTTP 200 不单独等同完整 Agent 兼容。请在 OmniProxy 调用记录中确认来源和模型。

官方来源 · goose ↗