# Ankole

> Ankole 是配备公司大脑的开源 Claude Tag 替代方案，也是一套企业级 Agent Harness。公司大脑为 Agent 提供企业决策所需的共享上下文。

面向 AI Agent 的 Ankole 文档。每个页面链接都打开该页的 Markdown 版本。

部署或配置 Ankole 实例时，请先阅读[快速开始](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md)。它涵盖所有部署方式、身份源、LLM Provider 和聊天渠道。排查故障原因时，请阅读[常见问题与故障排查](https://ankole.agentbull.com/zh-Hans-CN/docs/faq/index.md)。

## 快速上手

- [介绍](https://ankole.agentbull.com/zh-Hans-CN/docs/introduction/index.md): 介绍 Ankole Agent Harness、公司大脑和私有部署实例的工作方式。
- [快速开始](https://ankole.agentbull.com/zh-Hans-CN/docs/quickstart/index.md): 部署 Ankole，配置企业身份和模型，接入聊天平台，直到用户能在 IM 中收到 Agent 的真实回复。
- [适配器配置指南](https://ankole.agentbull.com/zh-Hans-CN/docs/adapter-configuration/index.md): 按平台查找 Ankole 身份源和聊天渠道的应用类型、凭证、权限与验证步骤。

## 使用指南

- [环境变量](https://ankole.agentbull.com/zh-Hans-CN/docs/worker-env/index.md): 通过 Console 为全部 Agent 或单个 Agent 配置命令行工具、MCP 服务和后台 Agent 任务所需的环境变量。
- [Agent](https://ankole.agentbull.com/zh-Hans-CN/docs/agents/index.md): 说明如何在 Console 中创建 Agent，并设置负责人、长期设定、模型、能力和环境变量。
- [信号路由规则](https://ankole.agentbull.com/zh-Hans-CN/docs/signal-bindings/index.md): 把一个聊天应用连接到指定 Agent，并设置群聊消息的处理方式。
- [群聊主动介入](https://ankole.agentbull.com/zh-Hans-CN/docs/ambient-intervention/index.md): Agent 在"可主动介入"的群里如何判断是否发言、如何回到提问的人，以及如何用频道常驻指令告诉它什么时候该说话。
- [Brain](https://ankole.agentbull.com/zh-Hans-CN/docs/brain/index.md): 让 Agent 从对话、文件和网页中积累可追溯的组织知识，并在明确的披露边界内召回、修正和遗忘。
- [Workflow：并行子 Agent](https://ankole.agentbull.com/zh-Hans-CN/docs/workflows/index.md): 把有界工作拆给并行子 Agent，并在原会话中收回一个结构化结果。
- [后台 Agent 任务](https://ankole.agentbull.com/zh-Hans-CN/docs/background-jobs/index.md): 把耗时工作交给可恢复的后台任务，同时继续当前对话。
- [计划任务](https://ankole.agentbull.com/zh-Hans-CN/docs/schedules/index.md): 用 Cron 重复执行任务，或让 Agent 通过 Checkback 在指定时间回来继续工作。
- [Automation Job](https://ankole.agentbull.com/zh-Hans-CN/docs/automation-jobs/index.md): 让确定性脚本承接 Cron、Checkback 和 Webhook 触发：机械检查静默完成，需要判断时再唤醒 Agent。
- [Webhook 委托](https://ankole.agentbull.com/zh-Hans-CN/docs/webhook-delegations/index.md): 让 Agent 或确定性脚本无需轮询即可等待低频外部事件。
- [图像生成](https://ankole.agentbull.com/zh-Hans-CN/docs/image-generation/index.md): 为 Agent 选择图像模型，并在聊天中生成或修改图片。
- [OCR 文字识别](https://ankole.agentbull.com/zh-Hans-CN/docs/ocr/index.md): 让 Agent 从扫描 PDF、照片、截图和收据中读取文字，无需 GPU 或外部 OCR 服务。
- [文件管理](https://ankole.agentbull.com/zh-Hans-CN/docs/file-management/index.md): 在 Console 中上传参考资料、下载 Agent 产物，并管理 Agent 的持久文件。
- [Agent 能力库](https://ankole.agentbull.com/zh-Hans-CN/docs/skills/index.md): 为全部或单个 Agent 启用 Agent Plugin、Skill 和 Control Plane Plugin。
- [Web 工具](https://ankole.agentbull.com/zh-Hans-CN/docs/web-tools/index.md): 为 Agent 配置网页搜索和正文读取，并判断何时改用浏览器。
- [技能教训](https://ankole.agentbull.com/zh-Hans-CN/docs/skill-lessons/index.md): 让每个 Agent 在不改动共享 Skill 的前提下，获得简短的过程注意事项。
- [ChatGPT 订阅 Provider](https://ankole.agentbull.com/zh-Hans-CN/docs/chatgpt-subscription-provider/index.md): 通过设备码登录把 ChatGPT 订阅接入 AIGateway，并用凭据池管理多个账号。
- [让 Agent 读取图片](https://ankole.agentbull.com/zh-Hans-CN/docs/vision/index.md): 为 Agent 配置图片理解模型，并验证聊天中的截图、照片和图表是否可以正常读取。
- [系统配置](https://ankole.agentbull.com/zh-Hans-CN/docs/app-configuration/index.md): 在 Console 中管理 Ankole 的 AppConfigure 运行时设置，并查阅内置配置键。
- [LLM 可观测性](https://ankole.agentbull.com/zh-Hans-CN/docs/llm-observability/index.md): 把带有 AIGateway LLM 语义的可选跨运行时 Agent Turn trace 导出到 OTLP/HTTP 接收端。
- [主体与权限组](https://ankole.agentbull.com/zh-Hans-CN/docs/principal-and-groups/index.md): 从身份源同步人员和组织架构，并用目录组、静态组或动态组统一分配权限。
- [工作节点](https://ankole.agentbull.com/zh-Hans-CN/docs/worker-management/index.md): 在 Console 中查看 Agent Computer Worker 的状态、容量和最近心跳，并处理常见故障。
- [查看日志](https://ankole.agentbull.com/zh-Hans-CN/docs/log-reading/index.md): 从 Docker Compose 或 Kubernetes 获取 Ankole 日志，并用事件名和上下文字段定位问题。

## 开发者指南

- [架构](https://ankole.agentbull.com/zh-Hans-CN/docs/architecture/index.md): 说明控制面、Agent Computer Worker、Actor Runtime、Brain 和后台 Agent 任务如何构成 Ankole Agent Harness。
- [AIGateway API](https://ankole.agentbull.com/zh-Hans-CN/docs/ai-gateway/index.md): OpenResponses 兼容的 AI 边界——HTTP、SSE、WebSocket 端点，无状态与有状态调用，以及 provider 路由。
- [SignalsGateway](https://ankole.agentbull.com/zh-Hans-CN/docs/signals-gateway/index.md): 共享工作入口层——聊天、webhook 和 provider 事件如何变成 actor 事件，而又不把来源事实错写成执行状态。
- [Actor Runtime](https://ankole.agentbull.com/zh-Hans-CN/docs/actor-runtime/index.md): 一个长时 session 如何存活、唤醒、失败与恢复——actor key、OTP 故障域、activation 隔离栏，以及 RuntimeFabric 的实时路径。
- [Background Agent Jobs](https://ankole.agentbull.com/zh-Hans-CN/docs/background-agent-jobs/index.md): 跨越 worker 故障的持久、可恢复工作——job 状态机、等待输入、唤醒 owner，以及与 Actor Runtime 的边界。
- [主体与 AuthZ](https://ankole.agentbull.com/zh-Hans-CN/docs/principal-authz/index.md): Ankole 实例的权限边界，包括主体、授权规则、权限组成员关系和运行时权限检查。
- [Agent Library](https://ankole.agentbull.com/zh-Hans-CN/docs/agent-library/index.md): 一个 agent 能做什么——skill 作为文件系统 bundle，Agent Plugin 作为 Codex 包，以及按 agent 解析的“默认再覆盖”启用模型。
- [Agent Computer Worker](https://ankole.agentbull.com/zh-Hans-CN/docs/agent-computer-worker/index.md): Bun + TypeScript 执行节点如何运行模型循环、工具、文件、终端状态与流式输出，以及控制面如何隔离每个回合。
- [Rust Kernel](https://ankole.agentbull.com/zh-Hans-CN/docs/kernel/index.md): 共享的原生层——对授权、RuntimeFabric 传输和 AI 数据面原语的一份 Rust 实现，同时被 Elixir 控制面和 Bun worker 加载。
- [Control Plane Plugins](https://ankole.agentbull.com/zh-Hans-CN/docs/control-plane-plugins/index.md): 第一方 Elixir 扩展模型——已发现与已激活的 plugin、子系统契约、AppConfigure 键、受监督子进程，以及下一次启动才生效的启用边界。
- [开发 Skill 与 Control Plane Plugin](https://ankole.agentbull.com/zh-Hans-CN/docs/writing-a-skill/index.md): 为 Agent 增加工作方法，或为控制面增加身份源、聊天适配器、配置项和后台服务。
- [Worker CLI 能力](https://ankole.agentbull.com/zh-Hans-CN/docs/cli-capabilities/index.md): 把 Agent 能力做成 shell 命令，由 --help 承载契约，并把一句话指针放在 Agent 做相关决策的位置。
- [添加 provider](https://ankole.agentbull.com/zh-Hans-CN/docs/adding-a-provider/index.md): 如何声明一个 AIGateway provider——DSL、编译后的定义、设置、能力、prepare 函数、基于 plugin 的注册。
- [上下文压缩与 compaction](https://ankole.agentbull.com/zh-Hans-CN/docs/context-compression-and-caching/index.md): Ankole 如何让长会话保持在模型上下文内——AIGateway 自动历史 compaction 与逐字用户原文保留。
- [Agent 循环](https://ankole.agentbull.com/zh-Hans-CN/docs/agent-loop/index.md): 控制面回合生命周期与 worker 侧 agent 循环之间的边界——各自拥有什么、如何通信、迭代预算与重试住在哪里。
- [Prompt 组装](https://ankole.agentbull.com/zh-Hans-CN/docs/prompt-assembly/index.md): agent 每个回合看到的系统 prompt 如何构建——控制面数据提供者、两条传给 worker 的通道、worker 侧组装出最终 prompt 的过程。
- [Provider 运行时](https://ankole.agentbull.com/zh-Hans-CN/docs/provider-runtime/index.md): AIGateway 如何把选择符解析到 provider、构建准备好的请求、经 kernel 分发——从模型调用到 provider 响应的三阶段。
- [工具运行时](https://ankole.agentbull.com/zh-Hans-CN/docs/tools-runtime/index.md): Worker 如何为每个回合定义和分发工具，包括主回合的 Workflow 工具与受限的 Workflow 任务工具集。
- [轨迹与消息格式](https://ankole.agentbull.com/zh-Hans-CN/docs/trajectory-format/index.md): Ankole 如何存储和投影会话消息与后台任务轨迹——两种存储形态、ChatML 规范形式、剥离协议细节的模型可见投影。
- [代码执行](https://ankole.agentbull.com/zh-Hans-CN/docs/code-execution/index.md): Ankole Agent 如何在普通对话和持久的后台 Agent 任务中运行代码。
- [使用 MCP-backed Skill](https://ankole.agentbull.com/zh-Hans-CN/docs/using-mcp/index.md): 已启用的 Skill 如何通过 mcporter 把 Agent 或 Automation 脚本路由到 MCP server。
- [任务清单与澄清](https://ankole.agentbull.com/zh-Hans-CN/docs/todo-and-clarify/index.md): Ankole agent 如何为复杂任务做计划、如何在任务中途解决真正的歧义——todo 工具（按会话、同时最多一项进行中）和 clarify 工具（一个问题，持久记录，结束本回合）。agent 各拿它们做什么，运维不该期待它们做什么。
- [审计轨迹](https://ankole.agentbull.com/zh-Hans-CN/docs/audit-trail/index.md): 如何阅读 Ankole 的审计面——AuthZ 授权记录、控制面结构化日志、各自记录了谁在何时改了什么。
- [AIGateway API 使用](https://ankole.agentbull.com/zh-Hans-CN/docs/aigateway-api-usage/index.md): 外部调用方如何使用 AIGateway REST API——OpenResponses 兼容端点、agent vs admin token、无状态与有状态调用、完整示例。

## 参考

- [kit CLI 参考](https://ankole.agentbull.com/zh-Hans-CN/docs/kit-cli/index.md): devkit 命令界面——运维者或贡献者会跑的每一条 `bun run kit` 命令、它做什么，以及包裹它的脚本。
- [MCP server 参考](https://ankole.agentbull.com/zh-Hans-CN/docs/mcp/index.md): Skill-backed MCP 依赖如何进入 Main、Background 与 Automation 执行。
- [部署环境变量](https://ankole.agentbull.com/zh-Hans-CN/docs/environment-variables/index.md): 查阅控制面和 Agent Computer Worker 在进程启动时读取的部署配置。
- [Console API 参考](https://ankole.agentbull.com/zh-Hans-CN/docs/console-api/index.md): Console 使用的 /api/v1 REST 接口参考，包括认证、资源路由和授权操作。
- [常见问题与故障排查](https://ankole.agentbull.com/zh-Hans-CN/docs/faq/index.md): 按实际症状定位 Ankole 的部署、身份源、模型、Worker 和聊天渠道问题。

## 操作指南

- [用 Deep Research 完成长时间调研](https://ankole.agentbull.com/zh-Hans-CN/docs/deep-research-job/index.md): 把多来源调研交给后台 Agent 任务，用可插拔的研究方法产出有证据链、经独立复核的报告。
- [Git 集成](https://ankole.agentbull.com/zh-Hans-CN/docs/git-integration/index.md): Ankole Agent 如何在普通对话或后台 Agent 任务中使用 git。
- [Jupyter 数据分析](https://ankole.agentbull.com/zh-Hans-CN/docs/jupyter-data-analysis/index.md): 如何设置一个通过 live Jupyter kernel 运行迭代 Python 数据分析的 agent——jupyter-live-kernel skill、DataFrame 检查、完整示例。
- [浏览器自动化](https://ankole.agentbull.com/zh-Hans-CN/docs/browser-automation/index.md): Ankole agent 如何驱动一个真实浏览器会话——browser skill、何时该用它而不是 web_search/web_fetch、如何启用、以及为什么 agent 必须用预配置的 ankole-browser CLI 而不是自己启动 Chromium。
- [PDF 生成](https://ankole.agentbull.com/zh-Hans-CN/docs/pdf-generation/index.md): 如何设置一个创建、检查和编辑 PDF 文件的 agent——pdf skill、它用的工具、完整示例。
- [Context.dev 网页数据](https://ankole.agentbull.com/zh-Hans-CN/docs/context-dev/index.md): 通过 Context.dev API 让 Agent 读取拒绝抓取的页面、整站抓取、按 schema 抽取结构化数据、查询品牌资料，并按计划监控页面变化。
- [运维技巧](https://ankole.agentbull.com/zh-Hans-CN/docs/tips/index.md): 运行 Ankole 时省时间的短小、经过验证的动作——读日志、限定 agent 范围、轮换 secret、从卡住的回合恢复、把 model profile 槽当拨盘用。
- [自动化蓝图](https://ankole.agentbull.com/zh-Hans-CN/docs/automation-blueprints/index.md): 把触发器与 Agent session、Automation Job、后台任务和信号路由规则组合成自动化，并区分 Workflow。
- [成本管理](https://ankole.agentbull.com/zh-Hans-CN/docs/cost-management/index.md): 控制 Ankole 花费的杠杆——模型档案、reasoning effort、Web 工具、回合预算、Workflow fanout 和后台任务上限。
- [备份与还原](https://ankole.agentbull.com/zh-Hans-CN/docs/backup-and-restore/index.md): 必须备份的两样——PostgreSQL 和 Agent Home——如何备份、如何还原，以及为什么未经测试的备份不算备份。
- [安全加固](https://ankole.agentbull.com/zh-Hans-CN/docs/security-hardening/index.md): 加固 Ankole 实例，包括最小权限、Secret 管理、SSRF 防护、凭证轮换和减少外部入口。
- [性能调优](https://ankole.agentbull.com/zh-Hans-CN/docs/performance-tuning/index.md): 了解并发回合、数据库连接池、PostgreSQL 最大连接数、Worker 回合上限和 Agent 任务槽怎样共同决定一个实例的并发能力。
- [灾难恢复](https://ankole.agentbull.com/zh-Hans-CN/docs/disaster-recovery/index.md): 恢复 Ankole 实例，包括可恢复数据、不可恢复数据、跨主机迁移和恢复演练。
- [贡献](https://ankole.agentbull.com/zh-Hans-CN/docs/contributing/index.md): 一次 Ankole 贡献合并的路径——规则住在哪里、如何设置、如何跑对的检查、项目要求的 changelog 与 PR 纪律。

## 其他语言

- [English](https://ankole.agentbull.com/en-US/llms.txt)
- [日本語](https://ankole.agentbull.com/ja-JP/llms.txt)
- [한국어](https://ankole.agentbull.com/ko-KR/llms.txt)

## Optional

- [完整文档](https://ankole.agentbull.com/zh-Hans-CN/llms-full.txt): 本语言的全部页面，合并为一个 Markdown 文件