消息通道与插件连接

使用 moi-cli agent 的消息通道与插件连接子命令,为智能体或团队建立入站消息接收连接、维护外部渠道实例与回调规则,以及完成外部插件账号的 OAuth 授权与解绑。执行前请先完成 配置与身份认证。

连接入站消息通道

外部聊天平台的应用创建与权限配置见 IM 双向通信。在终端创建入站连接前,先查询当前部署开放的接入能力组合(provider、channel_type、receive_mode)以及目标智能体已有的连接:

moi-cli -auth pat -o agent list-ingress-capabilities --workspace-id "$WORKSPACE_ID"

moi-cli -auth pat -o agent list-ingress-connections \
  --workspace-id "$WORKSPACE_ID" \
  --target-kind agent \
  --target-workspace-id "$AGENT_WORKSPACE_ID" \
  --target-id "$AGENT_ID"

若当前部署支持 slack、slack_app 与 managed_stream 组合且尚无可用连接,将目标智能体、可用模型及 Slack 凭据写入受权限保护的本地文件 ingress.json(可通过 moi-cli schema agent create-ingress-connection 核对输入结构):

{
  "target": {
    "kind": "agent",
    "workspace_id": "<agent-workspace-id>",
    "id": "<agent-id>"
  },
  "provider": "slack",
  "channel_type": "slack_app",
  "receive_mode": "managed_stream",
  "agent_model": "<available-model>",
  "managed_stream": {
    "app_id": "<slack-app-id>",
    "app_token": "<slack-app-token>",
    "bot_token": "<slack-bot-token>"
  }
}

创建连接并读取运行状态:

INGRESS_JSON="$(moi-cli -auth pat -o agent create-ingress-connection \
  --workspace-id "$WORKSPACE_ID" \
  --json-file ingress.json)"

export CONNECTION_ID="$(printf '%s' "$INGRESS_JSON" | jq -r '.id')"

moi-cli -auth pat -o agent get-ingress-connection \
  --workspace-id "$WORKSPACE_ID" \
  --connection-id "$CONNECTION_ID"

创建 Slack 托管长连接后,服务端自动启动接收器。再次运行 get-ingress-connection 检查 desired_state、observed_state 与 last_error_code:

  • 处于 starting 或 reconnecting 时继续有限次观察状态收敛。

  • 出现 auth_failed 或 config_invalid 时先核正外部应用令牌与权限配置。

  • 状态正常后,在 Slack 向应用发送一条验证消息,核对目标智能体运行记录与会话回复以确认收发链路就绪。

维护场景

命令与说明

校验回调模式连接

agent verify-ingress-connection 仅用于回调接收模式,Slack managed_stream 长连接无需调用该命令。

回调或邮件轮询接入

回调模式与邮件轮询模式引用已创建的 channel_instance_id,与 managed_stream 内联凭据结构相互独立。

停用或删除入站连接

停用时通过 agent update-ingress-connection 提交 enabled: false 及最新两项版本号并回读状态;移除连接使用 agent delete-ingress-connection。

管理渠道实例与回调规则

使用以下子命令维护工具渠道实例与外部回调路由规则(复杂请求体可通过 moi-cli schema agent <subcommand> 查看,凭据配置统一保存为受保护的 --json-file):

场景

子命令

说明

查看连接器目录与维护渠道实例

list-connector-catalog、create-channel-instance、list-channel-instances、get-channel-instance、update-channel-instance、disable-channel-instance、bind-channel

修改或停用前先运行 get-channel-instance 读取当前配置与绑定关系。

测试渠道配置与实例连通性

test-channel-configuration、test-channel-instance

会向目标外部平台发起实际网络请求以验证凭据与连通性。

管理回调规则

create-callback-rule、list-callback-rules、get-callback-rule、update-callback-rule、delete-callback-rule

配置或更新外部事件回调到工作区目标的路由规则。

连接插件账号与完成 OAuth 授权

控制台界面授权说明见 连接插件账号与恢复授权。在 CLI 中先列出插件发布与当前工作区已有的插件连接,再读取目标发布的 connections 声明:

moi-cli -auth pat -o agent list-plugin-releases --workspace-id "$WORKSPACE_ID" --namespace system
moi-cli -auth pat -o agent list-plugin-connections --workspace-id "$WORKSPACE_ID"

moi-cli -auth pat -o agent get-plugin-release \
  --workspace-id "$WORKSPACE_ID" \
  --release-id "$RELEASE_ID" \
  --namespace "$RELEASE_NAMESPACE"

若工作区已有匹配连接,直接跳至下方授权状态检查;需要新建连接时,从 get-plugin-release 输出的 connections 中选取驱动类型为 oauth 的条目,记录其 requirement 与 profile 并准备 connection.json(无需在此请求中填写外部平台账号密码):

{
  "release_namespace": "system",
  "release_id": "<plugin-release-id>",
  "requirement": "<connection-requirement-key>",
  "profile": "<oauth-profile-key>",
  "name": "我的插件账号"
}

创建插件连接并记录返回的连接 id 与 version:

CONN_JSON="$(moi-cli -auth pat -o agent create-plugin-connection \
  --workspace-id "$WORKSPACE_ID" \
  --json-file connection.json)"

export CONNECTION_ID="$(printf '%s' "$CONN_JSON" | jq -r '.id')"
export CONNECTION_VERSION="$(printf '%s' "$CONN_JSON" | jq -r '.version')"

发起并推进 OAuth 授权

查询当前授权状态后,传入 --expected-version 发起 OAuth 流程:

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

moi-cli -auth pat -o agent begin-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --expected-version "$CONNECTION_VERSION"

根据 begin-plugin-oauth 返回的 grant 类型分别完成授权:

  • browser_handoff:在浏览器打开返回的 authorization_url 完成外部平台登录确认,随后重新运行 get-plugin-authorization 核对状态(该模式不返回可供 CLI 轮询的 attempt_id)。

  • 返回非空 attempt_id 的授权模式(如设备码授权,需先按提示在外部页面输入 user_code):保存 ATTEMPT_ID,按响应 poll_after 指定的间隔与总超时上限调用 poll-plugin-oauth:

moi-cli -auth pat -o agent poll-plugin-oauth \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --attempt-id "$ATTEMPT_ID" \
  --expected-version "$CONNECTION_VERSION"

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

警告

每次 poll-plugin-oauth 仅推进单次状态检查,请按返回的 status、reason、next_action 与 poll_after 控制轮询节奏:

  • get-plugin-authorization 返回结果中的 attempt_id 可能为空,中途恢复轮询时继续使用已保存的 ATTEMPT_ID。

  • 若连接 version 发生变化,应立即停止旧尝试并重新读取连接与授权详情,切勿将新版本号直接拼入旧 ATTEMPT_ID 继续轮询。

完成账号授权后,若尚未安装插件或需将该账号绑定到插件安装项,使用 install-plugin、update-plugin-installation 与 get-plugin-installation 将 CONNECTION_ID 和所选 profile 绑定至对应的连接 requirement。

断开插件账号连接

先从最新 get-plugin-authorization 输出中读取当前 generation,确认影响范围后执行断开并回读验证:

moi-cli -auth pat -o agent disconnect-plugin-connection \
  --workspace-id "$WORKSPACE_ID" \
  --id "$CONNECTION_ID" \
  --expected-generation "$GENERATION"

moi-cli -auth pat -o agent get-plugin-authorization --workspace-id "$WORKSPACE_ID" --id "$CONNECTION_ID"

断开连接后,依赖该外部账号的插件工具调用需重新完成授权方可继续运行。

限制和注意事项

  • 请妥善限制 ingress.json 等包含外部平台 App Token、Bot Token 文件的本地读写权限(如 chmod 600),切勿将真实令牌、授权 URL、OAuth 回调参数或密钥写入版本库与公开日志。

  • 入站连接就绪、插件账号授权成功与插件安装绑定分属独立状态,排障时请分别通过 get-ingress-connection、get-plugin-authorization 和 get-plugin-installation 核实。

最后更新于