跳转到主要内容

连接 AI 代理

使用交互式 OAuth、无人值守服务连接或 API 密钥将 AI 代理连接到 Kanera。 正确的方法取决于代理是否以人为本、在无监督下运行,还是仅支持静态凭据。

对于 ChatGPT 或受支持的 Codex 表面,请安装 Kanera 插件并通过其 OAuth 提示连接您的帐户。 Follow 设置 ChatGPT 或 设置 Codex;该插件包括 Kanera 技能和 MCP 连接。

对于其他个人助理,如果客户端支持带浏览器身份验证的远程 MCP,则使用 OAuth。 您添加 Kanera 的 MCP 地址,批准连接,代理将以您的身份行事,同时尊重您在每个看板上的角色。 API 密钥 当客户端不支持 OAuth 时。

编码代理的快速设置​

将此内容粘贴到 Claude Code、Codex、Cursor、GitHub Copilot、Gemini CLI、OpenCode 或其他编码代理中:

Fetch https://www.kanera.app/agent-setup/prompt.md and follow it.

提示将安装 Kanera 的官方 Agent Skill,使用当前代理配置注册托管的 MCP 服务器,并在客户端支持的地方启动 OAuth 。 在批准访问前,请查看浏览器同意屏幕。

选择连接方式​

连接它是谁您在哪里设置它最适合
OAuth(交互式)您,浏览器同意屏幕后。 没有API密钥。您将 MCP 地址添加到您的代理;Kanera 处理登录和同意。 配置文件设置 -> API 密钥.Claude、ChatGPT、Copilot 或 Codex 中的个人 AI 助理。
OAuth(设备代码)您,在浏览器中批准短代码后。 无 API 密钥。客户端显示代码;您在 Kanera 上批准它 连接设备 请在下面输入您的密码 配置文件设置 -> API 密钥.无法打开浏览器重定向的 CLI、SSH 会话或无头计算机。
无人值守代理(服务连接)工作区服务标识，范围为读取、写入或管理。工作区设置 -> API，“无人值守的人工智能代理”。CI、cron 作业或无需人工点击“允许”的服务器端代理。
API 密钥密钥的所有者(个人)或工作区(工作区密钥 ) 。配置文件设置 -> API 密钥 或 工作区设置 -> API.本地 stdio MCP,或不支持 OAuth 的客户端。

所需经费​

  • 您的 AI 客户端必须支持使用 OAuth 的远程 MCP 服务器。 仅支持静态载体令牌的客户端应使用 API 密钥 相反。
  • 交互式代理连接适用于每个 Kanera 计划,包括 Free。 在 Free 组织的看板上,每个人的代理共享每秒 5 次和每分钟 60 次请求的限制;Pro 看板允许 20 和 400。 费率限额.

我如何知道我的代理是否支持 OAuth?​

没有固定的列表,客户支持随着时间的推移而变化,所以可靠的检查是尝试它:

  1. 将 Kanera 的 MCP 地址添加到您的客户端作为远程或自定义 MCP 服务器。
  2. 如果客户端支持 OAuth,它将打开一个 Kanera 浏览器选项卡,以便登录和同意。
  3. 如果客户端要求您提供 API 密钥、令牌或 Authorization 或者它根本无法连接,它不支持OAuth。 使用一个 API 密钥 相反。

描述支持"远程 MCP 服务器 " 、 "自定义连接器"或"OAuth"的客户端通常可以工作。 对于仅运行本地 stdio 服务器的客户端,将其指向 kanera mcp 从 Kanera CLI 之后 kanera auth login;它通过您的 OAuth 登录来中继托管服务器，因此您仍然不需要密钥。

连接代理(交互式)​

  1. 开放 配置文件设置 -> API 密钥.

  2. 在 AI代理连接 复制链接 MCP地址。对于 Kanera 的托管服务，这是：

    https://mcp.kanera.app/mcp

  3. 将该地址添加到您的 AI 客户端作为远程 MCP 服务器。下 或手动配置，选择 Claude Code、Cursor、VS Code / GitHub Copilot、Codex 或 Gemini CLI，复制已填写的 MCP 地址的现成命令或配置。对于其他客户端，请按照客户端自己的步骤添加自定义或远程 MCP 连接器。

  4. 客户端将打开一个 Kanera 浏览器选项卡。 如果您尚未登录,请登录,然后查看同意屏幕。

  5. 选择 允许访问。 Kanera 返回到现已连接的代理。

您不需要在任何时候输入 API 密钥,代理接收一个短期访问令牌,并在后台自动刷新它。

显示代理设置提示、Kanera MCP 地址、可复制的 Claude Code 设置命令和连接代理管理的个人 API 设置。

OAuth 将工具连接起来;它本身并不会教会客户端 Kanera 特定的工作流程。 如果客户端支持 Agent Skills,还应安装 Kanera 代理技能:

npx -y skills add https://github.com/happendev/Kanera/tree/main/integrations/skills/kanera --yes --global

该技能指导代理读取当前状态、解析稳定 ID、安全地进行请求的更改,以及正确处理身份验证或权限失败。 请参阅本节中的客户端特定设置指南,以了解手动技能位置。

同意屏幕将为代理命名并解释连接边界。 通过这种方式连接的代理将:

  • 阅读 您可以访问的看板、卡片、笔记、评论和活动。
  • 创建和更新板内容 无论你是哪里的编辑。
  • 创建和管理工作区 无论您是哪个组织的管理员,它都可以创建工作区和独立的看板。 作为工作区管理员,它可以向该工作区添加看板,并创建、编辑、启用和删除其自动化功能。 其他管理功能,如编辑列表、字段、标签和成员,都保留在 Kanera 界面中。

Kanera 使用以下 OAuth 作用域来处理用户授权代理:

范围赠款
kanera:read阅读您可以访问的论坛内容。
kanera:write创建和更新您作为编辑者的论坛内容。
offline_access当客户请求时接受。每当客户端注册刷新时，Kanera 都会发出刷新令牌，因此代理可以保持连接，而无需要求您再次登录。

交互式和设备代码连接始终接收 kanera:read 以及 kanera:write，即使客户端省略范围或仅请求读取。这使服务器与以不同方式处理操作权限的客户端兼容。 AI 客户端仍然负责决定用户可以访问哪些工具以及何时需要确认。 Kanera 在每个请求上独立检查连接用户的当前角色，因此观察者无法写入板。在Kanera云上， 组织 AI 代理政策 您还可以将代理设置为只读或关闭组织的板。 offline_access 仍然是可选的,因为它控制令牌刷新,而不是 Kanera 工具权限。

管理和断开代理的连接​

开放 配置文件设置 -> API 密钥 找到最好的 AI代理连接 1. 关于第1款的建议

  • 每个已连接的代理都显示其名称、授予的作用域以及连接时间。
  • 选择 断开代理 该连接的访问和刷新令牌立即停止工作,因此代理立即失去访问权限。

断开连接是切断您不再使用或不信任的 AI 客户端的最快方式。

无人值守代理(服务连接)​

交互式 OAuth 需要一个人点击 允许。对于 CI、cron 作业或无人在场的服务器端自定义代理，创建一个 无人值守代理 它使用 OAuth 使用客户端 id 和密钥进行身份验证。 client_credentials 赠款。

如果有人在场,但客户端无法打开浏览器重定向,例如 CLI 或 SSH 会话,请使用 设备授权 您在任何设备上的浏览器中批准一个短代码,连接就会代替您。

创建无人值守代理​

  1. 打开工作区并转到 工作区设置 -> API.
  2. 在 无人值守的AI代理 请输入一个密码 姓名.
  3. 选择一个 最大范围: 阅读, 写, 或 管理员。代理可以请求此范围或更低，但绝不能更高。
  4. 选择 创建代理连接.
  5. 复制一次所示凭据: client_id, client_secret, 和 token_url。将它们存储在您特工的秘密管理器中。 Kanera 再也没有透露这个秘密。

创建无人值守代理需要工作区管理员访问权限。 在托管 Kanera 上,它还需要 Pro 或 Pro 试用版,降级到 Free 将禁用它,直到组织再次升级。

管理员 通过 MCP 添加自动化管理功能:创建、编辑、启用和删除规则。 不允许通过 MCP 创建工作区或进行一般的板、列表、字段、标签或会员管理。 启用的规则可以发布评论或将卡片和列表数据发送到配置的外部 webhook 端点;在启用之前检查其操作。

用于创建带有名称和最大作用域的无人值守 AI 代理的 Workspace API 设置。

使用无人值守代理​

将客户端 id 和密钥交换为短期 MCP 访问令牌,然后配置代理以将其与 MCP 服务器一起使用。 resource 值是 Kanera 显示的确切 MCP 地址。

# 1. Get an access token (valid for 15 minutes).
curl -X POST https://api.kanera.app/oauth/token \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=client_credentials \
  -d scope=kanera:read \
  -d resource=https://mcp.kanera.app/mcp

# Response: { "access_token": "kanera_mcp_...", "token_type": "Bearer", "expires_in": 900, "scope": "kanera:read" }

配置代理以调用 MCP 端点:

Authorization: Bearer kanera_mcp_...

无人值守代理不会收到刷新令牌。 当前令牌过期时请求新的访问令牌。 请求的作用域总是限制在创建连接时选择的最大作用域。 当自定义无人值守集成需要直接调用公共 REST API 时,请使用工作区或板 API 密钥。

要撤销无人值守代理,请将其从 无人值守的AI代理 其令牌和底层工作区凭据将立即停止工作。

对于自定义 OAuth 客户端​

兼容的客户端会自动处理此流程。 如果您正在构建自己的客户端,则需要满足以下重要要求:

  • 从 MCP 端点公布的元数据中发现授权服务器。
  • 使用 PKCE 并注册一个精确的重定向地址。
  • 发送确切的 MCP 地址为 resource 在授权和每次令牌或刷新交换期间。
  • 只将所产生的访问令牌发送到该 MCP 地址,而不是 /api/v1.

见下文第10段。 MCP 技术参考 设备授权和请求示例。

从发布未绑定 OAuth 令牌的版本升级会撤销现有授权和令牌,因为它们没有可信的 MCP 受众。 已注册的客户端定义保留,但每个用户或无人值守的客户端必须在该旧受众绑定迁移后重新连接一次。 读/写策略更改不会撤销当前连接:服务器升级后,现有的有效 OAuth 会话将具有写入功能,无需重新连接。

故障排除​

问题要检查什么
客户端请求 API 密钥,而不是打开浏览器。客户端不支持远程 MCP OAuth。 使用 API 密钥 相反。
“您的计划中不提供工作区 API 密钥和无人值守的 AI 代理。”无人值守服务代理需要 Pro 或 Pro 试用版。 升级组织,或以您自己的身份进行交互式连接,适用于所有计划。
浏览器同意步骤失败或连接"无效或过期 " 。从客户端重新启动连接。 授权代码是一次性的,5 分钟后过期。
标记端点返回 invalid_target.确保客户端发送的确切 MCP 地址 配置文件设置 -> API 密钥 作为 resource 在授权和每次令牌交换期间。
从未绑定令牌版本升级后，之前有效的 OAuth 连接会立即失败。只有旧版受众绑定迁移会故意撤销未绑定的授权和令牌;而读/写策略更新则不会。
代理连接,但无法编辑。确认客户端允许写入操作,并且您的Kanera用户是目标论坛的编辑者。 观察者不能写入。 创建工作区或论坛以及管理自动化也需要相应的管理员角色。 AI代理政策 至 只读，代理根本无法在那里写入。
“该组织的人工智能代理访问权限已关闭。”拥有该看板的组织的管理员已设置其 AI代理政策 至 关闭。要求他们改变它；重新连接代理没有帮助。
无人值守的代理得到 403 根据要求。请求的作用域超过了连接的最大作用域,或者工作区凭据不再具有访问权限。