跳到主要内容

快速入门

本指南带你从零开始搭建一个能够应对实际使用的 AigenLabs 环境。完成安装、选择 provider（服务提供商）、验证对话正常运行，并了解出现问题时的处理方法。

更喜欢看视频？​

Onchain AI Garage 制作了一套涵盖安装、配置和基本命令的 Masterclass 演示视频——如果你更习惯跟着视频操作，这是本页的绝佳补充。更多内容请查看完整的 AigenLabs Agent 教程与使用案例 播放列表。

适用人群​

  • 全新用户，想以最短路径完成可用配置
  • 正在切换 provider，不想因配置错误浪费时间
  • 为团队、机器人或长期运行的工作流配置 AigenLabs
  • 厌倦了"安装成功但什么都做不了"的情况

最快路径​

根据你的目标选择对应行：

目标先做这步再做这步
只想让 AigenLabs 在本机跑起来aigenlabs setup运行一次真实对话并验证有响应
已知道要用哪个 provideraigenlabs model保存配置，然后开始聊天
想搭建机器人或长期运行的服务CLI 正常后运行 aigenlabs gateway setup接入 Telegram、Discord、Slack 或其他平台
想使用本地或自托管模型aigenlabs model → 自定义 endpoint验证 endpoint、模型名称和上下文长度
想要多 provider 故障转移先运行 aigenlabs model基础对话正常后再添加路由和故障转移

经验法则： 如果 AigenLabs 无法完成一次正常对话，暂时不要添加更多功能。先让一次完整对话跑通，再逐步叠加 gateway、cron、skills、语音或路由。

1. 安装 AigenLabs Agent​

方式 A — pip（最简单）：

pip install aigenlabs-agent
aigenlabs postinstall     # 可选：安装 Node.js、浏览器、ripgrep、ffmpeg 并运行 setup

PyPI 发布版本跟踪带标签的版本（主/次版本发布），而非 main 分支上的每次提交。如需最新代码，请使用方式 B。

方式 B — git 安装器（跟踪 main 分支）：

# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://docs.aigenlabs.vn/install.sh | bash
Android / Termux

如果你在手机上安装，请参阅专门的 Termux 指南，其中包含经过测试的手动安装步骤、支持的扩展功能以及当前 Android 特有的限制。

Windows 用户

请先安装 WSL2，然后在 WSL2 终端中运行上述命令。

安装完成后，重新加载 shell：

source ~/.bashrc   # 或 source ~/.zshrc

详细的安装选项、前置条件和故障排查，请参阅 安装指南。

2. 选择 Provider​

这是最重要的配置步骤。使用 aigenlabs model 以交互方式完成选择：

aigenlabs model
最简路径：Nous Portal

一个订阅涵盖 300+ 个模型，以及 Tool Gateway（网页搜索、图像生成、TTS、云端浏览器）。全新安装时：

aigenlabs setup --portal

该命令一次性完成登录、设置 Nous 为 provider 并开启 Tool Gateway。

推荐默认选项：

Provider说明配置方式
Nous Portal订阅制，零配置通过 aigenlabs model 进行 OAuth 登录
OpenAI CodexChatGPT OAuth，使用 Codex 模型通过 aigenlabs model 进行设备码认证
Anthropic直接使用 Claude 模型——Max 计划 + 额外用量积分（OAuth），或按 token 付费的 API keyaigenlabs model → OAuth 登录（需要 Max + 额外积分），或 Anthropic API key
OpenRouter跨多个 provider 的多模型路由输入 API key
Z.AIGLM / Zhipu 托管模型设置 GLM_API_KEY / ZAI_API_KEY
Kimi / MoonshotMoonshot 托管的编程和对话模型设置 KIMI_API_KEY（或 Kimi-Coding 专用的 KIMI_CODING_API_KEY）
Kimi / Moonshot China中国区 Moonshot endpoint设置 KIMI_CN_API_KEY
Arcee AITrinity 模型设置 ARCEEAI_API_KEY
GMI Cloud多模型直连 API设置 GMI_API_KEY
MiniMax (OAuth)通过浏览器 OAuth 使用 MiniMax-M2.7，无需 API keyaigenlabs model → MiniMax (OAuth)
MiniMax国际版 MiniMax endpoint设置 MINIMAX_API_KEY
MiniMax China中国区 MiniMax endpoint设置 MINIMAX_CN_API_KEY
Alibaba Cloud通过 DashScope 使用 Qwen 模型设置 DASHSCOPE_API_KEY
Hugging Face通过统一路由器使用 20+ 开源模型（Qwen、DeepSeek、Kimi 等）设置 HF_TOKEN
AWS Bedrock通过原生 Converse API 使用 Claude、Nova、Llama、DeepSeekIAM 角色或 aws configure（指南）
Kilo CodeKiloCode 托管模型设置 KILOCODE_API_KEY
OpenCode Zen按需付费访问精选模型设置 OPENCODE_ZEN_API_KEY
OpenCode Go$10/月订阅，访问开源模型设置 OPENCODE_GO_API_KEY
DeepSeek直接访问 DeepSeek API设置 DEEPSEEK_API_KEY
NVIDIA NIM通过 build.nvidia.com 或本地 NIM 使用 Nemotron 模型设置 NVIDIA_API_KEY（可选：NVIDIA_BASE_URL）
GitHub CopilotGitHub Copilot 订阅（GPT-5.x、Claude、Gemini 等）通过 aigenlabs model 进行 OAuth，或设置 COPILOT_GITHUB_TOKEN / GH_TOKEN
GitHub Copilot ACPCopilot ACP agent 后端（在本地启动 copilot CLI）aigenlabs model（需要 copilot CLI + copilot login）
Custom EndpointVLLM、SGLang、Ollama 或任何兼容 OpenAI 的 API设置 base URL + API key

对于大多数初次使用的用户：选择一个 provider，接受默认值（除非你明确知道为何要修改）。完整的 provider 目录及环境变量和配置步骤请参阅 Providers 页面。

最低上下文要求：64K token

AigenLabs Agent 要求模型至少具备 64,000 个 token 的上下文窗口。上下文窗口较小的模型无法为多步骤工具调用工作流维持足够的工作内存，启动时将被拒绝。大多数托管模型（Claude、GPT、Gemini、Qwen、DeepSeek）均轻松满足此要求。如果你运行本地模型，请将其上下文大小设置为至少 64K（例如 llama.cpp 使用 --ctx-size 65536，Ollama 使用 -c 65536）。

提示

你可以随时通过 aigenlabs model 切换 provider——没有锁定。所有支持的 provider 完整列表及配置详情，请参阅 AI Providers。

配置的存储方式​

AigenLabs 将密钥与普通配置分开存储：

  • 密钥和 token → ~/.aigenlabs/.env
  • 非密钥配置 → ~/.aigenlabs/config.yaml

通过 CLI 设置值是最简便的方式，系统会自动将值写入正确的文件：

aigenlabs config set model anthropic/claude-opus-4.6
aigenlabs config set terminal.backend docker
aigenlabs config set OPENROUTER_API_KEY sk-or-...

3. 运行第一次对话​

aigenlabs            # 经典 CLI
aigenlabs --tui      # 现代 TUI（推荐）

你会看到一个欢迎横幅，显示你的模型、可用工具和 skills。使用一个具体且易于验证的 prompt（提示词）：

选择你的界面

AigenLabs 提供两种终端界面：经典的 prompt_toolkit CLI，以及更新的 TUI（支持模态覆盖层、鼠标选择和非阻塞输入）。两者共享相同的会话、斜杠命令和配置——分别用 aigenlabs 和 aigenlabs --tui 试试看。

Summarize this repo in 5 bullets and tell me what the main entrypoint is.
Check my current directory and tell me what looks like the main project file.
Help me set up a clean GitHub PR workflow for this codebase.

成功的标志：

  • 横幅显示你选择的模型/provider
  • AigenLabs 无错误地回复
  • 需要时能够使用工具（终端、文件读取、网页搜索）
  • 对话可以正常进行超过一轮

如果以上都正常，你已经过了最难的部分。

4. 验证会话功能​

继续之前，确认恢复功能正常：

aigenlabs --continue    # 恢复最近的会话
aigenlabs -c            # 简写形式

这应该会带你回到刚才的会话。如果不行，检查你是否在同一个 profile 下，以及会话是否实际已保存。当你同时管理多个配置或多台机器时，这一点很重要。

5. 尝试核心功能​

使用终端​

❯ What's my disk usage? Show the top 5 largest directories.

Agent 会代你执行终端命令并显示结果。

斜杠命令​

输入 / 查看所有命令的自动补全下拉列表：

命令功能
/help显示所有可用命令
/tools列出可用工具
/model交互式切换模型
/personality pirate尝试一个有趣的人格
/save保存对话

多行输入​

按 Alt+Enter、Ctrl+J 或 Shift+Enter 换行。Shift+Enter 需要终端能将其作为独立序列发送（Kitty / foot / WezTerm / Ghostty 默认支持；iTerm2 / Alacritty / VS Code 终端需启用 Kitty 键盘协议）。Alt+Enter 和 Ctrl+J 在所有终端中均可使用。

中断 Agent​

如果 agent 响应时间过长，输入新消息并按 Enter——这会中断当前任务并切换到你的新指令。Ctrl+C 同样有效。

6. 添加下一层功能​

仅在基础对话正常后进行。按需选择：

机器人或共享助手​

aigenlabs gateway setup    # 交互式平台配置

接入 Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant 或 Microsoft Teams。

自动化与工具​

  • aigenlabs tools — 按平台调整工具访问权限
  • aigenlabs skills — 浏览并安装可复用的工作流
  • Cron — 仅在机器人或 CLI 配置稳定后使用

沙箱终端​

为了安全起见，在 Docker 容器或远程服务器中运行 agent：

aigenlabs config set terminal.backend docker    # Docker 隔离
aigenlabs config set terminal.backend ssh       # 远程服务器

语音模式​

# 在 AigenLabs 安装目录下运行（curl 安装器在 Linux/macOS 上将其放置于
# ~/.aigenlabs/aigenlabs-agent，在 Windows 上为 %LOCALAPPDATA%\aigenlabs\aigenlabs-agent）：
cd ~/.aigenlabs/aigenlabs-agent
uv pip install -e ".[voice]"
# 包含 faster-whisper，用于免费的本地语音转文字

然后在 CLI 中输入：/voice on。按 Ctrl+B 开始录音。参阅 语音模式。

Skills​

aigenlabs skills search kubernetes
aigenlabs skills install openai/skills/k8s

或在聊天会话中使用 /skills。

MCP 服务器​

# 添加到 ~/.aigenlabs/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

编辑器集成（ACP）​

ACP 支持已包含在标准 [all] 扩展中，因此 curl 安装器已默认包含。直接运行：

aigenlabs acp

（如果安装时未包含 [all]，请先运行 cd ~/.aigenlabs/aigenlabs-agent && uv pip install -e ".[acp]"。）

参阅 ACP 编辑器集成。

常见故障模式​

以下是最容易浪费时间的问题：

现象可能原因解决方法
AigenLabs 启动但回复为空或异常Provider 认证或模型选择有误重新运行 aigenlabs model，确认 provider、模型和认证信息
自定义 endpoint "可用"但返回乱码base URL、模型名称有误，或实际上不兼容 OpenAI先用独立客户端验证该 endpoint
Gateway 启动但无法收到消息Bot token、白名单或平台配置不完整重新运行 aigenlabs gateway setup 并检查 aigenlabs gateway status
aigenlabs --continue 找不到旧会话切换了 profile 或会话从未保存检查 aigenlabs sessions list，确认你在正确的 profile 下
模型不可用或出现异常的故障转移行为Provider 路由或故障转移设置过于激进在基础 provider 稳定之前关闭路由
aigenlabs doctor 标记配置问题配置值缺失或已过期修复配置，在添加功能前重新测试普通对话

恢复工具包​

当感觉有问题时，按以下顺序操作：

  1. aigenlabs doctor
  2. aigenlabs model
  3. aigenlabs setup
  4. aigenlabs sessions list
  5. aigenlabs --continue
  6. aigenlabs gateway status

这个顺序能让你快速从"感觉哪里不对"回到已知的正常状态。

快速参考​

命令说明
aigenlabs开始聊天
aigenlabs model选择 LLM provider 和模型
aigenlabs tools配置每个平台启用的工具
aigenlabs setup完整配置向导（一次性配置所有内容）
aigenlabs doctor诊断问题
aigenlabs update更新到最新版本
aigenlabs gateway启动消息 gateway
aigenlabs --continue恢复上次会话

下一步​