obs-agent-connector 命令参考¶

本文汇总 obs-agent-connector 支持的 Agent、常用命令和命令行参数，便于快速查阅。

支持的 Agent¶

Agent 标识	产品名称	集成方式	macOS	Linux	Windows	说明
`claude`	Claude Code	`obs-agent-connector` 内置	✅	✅	✅	使用 Stop / SessionEnd Hook 适配器
`codebuddy`	CodeBuddy	`obs-agent-connector` 内置	✅	✅	✅	支持 Stop / SessionEnd Hook 及原生 `index.json` 重放；Linux x64 已通过产品验证
`codex`	Codex	`obs-agent-connector` 内置	✅	✅	✅	使用 Stop Hook 适配器，并内置 Codex 信任与配置处理能力
`cursor`	Cursor	`obs-agent-connector` 内置	✅	✅	✅	检测 `~/.cursor`，优先使用 `cursor-agent`，并管理用户级 Cursor Hooks
`dsh`	DeepSeek Harness	`dsh-otel-plugin`	✅	✅	✅	使用 DeepSeek Harness 配置包
`hermes`	Hermes	`hermes-otel-plugin`	✅	✅	❌	使用 Hermes 插件
`opencode`	OpenCode	`opencode-otel-plugin`	✅	✅	✅	使用 `~/.config/opencode` 下的 OpenCode 配置目录
`openclaw`	OpenClaw	`openclaw-otel-plugin`	✅	✅	✅	使用 OpenClaw 插件
`qoder`	Qoder	`qoder-otel-plugin`	✅	✅	✅	自动识别中国版或国际版目录，并传入对应的 `--variant` 参数
`workbuddy`	WorkBuddy	`workbuddy-otel-plugin`	✅	❌	✅	使用检测到的 WorkBuddy 配置目录，并在其中写入 `gtrace.json`

Agent 说明¶

Agent 标识	说明
`claude`	使用内置适配器，并将托管的运行时配置写入 `~/.obs-agent-connector/claude/`。
`codebuddy`	使用内置适配器。连接器负责管理 `~/.codebuddy/settings.json` 中的 Hook 配置。
`cursor`	使用内置适配器，检测本地 Cursor CLI，并在可用时优先使用 `cursor-agent`。
`dsh`	当 `PATH` 中存在 `dsh` 可执行文件，或存在 `~/.dsh` 目录时可被发现。默认配置为 `web`，运行时配置由 `dsh-otel-plugin` 生成。
`qoder`	自动检测国际版或中国版目录，并使用对应的变体。
`qoder-cn`	兼容旧版本的 Agent 标识，始终使用中国版目录。
`hermes`	Hermes 使用 YAML 配置，不属于当前支持的 JSON 配置结构，因此 CLI 不管理其运行时启用或停用状态。
`openclaw`	支持通过 `~/.openclaw/openclaw.json` 启用或停用运行时；由于插件自行管理私有配置结构，暂不支持 `config <agent>`。
`workbuddy`	支持 macOS 和 Windows，暂不支持 Linux。

常用命令¶

obs-agent-connector list
obs-agent-connector status <agent>
obs-agent-connector discover
obs-agent-connector discover -u
obs-agent-connector install <agent>
obs-agent-connector config <agent> list
obs-agent-connector config <agent> edit --enabled=false --endpoint=<Endpoint>
obs-agent-connector update <agent>
obs-agent-connector enable <agent>
obs-agent-connector disable <agent>
obs-agent-connector remove <agent>
obs-agent-connector uninstall
obs-agent-connector version
obs-agent-connector version -u

常用参数¶

通用安装参数¶

执行 install <agent> 时，常用参数如下：

参数	说明
`--endpoint`	OBS / GTrace 数据接收地址，例如 `<Endpoint>`
`--x-token`	数据上报使用的身份验证 Token
`--agent-id`	覆盖自动生成的 `agent_id`
`--agent-name`	覆盖自动生成的 `agent_name`
`--static-base`	覆盖本次安装使用的基础地址，外部开源插件从 `<static-base>/agent_plugins` 获取
`--yes`	跳过确认步骤
`--dry-run`	仅输出执行计划和命令预览，不进行实际修改

默认身份信息生成规则：

未指定 --agent-id 时，CLI 自动生成 agid_<不含短横线的 uuidv4>；
未指定 --agent-name 时，CLI 自动生成 <hostname>_<agent>_<YYYYMMDD>。

外部插件调用约定：

连接器只向插件传递公共版本、--type gtrace、Endpoint、Token、标签以及配置或变体参数；
插件安装器自行负责压缩包下载、校验和验证、插件注册和私有运行时配置；
连接器不会传递 --source，也不会读写外部插件的私有 gtrace.json。

内置适配器安装参数¶

以下参数适用于内置的 claude、codebuddy、codex 和 cursor 适配器：

参数	说明
`--trace-path`	覆盖 Trace 数据上报路径
`--metrics-path`	覆盖 Metrics 数据上报路径
`--header`	添加 HTTP 请求头，可重复使用
`--tag`	添加资源属性，可重复使用
`--capture-content`	内容采集模式，可选值为 `none`、`preview` 或 `full`
`--max-chars`	采集内容的最大字符数
`--enable`	将运行时配置设置为 `enabled=true`
`--disable`	将运行时配置设置为 `enabled=false`

CodeBuddy 的配置会合并写入现有的 ~/.codebuddy/gtrace.json，不会删除无法识别的字段。

`discover` 参数¶

参数	说明
`-u`	更新已安装的插件，并安装发现但尚未安装的插件
`--endpoint`	覆盖本次执行使用的已保存 Endpoint
`--x-token`	覆盖本次执行使用的已保存 Token
`--yes`	跳过确认步骤
`--dry-run`	仅输出发现、安装和更新计划

`update` 参数¶

参数	说明
`--static-base`	覆盖插件下载基础地址
`--yes`	跳过确认步骤
`--dry-run`	仅输出更新计划

使用说明：

update 每次只接受一个 Agent；
update claude、update codebuddy、update codex 和 update cursor 会重新校准内置 Hook；
更新外部插件时会保留当前运行时配置。

`enable` 和 `disable` 参数¶

参数	说明
`--dry-run`	仅输出配置变更，不写入配置文件

当前支持通过 JSON 配置启用或停用运行时的 Agent：

claude
codebuddy
codex
cursor
dsh
opencode
openclaw
qoder
workbuddy

`remove` 参数¶

参数	说明
`--yes`	跳过确认步骤
`--dry-run`	仅输出移除计划
`--purge-config`	同时删除运行时配置；对于 CodeBuddy，还会删除数据上报状态

`version` 参数¶

参数	说明
`-u`	将连接器更新到最新版本
`--offline`	仅显示本地版本，不检查远端版本

安装脚本参数¶

`install.sh`¶

参数	说明
`--version`	安装指定版本的连接器，默认为 `latest`
`--install-dir`	连接器二进制文件的安装目录
`--config-dir`	连接器配置目录
`--download-base-url`	连接器安装包和元数据的下载基础地址
`--endpoint`	OBS / GTrace 数据接收地址
`--x-token`	身份验证 Token
`--plugin-source`	插件来源，当前支持 `oss` 或 `github`
`--plugin-base-url`	外部插件下载基础地址
`--binary-only`	仅更新连接器二进制文件，不写入 `config.json`

`install.ps1`¶

参数	说明
`-Version`	安装指定版本的连接器，默认为 `latest`
`-InstallDir`	连接器二进制文件的安装目录
`-ConfigDir`	连接器配置目录
`-DownloadBaseUrl`	连接器安装包和元数据的下载基础地址
`-Endpoint`	OBS / GTrace 数据接收地址
`-XToken`	身份验证 Token
`-PluginSource`	插件来源，当前支持 `oss` 或 `github`
`-PluginBaseUrl`	外部插件下载基础地址
`-BinaryOnly`	仅更新连接器二进制文件，不写入 `config.json`
`-NoPathUpdate`	不更新用户的 `PATH` 环境变量

使用示例¶

安装内置的 CodeBuddy 适配器：

obs-agent-connector install codebuddy --yes

使用指定的 Endpoint 和 Token 安装外部插件：

obs-agent-connector install dsh \
  --endpoint <Endpoint> \
  --x-token <X-Token> \
  --yes

发现所有 Agent，并同步已安装的插件：

obs-agent-connector discover -u --yes

移除插件但保留其配置：

obs-agent-connector remove codex --yes

更新连接器：

obs-agent-connector version -u

obs-agent-connector 命令参考¶

支持的 Agent¶

Agent 说明¶

常用命令¶

常用参数¶

通用安装参数¶

内置适配器安装参数¶

discover 参数¶

update 参数¶

enable 和 disable 参数¶

remove 参数¶

version 参数¶