跳到正文
Ankole

快速开始

面向 AI Agent:本页的 Markdown 版本位于 https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md,全站文档索引位于 https://ankole.agentbull.com/zh-Hans-CN/llms.txt。

Ankole 的部署结构

一套 Ankole 私有化部署实例由一个逻辑控制面,以及每位 Agent 各自独占的一个 Agent Computer Worker 组成。控制面持有持久领域状态与监督权,负责全局管理与调度;Worker 则负责承载 Agent 的实际运行,相当于每位 Agent 专属的工作电脑。

不同 Agent 之间绝不共用 Worker,正如团队中每位同事都有各自独立的工作电脑。创建 Agent 时,控制面会通过绑定的 WorkerProvider 自动为其开通专属 Worker,并在后续运行中负责该 Worker 的停止、升级替换与销毁回收。

每套部署实例均需要 PostgreSQL 数据库、控制面云盘文件存储,以及每位 Agent 的持久 Home 存储。官方 Kubernetes Helm Chart 默认采用共享的 ReadWriteMany Home PVC 搭配独立的 ReadWriteOnce 缓存 PVC——其中持久 Home 必须纳入定期备份,缓存卷则无需备份。

单个站点可以容纳多个逻辑隔离的租户:站点管理员负责维护底层共享基础设施,各租户各自拥有独立的人员主体、Agent、Brain 知识库与外部平台连接。站点管理台默认位于 /site-admin-console;如需修改路径,请在启动前设置环境变量 ANKOLE_SITE_ADMIN_CONSOLE_PATH(Helm 部署对应配置 controlPlane.siteAdminConsolePath)。

术语表

以下术语表是 Ankole 用户文档与控制台界面的统一用语规范。括号内保留英文原名以便对照第三方平台后台、配置字段与 API;后文统一使用简称。

统一名称 含义 后文简称
站点(Site) 一套共享底层基础设施、由站点管理员统一运维的完整 Ankole 部署实例 站点
租户(Tenant) 站点内单个组织的人员、Agent、Brain、外部平台连接及业务数据边界 租户
主体(Principal) Ankole 中可拥有身份标识与访问权限的自然人、Agent 或系统服务 主体
身份源提供商(Identity Provider,IdP) 为 Console 提供企业单点登录,并向 Ankole 同步员工、通讯录与组织架构的外部身份源 IdP
聊天平台 Slack、Teams、飞书 / Lark、钉钉、企业微信、Telegram、Discord、LINE、WhatsApp 或电子邮箱等承载对话的外部平台 平台
聊天渠道(Channel Provider) 接入 Ankole 的一套外部聊天应用或机器人凭证配置,用于收取消息并发回 Agent 回复 聊天渠道
对话(Conversation) 人与 Agent 共同参与的交流空间;原生对话发言以 Ankole 为准,外部平台对话发言以宿主平台为准 对话
消息(Message) 在对话中正式提交、对参与者可见的发言记录 消息
信号(Signal) 由对话发言、定时触发、外部事件或子任务完成所生成并持久接纳的输入刺激 信号
执行会话(Session) 持有专属信号队列与可恢复执行进度的运行上下文,可用于对话、定时任务、后台任务或工作流任务 执行会话
投递(Delivery) 向外部对话发送回复时的持久化投递意图、尝试记录与最终回执 投递
信号路由规则(Signal Binding) 定义将哪个信号源收到的消息或事件转交给哪位 Agent 处理的绑定规则 路由规则
大语言模型提供商(LLM Provider) 保存模型接口地址、访问凭证及可用模型列表的配置 模型提供商
模型档案(Model Profile) 按 Site -> Pod -> Agent/System 三层稀疏继承的能力槽位(如 primary、light、heavy 及多模态与检索槽位) 模型档案

让 Agent 帮你完成安装

你也可以将下面这段提示词直接发给 Codex、Claude Code 或其他能操作终端的编程 Agent,由它代劳部署与引导检查:

请参考 https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md,帮我部署并配置一个 Ankole 私有化部署实例。请先检查我的运行环境,帮我在 Docker Compose、Kubernetes 和源码安装中选择最合适的部署方式。随后配置登录方式(免密邮箱验证码 Email OTP 或企业 SSO 身份源提供商 IdP)、大语言模型提供商(LLM Provider)、Agent、聊天渠道(Channel Provider)和信号路由规则(Signal Binding)。如果我没有指定登录方式和聊天平台,请先询问我使用哪种登录方式(SMTP 邮箱验证码或企业 IdP)和聊天平台,不要自行选择。切勿在对话或命令输出中泄露任何密钥。直到我能在所选 IM 中收到 Agent 的真实回复,整个部署与配置才算完成。

1. 部署 Ankole

单机部署推荐使用 Docker Compose,企业级集群环境推荐使用 Kubernetes;源码安装仅用于本地功能开发与故障调试。

租户页面使用 <tenant-slug>.<site-host>(例如 team.ankole.example.com)。公网部署时,请为每个租户主机名配置 DNS、HTTPS 证书与代理或 Ingress 规则,使其指向同一控制面。下方 Compose 的 Caddy 配置与 Helm 的 Ingress 示例仅覆盖站点主机名。

Worker 部署标识(installation)长度须为 1–20 个字符,仅支持小写字母、数字和连字符(-),且首尾字符必须为字母或数字(例如 e2e-1011b01)。Docker Compose 通过 ANKOLE_WORKER_INSTALLATION 设置(默认为 ankole);Helm 通过 worker.installation 设置(留空时默认采用 Release 名称)。请在首次启动前确定该标识,上线后保持不变——底层 Worker 实例命名与持久 Home 存储路径均与该标识绑定。

单台主机统一运行 PostgreSQL 18、ankole-function-runtime、控制面和 Caddy,并由所选 WorkerProvider 为每个 Agent 创建专属 Worker。

开始之前

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

基础设置

使用 Docker Compose 安装

请勿将模型 API 密钥写入部署配置文件;待登录 Console 后,再在界面中添加模型凭证。

  1. 01

    下载部署文件

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

    生成四组彼此独立的密钥

    复制并运行以下命令,再将完整输出粘贴到 `.env` 文件中。

    bash
    printf '%s\n' \
      '# PostgreSQL 数据库的密码' \
      "POSTGRES_PASSWORD=$(openssl rand -hex 24)" \
      '' \
      '# ANKOLE 的主加密密钥' \
      "ANKOLE_SECRET_BASE=$(openssl rand -hex 32)" \
      '' \
      '# 控制面的 Erlang distribution cookie' \
      "RELEASE_COOKIE=$(openssl rand -hex 32)" \
      '' \
      '# 控制面与 ankole-function-runtime 共享的认证令牌' \
      "ANKOLE_FUNCTION_RUNTIME_TOKEN=$(openssl rand -hex 32)"
  3. 03

    设置 Docker Socket 所属用户组

    控制面以非特权用户身份运行,需借助容器内看到的 Docker Socket 所属用户组权限来创建和管理 Worker 容器。

    在 Linux 主机上,将 .env 中的 ANKOLE_DOCKER_GID 设为下方命令输出的组 ID;在 macOS 的 Docker Desktop 上,直接设置 ANKOLE_DOCKER_GID=0(Docker Desktop 映射进容器的 Socket 所属组恒为 0,与宿主机显示的组无关)。仅当 Socket 路径不在 /var/run/docker.sock 时,才需额外设置 ANKOLE_DOCKER_SOCKET。

    bash
    stat -c %g /var/run/docker.sock   # Linux

    持有 Docker Socket 访问权限等同于拥有宿主机的 root 权限,请将所在主机视为受信任的第一方计算边界加以保护。

  4. 04

    配置访问域名

    将 ANKOLE_HOST 设为解析到当前主机的域名,并确保 ACME_EMAIL 能够正常接收证书通知。

    ANKOLE_HOST
    ankole.example.com
    用户访问、企业 SSO 回调和外部平台回调共用的 HTTPS 域名。
    ACME_EMAIL
    ops@example.com
    Caddy 申请和续签证书时使用的联系邮箱。
  5. 05

    启动并检查服务

    Docker Compose 会先启动 PostgreSQL 18 与 ankole-function-runtime,完成数据库迁移后,再启动控制面与 Caddy。

    bash
    docker compose pull
    docker compose up -d
    docker compose ps
  6. 06

    打开首次设置页面

    打开 https://<ANKOLE_HOST>/setup,输入日志中输出的激活码。

    bash
    docker compose logs control-plane | grep "SETUP ACTIVATION CODE"

2. 先设置登录与身份源

Ankole 专为企业私有化部署设计。一套站点可承载多个租户;各租户内的 Agent、员工与系统服务均统一建模为主体(Principal),并由权限模块(AuthZ)集中鉴权。完成 /setup 初始化后,首位登录的管理员会同时获得站点级 siteadmin(可访问 /site-admin-console 站点管理台)与默认 Pod 的 pod_admin 权限。进入控制台调整租户级设置前,请先在左上角切换至目标租户。

在 /setup 初始化向导中,你既可以选择免密邮箱验证码(Email OTP,email_otp)(通过自有 SMTP 服务器发送 6 位验证码),也可以接入**企业 SSO 身份源提供商(IdP)**来同步员工名册、通讯录与部门架构。请务必先完成登录与身份初始化,再去配置外部聊天渠道。

设置项 负责什么 在哪里设置
邮箱验证码(email_otp) 免密 6 位邮箱验证码登录(authn.email.mail SMTP 发信与 SiteCredential 绑定)及邮件邀请成员 /setup(邮箱验证码),或命令行 mix ankole.authn.mail.put
IdP 企业 SSO 单点登录,以及员工、通讯录、组织架构与权限组的同步 首次在 /setup 配置,后续在 Console → 身份源提供商 管理
聊天渠道 收取外部 IM 消息并发回 Agent 的回复 在 Console → 信号路由 中配置

登录认证方式与日常对话所用的聊天渠道完全解耦,可以来自不同平台:例如用邮箱验证码或 Google Workspace 登录后台,而在 Slack 中与 Agent 对话;或者用 Microsoft Entra ID 登录后台,而将 Agent 接入飞书、Slack、钉钉、Teams 或企业微信。

按所选登录方式完成首次设置

在下方切换至邮箱验证码或企业实际使用的身份源,按对应标签页的步骤依次操作。每个企业 SSO 标签页均从第三方管理后台创建应用讲起,直至完成首次登录与通讯录全量同步。

若对应的企业平台适配器是在本次操作中刚刚启用的,请在完成首次登录后按当前部署方式重启一次控制面进程,以便通讯录长连接或 Microsoft Graph 订阅等插件后台任务完整启动。

使用一个 Slack 应用完成 Console 登录,并同步工作区(Workspace)成员和用户组。默认配置需要 OAuth 客户端凭证、Bot Token 和 App Token。

开始之前

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

基础设置

配置 Slack IdP

  1. 01

    先从 Ankole 复制回调地址

    打开 https://<ANKOLE_HOST>/setup,输入激活码。在插件页勾选“Slack 适配器”并保存,然后选择 Slack。

    “配置 ID(Provider ID)”保持 slack-main。使用页面上的“复制”按钮复制登录回调地址;后续切勿手写或改动该地址。

  2. 02

    创建 Slack 应用

    打开 Slack API 的 Your Apps 页面,选择 Create New App → From scratch,填写应用名称并选择员工所在的工作区。

    进入 Basic Information → App Credentials,复制 Client ID 和 Client Secret。

  3. 03

    登记登录回调地址

    进入 OAuth & Permissions → Redirect URLs,点击 Add New Redirect URL,粘贴刚才从 Ankole 复制的完整地址并保存。

    Ankole 登录默认请求 openid、profile、email 三个用户身份权限(Scope),请勿将其改成聊天机器人的权限。

  4. 04

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

    仍停留在 OAuth & Permissions 页面,找到 Bot Token Scopes,依次添加下面三项权限;随后点击 Install to Workspace 并批准安装。

    • users:read

      读取成员资料

    • users:read.email

      读取成员邮箱

    • usergroups:read

      读取用户组及成员关系

    安装完成后复制 Bot User OAuth Token(必须以 xoxb- 开头)。此后每次新增权限范围(Scope),都必须重新安装应用。

  5. 05

    获取 App Token 并启用 Socket Mode

    回到 Basic Information → App-Level Tokens,点击 Generate Token and Scopes,添加下方权限,生成并复制以 xapp- 开头的令牌;随后进入 Socket Mode 页面开启 Enable Socket Mode。

    • connections:write

      允许 App Token 建立 Socket Mode 连接

  6. 06

    订阅通讯录变更事件

    进入 Event Subscriptions 开启事件订阅,在 Subscribe to bot events 中逐项添加下面五个事件。

    • team_join

      新成员加入工作区

    • user_change

      成员资料发生变化

    • subteam_created

      创建用户组

    • subteam_updated

      用户组资料发生变化

    • subteam_members_changed

      用户组成员发生变化

  7. 07

    把 Slack 凭证填回 Ankole

    确认“同步通讯录”和“实时同步通讯录变更”已开启,然后点击“验证配置并登录”,在 Slack 授权页完成登录。

    • Client ID:Basic Information 中的 Client ID
    • Client Secret:同一页的 Client Secret
    • Workspace ID:可选。填写 Slack 网页地址 /client/T… 中以 T 开头的值,可预先指定登录的工作区,但不限制通讯录同步范围
    • Bot User OAuth Token:刚才获取的 xoxb- 令牌
    • App-Level Token:刚才获取的 xapp- 令牌
  8. 08

    确认登录和首次同步

    浏览器跳回 Ankole 后,当前 Slack 用户会同时获得 siteadmin(访问 /site-admin-console 站点管理台)与默认 Pod 的 pod_admin 权限。打开 Console → 身份源提供商,选择 slack-main,再点击“运行全量同步”。

    同步完成后,在 Console → 主体和权限组中确认工作区成员与 Slack 用户组已经出现。

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

模型档案通过引用已登记的模型提供商解析路由,因此请先登录 Console 打开 模型提供商 → 新增提供商,选择提供商类型,粘贴 API 密钥并保存。Console 会自动给出 Provider ID,接口地址默认使用该提供商的官方地址;只有 Azure OpenAI 这类按资源分配地址的服务,以及自建或兼容端点,才需要填写地址。控制面会对所有提供商凭证加密存储,切勿将模型 API 密钥写入部署环境变量或 Agent 工作区文件中。

接着打开 Console → Model Profiles,配置站点默认的语言模型槽位,所有 Pod 和 Agent 都会继承(按 Site -> Pod -> Agent/System 三层稀疏继承,并支持 heavy -> primary 与 light -> primary 自动回退):

Profile 建议用途
primary 日常对话与工具调用使用的主模型(必填;light 与 heavy 未配置时均回退至此)
light 高频、低成本轻量回合与 ankole_brain 日常事实抽取
heavy 高复杂度深度综合、持久后台 Agent 任务、离线 Dreaming 归纳与技能教训复审

首次跑通链路时,只需在站点默认配置里为 primary 绑定一个已验证可用的提供商和模型,所有 Agent 与 ankole_brain 即可直接运行;待确认端到端对话顺畅后,再将 light 与 heavy 拆分为不同档位的模型。

在 Pod 工作区中,系统已为每位内部成员自动配备 1:1 专属个人助理(可在 Pod Chat 中直接对话)。如需创建供团队共享或对接外部 IM 渠道的专业岗位 AI 同事,请打开 Agents → New Agent,设定语义清晰的租户内小写 uid(例如 research-analyst)、显示名称、角色定位、负责人与 WorkerProvider 并保存。新建 Agent 默认继承站点与 Pod 的模型档案(无需逐项重复填表,仅需按需覆盖特定槽位),其行为准则与视觉设计规范则在 Meta Ankole → Agents 的 AGENTS.md 与 DESIGN.md 中统一维护。

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

团队成员在内置 Pod Chat 中可直接与个人助理和 AI 同事对话,无需配置路由规则。如需接入外部 IM 渠道,请先在 Console 中确认目标平台的控制面插件(Control Plane Plugin)已启用。对于接入了 Ankole.Connectors 的平台(如飞书 / Lark),在 Pod → Connections(/connectors)或 Console 中登记一套共享应用连接(authConfigId)后,即可将同一个飞书自建应用直接复用于 SSO 登录、通讯录同步、IM 信号路由、MCP 工具包与事件触发器,无需重复创建应用或二次粘贴密钥。当多位 AI 同事需要展示各自独立的机器人名称、头像或权限范围时,也可分别登记独立的机器人连接并绑定各自的信号路由规则。

在账号映射机制上,Slack、Teams、飞书 / Lark、钉钉与企业微信属于企业办公平台,发信人直接对应 IdP 同步的企业通讯录成员;Telegram、Discord、LINE 与 WhatsApp 则属于个人消费级 IM,发信人没有企业员工档案,默认需由管理员先在身份 → 待绑定账号中将每位新发信人关联至已有账号后,Agent 才会为其提供服务(WhatsApp 若检测到发信手机号已归属某个已知主体,则会自动完成映射);电子邮件渠道接入的是单个专用邮箱,仅识别命中显式邮箱身份绑定的发件人。

Slack 通过 Socket Mode 连接:由 Ankole 主动向外建立 WebSocket 长连接,无需向 Slack 开放公网 Webhook。

开始之前

  • 具备创建并安装 Slack 应用的权限
  • 一个测试频道或私聊窗口

基础设置

准备 Slack 应用

  1. 01

    新建应用并启用 Socket Mode

    新建一个 Slack 应用,在 Basic Information 中生成 App-Level Token 并添加下方权限,随后开启 Socket Mode。

    • connections:write

      允许 App Token 建立 Socket Mode 连接

  2. 02

    订阅聊天和频道状态事件

    进入 Event Subscriptions → Subscribe to bot events,逐项添加以下事件。该清单严格对应 Slack 适配器实现的消息收发、表情回应(reaction)与频道状态同步能力。

    • app_mention

      接收频道中的 @ 消息

    • message.channels

      接收公开频道消息

    • message.groups

      接收私有频道消息

    • message.im

      接收私聊消息

    • message.mpim

      接收多人私聊消息

    • reaction_added

      接收新增 reaction

    • reaction_removed

      接收移除 reaction

    • member_joined_channel

      同步频道成员加入

    • member_left_channel

      同步频道成员离开

    • channel_rename

      同步频道改名

    • group_rename

      同步私有频道改名

    • channel_deleted

      同步频道删除

    • channel_archive

      同步频道归档

  3. 03

    启用私聊入口

    进入 App Home → Show Tabs,开启 Display Messages tab,并勾选 Allow users to send Slash commands and messages from the messages tab——若只开启标签页而不勾选允许发信,员工虽能看到消息页却无法向 Agent 发送私聊。

  4. 04

    启用 Slack 原生交互

    进入 Interactivity & Shortcuts 并启用 Interactivity。Socket Mode 会直接复用现有 WebSocket 通道投递 Block Kit 按钮点击事件,无需填写公网 Request URL。

  5. 05

    添加完整聊天权限并安装应用

    在 OAuth & Permissions → Bot Token Scopes 中逐项添加以下权限。该清单仅涵盖 Ankole 实际调用的 Slack 接口,请勿额外添加未使用的 Assistant、工作流、文档或会议权限。

    • app_mentions:read

      读取发给机器人的 @ 消息

    • channels:read

      同步公开频道及成员

    • channels:history

      读取公开频道消息并核对回信

    • groups:read

      同步私有频道及成员

    • groups:history

      读取私有频道消息并核对回信

    • im:read

      同步私聊会话

    • im:history

      读取私聊消息并核对回信

    • mpim:read

      同步多人私聊会话及成员

    • mpim:history

      读取多人私聊消息并核对回信

    • chat:write

      发送、更新和撤回机器人消息

    • reactions:read

      接收 reaction 变化

    • reactions:write

      添加和移除 reaction

    • files:read

      读取消息中的文件

    • files:write

      上传 Agent 发送的文件

    • users:read

      识别频道成员并排除机器人账号

    每次修改权限范围(Scope)后,都必须重新将应用安装到工作区,并把新生成的 Bot Token 更新回 Ankole。

  6. 06

    准备 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、钉钉、企业微信、Telegram、Discord、LINE、WhatsApp 或 Email
规则名称 填写稳定的标识名称,例如 slack-main 或 lark-main
Group message mode 首次联调测试请选择 addressed_only
聊天渠道配置 填入上方对应平台标签页中准备好的各项凭证与参数

保存后,确认该规则在列表中显示为启用状态。若保存时提示凭证校验有误,请先修正凭证再去聊天软件测试——在凭证通过检查前,平台适配器不会建立连接。

5. 在 IM 中与 Agent 对话

将配置好的机器人拉入测试会话。首次在群聊中测试时,请明确 @ 提及它:

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

收到由真实大模型生成的回复后,即可继续在 Meta Ankole → Agents 中打磨 AGENTS.md 与 DESIGN.md 规范,并按业务需求细化模型档位与群聊介入策略。

Agent 没有回复时

若迟迟未收到回复,请按以下顺序逐项排查:

  1. 聊天平台后台中的应用已发布最新版本,且当前测试账号在应用可用范围内。
  2. 机器人已被邀请加入测试所在的频道、团队或群聊会话。
  3. 平台要求的消息接收事件与接口权限均已审批生效。
  4. 信号路由规则处于启用状态,且指向正确的目标 Agent。
  5. 目标 Agent 能解析出有效的 primary 模型档案(来自 Console → Model Profiles 的站点/Pod 默认值或 Agent 覆盖配置)。
  6. 模型提供商的 API 凭证与模型名称真实有效。
  7. 若本轮需要环境工具或 Codex 任务,在 Console → 工作节点 中检查对应 Worker 的状态及启动失败原因。创建 Agent 时会请求启动一次 Worker;空闲释放后,纯问答与控制面工具无需等待 Worker 就绪。

使用 Docker Compose 部署时,可运行 docker compose logs -f control-plane 查看控制面实时日志;如需查看 Worker 日志,先运行 docker ps -a --filter label=ankole.installation=ankole 列出 Worker 容器,再执行 docker logs CONTAINER_NAME 查看目标容器。使用 Kubernetes 部署时,分别查看控制面 Pod 与对应 Worker Pod 的日志即可。排查问题时请仅截取相关报错行,切勿打印环境变量或任何敏感密钥。

跑通首条回复后,可继续阅读 Agent、信号路由规则或 后台 Agent 任务。