跳到正文
Ankole
文档
GitHub
菜单
文档
GitHub
文档
把 Ankole 跑起来，要知道的都在这里
完成部署，理解运行时模型，并运维一个完全由你掌控的私有化部署实例。
从「介绍」开始读
01
快速上手
介绍
了解 Ankole 的核心定位、自主劳动力与 Copilot 的区别，以及私有化部署实例的组件构成。
快速开始
部署 Ankole，配置企业身份和模型，接入聊天平台，直到用户能在 IM 中收到 Agent 的真实回复。
02
使用指南
环境变量
通过 Console 为全部 Agent 或单个 Agent 配置命令行工具、MCP 服务和后台 Agent 任务所需的环境变量。
Agent
在 Console 中创建 Agent，设置职责、长期行为、模型、能力和环境变量。
信号路由规则
把一个聊天应用连接到指定 Agent，并设置群聊消息和记忆的处理方式。
后台 Agent 任务
把耗时工作交给可恢复的后台任务，同时继续当前对话。
计划任务
用 Cron 重复执行任务，或让 Agent 通过 Checkback 在指定时间回来继续工作。
图像生成
为 Agent 选择图像模型，并在聊天中生成或修改图片。
Webhook 委托
让 Agent 或确定性脚本无需轮询即可等待低频外部事件。
长期记忆
了解 Ankole 如何从对话、任务和外部资料中形成会持续演化的长期记忆，并检查、纠正和维护 Agent 的知识与技能经验。
文件管理
在 Console 中上传参考资料、下载 Agent 产物，并管理 Agent 的持久文件。
Agent 能力库
为全部或单个 Agent 启用 Agent Plugin、Skill 和 Control Plane Plugin。
Web 工具
为 Agent 配置网页搜索和正文读取，并判断何时改用浏览器。
ChatGPT 订阅 Provider
通过设备码登录把 ChatGPT 订阅接入 AIGateway，并用凭据池管理多个账号。
让 Agent 读取图片
为 Agent 配置图片理解模型，并验证聊天中的截图、照片和图表是否可以正常读取。
系统配置
在 Console 中管理 Ankole 的 AppConfigure 运行时设置，并查阅内置配置键。
主体与权限组
从身份源同步人员和组织架构，并用目录组、静态组或动态组统一分配权限。
工作节点
在 Console 中查看 Agent Computer Worker 的状态、容量和最近心跳，并处理常见故障。
查看日志
从 Docker Compose 或 Kubernetes 获取 Ankole 日志，并用事件名和上下文字段定位问题。
03
开发者指南
架构
了解控制面、Agent Computer Worker、Actor Runtime、Brain 和后台 Agent 任务如何组成 Ankole。
AIGateway API
OpenResponses 兼容的 AI 边界——HTTP、SSE、WebSocket 端点，无状态与有状态调用，以及 provider 路由。
SignalsGateway
共享工作入口层——聊天、webhook 和 provider 事件如何变成 actor 事件，而又不把来源事实错写成执行状态。
Actor Runtime
一个长时 session 如何存活、唤醒、失败与恢复——actor key、OTP 故障域、activation 隔离栏，以及 RuntimeFabric 的实时路径。
Brain
Ankole 实例的长期记忆，包括整理后的知识、原始聊天召回、Dreaming 和人工审核；PostgreSQL 记录是事实，Markdown 是投影。
Background Agent Jobs
跨越 worker 故障的持久、可恢复工作——job 状态机、等待输入、唤醒 owner，以及与 Actor Runtime 的边界。
主体与 AuthZ
Ankole 实例的权限边界，包括主体、授权规则、权限组成员关系和运行时权限检查。
Agent Library
一个 agent 能做什么——skill 作为文件系统 bundle，Agent Plugin 作为 Codex 包，以及按 agent 解析的“默认再覆盖”启用模型。
Agent Computer Worker
Bun + TypeScript 执行节点如何运行模型循环、工具、文件、终端状态与流式输出，以及控制面如何隔离每个回合。
Rust Kernel
共享的原生层——对授权、RuntimeFabric 传输和 AI 数据面原语的一份 Rust 实现，同时被 Elixir 控制面和 Bun worker 加载。
Control Plane Plugins
第一方 Elixir 扩展模型——已发现与已激活的 plugin、子系统契约、AppConfigure 键、受监督子进程，以及下一次启动才生效的启用边界。
开发 Skill 与 Control Plane Plugin
为 Agent 增加工作方法，或为控制面增加身份源、聊天适配器、配置项和后台服务。
Worker CLI 能力
把 Agent 能力做成 shell 命令,由 --help 承载契约,并把一句话指针放在 Agent 做相关决策的位置。
添加 provider
如何声明一个 AIGateway provider——DSL、编译后的定义、设置、能力、prepare 函数、基于 plugin 的注册。
上下文压缩与 compaction
Ankole 如何让长会话保持在模型上下文内——AIGateway 自动历史 compaction、逐字用户原文保留、Brain dreaming 的常驻长期记忆 memo compactor。
Agent 循环
控制面回合生命周期与 worker 侧 agent 循环之间的边界——各自拥有什么、如何通信、迭代预算与重试住在哪里。
Prompt 组装
agent 每个回合看到的系统 prompt 如何构建——控制面数据提供者、两条传给 worker 的通道、worker 侧组装出最终 prompt 的过程。
Provider 运行时
AIGateway 如何把选择符解析到 provider、构建准备好的请求、经 kernel 分发——从模型调用到 provider 响应的三阶段。
工具运行时
worker 如何收集、schema 化、分发一个回合提供给模型的工具——AgentTool 契约、按回合组装、schema 转换、调用分发路径。
轨迹与消息格式
Ankole 如何存储和投影会话消息与后台任务轨迹——两种存储形态、ChatML 规范形式、剥离协议细节的模型可见投影。
代码执行
Ankole Agent 如何在普通对话和持久的后台 Agent 任务中运行代码。
使用 MCP server
Ankole agent 如何把 Model Context Protocol server 当工具用——server 声明在哪、两种传输、默认超时、为什么 agent 只在声明它的 skill 启用时才看得到 server，以及运维如何改变 agent 看得到的 MCP server。
任务清单与澄清
Ankole agent 如何为复杂任务做计划、如何在任务中途解决真正的歧义——todo 工具（按会话、同时最多一项进行中）和 clarify 工具（一个问题，持久记录，结束本回合）。agent 各拿它们做什么，运维不该期待它们做什么。
审计轨迹
如何阅读 Ankole 的审计面——Brain 审计日志、控制面结构化日志、各自记录了谁在何时改了什么。
AIGateway API 使用
外部调用方如何使用 AIGateway REST API——OpenResponses 兼容端点、agent vs admin token、无状态与有状态调用、完整示例。
04
参考
kit CLI 参考
devkit 命令界面——运维者或贡献者会跑的每一条 `bun run kit` 命令、它做什么，以及包裹它的脚本。
MCP server 参考
Model Context Protocol server 如何声明与加载——openai.yaml 依赖模型、两种传输、超时，以及已启用 skill 如何贡献 server。
部署环境变量
查阅控制面和 Agent Computer Worker 在进程启动时读取的部署配置。
Console API 参考
Console 使用的 /api/v1 REST 接口参考，包括认证、资源路由和授权操作。
常见问题与故障排查
按实际症状定位 Ankole 的部署、身份源、模型、Worker 和聊天渠道问题。
05
操作食谱
用 Deep Research 完成长时间调研
把多来源调研交给后台 Agent 任务，用可插拔的研究方法产出有证据链、经独立复核的报告。
Git 集成
Ankole Agent 如何在普通对话或后台 Agent 任务中使用 git。
Jupyter 数据分析
如何设置一个通过 live Jupyter kernel 运行迭代 Python 数据分析的 agent——jupyter-live-kernel skill、DataFrame 检查、完整示例。
浏览器自动化
Ankole agent 如何驱动一个真实浏览器会话——browser skill、何时该用它而不是 web_search/web_fetch、如何启用、以及为什么 agent 必须用预配置的 ankole-browser CLI 而不是自己启动 Chromium。
PDF 生成
如何设置一个创建、检查和编辑 PDF 文件的 agent——pdf skill、它用的工具、完整示例。
运维技巧
运行 Ankole 时省时间的短小、经过验证的动作——读日志、限定 agent 范围、轮换 secret、从卡住的回合恢复、把 model profile 槽当拨盘用。
自动化蓝图
把触发器与 Agent session、automation job、后台任务和信号路由规则组合成自动化。
成本管理
控制 Ankole 花费的杠杆——model profile 档位、reasoning effort、web 工具按需、agent 循环预算、后台任务重试与槽位上限。
备份与还原
必须备份的两样——PostgreSQL 和 Agent Home——如何备份、如何还原，以及为什么未经测试的备份不算备份。
安全加固
加固 Ankole 实例，包括最小权限、Secret 管理、SSRF 防护、凭证轮换和减少外部入口。
性能调优
了解并发回合、数据库连接池、PostgreSQL 最大连接数、Worker 回合上限和 Agent 任务槽怎样共同决定一个实例的并发能力。
灾难恢复
恢复 Ankole 实例，包括可恢复数据、不可恢复数据、跨主机迁移和恢复演练。
贡献
一次 Ankole 贡献合并的路径——规则住在哪里、如何设置、如何跑对的检查、项目要求的 changelog 与 PR 纪律。
Ankole