这是本节的多页打印视图。 .
快速开始
最近更新：
- 1: AGW 是什么
- 2: 核心概念
- 3: 安装与配置 Server
- 4: 开始第一次对话
第一次使用 AGW，可以按下面的顺序完成安装和对话。只想先了解用途，阅读“AGW 是什么”即可；已经连接 Server，则直接进入“开始第一次对话”。
- AGW 是什么：了解能完成哪些工作，以及任务在哪里运行。
- 安装与配置 Server：选择安装包，完成初始化和客户端连接。
- 开始第一次对话：配置模型和 Agent，验证一次连续对话。
遇到不熟悉的名词时，查阅核心概念。
1 - AGW 是什么
最近更新：
AGW 是面向个人和小型研发团队的自托管 Agent 工作平台，也可作为 Agent 网关提供服务。它将自定义 Agent、Claude Code、Codex 和 Pi 等外部 Agent 放在统一界面中，围绕项目保留对话与执行记录。
核心概念
| 概念 | 用途 |
|---|---|
| Model Provider | 连接提供商与模型，指定实际使用的模型配置 |
| Agent | 配置指令、模型和能力，或接入已有外部 Agent |
| Project | 保存工作目录、上下文与会话的任务空间 |
| Chat | 发起交互式执行，查看消息、工具活动并处理人工输入 |
| Agentflow | 将多个节点连接成可执行流程 |
| Job | 按一次性、间隔或 Cron 触发 Agent 或 Agentflow |
各概念的区别及配合方式见核心概念。
可以用 AGW 做什么
假设正在维护一个代码项目：可以先让 Agent 解释陌生代码，再让另一个 Agent 审查修改；讨论和结果保存在项目的会话中。需要重复完成的工作，例如每周整理进展，可以在手动验证后设为定时任务。
| 需求 | 从哪里开始 |
|---|---|
| 问问题、整理一段文字 | 创建 Agent，在 Chat 中发送任务 |
| 阅读或修改项目文件 | 设置 Project 工作目录，再为 Agent 配置相应工具 |
| 让不同 Agent 接着讨论 | 在同一会话中切换 Agent，说明下一步任务 |
| 按固定步骤协作 | 用 Agentflow 连接各个步骤，按需加入人工确认 |
| 定期重复一项工作 | 用 Job 设置时间，并查看每次执行结果 |
任务在哪里运行
**Server（服务端）**是实际运行 AGW 的程序。Web、Desktop 和 Mobile 是操作它的客户端。使用远程 Server 时，Agent 访问的是远程主机上的文件、命令和工具；在手机中打开会话，不会让任务改在手机上运行。
首次在自己的电脑上使用，可以选择包含 Server 的 Desktop Full。希望通过浏览器使用，可以部署 Docker 或 Portable Server。模型服务需要另外配置；选择远程模型时，发送给模型的内容会离开 AGW 所在主机。
选择部署方式
**Standalone（单机）**把管理页面、对话执行和定时任务放在一个 Server 中，默认使用 SQLite 数据库，适合本机使用和单台主机部署。
Control/Data Plane 分离部署把管理与调度交给控制面，把实际执行交给数据面。它适合需要分别部署管理服务、增加执行节点的场景，但也需要共享 PostgreSQL、密钥和工作目录，并配置请求转发。
通常可以先从 Standalone 开始。安装选项见安装与配置 Server；需要分离部署时，再阅读部署步骤与路由配置。
从一个小任务开始
- 安装与配置 Server并初始化服务。
- 配置一个可用模型，创建一个 Agent。
- 在 Chat 发送简单问题，确认模型和执行链路正常。
- 有文件需求时创建 Project；有固定步骤时再使用 Agentflow；有周期需求时再配置 Job。
执行记录保存在你的服务数据库中。自托管不代表所有推理都发生在本机：选择远程模型提供商时，请求仍会发送到该提供商。
当前边界
AGW 尚未达到 1.0。它适合清晰、可拆分的任务与人机协作；复杂任务仍需要清楚的输入、完成标准和人工检查。当前使用管理员登录、第三方账号登录及 API Key，尚不提供角色管理或按 API Key 分配权限范围。
实现与参考
2 - 核心概念
最近更新：
在 AGW 中，模型负责推理，Agent 组织指令和能力，Project 提供工作空间。你可以通过 Chat 与 Agent 交互，也可以用 Agentflow 编排步骤、用 Job 安排执行时间。
模型与 Model Provider
模型相关配置分为三层：
| 概念 | 描述什么 |
|---|---|
| Provider | 模型服务的协议、地址和认证信息 |
| Model | 模型标识、上下文窗口和最大输出等规格 |
| Model Provider | 将一个模型与提供它的服务关联，供 Agent 选择 |
例如，你可以将同一个模型关联到不同的 Provider，再为 Agent 选择实际使用的连接。配置方法见模型提供商。
Agent：执行任务的角色
Agent 定义任务由谁完成、遵循什么指令，以及可以使用哪些能力。
- 自定义 Agent：在 AGW 中配置模型、指令、工具和 Skills，由 AGW 运行。
- 外部 Agent：接入 Claude Code、Codex、Pi 等 CLI，使用执行节点上已安装并配置好的工具环境。
Agent 定义可以用于多次任务；一次执行则是它处理某次输入的过程。例如，“代码解释助手”是 Agent，“解释这个函数”是一次输入。参见创建自定义 Agent与接入外部 Agent。
Project：工作空间
Project 围绕一项工作组织目录、上下文与会话。例如，一个代码仓库可以对应一个 Project，其中分别保存代码阅读、问题排查等会话。
主工作目录 Workspace 是 Agent 默认的工作目录。附加目录允许访问更多服务端路径；在文件浏览器中切换目录，不会改变 Agent 的默认工作目录。
这些路径必须对 Server 或执行节点可见。详细说明见Projects、文件与工作目录。
Chat、会话与执行
Chat 是交互入口；会话保存连续交流的上下文与记录；执行是 Agent 或 Agentflow 处理输入的过程。
在一次会话中，你可以连续发送多条消息。执行过程中可以查看回复和工具活动，处理审批或补充信息请求。页面断开连接不等于执行已经停止，重新连接后应查看实际状态：会话列表中的图标会显示 Running（运行中）、Last turn failed（上一轮失败）或 Last turn interrupted（上一轮被中断）。
使用方法见Chat 与执行记录。
Agent Capability（Agent 能力）
Capability 是 Agent 完成任务时可以使用的能力。以下概念分别描述具体操作、工具组合、任务说明，以及外部服务的接入方式。
Tools
Tool 是一项可调用的具体操作，例如读取文件或查询任务。Agent 根据任务需要调用工具，并使用返回的结果继续处理问题。
ToolBlocks
ToolBlock 是需要整体选择和管理的一组关联 Tool，用来保持行为与状态一致。它按整组选用，模型仍逐个调用其中的 Tool。
例如，todo 组合了添加、列出和完成待办事项等工具。选择它后，模型可以调用 todos_add、todos_get_all、todos_complete 等成员；这些成员不能作为独立工具单独选用或移除。
Skills
Skill 围绕任务提供使用说明、资源和可选工具，指导 Agent 如何完成工作。例如，agw-job 提供任务管理说明及工具。
Skill 分为 Built-in（内置）、**Local（本地）**和 **Remote（远程）**三类。Built-in 由 AGW 模块提供，例如上面的 agw-job；用户可以添加 Local 或 Remote Skill：Local 上传到 AGW 服务端，Remote 从指定网址读取。根据内容由谁维护、是否需要随包提供资源来选择，具体格式和更新规则见 Tools 与 Skills。
MCP
MCP 是连接工具服务的协议。配置 MCP Server 后，AGW 可以从服务中发现并调用工具，让 Agent 使用该服务提供的能力。配置方法见 MCP 服务。
Plugins
Plugin 定义一个集成提供哪些能力，以及如何接入服务，包括连接方式、认证方式、工具来源和内置 Skills。例如，GitHub Plugin 定义 GitHub 的认证与工具能力。
Integrations
Integrations 是用户选择和配置外部服务的入口，分为两部分：
- Available integrations（可用集成）：可供选择和配置的集成目录，例如 GitHub。目录展示 Plugin 定义的能力。
- Configured integrations（已配置的集成）：用户配置好的具体账号或服务端点。同一种集成可以配置多个账号，例如个人和工作 GitHub 账号。
Agent 选择具体的已配置集成，只有归属匹配且处于 Ready 状态的账号或端点才能提供能力。已配置集成在代码中对应 Connection 类型。
配置方法见 Integrations。
Agentflow 与 Job
Agentflow 决定步骤如何协作。它可以组合多个 Agent，以及分支、并行、人工审批等节点。例如，让一个 Agent 收集材料，另一个 Agent 整理摘要，再由人确认输出。
Job 决定什么时候运行。它按一次性、间隔或 Cron 触发一个 Agent 或 Agentflow，并记录每次尝试的结果。一个简单的定时问答任务可以直接选择 Agent；需要多个步骤时再选择 Agentflow。
二者可以独立使用：Agentflow 可以在 Chat 中手动运行，Job 也可以只执行一个 Agent。参见Agentflows与Jobs。
把概念串起来
以定期整理项目进展为例：
- 创建 Project，设置项目的工作目录。
- 配置 Model Provider，创建负责整理进展的 Agent。
- 为 Agent 绑定读取资料需要的工具或已配置的集成。
- 在 Chat 中运行一次，确认结果符合要求。
- 如需分工或审批，用 Agentflow 组织步骤；如需定期执行，用 Job 设置时间。
第一次使用时，先完成一次简单对话，再按任务需要增加其他能力。
3 - 安装与配置 Server
最近更新：
AGW 需要一个持续运行的 Server，以及用来操作它的客户端。首次在本机使用可选 Desktop Full；已有 Server 则选 Desktop Client，或直接使用浏览器。安装后再配置模型服务或外部 Agent，即可开始对话。
安装方式
| 方式 | 适合场景 | 主要区别 |
|---|---|---|
| Desktop Full | 在本机使用图形界面 | 同时安装桌面客户端和 Server，Server 作为当前用户的后台服务运行 |
| Desktop Client | 连接已运行的 Server | 只安装桌面客户端，不包含 Server，可连接本机或远程 Server |
| Docker | 容器化部署、自托管 | 在容器中运行 Server，包含 Web 界面，通过挂载保存数据和访问工作目录 |
| Portable Server | 直接在主机上部署服务 | 直接运行 Server 可执行程序，包含 Web 界面，无需 Docker 或桌面客户端 |
| 源码运行 | 开发与调试 | 自行构建和运行后端及所需客户端，可修改代码并调试各模块 |
Desktop
- 打开 GitHub Releases。
- 按平台选择 Full 或 Client。Windows、Ubuntu 当前提供 x64；macOS 提供 x64 和 arm64。
- Full 首次启动时完成 Server 的初始化；Client 连接现有 Server。
Full 和 Client 使用相同的应用标识，只能安装其中一种。Full 安装包含 Desktop Client 以及当前用户级 Server 后台服务；关闭 Desktop 不会自动停止 Server。安装包当前未签名或公证。
Docker 与 Portable Server
Docker 镜像随版本发布到 ghcr.io/zxyao145/agw。Portable Server 不随 Release 提供，需要在仓库根目录自行构建，例如 PUBLISH_MODE=portable APP_VERSION=0.1.0 RIDS=linux-x64 ./publish.sh，再按单机部署文档启动 agw-server serve。
根据部署需求选择以下方式：
- 单机与 Docker 部署：在一个 Server 中运行完整服务，适合本地试用和单机自托管。
- Control/Data Plane 分离部署：将管理与调度、任务执行分开运行，适合需要独立部署或扩展执行节点的场景，包含共享数据库、目录及 Nginx 路由配置说明。
需要团队共享或远程访问时，配置域名、HTTPS 和反向代理。
Docker 镜像不包含 Claude Code、Codex、Pi 等任何外部 Agent；如需使用，请自行在容器中安装并完成相关配置。
源码
参考开发环境，先启动 Standalone Host，再运行 Web。后端默认端口为 30816，Web 开发端口为 3001。
配置 Server
前提：Server 已启动，数据库配置有效，数据目录可写。默认单机模式使用 SQLite 和 InProcess 执行。
首次初始化
- 打开 Server 的
/setup页面，例如本机的http://localhost:30816/setup。Docker 或 Portable Server 包含 Web；源码模式也可先完成服务端初始化。 - 设置管理员密码。只有在 Server 所在主机上直接用
localhost或回环地址访问时，才不需要 Setup Code。通过域名、反向代理或其他主机访问，以及访问 Docker 容器映射的端口时，还需要填写启动日志中的一次性 Setup Code。 - 提交后等待数据库初始化完成，页面会进入应用，无需再次重启。
初始化成功后，密码和登录设置会保存在数据库中，后续启动无需重复设置。需要备份或迁移时，请一并保存数据库和加密密钥，参见备份与升级。
连接客户端
- 远程 Web 使用管理员密码登录，获得会话 Cookie。Server 配置了身份提供商时，Web 登录页还会显示第三方账号按钮；Desktop 在 Settings → Connections & app 中每个 Server 下方显示 Sign in with … 按钮，通过系统浏览器登录后自动获得 API Key，见配置与认证。
- Desktop、Mobile 和自动化使用 API Key，通过
Authorization: Bearer agw_...请求头发送。API Key 明文只在创建时显示一次。 - Desktop Full 的本地初始化由 Server 页面完成，主进程随后配置自己的 API Key，并使用操作系统凭据存储保护它。
API Key（访问密钥）相当于客户端连接 Server 的钥匙。给 Desktop Client 或 Mobile 配置远程连接时，先登录 Web，在 Settings 的 Server access 页面中，于 API tokens 填写 Token name 并创建一个 API Key，再将 Server 地址和完整的 API Key 填入客户端。Desktop Client 在 Settings → Connections & app 中点击 +（Add remote Server），填写 Name、Server URL 和 API token。手机上的 localhost 指手机本身，不能用它访问电脑上的 Server。
无人值守初始化
可以通过环境变量 Setup__AdminPassword 注入初始密码。分离部署仅在 Control Plane 初始化；Data Plane 不提供 Setup。不要将实际密码写进代码或站点文档。
已经初始化的服务不会被 Setup 参数覆盖。数据库与执行方式应在启动前使用标准配置设置，不能通过 Setup 表单切换。
完成后进入第一次对话。登录失败时先确认请求连接的是预期 Server。
实现与参考
4 - 开始第一次对话
最近更新：
前提：已完成初始化，可以进入管理界面，并有可用模型提供商的凭据。此流程先创建自定义 Agent，不需要外部 CLI。
1. 准备模型连接
打开模型管理页面，配置下面三项。不同客户端的表单布局可能不同，但需要的信息相同。
| 配置 | 要准备什么 | 用途 |
|---|---|---|
| Provider | 服务商要求的协议、API 地址和 API Key | 告诉 AGW 去哪里调用模型、如何认证 |
| Model | 服务商提供的模型 ID、上下文窗口和最大输出长度 | 告诉 AGW 使用哪个模型及其内容长度限制 |
| Model Provider | 将模型与提供商关联 | 作为 Agent 实际选择的模型连接 |
模型 ID 应使用服务商给出的准确值。自动发现时出现的 256,000 / 64,000 只是上下文窗口和最大输出的默认值，需要按实际规格调整。字段说明见模型提供商。
2. 创建一个简单的 Agent
在 Agents 中点击 Create。Agent Type 保持默认的 System（自定义 Agent），Display Name 填写“问答助手”，在 Model Provider 中选择刚配置的连接，并在 Instructions 中填写：
点击 Create 保存，并在 Agents 列表中确认 Enabled 开关已打开；新建的 Agent 默认启用。这次只验证文字对话，工具、Skills 和工作流可以稍后再配置。
3. 发送第一条消息
打开 Chat，确认当前 Server，并选择一个可用 Project：Desktop 在窗口顶部的项目标签页中选择，Web 在左侧栏顶部的下拉框中选择。然后在输入框左上方的选择器中选择“问答助手”，发送：
应能看到回复逐步出现，随后本次执行结束。再发送“把刚才的解释说得更简单一些”，检查 Agent 能否接着上一条消息回答。这可以同时验证模型连接和连续对话。
下一步
先验证纯文本对话，再按任务添加工具与 Skills。文件任务需要配置 Project 的工作目录；已有 Codex 或 Claude Code 环境可以使用外部 Agent。
没有收到回复
检查所选 Model Provider 是否可用、模型 ID 是否正确、凭据与地址是否匹配，并查看 Server 日志。会话列表中的图标显示会话状态：Running 表示仍在运行，Last turn failed 表示上一轮失败，Last turn interrupted 表示上一轮被中断。对话也可能在等待审批或用户输入；这种状态需要在 Chat 中处理。不要在未验证模型前同时加入大量工具或复杂流程。