跳轉到主要內容

連線 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 根據要求。請求的作用域超過了連線的最大作用域,或者工作區憑據不再具有訪問許可權。