TinyAGI：为独立开发者打造的AI智能体团队编排器实战指南

1. 项目概述：一个为独立开发者打造的AI团队管家

如果你和我一样，是一个独立开发者、自由职业者或者小型工作室的负责人，那你一定对“一人公司”这个概念不陌生。我们身兼数职，既要写代码，又要做设计，还得处理客户沟通和项目管理，恨不得一天有48小时。过去几年，我尝试过各种AI工具来提升效率，从单聊的ChatGPT到能执行代码的Claude Code，但它们始终是“单兵作战”。我需要一个能帮我写代码的“程序员”，一个能帮我润色文档的“文案”，一个能帮我分析需求的“产品经理”，并且它们之间还能互相协作，形成一个真正的“虚拟团队”。这就是我找到并深度使用TinyAGI的原因。

TinyAGI，这个项目最初叫TinyClaw，它的核心定位非常精准：为“一人公司”服务的AI智能体团队编排器。它不是一个简单的聊天机器人聚合器，而是一个完整的、可编程的AI代理协作平台。你可以把它想象成一个微型的、24小时在线的“AI公司后台”。在这个后台里，你可以创建多个拥有不同技能和上下文的AI智能体（Agent），将它们编入不同的团队（Team），然后通过Discord、Telegram、WhatsApp甚至网页端，向这个“公司”下达任务。智能体们会各司其职，甚至互相“派活”，最终给你一个整合的结果。

我使用它已经超过三个月，从最初的简单指令执行，到如今构建了一个包含“开发”、“文案”、“客服”三个角色的稳定工作流。它彻底改变了我处理多线程任务的方式。接下来，我将从一个深度使用者的角度，为你彻底拆解TinyAGI，分享从零搭建到高阶实战的全部细节、踩过的坑以及那些官方文档没写的“骚操作”。

2. 核心架构与设计哲学：为什么是“团队”，而不仅仅是“多个机器人”？

在深入命令行之前，我们必须先理解TinyAGI的设计思想。市面上有很多能让AI执行代码的工具，也有很多多AI对话的客户端，但TinyAGI的独特之处在于它的“团队协作”和“编排”能力。这不仅仅是功能上的堆砌，而是一种架构哲学。

2.1 隔离的工作空间：每个智能体都是独立的“员工”

这是TinyAGI最基础也最重要的设计。当你创建一个名为coder的智能体时，系统会在你的工作空间目录（默认是~/tinyagi-workspace/）下，为它创建一个专属文件夹：~/tinyagi-workspace/coder/。这个文件夹就是它的“工位”。

这个工位里有什么？

• 独立的对话历史：你和coder的所有对话，都保存在它自己的上下文中，与其他智能体（如writer）完全隔离。这意味着你可以同时和coder深入讨论一个复杂的算法，同时让writer去写另一份产品说明书，两者互不干扰。
• 专属的配置文件：每个智能体的工位里，都会复制一份.claude/目录（如果你使用Claude Code）或相应的CLI配置。这允许你为不同的智能体定制不同的系统提示词（System Prompt）、文件忽略规则等。例如，你可以给coder设置“你是一个严谨的Python后端专家”，而给writer设置“你是一个风趣的技术布道师”。
• 独立的心跳任务：每个智能体都可以有自己的heartbeat.md文件，里面定义了定期自动执行的任务。比如，让coder每小时检查一次代码仓库是否有未处理的合并请求，让writer每天下午总结当日文档进度。

实操心得：工作空间是核心资产我强烈建议将~/tinyagi-workspace/目录纳入你的版本控制系统（如Git）。这里存储了你为每个智能体精心调教的对话历史和上下文。一旦系统崩溃或需要迁移，直接恢复这个目录，你的整个“AI团队”就能立刻恢复工作状态，记忆丝毫不差。

2.2 基于队列的消息总线：确保任务不丢失、不混乱

想象一下，你同时从Discord和Telegram向coder发送了任务，或者一个任务触发了团队内多个智能体的连锁反应。如果没有一个可靠的消息处理机制，很容易出现消息丢失、处理顺序错乱或并发冲突。

TinyAGI在底层使用SQLite数据库作为消息队列。所有来自不同渠道（Discord、Telegram、WhatsApp、Web、CLI）的消息，都会首先被“排队”（enqueue）到数据库中。这个队列系统有几个关键特性：

1. 原子性事务：通过SQLite的WAL（Write-Ahead Logging）模式，确保即使在系统意外崩溃时，也不会出现“消息已接收但未处理”或“处理了一半”的中间状态。
2. 并行处理与顺序保证：不同的智能体可以并行处理各自队列中的消息。但对于同一个智能体，消息严格按照先进先出（FIFO）的顺序处理。这保证了你和某个智能体的对话逻辑是连贯的。
3. 重试与死信队列：如果一个消息处理失败（比如网络超时），系统会自动重试（默认最多5次）。如果最终仍然失败，消息会被移入“死信队列”（dead-letter queue），方便你后续排查问题，而不是静默丢弃。

消息流转的完整路径：

你 @coder 写个爬虫 -> Discord客户端接收 -> 消息入队（SQLite `messages`表，状态`pending`） -> 队列处理器发现 `coder` 有空闲 -> 消息状态变为 `processing` -> 调用 `claude` CLI，在 `~/tinyagi-workspace/coder/` 目录下执行 -> `claude` 生成回复 -> 回复入队（`responses`表） -> 队列处理器将回复发送回Discord频道 -> 消息状态变为 `completed`

这套机制虽然听起来复杂，但对用户是完全透明的。它的价值在于提供了企业级的可靠性，让你可以放心地把关键任务交给它，不用担心因为一个临时的网络波动导致任务“石沉大海”。

2.3 团队（Teams）与聊天室（Chatroom）：智能体间的社交网络

这是TinyAGI从“工具”升维到“平台”的关键。智能体不是孤岛，它们需要协作。

• 团队（Team）：你可以把多个智能体编入一个团队，并指定一个“队长”（leader agent）。当你向团队发送消息（如@dev 我们需要重构用户模块）时，消息默认会路由给队长。队长在处理过程中，可以在其回复中“@”提及团队内的其他成员（如“@reviewer请帮我审查一下这段代码”）。被提及的智能体会被自动触发，接手下一步工作。
  • 链式执行（Chain）：A -> B -> C 的线性协作。
  • 扇出执行（Fan-out）：A 同时 @B 和 @C，B和C并行处理。
• 聊天室（Chatroom）：每个团队都有一个永久的、异步的群聊室。智能体在协作过程中，所有的讨论和中间成果都会以[#team_id: 内容]的形式发布到聊天室。你可以通过TUI（终端界面）或TinyOffice网页端实时查看这个聊天室，就像在看一个Slack频道。这提供了无与伦比的可观测性，你随时可以知道你的“AI员工们”在讨论什么，进度如何。

踩坑记录：团队协作的“幽灵消息”早期使用时，我发现有时被 @ 的智能体没有反应。排查后发现，是因为智能体在回复中提及队友的格式不对。正确的格式是必须在消息体中明确写出@agent_id（如“@reviewer请审查”）。如果只是心里想着让下一个干，但回复里没写，协作链就断了。后来我养成了习惯，在给智能体的初始指令中就明确要求：“完成后，请将结果交给@writer进行文档化。” 这样能极大提高协作成功率。

3. 从零到一：手把手搭建你的第一个AI团队

理论讲完了，我们动真格的。假设你是一个全栈开发者，想搭建一个“开发团队”，里面有一个写代码的coder和一个做代码审查的reviewer。

3.1 环境准备与一键安装

TinyAGI对系统要求很宽松，macOS、Linux和Windows（通过WSL2）都可以。首先确保你有Node.js v18或更高版本。

最推荐的安装方式是一行命令：

curl -fsSL https://raw.githubusercontent.com/TinyAGI/tinyagi/main/scripts/install.sh | bash

这条命令会做几件事：下载最新发布版、安装tinyagi命令行工具到系统路径、创建默认配置。安装完成后，直接在终端输入：

tinyagi

奇迹就此发生。这个命令会：

1. 启动TinyAGI的后台守护进程（Daemon）。
2. 在~/.tinyagi/下生成配置文件settings.json。
3. 在~/tinyagi-workspace/下创建默认智能体tinyagi的工作目录。
4. 自动打开你的浏览器，跳转到TinyOffice网页控制台（通常位于http://localhost:3000）。

没错，连配置向导都省了，它直接给你一个可用的起点。默认的智能体tinyagi使用的是Anthropic的Claude模型（需要你事先通过claudeCLI登录授权）。

3.2 配置你的AI“大脑”：提供商（Provider）与模型

TinyAGI本身不提供AI能力，它是一个“编排器”，需要连接后端的AI服务。它原生支持两大主流提供商：

1. Anthropic Claude：通过claudeCLI。你需要先安装并登录claudeCLI（npm install -g @anthropic-ai/claude然后claude auth login）。
2. OpenAI Codex：通过codexCLI。

关键一步：存储你的API密钥为了让TinyAGI能无缝调用，你需要将API密钥或OAuth令牌交给它管理，这样就不用每次单独配置CLI环境变量了。

# 对于Anthropic（优先使用OAuth Token，更稳定） tinyagi provider anthropic --oauth-token sk-ant-oat01-... # 或者使用API Key tinyagi provider anthropic --api-key sk-ant-... # 对于OpenAI tinyagi provider openai --api-key sk-...

这些凭证会被安全地加密存储在~/.tinyagi/settings.json的models字段下。TinyAGI在调用CLI时，会自动设置相应的环境变量（如ANTHROPIC_API_KEY）。

高级玩法：自定义提供商这是TinyAGI非常强大的一个功能。你可以接入任何兼容OpenAI或Anthropic API格式的服务，比如：

• OpenRouter：聚合了数十个开源和闭源模型。
• 本地模型：使用ollama、lmstudio或vllm等架设的本地API服务。
• 其他云服务商的API网关。

添加一个自定义提供商（例如，连接本地的Ollama）：

tinyagi provider add

根据交互提示输入：

• Provider ID:local-llama
• Name:Local Llama3
• Harness (选择claude或codex格式):claude
• Base URL:http://localhost:11434/v1(Ollama的默认API地址)
• API Key: （本地服务通常不需要，可以留空或填dummy）
• Default Model:llama3.2

现在，你就可以在创建智能体时，指定它的提供商为custom:local-llama了。

3.3 创建与配置你的专属智能体

现在我们来创建“开发团队”的两个成员。

1. 创建代码编写智能体coder：

tinyagi agent add

交互式命令行会引导你：

• Agent ID:coder(用于在命令中引用的简短标识)
• Name:Code Master(显示名)
• Provider: 选择你刚配置好的，比如anthropic
• Model: 例如claude-3-5-sonnet-20241022
• Working Directory: 直接回车使用默认路径 (~/tinyagi-workspace/coder)

2. 创建代码审查智能体reviewer：重复tinyagi agent add流程。

• Agent ID:reviewer
• Name:Code Reviewer
• Provider: 可以选择同一个anthropic，也可以选另一个，比如openai的gpt-4o，实现多模型协作。
• Model:claude-3-haiku-20240307(Haiku速度快，适合做审查)
• Working Directory:~/tinyagi-workspace/reviewer

3. （可选）深度定制智能体每个智能体的工作目录下，都有一个.claude/config.json（如果用的是Claude）。你可以编辑这个文件，为这个智能体设定独特的系统指令（systemPrompt）。例如，为coder设置：

{ "systemPrompt": "你是一个经验丰富的全栈软件工程师，精通Python、JavaScript和Go。你写的代码必须简洁、高效、有完整的错误处理和日志。你热爱编写清晰的注释和文档。在给出解决方案前，总是先分析潜在的风险和边缘情况。" }

为reviewer设置：

{ "systemPrompt": "你是一个苛刻的代码审查员。你的任务是找出代码中的bug、安全漏洞、性能问题、不规范的写法以及可读性差的代码。对于每一处问题，必须指出具体行号、问题性质、严重程度（高/中/低）并提供具体的修改建议。你的审查意见应该直接、犀利。" }

3.4 组建团队并连接沟通渠道

1. 创建开发团队dev：

tinyagi team add

• Team ID:dev
• Name:Development Team
• Agents: 输入coder,reviewer（将刚才创建的两个智能体加入团队）
• Leader Agent:coder（指定coder为队长）

2. 连接Discord（推荐用于桌面端协作）这是最稳定、功能最全的渠道。

tinyagi channel setup

选择discord，然后你需要：

1. 访问 Discord开发者门户 ，创建一个新的应用（Application）。
2. 在“Bot”页面，点击“Add Bot”，创建机器人。
3. 复制生成的Bot Token，粘贴到TinyAGI的配置中。
4. 在Bot设置里，在“Privileged Gateway Intents”下，开启“Message Content Intent”。这一步至关重要，否则机器人看不到消息内容。
5. 在“OAuth2” -> “URL Generator”页面，勾选bot和applications.commands权限，并赋予它“Read Messages/View Channels”和“Send Messages”等必要权限。然后复制生成的链接，在浏览器中打开，将机器人邀请到你的服务器。

完成这些后，TinyAGI的Discord客户端就会连接上，你可以在服务器的任意频道里@你的智能体了。

3. 连接Telegram（推荐用于移动端快速指令）

tinyagi channel setup

选择telegram。

1. 在Telegram中搜索@BotFather。
2. 发送/newbot并按提示操作，给你的机器人起名。
3. 创建成功后，BotFather会给你一个Bot Token，将其粘贴到TinyAGI配置中。
4. 找到你的机器人，发起对话，点击“START”。

4. 连接WhatsApp（用于最日常的沟通）

tinyagi channel setup

选择whatsapp。TinyAGI会启动一个无头浏览器实例，并在终端显示一个二维码。

1. 在你的手机WhatsApp上，点击右上角菜单 -> 已关联的设备 -> 关联设备。
2. 扫描终端里的二维码。
3. 关联成功后，你就可以像给好友发消息一样，在WhatsApp里给你的AI团队发任务了。注意：请确保用于运行TinyAGI的电脑网络稳定，WhatsApp Web的会话可能会因为网络问题或长时间无操作而断开，需要重新扫描。

避坑指南：渠道配置的常见问题

• Discord机器人无响应：99%的原因是没开启“Message Content Intent”。请返回Discord开发者门户检查。
• Telegram机器人收不到消息：确保你已经和机器人开始了对话（发了/start）。
• WhatsApp二维码不显示或扫描失败：首先确保系统安装了Chromium或Chrome。如果失败，尝试运行tinyagi channels reset whatsapp重置状态，然后重新tinyagi channel setup whatsapp。有时需要科学稳定的网络环境。

至此，你的AI团队已经组建完毕，并且可以通过三个最流行的即时通讯工具进行访问。接下来，我们看看如何真正地“使用”他们。

4. 实战演练：与你的AI团队高效协作

一切就绪，让我们开始派活。假设你正在开发一个简单的待办事项API。

4.1 基础指令：与单个智能体对话

在任何已连接的渠道（Discord/Telegram/WhatsApp），或TinyOffice的聊天控制台，你都可以直接发送消息。

• 默认路由：发送帮我写一个FastAPI的hello world端点。这条消息会被发送给默认的tinyagi智能体（或你在设置中指定的默认智能体）。
• 指定智能体：发送@coder 用FastAPI创建一个TODO列表的RESTful API，需要GET/POST/PUT/DELETE端点，使用SQLite数据库。这条消息会精准路由到coder智能体。

coder会在它的独立工作空间里开始工作。它会生成main.py、models.py、database.py等文件。你可以通过TinyOffice的日志面板，或者直接查看~/tinyagi-workspace/coder/目录，来跟踪它的进度。

4.2 团队协作：触发智能体间的接力

现在，你想让reviewer审查一下coder刚写的代码。有两种方式：

方式一：你在对话中手动@你回复coder的输出，或者新开一条消息：@reviewer 请审查一下 @coder 刚刚生成的FastAPI代码，重点关注错误处理和安全性。

方式二：让coder在完成任务后自动呼叫reviewer（更自动化）你在给coder的初始指令中就写明：@coder 创建TODO API，完成后请将代码交给 @reviewer 进行审查。

当coder完成代码编写后，它会在回复中写道：“代码已生成，请@reviewer进行审查。” 此时，TinyAGI的团队协作引擎会捕捉到这条消息中对reviewer的提及，并自动将coder的整个对话上下文（包括生成的代码文件）作为新任务，传递给reviewer智能体。

reviewer被触发后，会基于它的系统指令（那个“苛刻的审查员”），开始分析代码，并直接在团队聊天室（#dev）里发布审查意见：

[#dev: @coder 我对你创建的 `main.py` 提出以下审查意见： 1. (高) 第15行：直接使用用户输入的`task`内容拼接SQL语句，存在SQL注入风险。应使用参数化查询。 2. (中) 第28行：删除操作未检查任务是否存在，成功删除不存在的ID也会返回204。建议先查询，不存在则返回404。 3. (低) 第5行：导入未使用的模块 `json`，建议移除。 ...]

现在，coder和reviewer甚至可以在聊天室里展开讨论（当然，是通过你）。你可以看到完整的协作流水线。

4.3 使用TinyOffice进行可视化管控

命令行和聊天工具适合快速交互，而TinyOffice则是你的“总控中心”。在浏览器打开http://localhost:3000（或运行tinyagi office后自动打开的地址）。

• 仪表盘：实时看到消息队列的长度、系统状态、最近的事件流。一眼就知道系统是否繁忙。
• 聊天控制台：这里可以像在Discord里一样发送消息，并且能更清晰地看到消息属于哪个智能体、哪个团队。
• 智能体与团队管理：图形化界面创建、编辑、删除智能体和团队，比命令行更直观。
• 任务看板：这是项目管理神器。你可以创建任务卡片，拖拽到“待处理”、“进行中”、“已完成”等列，并可以将任务直接分配给某个智能体或团队。智能体完成任务后，可以在聊天中更新任务状态。
• 日志与事件：所有消息的入队、处理、完成日志，以及系统事件，都可以在这里查询和过滤，是调试和审计的必备工具。
• 办公室视图：一个非常酷的模拟办公室场景，你的智能体们以卡通形象出现，当它们忙碌或互相发送消息时，会有对应的动画，让你对系统运行状态有更感性的认识。

4.4 高级功能：插件、心跳与发送者配对

插件系统如果你有定制化需求，TinyAGI提供了插件接口。你可以编写JavaScript插件，监听各种事件（如message:beforeEnqueue,agent:beforeInvoke）或添加消息钩子。例如，你可以写一个插件，自动将所有消息内容在处理前进行敏感信息过滤，或者将所有的任务完成情况自动同步到你的Notion数据库。插件放在~/.tinyagi/plugins/目录下即可被自动加载。

心跳任务每个智能体的工作目录下都有一个heartbeat.md文件。智能体会定期（默认每小时）读取这个文件的内容作为指令去执行。你可以把它当成一个“定时巡检任务”。 例如，在coder的heartbeat.md里写：

检查 `~/projects/my-api/` 目录下的Git状态，是否有未提交的更改或未推送的提交？ 如果有，列出它们。 检查项目的依赖是否有安全漏洞（可以结合`npm audit`或`safety check`命令）。

这样，每隔一小时，coder就会自动检查代码状态和安全性，并在聊天室或直接向你汇报。

发送者配对出于安全考虑，你可能不希望任何人都能通过你的公开Discord频道或Telegram机器人向你的AI团队发号施令。TinyAGI提供了“发送者配对”功能。

1. 当一个新的用户（发送者）第一次向你的机器人发送消息时，TinyAGI会生成一个随机的配对码（如ABCD1234）并回复给对方。
2. 你需要在你的终端运行tinyagi pairing pending查看待批准的发送者和配对码。
3. 运行tinyagi pairing approve ABCD1234来批准该发送者。
4. 此后，该发送者的消息才会被正常处理。未经批准的发送者，其后续消息会被静默忽略。

5. 运维、排错与性能调优

将这样一个系统用于生产，稳定性至关重要。以下是我在长期使用中积累的运维经验。

5.1 日常运维命令速查

5.2 常见问题与解决方案

问题1：消息卡住，一直显示“处理中”这是最常见的问题，通常是因为底层AI CLI（如claude）调用超时或崩溃，导致消息状态未被更新。

• 排查：首先运行tinyagi logs queue，查看卡住的消息ID和错误信息。
• 解决：

  # 1. 停止TinyAGI tinyagi stop # 2. 手动清理处理中的队列（谨慎操作！这会丢失正在处理的任务） rm -rf ~/.tinyagi/queue/processing/* # 3. 重启 tinyagi start

• 根治：检查你的网络连接和AI提供商API的稳定性。考虑为智能体设置更长的超时时间（可通过自定义提供商配置）。

问题2：智能体“失忆”，不记得之前的对话

• 原因：每个智能体的对话历史由对应的CLI（如claude）在它的工作目录内维护。如果工作目录下的.claude/等目录被意外删除或损坏，历史就会丢失。
• 预防：定期备份~/tinyagi-workspace/目录。
• 解决：无法恢复，但可以防止未来发生。确保不要手动删除工作目录下的隐藏文件夹。

问题3：Discord/Telegram机器人能收到消息但不回复

• 排查：运行tinyagi logs discord或tinyagi logs telegram，看是否有错误日志。常见原因是网络问题导致消息发送失败。
• 解决：检查机器人的权限是否足够（尤其是在Discord的某些频道）。重启渠道服务有时也有效：tinyagi stop然后tinyagi start。

问题4：团队协作中，被@的智能体没有触发

• 确认：检查发送消息的智能体，其回复中是否包含了正确的@agent_id格式。必须是独立的单词，如“请@reviewer看看”。如果写成“请reviewer看看”则无效。
• 检查：运行tinyagi team show dev，确认reviewer确实在dev团队的成员列表中。

5.3 性能调优与最佳实践

1. 按需选择模型：不要所有智能体都用最强大（也最贵最慢）的模型。像reviewer这种审查角色，可以用速度快、成本低的模型（如Claude Haiku）。核心的coder可以用能力更强的Sonnet或Opus。
2. 善用工作目录：将相关的项目文件放在智能体的工作目录下。这样智能体可以通过CLI直接读写这些文件，上下文理解更准确。例如，把你的前端项目放在~/tinyagi-workspace/coder/frontend/，后端项目放在~/tinyagi-workspace/coder/backend/。
3. 精细化系统指令：花时间打磨每个智能体工作目录下的.claude/config.json中的systemPrompt。一个清晰、具体的系统指令，能极大提升智能体的输出质量和稳定性。可以包括角色设定、技术栈偏好、代码风格要求、审查标准等。
4. 监控队列深度：定期使用tinyagi status或查看TinyOffice仪表盘。如果pending队列持续很长，说明你的AI团队“忙不过来了”，可能需要增加智能体实例，或者优化任务指令以减少AI的处理时间。
5. 分离环境：如果你在服务器上部署，考虑使用Docker。项目提供的docker-compose.yml可以一键部署，并能更好地隔离环境，管理数据卷。

经过几个月的深度使用，TinyAGI已经从我的一个“新奇玩具”变成了日常开发流程中不可或缺的“副驾驶”。它不仅仅是一个调用AI的接口，而是一个真正可以承载工作流、具备记忆和协作能力的智能体平台。对于独立开发者和小团队来说，它极大地降低了构建个性化、自动化AI工作流的门槛。如果你也厌倦了在不同AI工具间反复切换、复制粘贴，不妨花上一个下午，按照这份指南搭建起你的第一个AI团队，体验一下让“虚拟员工”为你打工的乐趣。