快速开始

Ankole 的部署结构

一套 Ankole 私有化部署实例由一个控制面和一个或多个 Agent Computer Worker 组成。控制面是管理平台；Worker 负责实际运行 Agent，相当于给 Agent 配的工作电脑。

一台 Worker 可以供多个 Agent 使用。金融等需要严格隔离的场景，建议每个 Agent 独享一台 Worker，就像工作电脑既可以给几个实习生共用，也可以一人一台。

每个实例还需要 PostgreSQL 和持久化磁盘。单机部署可以使用本地硬盘或虚拟硬盘；Kubernetes 部署则要使用 NFS 等支持 ReadWriteMany 的共享卷。

术语表

本页是 Ankole 用户文档和界面用语的准则。括号内保留英文名称，方便对照第三方平台、配置字段和 API；后文只使用简称。

统一名称	含义	后文简称
私有化部署实例	一家企业自行部署并管理的一套完整 Ankole 系统	实例
主体（Principal）	Ankole 中可以拥有身份和权限的人、Agent 或系统服务	主体
身份源提供商（Identity Provider，IdP）	为 Console 提供单点登录，并向 Ankole 同步员工、通讯录和组织架构的外部身份源	IdP
聊天平台	Slack、Teams、飞书 / Lark 或钉钉等承载会话的外部平台	平台
聊天渠道（Channel Provider）	接入 Ankole 的一套聊天应用或机器人配置，用来接收消息和发送 Agent 回复	聊天渠道
信号路由规则（Signal Binding）	决定把哪个信号源收到的消息或事件交给哪个 Agent	路由规则
大语言模型提供商（LLM Provider）	保存模型服务地址、凭证和可用模型的配置	模型提供商
后台 Agent 任务档案（内部键：`coding`）	选择后台 Agent 任务使用的 AIGateway Provider 和模型；普通对话不会根据代码量切换到它	后台 Agent 任务

让 Agent 帮你完成安装

你也可以把下面这段话直接发给 Codex、Claude Code，或其他能操作终端的 Agent：

请参考 https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/，帮我部署并配置一个 Ankole 私有化部署实例。请先检查我的运行环境，帮我在 Docker Compose、Kubernetes 和源码安装中选择最合适的部署方式。随后配置身份源提供商（IdP）、大语言模型提供商（LLM Provider）、Agent、聊天渠道（Channel Provider）和信号路由规则（Signal Binding）。如果我没有指定 IdP 和聊天平台，请先询问我使用哪个身份源和聊天平台，不要自行选择。不要在对话或命令输出里泄露 secret。直到我能在选定的 IM 中收到 Agent 的真实回复，这项工作才算完成。

1. 部署 Ankole

单机部署推荐 Docker Compose，企业环境推荐 Kubernetes；源码安装适合开发和排错。

大多数团队从这里开始。一台装有 Docker 的 Linux、macOS 或 Windows 电脑，就能运行 PostgreSQL、控制面、一个 Agent Computer Worker 和 Caddy HTTPS。

开始之前

能运行 Linux amd64 或 arm64 容器的 Linux、macOS 或 Windows 主机
Docker Engine 与 Compose 插件，或 Docker Desktop
持久化磁盘、一个域名，以及可用的 80、443 端口

基础设置

使用 Docker Compose 安装

不要把模型 API key 写进部署文件。登录 Console 后，再在其中添加凭证。

下载部署文件

bash

git clone https://github.com/AgentBull/ankole.git
cd ankole/tools/deploy/docker-compose
cp .env.example .env
chmod 600 .env

生成三个彼此独立的 secret

复制并运行这条命令，再把完整输出粘贴到 .env。

bash

printf '%s\n' \
  '# PostgreSQL 数据库的密码' \
  "POSTGRES_PASSWORD=$(openssl rand -hex 32)" \
  '' \
  '# ANKOLE的主加密密钥' \
  "ANKOLE_SECRET_BASE=$(openssl rand -hex 32)" \
  '' \
  '# ANKOLE的Agent Worker和控制面的相互通讯密钥' \
  "ANKOLE_RUNTIME_FABRIC_WORKER_AUTH_KEY=$(openssl rand -hex 32)"

03
配置访问域名
把 ANKOLE_HOST 设为指向这台主机的域名。ACME_EMAIL 应能收到证书通知。
ANKOLE_HOST
ankole.example.com
用户访问、SSO 回调和 provider 回调共用的 HTTPS 域名。
ACME_EMAIL
ops@example.com
Caddy 申请和续签证书时使用的联系邮箱。
04
启动并检查服务
Compose 会先等待 PostgreSQL 就绪，再执行 migration、写入 Worker key，最后启动控制面、Worker 和 Caddy。
bash
```
docker compose pull
docker compose up -d
docker compose ps
```
05
打开首次设置页面
打开 https://<ANKOLE_HOST>/setup，输入日志中的 activation code。
bash
```
docker compose logs control-plane | grep "SETUP ACTIVATION CODE"
```

2. 先设置身份源提供商

Ankole 的核心设计目标是服务企业内部的私有化部署。每家企业拥有一套实例。在同一个实例内，Agent、人类员工和系统服务都表示为主体，并由授权管理模块（AuthZ）统一管控权限。

因此，除了像 Hermes Agent、OpenClaw 那样配置聊天渠道，Ankole 还要连接企业的外部身份源，用来同步通讯录和组织架构。首次设置时，先配置 IdP，使用企业账号登录 Console，再添加聊天渠道。

设置项	负责什么	在哪里设置
IdP	Console 的 SSO 登录，以及员工、通讯录、组织架构和权限组的同步	先在 `/setup`，之后在 Console → 身份源提供商
聊天渠道	接收 IM 消息并发送 Agent 回复	在 Console → 信号路由中配置

身份源和聊天渠道也可以来自不同平台。例如，员工通过 Google Workspace 登录 Console，但在 Slack 中与 Agent 对话；也可以使用 Entra ID 登录，把聊天放在飞书、Slack、钉钉或 Teams。

按所选 IdP 完成首次设置

先选出企业实际使用的身份源，再照着对应标签页操作。每套步骤都从第三方后台创建应用开始，一直写到首次登录和通讯录同步。

如果这次才启用对应的适配器，请在首次登录后按当前部署方式重启一次控制面。这样，通讯录长连接、Graph 订阅等插件后台任务才会完整启动。

用一套 Slack app 完成 Console 登录，并同步 workspace 成员和用户组。默认配置需要 OAuth Client、Bot Token 和 App Token。

开始之前

可创建并安装 Slack app 的 workspace 管理员
Ankole 对外可访问的 HTTPS 地址
用于首次登录的 workspace 成员账号

基础设置

配置 Slack IdP

01
先从 Ankole 复制回调地址
打开 https://<ANKOLE_HOST>/setup，输入 activation code。在插件页勾选「Slack 适配器」并保存，然后选择 Slack。
Provider ID 保持 slack-main。复制页面显示的登录回调地址；后面不要手写或改动它。
02
创建 Slack app
打开 Slack API 的 Your Apps 页面，选择 Create New App → From scratch。填写应用名，并选择员工所在的 workspace。
进入 Basic Information → App Credentials，复制 Client ID 和 Client Secret。
打开 Slack Your Apps
03
登记登录回调地址
进入 OAuth & Permissions → Redirect URLs，选择 Add New Redirect URL，粘贴刚才从 Ankole 复制的完整地址，然后保存。
Ankole 默认请求 openid、profile、email 三个登录 scope，不要把它们改成聊天机器人的 scope。
Slack 登录配置说明
04
授予通讯录权限并取得 Bot Token
仍在 OAuth & Permissions 中，找到 Bot Token Scopes，依次添加下面四项。然后选择 Install to Workspace，并批准安装。
- users:read
  读取成员资料
- users:read.email
  读取成员邮箱
- usergroups:read
  读取用户组及成员关系
- team:read
  读取 workspace 基本信息
安装完成后，复制 Bot User OAuth Token。它必须以 xoxb- 开头。以后每次增加 scope，都要重新安装应用。
05
取得 App Token，并启用 Socket Mode
回到 Basic Information → App-Level Tokens，选择 Generate Token and Scopes，添加下面这项 scope，生成并复制以 xapp- 开头的 token。然后进入 Socket Mode，打开 Enable Socket Mode。
- connections:write
  允许 App Token 建立 Socket Mode 连接
06
订阅通讯录变更事件
进入 Event Subscriptions，打开事件订阅。在 Subscribe to bot events 中逐项添加下面五个事件。
- team_join
  新成员加入 workspace
- user_change
  成员资料发生变化
- subteam_created
  创建用户组
- subteam_updated
  用户组资料发生变化
- subteam_members_changed
  用户组成员发生变化
Slack Socket Mode 配置说明
07
把 Slack 凭证填回 Ankole
保持「启用 OIDC」「同步目录」「实时目录同步」开启，然后选择「保存并使用 OIDC 登录」。在 Slack 授权页完成登录。
- Client ID：Basic Information 中的 Client ID
- Client Secret：同一页的 Client Secret
- Workspace ID：Slack 网页地址 /client/T… 中以 T 开头的那一段；它把登录和目录同步限定在这个 workspace
- Bot Token：刚才取得的 xoxb- token
- App Token：刚才取得的 xapp- token
08
确认登录和首次同步
浏览器回到 Ankole 后，当前 Slack 用户会成为这套实例的第一位 root 管理员。打开 Console → 身份源提供商，选择 slack-main，再选择「运行全量同步」。
同步完成后，在 Console → 主体和权限组中确认 workspace 成员与 Slack 用户组已经出现。

3. 添加模型提供商，并创建 Agent

Agent 的模型档案只保存模型引用，因此要先添加模型提供商。登录 Console，打开 模型提供商 → 新增提供商，选择 Provider 类型，填写固定的 Provider ID、服务地址和凭证，然后保存。

控制面会加密保存 Provider 凭证。不要再把凭证写进部署环境变量或 Agent 文件。

打开 Agents → New Agent。填写一个以后不再更改的 UID 和容易辨认的名称，并在 mission 中写清它负责什么，以及怎样才算交付合格。

接着配置 model profile：

Profile	建议用途
`primary`	大多数任务使用的模型
`light`	简单、高频的任务
`heavy`	复杂推理任务

这三个 profile 缺一不可。第一次配置时，可以让它们共用同一个已经验证可用的 provider 和模型。确认聊天可以正常收发后，再按需要拆分。

4. 连接聊天渠道并创建信号路由规则

先在 Console 中启用聊天平台对应的 Control Plane Plugin，再去该平台创建机器人或应用。即使 IdP 和聊天渠道来自同一平台，正式使用时也建议分别创建应用。这样，登录和通讯录权限不会与机器人权限混在一起，凭证轮换和应用发布也互不影响。

一个聊天应用通常对应一个机器人身份。多个 Agent 如果要使用不同的机器人名称、头像或权限，就要在同一平台创建多套应用。准备好应用后，紧接着在 Console 中创建路由规则，把这套应用连接到指定的 Agent。

Slack 通过 Socket Mode 连接。Ankole 会主动建立 WebSocket，所以不必向 Slack 开放公共 webhook。

开始之前

有权限创建并安装 Slack app
一个测试频道或私聊

基础设置

准备 Slack app

01
新建应用并启用 Socket Mode
新建一个 Slack app。在 Basic Information 中创建 App-Level Token，添加下面这项权限，再启用 Socket Mode。
- connections:write
  允许 App Token 建立 Socket Mode 连接
02
订阅机器人收消息所需的事件
进入 Event Subscriptions → Subscribe to bot events，逐项添加下面两个事件。
- app_mention
  在频道里 @ 机器人
- message.im
  给机器人发私信
03
添加 scope，并安装应用
在 OAuth & Permissions → Bot Token Scopes 中逐项添加。前两项必需；其余项目按准备使用的会话类型添加。
- app_mentions:read
  读取频道中发给机器人的 @ 消息
- chat:write
  发送机器人回复
- channels:history
  读取公开频道消息
- groups:history
  需要读取私有频道时添加
- im:history
  需要读取私聊时添加
修改 scope 后，要重新安装应用到 workspace，新权限才会生效。
04
准备 Console 字段
botToken
xoxb-…
Bot User OAuth Token，必须以 xoxb- 开头。
appToken
xapp-…
Socket Mode 使用的 App-Level Token，必须以 xapp- 开头。

在 Console 中完成连接

当前版本使用直连：一条路由规则把一个聊天渠道连接到一个 Agent。它记录使用哪个适配器、哪套应用凭证、由哪个 Agent 回复，以及怎样处理群聊消息和记忆。多个机器人要分别创建多条路由规则。

打开 Console → 信号路由 → 新增路由规则，依次设置：

字段	如何选择
Target Agent	第 3 步创建的 Agent
Adapter	Slack、Teams、飞书 / Lark 或钉钉
规则名称	起一个固定的名称，例如 `slack-main` 或 `lark-main`
Group message mode	第一次测试选择 `addressed_only`
Confidential memory	第一次测试先关闭
聊天渠道配置	填入对应平台 Tab 中准备好的凭证和字段

保存后，应能在列表中看到启用状态。如果表单提示凭证有误，先改正再去 IM 测试；凭证没有通过检查，adapter 就不会建立连接。

5. 在 IM 中与 Agent 对话

把机器人加入测试会话。第一次在群里测试时，请明确 @ 它：

@Ankole 你能做什么？你现在服务哪个团队？

收到真实模型生成的回复后，就可以继续调整 Agent 的 mission、模型和群聊策略。

Agent 没有回复时

按下面的顺序逐项检查：

聊天平台中的应用已发布最新版本，测试用户也在可用范围内。
机器人已经加入对应的频道、团队或会话。
必需的消息事件与权限已经生效。
路由规则已启用，并指向正确的 Agent。
Agent 已配置 primary、light 与 heavy。
模型提供商凭证和模型选择器有效。
至少有一个 Worker 显示为 ready。

使用 Compose 时，运行 docker compose logs -f control-plane worker。使用 Kubernetes 时，查看控制面和 Worker Pod 的日志。只查看相关错误，不要输出环境变量或 secret。

收到回复后，可以继续阅读 Agent、信号路由规则或后台 Agent 任务。

快速开始

Ankole 的部署结构

术语表

让 Agent 帮你完成安装

1. 部署 Ankole

使用 Docker Compose 安装

下载部署文件

生成三个彼此独立的 secret

配置访问域名

启动并检查服务

打开首次设置页面

2. 先设置身份源提供商

按所选 IdP 完成首次设置

配置 Slack IdP

先从 Ankole 复制回调地址

创建 Slack app

登记登录回调地址

授予通讯录权限并取得 Bot Token

取得 App Token，并启用 Socket Mode

订阅通讯录变更事件

把 Slack 凭证填回 Ankole

确认登录和首次同步

3. 添加模型提供商，并创建 Agent

4. 连接聊天渠道并创建信号路由规则

准备 Slack app

新建应用并启用 Socket Mode

订阅机器人收消息所需的事件

添加 scope，并安装应用

准备 Console 字段

在 Console 中完成连接

5. 在 IM 中与 Agent 对话

Agent 没有回复时