消息通道与插件连接¶
使用 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 向应用发送一条验证消息,核对目标智能体运行记录与会话回复以确认收发链路就绪。
维护场景 |
命令与说明 |
|---|---|
校验回调模式连接 |
|
回调或邮件轮询接入 |
回调模式与邮件轮询模式引用已创建的 |
停用或删除入站连接 |
停用时通过 |
管理渠道实例与回调规则¶
使用以下子命令维护工具渠道实例与外部回调路由规则(复杂请求体可通过 moi-cli schema agent <subcommand> 查看,凭据配置统一保存为受保护的 --json-file):
场景 |
子命令 |
说明 |
|---|---|---|
查看连接器目录与维护渠道实例 |
|
修改或停用前先运行 |
测试渠道配置与实例连通性 |
|
会向目标外部平台发起实际网络请求以验证凭据与连通性。 |
管理回调规则 |
|
配置或更新外部事件回调到工作区目标的路由规则。 |
连接插件账号与完成 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核实。