<span id="消息通道与插件连接"></span>

# Messaging Channels and Plugins

Use the messaging channel and plugin connection subcommands under `moi-cli agent` to create inbound messaging connections for agents or teams, manage external channel instances and callback rules, and authorize or disconnect external plugin OAuth accounts. Complete [Configuration and Authentication](../configuration-authentication.md) before running commands.

(cli-message-connections)=
<span id="连接入站消息通道"></span>

## Connect inbound messaging channels

See [Two-way messaging](../../../guides/ai-studio/agents/manage-agents/im-connection/index.md) for platform-side app creation and permission requirements. Before creating an inbound connection from the CLI, inspect supported (`provider`, `channel_type`, `receive_mode`) combinations in your deployment and check existing connections on the target agent:

```bash
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"
```

When `slack`, `slack_app`, and `managed_stream` are listed in the deployment capabilities and no suitable connection exists yet, write the target agent, model, and Slack credentials to a restricted local file `ingress.json` (inspect field definitions via `moi-cli schema agent create-ingress-connection`):

```json
{
  "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>"
  }
}
```

Create the connection and inspect its runtime state:

```bash
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"
```

Creating a Slack managed stream connection starts receiver provisioning automatically. Re-run `get-ingress-connection` and check `desired_state`, `observed_state`, and `last_error_code`:

- Continue bounded observation while the connection is `starting` or `reconnecting`.
- Fix external app credentials or scopes first if `auth_failed` or `config_invalid` is reported.
- Once healthy, send a test message in Slack and verify the target agent's task history and reply in the conversation.

| Maintenance scenario | Command and behavior |
| --- | --- |
| Verify callback-mode ingress | `agent verify-ingress-connection` applies to callback receive modes only and is not used for Slack `managed_stream` connections. |
| Callback or mail-polling modes | Callback and mail-polling ingress connections reference an existing `channel_instance_id` rather than inline `managed_stream` tokens. |
| Disable or delete an ingress connection | Submit `enabled: false` with the two latest version fields via `agent update-ingress-connection` and read back status, or remove the connection with `agent delete-ingress-connection`. |

<span id="管理渠道实例与回调规则"></span>

## Manage channel instances and callback rules

Use the subcommands below to maintain tool channel instances and external callback routing rules (inspect JSON schemas via `moi-cli schema agent <subcommand>`, and store credentials in restricted `--json-file` inputs):

| Scenario | Subcommands | Description |
| --- | --- | --- |
| Browse catalog and maintain channel instances | `list-connector-catalog`, `create-channel-instance`, `list-channel-instances`, `get-channel-instance`, `update-channel-instance`, `disable-channel-instance`, `bind-channel` | Run `get-channel-instance` to inspect existing settings and bindings before updating or disabling an instance. |
| Test channel configurations and instances | `test-channel-configuration`, `test-channel-instance` | Sends live network requests to the external platform to validate credentials and connectivity. |
| Manage callback rules | `create-callback-rule`, `list-callback-rules`, `get-callback-rule`, `update-callback-rule`, `delete-callback-rule` | Create, inspect, update, or remove routing rules for inbound external callbacks. |

(cli-agent-plugin-releases)=
<span id="连接插件账号与完成-oauth-授权"></span>

## Connect plugin accounts and complete OAuth

See [Connect plugin accounts and recover authorization](../../../guides/ai-studio/agents/tools/plugin-connections.md) for console authorization workflows. From the CLI, list available plugin releases and existing workspace connections, then inspect `connections` on the selected release:

```bash
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"
```

If a matching connection already exists in the workspace, check its authorization status directly. Otherwise, select an entry with the `oauth` driver from `connections` in the `get-plugin-release` output, record its `requirement` and `profile`, and prepare `connection.json` (external account passwords are never placed in this payload):

```json
{
  "release_namespace": "system",
  "release_id": "<plugin-release-id>",
  "requirement": "<connection-requirement-key>",
  "profile": "<oauth-profile-key>",
  "name": "My Plugin Account"
}
```

Create the plugin connection and save its returned `id` and `version`:

```bash
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')"
```

<span id="发起并推进-oauth-授权"></span>

### Start and poll OAuth authorization

Inspect current authorization state and start the OAuth flow with `--expected-version`:

```bash
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"
```

Complete authorization according to the returned `grant` type:

- **`browser_handoff`**: Open `authorization_url` in a browser to complete sign-in on the external platform, then re-run `get-plugin-authorization` to verify state (this grant type does not issue a CLI-pollable `attempt_id`).
- **Grants returning a non-empty `attempt_id`** (such as device authorization, where you also enter `user_code` as prompted): Save `ATTEMPT_ID` and poll `poll-plugin-oauth` at the `poll_after` interval with a bounded overall timeout:

```bash
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"
```

:::{warning}
Each `poll-plugin-oauth` invocation performs one status check—pace retries using `status`, `reason`, `next_action`, and `poll_after`:
- `get-plugin-authorization` can omit `attempt_id` even while an attempt remains active; keep using your saved `ATTEMPT_ID` when resuming.
- If the connection `version` changes, stop polling the old attempt and re-inspect the connection and authorization state rather than pairing the new version number with the old `ATTEMPT_ID`.
:::

After authorization succeeds, bind `CONNECTION_ID` and the selected `profile` to the plugin's connection `requirement` via `install-plugin`, `update-plugin-installation`, and `get-plugin-installation`.

(cli-plugin-disconnect)=
<span id="断开插件账号连接"></span>

### Disconnect a plugin account

Read `generation` from the latest `get-plugin-authorization` output, confirm impact on active agents, and disconnect:

```bash
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"
```

Once disconnected, plugin tool calls that rely on this external account require re-authorization before running again.

<span id="限制和注意事项"></span>

## Limitations and notes

- Restrict local file permissions (for example `chmod 600`) on `ingress.json` and any files containing external App Tokens or Bot Tokens, and never commit live tokens, authorization URLs, OAuth callback parameters, or secrets to version control or shared logs.
- Inbound receiver health, plugin account authorization, and plugin installation bindings are tracked separately; inspect `get-ingress-connection`, `get-plugin-authorization`, and `get-plugin-installation` independently when troubleshooting.
