diff --git a/apps/docs/content/docs/meta.ja.json b/apps/docs/content/docs/meta.ja.json
index b82c667dda..aafeddda83 100644
--- a/apps/docs/content/docs/meta.ja.json
+++ b/apps/docs/content/docs/meta.ja.json
@@ -32,6 +32,7 @@
"---連携---",
"github-integration",
"lark-bot-integration",
+ "octo-im-integration",
"---セルフホスト & 運用---",
"environment-variables",
"auth-setup",
diff --git a/apps/docs/content/docs/meta.json b/apps/docs/content/docs/meta.json
index f9e67d17ed..843805c087 100644
--- a/apps/docs/content/docs/meta.json
+++ b/apps/docs/content/docs/meta.json
@@ -32,6 +32,7 @@
"---Integrations---",
"github-integration",
"lark-bot-integration",
+ "octo-im-integration",
"---Self-hosting & ops---",
"environment-variables",
"auth-setup",
diff --git a/apps/docs/content/docs/meta.ko.json b/apps/docs/content/docs/meta.ko.json
index aa097377a6..6d2e27df12 100644
--- a/apps/docs/content/docs/meta.ko.json
+++ b/apps/docs/content/docs/meta.ko.json
@@ -32,6 +32,7 @@
"---연동---",
"github-integration",
"lark-bot-integration",
+ "octo-im-integration",
"---자체 호스팅 & 운영---",
"environment-variables",
"auth-setup",
diff --git a/apps/docs/content/docs/meta.zh.json b/apps/docs/content/docs/meta.zh.json
index 8516fc0dd0..a2f165a868 100644
--- a/apps/docs/content/docs/meta.zh.json
+++ b/apps/docs/content/docs/meta.zh.json
@@ -31,6 +31,7 @@
"---集成---",
"github-integration",
"lark-bot-integration",
+ "octo-im-integration",
"---自部署运维---",
"environment-variables",
"auth-setup",
diff --git a/apps/docs/content/docs/octo-im-integration.ja.mdx b/apps/docs/content/docs/octo-im-integration.ja.mdx
new file mode 100644
index 0000000000..55eafcde68
--- /dev/null
+++ b/apps/docs/content/docs/octo-im-integration.ja.mdx
@@ -0,0 +1,109 @@
+---
+title: Octo IM 連携
+description: Multica のエージェントを Octo IM ボットに紐付けると、Octo の DM やグループからそのまま対話でき、エージェントの返信が会話にストリーミングで返ってきます。
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+任意の[エージェント](/agents)を Octo IM ボットに紐付けると、チームは Octo の中からそのまま使えます——ボットに DM するか、グループで @ メンションすれば、エージェントがチャットで答えます。返信は通常の Octo メッセージとして返り、エージェントの作業中はその場で更新されます。
+
+各ボットは 1 つの Multica エージェントと **1 対 1** で紐付きます。2 つ目のエージェントを紐付けるには 2 つ目のボットを使います。1 つのエージェントが 2 つのボットを持つことはありません。
+
+## この連携でできること
+
+| 入口 | 挙動 |
+|---|---|
+| **エージェント → 連携** | エージェント詳細ページに **連携（Integrations）** タブがあります（左サイドバーにも対応するセクション）。オーナーと管理者はそこに **Octo ボットを接続** が表示され、接続後は **Octo に接続済み** の状態に切り替わります。 |
+| **ボットに DM** | ワークスペースのメンバーが Octo でボットに直接メッセージを送ります。各会話はそのエージェントとの Multica [chat](/chat) セッションになり、エージェントがスレッド内で答えます。 |
+| **グループで @ メンション** | ボットを Octo のグループに追加して @ メンションします。読み取られるのはメンションしたメッセージだけで、グループ全体は監視しません。 |
+| **ストリーミング返信** | ボットはエージェントの答えを通常の Octo メッセージとして投稿し（Octo は Markdown をネイティブ表示）、エージェントの実行に合わせてその場で編集して更新します。各ステップごとに新しいメッセージを出さずに進捗と最終結果が見えます。 |
+
+
+Octo は **チャット**連携です——`/issue` コマンドはありません。ユーザーは自然言語でエージェントと対話します。issue を作成するには、エージェントチャットか Multica アプリを使ってください。（これが、`/issue` を追加する Lark Bot との主な違いです。）
+
+
+## エージェントを接続する（オーナー / 管理者）
+
+Octo ボットは QR スキャンではなく **ボットトークン** で設定します。
+
+1. お使いの Octo デプロイのボットプラットフォームから **User Bot トークン**（`bf_` で始まる）を取得します。
+2. Multica で **Agents → 対象のエージェント** を開きます。
+3. **連携（Integrations）** タブ（または左サイドバーの **連携** セクション）を開き、**Octo ボットを接続** をクリックします。エージェント ID は自動入力されロックされるので、ボットは開いたエージェントにしか紐付きません。
+4. **ボットトークン** を貼り付けます。デプロイにデフォルト API URL が設定されていない場合は、**API URL**（Octo ボット API のベース、例：`https://im.example.com/api`）も入力します。
+5. **ボットを設定** をクリックします。Multica はそのトークンで Octo に登録してトークンの有効性を検証し、ボットの識別情報を取得したうえで **Octo に接続済み** を表示します。
+
+
+あるOcto ボットは、**デプロイ全体で 1 つのエージェントにしか**紐付けられません。すでに別の場所に紐付いているボットを接続しようとすると、Multica は明確なメッセージで拒否します——先にそのエージェントから切断してください。
+
+
+**設定 → 連携 → Octo IM** からも同じダイアログでボットを設定できます。エージェントごとのボタンはエージェント ID を事前入力してくれるだけです。
+
+## ボットを使う（メンバー）
+
+### 最初のメッセージ：Octo の本人確認を紐付ける
+
+初めてボットにメッセージを送ると、ボットは **Octo の本人確認を紐付ける** ためのリンクを返します。リンクを開いて Multica にサインインすると、あなたの Octo アカウントが Multica のメンバーシップに紐付きます。これにより、エージェントがあなたの代わりに動作し、メッセージを正しいエージェントへ振り分けられるようになります。
+
+
+ボットを使えるのは**ワークスペースのメンバー**だけです。メンバーでない場合、または紐付けリンクをまだ使っていない場合、ボットはメッセージを処理しません——破棄されます（監査のため記録されますが、内容は含みません）。紐付けリンクは 1 回限り・15 分間有効です。期限切れになったら、ボットにもう一度メッセージを送って新しいリンクを受け取ってください。
+
+
+### エージェントと対話する
+
+- **何でも聞く** —— ボットに DM するか、グループで @ メンションします。この会話は通常のエージェントチャットセッションで、エージェントの返信はチャットに表示され、作業に合わせてその場で更新されます。
+- **Markdown 対応** —— エージェントの答えは Markdown で送られ、Octo がネイティブ表示します。
+
+エージェントが**オフライン**（ランタイム未接続）または**アーカイブ済み**の場合、ボットはメッセージを黙って破棄せず、短いステータス通知を返します。
+
+## 管理と切断
+
+ワークスペース全体の管理は **設定 → 連携 → Octo IM** にあります：
+
+- **接続済みのボット** に、ワークスペース内の各ボット、それぞれが紐付くエージェント、接続状態が一覧表示されます。この一覧は全メンバーに見えます。
+- **切断** は **オーナー / 管理者のみ** です。切断するとボットは Octo メッセージの受信を停止し、WebSocket 接続が解除されます。インストール記録は監査のため保持され、後で同じエージェントを再設定できます。
+
+ボットトークンのローテーション（または再登録）は、同じエージェントに対して **ボットを設定** をもう一度実行するだけです——稼働中の接続が自動的に新しい認証情報を取り込みます。
+
+## 権限
+
+- **接続 / 切断** にはワークスペースの**オーナー**または**管理者**が必要です。メンバーは接続済みボットの一覧は見られますが、設定・切断の操作はできません。
+- **ボットとの対話** には、ワークスペースのメンバーであり、かつ Octo の本人確認が紐付いていることが必要です。それ以外はすべて破棄されます。
+- 破棄されたメッセージについて、連携は本文を一切保存しません——監査用に破棄理由だけを記録します。ボットトークンは保存時に暗号化されます。
+
+## セルフホスト設定
+
+Multica Cloud では連携はすでに利用可能です——このセクションは飛ばしてください。
+
+セルフホストでは、Octo は**保存時暗号化キーを設定するまで無効**です。このキーは、ボットトークンがデータベースに触れる前に暗号化します。
+
+1. 32 バイトのキーを生成し、API サーバーに設定します：
+
+ ```dotenv
+ MULTICA_OCTO_SECRET_KEY=
+ ```
+
+ `openssl rand -base64 32` で生成できます。
+
+2. （任意）デフォルトの Octo ボット API URL を設定しておくと、管理者がインストールのたびに貼り付けずに済みます：
+
+ ```dotenv
+ MULTICA_OCTO_API_URL=https://im.example.com/api
+ ```
+
+3. ボットが送る本人確認リンクをクリック可能にするため、Multica アプリの公開 URL を設定します：
+
+ ```dotenv
+ MULTICA_PUBLIC_URL=https://multica.example.com
+ ```
+
+4. API を再起動します。`MULTICA_OCTO_SECRET_KEY` を設定するまで、**設定 → 連携** には「Octo 連携は無効」という通知が表示され、**Octo ボットを接続** の入口は非表示のままです。
+
+
+**紐付けリンクには `MULTICA_PUBLIC_URL` が必要です。** ボットの「本人確認を紐付ける」リンクは `{MULTICA_PUBLIC_URL}/octo/bind?token=…` を指します。この変数が未設定でも連携は動きますが、未紐付けのユーザーは有効なリンクを受け取れず、自分で紐付けできません。サーバーは起動時にこの状況をログに出すので、運用側が気づけます。
+
+
+## 次のステップ
+
+- [エージェント](/agents) —— 各ボットはちょうど 1 つのエージェントに紐付きます
+- [Chat](/chat) —— ボットの会話が Multica 内部で何にマッピングされるか
+- [環境変数](/environment-variables) —— セルフホスト設定の完全なリファレンス
diff --git a/apps/docs/content/docs/octo-im-integration.ko.mdx b/apps/docs/content/docs/octo-im-integration.ko.mdx
new file mode 100644
index 0000000000..3a438e2fcf
--- /dev/null
+++ b/apps/docs/content/docs/octo-im-integration.ko.mdx
@@ -0,0 +1,109 @@
+---
+title: Octo IM 연동
+description: Multica 에이전트를 Octo IM 봇에 연결하면 Octo의 DM이나 그룹에서 바로 대화할 수 있고, 에이전트의 답변이 대화로 스트리밍되어 돌아옵니다.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+아무 [에이전트](/agents)나 Octo IM 봇에 연결하면 팀이 Octo 안에서 바로 사용할 수 있습니다——봇에게 DM을 보내거나 그룹에서 @ 멘션하면 에이전트가 채팅에서 답합니다. 답변은 일반 Octo 메시지로 돌아오며, 에이전트가 작업하는 동안 그 자리에서 갱신됩니다.
+
+각 봇은 하나의 Multica 에이전트와 **일대일**로 연결됩니다. 두 번째 에이전트를 연결하려면 두 번째 봇을 사용합니다. 한 에이전트가 두 개의 봇을 갖는 일은 없습니다.
+
+## 이 연동이 하는 일
+
+| 진입점 | 동작 |
+|---|---|
+| **에이전트 → 연동** | 에이전트 상세 페이지에 **연동(Integrations)** 탭이 있습니다(왼쪽 사이드바에도 대응 섹션). 소유자와 관리자는 거기에서 **Octo 봇 연결**을 보고, 연결 후에는 **Octo에 연결됨** 상태로 바뀝니다. |
+| **봇에 DM** | 워크스페이스 멤버가 Octo에서 봇에게 직접 메시지를 보냅니다. 각 대화는 해당 에이전트와의 Multica [chat](/chat) 세션이 되고, 에이전트가 스레드 안에서 답합니다. |
+| **그룹에서 @ 멘션** | 봇을 Octo 그룹에 추가하고 @ 멘션합니다. 멘션한 메시지만 읽으며, 그룹 전체를 듣지는 않습니다. |
+| **스트리밍 답변** | 봇은 에이전트의 답변을 일반 Octo 메시지로 게시하고(Octo는 Markdown을 기본 렌더링), 에이전트 실행에 맞춰 그 자리에서 편집·갱신합니다. 단계마다 새 메시지를 만들지 않고도 진행 상황과 최종 결과가 보입니다. |
+
+
+Octo는 **채팅** 연동입니다——`/issue` 명령은 없습니다. 사용자는 자연어로 에이전트와 대화합니다. 이슈를 만들려면 에이전트 채팅이나 Multica 앱을 사용하세요. (이것이 `/issue`를 추가하는 Lark 봇과의 주요 차이입니다.)
+
+
+## 에이전트 연결하기 (소유자 / 관리자)
+
+Octo 봇은 QR 스캔이 아니라 **봇 토큰**으로 설정합니다.
+
+1. 사용 중인 Octo 배포의 봇 플랫폼에서 **User Bot 토큰**(`bf_`로 시작)을 발급받습니다.
+2. Multica에서 **Agents → 해당 에이전트**를 엽니다.
+3. **연동(Integrations)** 탭(또는 왼쪽 사이드바의 **연동** 섹션)을 열고 **Octo 봇 연결**을 클릭합니다. 에이전트 ID가 미리 채워지고 잠기므로, 봇은 연 에이전트에만 연결됩니다.
+4. **봇 토큰**을 붙여넣습니다. 배포에 기본 API URL이 설정되어 있지 않으면 **API URL**(Octo 봇 API의 베이스, 예: `https://im.example.com/api`)도 입력합니다.
+5. **봇 구성**을 클릭합니다. Multica는 그 토큰으로 Octo에 등록해 유효성을 검증하고 봇 신원을 가져온 뒤 **Octo에 연결됨**을 표시합니다.
+
+
+특정 Octo 봇은 **배포 전체에서 하나의 에이전트에만** 연결할 수 있습니다. 이미 다른 곳에 연결된 봇을 연결하려고 하면 Multica가 명확한 메시지로 거부합니다——먼저 그 에이전트에서 연결을 해제하세요.
+
+
+**설정 → 연동 → Octo IM**에서도 같은 대화상자로 봇을 구성할 수 있습니다. 에이전트별 버튼은 에이전트 ID를 미리 채워줄 뿐입니다.
+
+## 봇 사용하기 (멤버)
+
+### 첫 메시지: Octo 신원 연결
+
+봇에게 처음 메시지를 보내면 봇이 **Octo 신원을 연결**하라는 링크로 답합니다. 링크를 열고 Multica에 로그인하면 Octo 계정이 Multica 멤버십에 연결됩니다. 이를 통해 에이전트가 당신을 대신해 동작하고, 메시지를 올바른 에이전트로 라우팅할 수 있습니다.
+
+
+봇은 **워크스페이스 멤버**만 사용할 수 있습니다. 멤버가 아니거나 연결 링크를 아직 사용하지 않았다면, 봇은 메시지를 처리하지 않습니다——폐기됩니다(감사를 위해 기록되지만 내용은 포함되지 않습니다). 연결 링크는 일회용이며 15분간 유효합니다. 만료되면 봇에게 메시지를 한 번 더 보내 새 링크를 받으세요.
+
+
+### 에이전트와 대화하기
+
+- **무엇이든 물어보기** —— 봇에게 DM하거나 그룹에서 @ 멘션합니다. 이 대화는 일반 에이전트 채팅 세션이며, 에이전트의 답변이 채팅에 나타나고 작업에 맞춰 그 자리에서 갱신됩니다.
+- **Markdown 지원** —— 에이전트의 답변은 Markdown으로 전송되며 Octo가 기본 표시합니다.
+
+에이전트가 **오프라인**(런타임 미연결)이거나 **보관됨** 상태이면, 봇은 메시지를 조용히 버리지 않고 짧은 상태 알림으로 답합니다.
+
+## 관리 및 연결 해제
+
+워크스페이스 전체 관리는 **설정 → 연동 → Octo IM**에 있습니다:
+
+- **연결된 봇**에 워크스페이스의 각 봇, 각각이 연결된 에이전트, 그리고 연결 상태가 나열됩니다. 이 목록은 모든 멤버가 볼 수 있습니다.
+- **연결 해제**는 **소유자 / 관리자 전용**입니다. 해제하면 봇이 Octo 메시지 수신을 멈추고 WebSocket 연결이 해제됩니다. 설치 기록은 감사를 위해 보존되며, 나중에 같은 에이전트를 다시 구성할 수 있습니다.
+
+봇 토큰 교체(또는 재등록)는 같은 에이전트에 대해 **봇 구성**을 다시 실행하기만 하면 됩니다——실행 중인 연결이 자동으로 새 자격 증명을 가져갑니다.
+
+## 권한
+
+- **연결 / 해제**에는 워크스페이스 **소유자** 또는 **관리자**가 필요합니다. 멤버는 연결된 봇 목록은 볼 수 있지만 구성·해제 컨트롤은 없습니다.
+- **봇과 대화하기**에는 워크스페이스 멤버이면서 Octo 신원이 연결되어 있어야 합니다. 그 외에는 모두 폐기됩니다.
+- 폐기된 메시지에 대해 연동은 본문을 전혀 저장하지 않습니다——감사를 위해 폐기 사유만 기록합니다. 봇 토큰은 저장 시 암호화됩니다.
+
+## 셀프호스트 설정
+
+Multica Cloud에서는 연동이 이미 제공됩니다——이 섹션은 건너뛰세요.
+
+셀프호스트에서는 Octo가 **저장 시 암호화 키를 설정하기 전까지 꺼져 있습니다**. 이 키는 봇 토큰이 데이터베이스에 닿기 전에 암호화합니다.
+
+1. 32바이트 키를 생성해 API 서버에 설정합니다:
+
+ ```dotenv
+ MULTICA_OCTO_SECRET_KEY=
+ ```
+
+ `openssl rand -base64 32`로 생성할 수 있습니다.
+
+2. (선택) 기본 Octo 봇 API URL을 설정하면 관리자가 설치할 때마다 붙여넣지 않아도 됩니다:
+
+ ```dotenv
+ MULTICA_OCTO_API_URL=https://im.example.com/api
+ ```
+
+3. 봇이 보내는 신원 연결 링크가 클릭 가능하도록 Multica 앱의 공개 URL을 설정합니다:
+
+ ```dotenv
+ MULTICA_PUBLIC_URL=https://multica.example.com
+ ```
+
+4. API를 재시작합니다. `MULTICA_OCTO_SECRET_KEY`가 설정되기 전에는 **설정 → 연동**에 "Octo 연동이 활성화되지 않음" 알림이 표시되고 **Octo 봇 연결** 진입점은 숨겨진 채로 유지됩니다.
+
+
+**연결 링크에는 `MULTICA_PUBLIC_URL`이 필요합니다.** 봇의 "신원 연결" 링크는 `{MULTICA_PUBLIC_URL}/octo/bind?token=…`을 가리킵니다. 이 변수가 설정되지 않아도 연동은 동작하지만, 연결되지 않은 사용자는 유효한 링크를 받지 못해 스스로 연결할 수 없습니다. 서버는 시작 시 이 상황을 로그로 남겨 운영자가 알 수 있게 합니다.
+
+
+## 다음 단계
+
+- [에이전트](/agents) —— 각 봇은 정확히 하나의 에이전트에 연결됩니다
+- [Chat](/chat) —— 봇 대화가 Multica 내부에서 무엇에 매핑되는지
+- [환경 변수](/environment-variables) —— 전체 셀프호스트 구성 참조
diff --git a/apps/docs/content/docs/octo-im-integration.mdx b/apps/docs/content/docs/octo-im-integration.mdx
new file mode 100644
index 0000000000..f27c596745
--- /dev/null
+++ b/apps/docs/content/docs/octo-im-integration.mdx
@@ -0,0 +1,109 @@
+---
+title: Octo IM integration
+description: Bind a Multica agent to an Octo IM bot, then talk to it from an Octo DM or group — chat naturally and the agent's reply streams back into the conversation.
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+Bind any [agent](/agents) to an Octo IM bot and your team can work with it from inside Octo — DM the bot or @-mention it in a group, and the agent answers in the chat. Replies stream back as a normal Octo message that updates in place while the agent works.
+
+Each bot is bound **one-to-one** to a single Multica agent. Binding a second agent uses a second bot; one agent never has two bots.
+
+## What the integration does
+
+| Surface | Behavior |
+|---|---|
+| **Agent → Integrations** | The agent detail page has an **Integrations** tab (and a matching section in the left sidebar). Owners and admins see **Connect Octo bot** there; once connected it flips to a **Connected to Octo** status. |
+| **DM the bot** | A workspace member messages the bot directly in Octo. Each conversation becomes a Multica [chat](/chat) session with the agent; the agent answers in-thread. |
+| **@-mention in a group** | Add the bot to an Octo group and @-mention it. Only the mentioning message is read — the bot does not listen to the whole group. |
+| **Streaming reply** | The bot posts the agent's answer as a plain Octo message (Octo renders Markdown natively) and edits it in place as the agent runs, so you see progress and the final result without a new message per step. |
+
+
+Octo is a **chat** integration — there is no `/issue` command. People talk to the agent in natural language; to file issues, use the agent chat or the Multica app. (This is the main difference from the Lark Bot, which adds `/issue`.)
+
+
+## Connect an agent (owner / admin)
+
+Octo bots are configured with a **bot token**, not a QR scan.
+
+1. Obtain a **User Bot token** (it starts with `bf_`) from your Octo deployment's bot platform.
+2. In Multica, open the agent in **Agents → _your agent_**.
+3. Go to the **Integrations** tab (or use the **Integrations** section in the left sidebar) and click **Connect Octo bot**. The agent's ID is pre-filled and locked, so the bot can only bind to the agent you opened.
+4. Paste the **bot token**. If your deployment has not set a default API URL, also fill in the **API URL** (the Octo bot API base, e.g. `https://im.example.com/api`).
+5. Click **Configure bot**. Multica registers the bot against Octo to validate the token and capture its identity, then shows **Connected to Octo**.
+
+
+A given Octo bot can be bound to **only one agent across the whole deployment**. If you try to connect a bot that is already bound elsewhere, Multica refuses with a clear message — disconnect it from the other agent first.
+
+
+You can also configure bots from **Settings → Integrations → Octo IM** using the same dialog; the per-agent button just pre-fills the agent ID for you.
+
+## Use the bot (members)
+
+### First message: bind your Octo identity
+
+The first time you message the bot, it replies with a link asking you to **bind your Octo identity**. Open the link, sign in to Multica, and your Octo account is linked to your Multica membership. This is what lets the agent act on your behalf and route your messages to the right agent.
+
+
+Only people who are **members of the workspace** can use the bot. If you aren't a member, or you haven't redeemed the binding link yet, the bot won't process your message — it's dropped (and recorded for audit, without its contents). The binding link is single-use and valid for 15 minutes; if it lapses, send the bot another message to get a fresh one.
+
+
+### Chat with the agent
+
+- **Ask the agent anything** — DM the bot, or @-mention it in a group. The conversation is a normal agent chat session; the agent's reply appears in the chat and updates in place as it works.
+- **Markdown is rendered** — the agent's answer is sent as Markdown, which Octo displays natively.
+
+If the agent is **offline** (its runtime isn't connected) or **archived**, the bot replies with a short status notice instead of silently dropping your message.
+
+## Manage and disconnect
+
+Workspace-wide management lives in **Settings → Integrations → Octo IM**:
+
+- **Connected bots** lists every bot in the workspace and the agent each one is bound to, with its connection status. This list is visible to all members.
+- **Disconnect** is **owner / admin only**. Disconnecting stops the bot from receiving Octo messages and tears down its WebSocket connection; the installation record is kept for audit, and you can re-configure the same agent later.
+
+Rotating a bot token (or re-registering) is just re-running **Configure bot** for the same agent — the live connection picks up the new credentials automatically.
+
+## Permissions
+
+- **Connect / disconnect** require workspace **owner** or **admin**. Members see the connected-bots list but no configure or disconnect controls.
+- **Talking to the bot** requires being a workspace member with a bound Octo identity. Everyone else is dropped.
+- The integration never stores message bodies for dropped messages — only a drop reason, for audit. Bot tokens are encrypted at rest.
+
+## Self-host setup
+
+On Multica Cloud the integration is already available — skip this section.
+
+For self-host, Octo is **off until you set an at-rest encryption key**. The key encrypts each bot's token before it touches the database.
+
+1. Generate a 32-byte key and set it on the API server:
+
+ ```dotenv
+ MULTICA_OCTO_SECRET_KEY=
+ ```
+
+ Generate one with `openssl rand -base64 32`.
+
+2. (Optional) Set a default Octo bot API URL so admins don't paste it on every install:
+
+ ```dotenv
+ MULTICA_OCTO_API_URL=https://im.example.com/api
+ ```
+
+3. Set the public URL of your Multica app so the identity-binding link the bot sends is clickable:
+
+ ```dotenv
+ MULTICA_PUBLIC_URL=https://multica.example.com
+ ```
+
+4. Restart the API. Until `MULTICA_OCTO_SECRET_KEY` is set, **Settings → Integrations** shows an "Octo integration not enabled" notice and the **Connect Octo bot** entry points stay hidden.
+
+
+**Binding links need `MULTICA_PUBLIC_URL`.** The bot's "bind your identity" link points at `{MULTICA_PUBLIC_URL}/octo/bind?token=…`. If that variable is unset, the integration still runs but unbound users never receive a working link, so they can't self-serve. The server logs this at startup so the gap is visible.
+
+
+## Next
+
+- [Agents](/agents) — each bot is bound to exactly one agent
+- [Chat](/chat) — what a bot conversation maps to inside Multica
+- [Environment variables](/environment-variables) — full self-host configuration reference
diff --git a/apps/docs/content/docs/octo-im-integration.zh.mdx b/apps/docs/content/docs/octo-im-integration.zh.mdx
new file mode 100644
index 0000000000..6f8a478e97
--- /dev/null
+++ b/apps/docs/content/docs/octo-im-integration.zh.mdx
@@ -0,0 +1,109 @@
+---
+title: Octo IM 接入
+description: 把 Multica 智能体绑定到 Octo IM 机器人，就能直接在 Octo 里和它对话——私聊或群里 @ 它，智能体的回复会实时回到会话中。
+---
+
+import { Callout } from "fumadocs-ui/components/callout";
+
+把任意[智能体](/agents)绑定到 Octo IM 机器人，团队就能在 Octo 里直接使用它——私聊机器人，或在群里 @ 它，智能体就在会话里回复。回复会作为一条普通的 Octo 消息回到对话中，并随着智能体干活在原地更新。
+
+每个机器人与一个 Multica 智能体**一对一**绑定。再绑定一个智能体要用另一个机器人；一个智能体永远不会有两个机器人。
+
+## 这个集成能做什么
+
+| 入口 | 行为 |
+|---|---|
+| **智能体 → 集成** | 智能体详情页有一个 **集成（Integrations）** tab（左侧栏也有对应的区块）。所有者和管理员能在这里看到 **连接 Octo 机器人**；连接后会变成 **已连接到 Octo** 状态。 |
+| **私聊机器人** | 工作区成员在 Octo 里直接给机器人发消息。每段对话都会成为该智能体的一个 Multica [chat](/chat) 会话，智能体在会话里回复。 |
+| **群里 @ 它** | 把机器人加进 Octo 群再 @ 它。机器人只读取 @ 它的那条消息，不会监听整个群。 |
+| **流式回复** | 机器人把智能体的答复作为一条普通 Octo 消息发出（Octo 原生渲染 Markdown），并随着智能体运行在原地编辑更新——你能看到进度和最终结果，而不会每一步都新发一条消息。 |
+
+
+Octo 是一个**聊天**集成——没有 `/issue` 命令。用户用自然语言和智能体对话；要创建 issue，请用智能体聊天或 Multica 应用。（这是它与飞书 Bot 的主要区别，后者额外提供 `/issue`。）
+
+
+## 连接智能体（所有者 / 管理员）
+
+Octo 机器人用**机器人 token** 配置，不走扫码。
+
+1. 从你的 Octo 部署的机器人平台获取一个 **User Bot token**（以 `bf_` 开头）。
+2. 在 Multica 里，于 **Agents → 你的智能体** 打开该智能体。
+3. 进入 **集成（Integrations）** tab（或使用左侧栏的 **集成** 区块），点击 **连接 Octo 机器人**。智能体 ID 会被预填并锁定，所以机器人只会绑定到你打开的这个智能体。
+4. 粘贴 **机器人 token**。如果你的部署没有设默认 API 地址，再填一下 **API 地址**（Octo 机器人 API 的基础地址，例如 `https://im.example.com/api`）。
+5. 点 **配置机器人**。Multica 会拿这个 token 向 Octo 注册以校验有效性并获取机器人身份，然后显示 **已连接到 Octo**。
+
+
+同一个 Octo 机器人在**整个部署内只能绑定到一个智能体**。如果你尝试连接一个已经绑到别处的机器人，Multica 会用明确的提示拒绝——请先在那个智能体上解绑。
+
+
+你也可以在 **设置 → 集成 → Octo IM** 用同一个弹窗配置机器人；每个智能体上的按钮只是帮你把智能体 ID 预填好。
+
+## 使用机器人（成员）
+
+### 第一条消息：绑定你的 Octo 身份
+
+第一次给机器人发消息时，它会回一个链接，请你 **绑定你的 Octo 身份**。打开链接、登录 Multica，你的 Octo 账号就和你的 Multica 成员身份关联起来了。这样智能体才能代表你行事，并把你的消息路由到正确的智能体。
+
+
+只有**工作区成员**才能使用机器人。如果你不是成员，或者还没兑换绑定链接，机器人不会处理你的消息——消息会被丢弃（并记入审计，但不含内容）。绑定链接一次性、15 分钟内有效；过期了就再给机器人发一条消息，拿一个新的。
+
+
+### 和智能体对话
+
+- **随便问** —— 私聊机器人，或在群里 @ 它。这段对话就是一个普通的智能体聊天会话；智能体的回复出现在会话里，并随着它干活在原地更新。
+- **支持 Markdown** —— 智能体的答复以 Markdown 发送，Octo 原生显示。
+
+如果智能体**离线**（运行时未连接）或已**归档**，机器人会回一条简短的状态提示，而不是默默丢掉你的消息。
+
+## 管理与断开
+
+工作区级别的管理在 **设置 → 集成 → Octo IM**：
+
+- **已连接的机器人** 列出工作区里每个机器人、各自绑定的智能体，以及连接状态。该列表对所有成员可见。
+- **断开** 仅限**所有者 / 管理员**。断开会让机器人停止接收 Octo 消息并拆除其 WebSocket 连接；安装记录会保留以便审计，之后你可以重新配置同一个智能体。
+
+轮换机器人 token（或重新注册）只需对同一个智能体重新执行一次 **配置机器人**——活跃连接会自动用上新凭据。
+
+## 权限
+
+- **连接 / 断开** 需要工作区**所有者**或**管理员**。成员能看到已连接机器人列表，但没有配置或断开的控件。
+- **和机器人对话** 需要你是工作区成员且已绑定 Octo 身份。其他人一律被丢弃。
+- 对被丢弃的消息，集成从不存储消息内容——只记一个丢弃原因用于审计。机器人 token 在数据库中加密存储。
+
+## 自部署配置
+
+在 Multica Cloud 上集成已经可用——可跳过本节。
+
+自部署时，Octo **在你设置静态加密密钥之前是关闭的**。该密钥会在机器人 token 落库前对其加密。
+
+1. 生成一个 32 字节的密钥并设到 API 服务器上：
+
+ ```dotenv
+ MULTICA_OCTO_SECRET_KEY=
+ ```
+
+ 可用 `openssl rand -base64 32` 生成。
+
+2. （可选）设一个默认的 Octo 机器人 API 地址，省得管理员每次安装都粘：
+
+ ```dotenv
+ MULTICA_OCTO_API_URL=https://im.example.com/api
+ ```
+
+3. 设置 Multica 应用的公开 URL，让机器人发出的身份绑定链接可点击：
+
+ ```dotenv
+ MULTICA_PUBLIC_URL=https://multica.example.com
+ ```
+
+4. 重启 API。在 `MULTICA_OCTO_SECRET_KEY` 设置之前，**设置 → 集成** 会显示"Octo 集成未启用"提示，**连接 Octo 机器人** 的入口保持隐藏。
+
+
+**绑定链接依赖 `MULTICA_PUBLIC_URL`。** 机器人的"绑定身份"链接指向 `{MULTICA_PUBLIC_URL}/octo/bind?token=…`。如果该变量未设置，集成仍会运行，但未绑定用户永远收不到可用链接，也就无法自助绑定。服务器会在启动时记录这一情况，便于运维发现。
+
+
+## 下一步
+
+- [智能体](/agents) —— 每个机器人都绑定到恰好一个智能体
+- [Chat](/chat) —— 一段机器人对话在 Multica 内部对应什么
+- [环境变量](/environment-variables) —— 完整的自部署配置参考