将您的 Agent 连接到 GitLab Orbit
Tier: 专业版,旗舰版
Offering: JihuLab.com,私有化部署
GitLab Orbit CLI 可将您机器上的 Agent 连接到 GitLab Orbit。 GitLab Orbit skill 可教会您的 Agent 查询您的极狐GitLab 数据,例如合并请求、流水线 和漏洞,以及本地图谱。
极狐GitLab Duo Agent Platform 内置了 GitLab Orbit。更多信息,请参见 极狐GitLab Duo 中的 GitLab Orbit。 对于无法运行 shell 命令或更倾向于使用模型上下文协议(MCP)的 Agent,请使用 GitLab Orbit MCP 端点。 如果您的 Agent 已连接到极狐GitLab MCP 服务器,请将 GitLab Orbit 工具添加到该连接中。
设置您的 Agent
使用 GitLab CLI (glab) 安装 GitLab Orbit CLI 并设置您的 Agent。 如需快速入门,请参见快速入门。
先决条件:
- glab 1.126 或更高版本。要检查您的版本,请运行 glab version。
- 设置流程支持的 Agent。有关列表,请参见设置选项。
要设置您的 Agent:
- 转到您机器上的 Git 代码仓库。任何代码仓库均可。
- 运行 glab orbit setup。 首次使用时,glab 会询问是否下载 GitLab Orbit CLI。
- 在 Agent 列表中,保留或清除设置选中的 Agent,然后按 Enter。
- 当设置询问 Agent 插件时,选择是否安装它们,然后按 Enter。 这些插件是可选的。不安装它们,GitLab Orbit 也能照常工作。 要安装它们,请保持选中 Install the agent plugins。要跳过它们,请选择 Skip the agent plugins。
设置会为您的 Agent 安装 GitLab Orbit skill,并且除非您跳过,还会安装在 Claude Code 和 OpenCode 中显示 GitLab Orbit 调用的 Agent 插件。 随后,它会为代码搜索建立代码仓库索引。要检查代码仓库是否已建立索引,请运行 glab orbit workspace list。要加载该 skill,请启动 Agent 的新会话。要更新设置,请再次运行该命令。如需引导式的首次会话,请参见快速入门的第 3 步。
要在没有终端的情况下运行设置,例如从 Agent 或脚本中运行,请使用 --yes 确认提示:
shellglab orbit --yes setup --yes
第一个 --yes 确认下载。第二个跳过设置的提示并安装 Agent 插件。要跳过 Agent 插件,请添加 --skip agent-plugins。
要查询您的极狐GitLab 数据,还需使用 glab 登录。
如果您安装的是独立二进制文件,请运行 orbit 代替 glab orbit。
设置选项
设置支持 Claude Code (claude)、Codex (codex)、极狐GitLab Duo (duo)、OpenCode (opencode) 和 Pi (pi)。 默认情况下,设置会选择它在您机器上检测到的 Agent。
shellglab orbit setup [<agent>...] [options]
| 选项 | 描述 |
|---|---|
| <agent> | 仅设置这些 Agent,例如 claude codex。即使未检测到指定的 Agent,设置也会添加它。 |
| --all | 设置所有受支持的 Agent。 |
| --yes, -y | 跳过提示并使用默认答案。 |
| --skip <component> | 跳过 instructions、hooks、skill 或 agent-plugins。可重复使用。 |
| --install <component> | 无需提示即可添加组件,例如 --install agent-plugins。可重复使用。 |
| --skill full | 安装完整的 skill 文件,代替包装 skill。 |
| --no-index | 不为代码仓库建立索引。 |
| --project | 写入当前项目,代替您的用户配置。 |
| --dir <path> | 写入 <path>中的项目。隐含 --project。 |
| --dry-run | 显示更改,不写入任何内容。 |
| --verbose, -v | 列出设置更改的每个文件。 |
设置所做的更改
默认情况下,设置会写入您的用户配置,因此更改仅影响您本人。
| 组件 | Agent | 更改 |
|---|---|---|
| 指令 | 全部 | 每个新会话都会加载指令,以使用 orbit grep 搜索并使用 orbit context 读取代码。设置会移除先前设置写入 CLAUDE.md 或 AGENTS.md的块。 |
| Hooks | Claude Code、Codex、极狐GitLab Duo、OpenCode、Pi | 用于加载指令的 hook,以及提醒使用 orbit grep。对于 Claude Code,当 Agent 在已建立索引的代码仓库中运行 grep、rg、ack 或 ag 时会出现该提醒,且绝不会阻止该调用。对于 OpenCode,每个会话会出现一次提醒。 |
| Skill | Claude Code、Codex、极狐GitLab Duo、OpenCode | orbit skill,位于 ~/.agents/skills/orbit。对于极狐GitLab Duo,设置会写入完整的 skill 文件。对于 Claude Code,设置还会在 ~/.claude/skills/中链接该 skill,并在 settings.json中允许该 skill 命令,以便该 skill 无需提示即可加载。 |
| Agent 插件 | Claude Code、OpenCode | 一个显示每次 GitLab Orbit 调用的插件。对于 Claude Code,设置会在 ~/.claude/orbit/claude_plugin中安装 gitlab-orbit 插件,并在 settings.json中启用它;如果使用 --project,则在 .claude/settings.local.json中启用。对于 OpenCode,设置会在 ~/.config/opencode/plugins/orbit-ui/中安装 orbit-ui 插件。 |
其他支持 Agent Skills 规范的 Agent,例如 Gemini CLI, 也可以从 ~/.agents/skills/orbit 加载该 skill。
默认情况下,设置会安装一个包装 skill,用于加载您的极狐GitLab 实例所提供的 skill,因此该 skill 始终与您的实例匹配。如果 CLI 无法从您的实例获取该 skill,则使用 CLI 内置的副本。
您的实例还会提供 orbit-start skill,它会引导您完成首次会话。设置不会安装它。Agent 可通过 glab orbit skills get orbit-start 加载它。有关提示,请参见快速入门的第 3 步。
设置遵循以下规则:
- 设置仅更改其标记之间的文本以及它标记为自身所有的条目。
- 在设置首次更改文件之前,它会将副本保存为 <name>.orbit-backup。
- 设置会在您运行该命令的代码仓库中将 glab 选项 orbit_cli_auto_run 设置为 true,以便 hook 无需提示即可运行。 要为所有代码仓库设置该选项,请运行 glab config set orbit_cli_auto_run true --global。
- 使用 --project 或 --dir 时,设置会将 .claude/settings.json、.codex/hooks.json、.gitlab/duo/hooks.json 和 .pi/extensions/orbit.ts 等文件写入项目中。 团队通常会提交这些文件,因此该更改可以传达给您的团队成员。
在您的 Agent 中显示 GitLab Orbit 调用
glab orbit setup 可以为 Claude Code 和 OpenCode 安装可选的 Agent 插件,用于显示每次 GitLab Orbit 调用以及该会话调用的摘要:
- 在 Claude Code 中,该插件会在对话记录中标记每次调用,例如 ◎ Searched code login,并在提示下方显示摘要。
- 在 OpenCode 中,该插件会在提示上方显示最新调用,并在提示页脚中显示摘要。
先决条件:
- 对于 Claude Code,版本需为 2.1.287 或更高版本。
要安装这些插件,请运行 glab orbit setup 并选择 Install the agent plugins。 然后启动 Agent 的新会话。
要关闭该插件:
- 在 Claude Code 中,运行 /plugin 并关闭 gitlab-orbit。
- 在 OpenCode 中,删除 ~/.config/opencode/plugins/orbit-ui/ 目录。
移除设置
要移除设置写入的内容,包括 orbit skill 和 ~/.claude/skills/orbit 链接,请运行:
shellglab orbit uninstall
该命令会保持每个文件的其余部分不变。如果您在设置之后编辑过某个文件,该命令会保留该文件及其备份。它接受与设置相同的 Agent 名称以及 --yes、--dry-run、--verbose、--project 和 --dir 选项。