从 Composio 迁移

把现有 Composio 集成迁移到 Open Connector，而不让 Agent 代码接触凭证。

Open Connector 为连接和工具调用流程提供 Composio 兼容 API 挂载点。迁移不是数据库导入：需要在 Open Connector 中创建等价的 Auth Config 和连接，验证新路径后再切换 client 的 base URL。

迁移计划

盘点现有用法。 列出产品调用的 toolkit、认证方式、connected-account 标识符和 trigger/webhook 路由。
选择目标。 使用 Open Connector Cloud，或部署自托管实例。仓库当前的生产操作手册是部署到 AWS。
创建项目范围 API Key。 一个项目 Key 会把连接和工具调用限制在目标项目内。
重建 Auth Config。 选择连接器，使用可用的托管 OAuth 配置，或填入自己的 OAuth client credentials。
重新连接用户。 OAuth Token 是凭证，不是可迁移的应用数据。通过新的托管连接链接，或由应用发起连接，让每位用户重新授权。
灰度验证。 先让一个环境或少量租户指向 Open Connector，验证实际使用的工具，再切换其余流量。

修改 client 端点

新代码优先迁移到官方 SDK；如果希望保持最小改动，则只修改 Composio 构造器的 base URL：

import { createClient } from "@open-connector/sdk";

const oc = createClient({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY!,
  baseUrl: "https://api.openconnector.dev",
});

import Composio from "@composio/client";

const composio = new Composio({
  apiKey: process.env.OPEN_CONNECTOR_API_KEY!,
  baseURL: "https://api.openconnector.dev/composio",
});

自托管时只替换 origin：

https://connector.example.com/composio

官方 SDK 使用不带 /composio 的 Origin。不要把 /api/v3.1 加在 Composio baseURL 后；该 Client 会自行追加版本路径。

重建 OAuth 配置

若使用自己的 GitHub OAuth 应用，请先在 GitHub 中添加以下 callback URL：

https://api.openconnector.dev/api/v1/connectors/github/callback

自托管时替换为 Broker 的公网 origin。在控制台的 Auth Configs 创建认证配置，并在控制台连接账户；也可以由受信任的后端调用兼容 API。不要把现有 Composio access token 拷进新的 OAuth 连接；请通过供应商重新授权。

切换前验证

使用项目 Key 和同一个 connection identifier 检查账户、发现工具，并执行一个无副作用的请求：

curl "https://api.openconnector.dev/composio/api/v3.1/connected_accounts/conn_..." \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY"

curl "https://api.openconnector.dev/composio/api/v3.1/tools?toolkit_slug=github" \
  -H "x-api-key: $OPEN_CONNECTOR_API_KEY"

然后执行生产工作流真实使用的工具和输入。检查连接状态与 API 响应；目录中存在某个连接器，并不能证明凭证或可选子系统已经准备好。

端点映射

Composio 路径	Open Connector 托管路径
`https://backend.composio.dev/api/v3.1/auth_configs`	`https://api.openconnector.dev/composio/api/v3.1/auth_configs`
`https://backend.composio.dev/api/v3.1/connected_accounts`	`https://api.openconnector.dev/composio/api/v3.1/connected_accounts`
`https://backend.composio.dev/api/v3.1/tools/execute/{slug}`	`https://api.openconnector.dev/composio/api/v3.1/tools/execute/{slug}`
`https://backend.composio.dev/api/v3.1/toolkits`	`https://api.openconnector.dev/composio/api/v3.1/toolkits`

单独验证可选能力

兼容层不只包含核心的连接和执行循环，但可选子系统依赖宿主配置。如果您使用 webhook、trigger、files、tool-router 或 MCP 路由，请先验证实际端点和部署配置，再迁移对应工作负载。明确的 501 Not Implemented 表示该部署尚未绑定这个子系统。