本地部署
AgentWeave 本地部署让你在自己的电脑或服务器上运行整个 AgentWeave 平台——数据、模型、算力都在你自己掌控之中。你只需用 AgentWeave Deployer 安装一次、接入一个模型服务，即可在私有门户中创建并使用 Agent。
1. 概述与核心场景
本地部署是一套自包含的 AgentWeave 实例（后端、Agent 运行时、数据库、对象存储与登录服务），以 Docker 方式运行在你自己的硬件上。部署完成后，它支持三大核心场景：
- 用你自己的模型与算力运行自己的 Agent。 安装时接入任意 OpenAI 兼容的模型服务，然后完全在本地部署内导入并运行 Agent，数据不出内网。→ 场景一
- 一键直达你常用的外部 Agent。 注册一个轻量的「网页跳转（Web-redirect）Agent」，它出现在你的门户里，点击后打开外部网址、离开平台——相当于指向外部 Agent 的快捷方式。→ 场景二
- 经云端使用本地算力。 通过安全的**边缘隧道（edge tunnel）**把云端 AgentWeave Agent 绑定到你的本地部署。你（或你的用户）在公有云上与该 Agent 对话，请求却由本地部署的算力来处理。→ 场景三
第 3–5 节分别端到端讲解每个场景（如何创建 Agent、如何使用）。先完成平台安装。
2. 安装与配置 AgentWeave
安装由 AgentWeave Deployer 桌面应用引导，左侧导航共四步——Bundle（部署包）→ Environment（环境变量）→ Install（安装）→ Status（状态）。
2.1 下载
在 AgentWeave 本地部署下载页 下载 AgentWeave Deployer 与 Local Bundle（本地部署包）。
2.2 导入部署包（Bundle）
打开 Deployer，进入 Bundle 步骤，选择下载好的部署包导入，系统会自动解压。部署包内含安装所需的全部内容——env_local.sh、docker-compose.yml、安装脚本以及容器镜像。此处还可选导入 Docling 文档处理附加组件。
2.3 配置环境变量（Environment）
在 Environment 步骤，Deployer 会编辑部署包内的 env_local.sh 文件（其路径显示在顶部）。配置项按可折叠的分组划分，只有「AI models」这一组是必填的，其余都自带可用的默认值。
AI models（必填）
这一组告诉你的部署要调用哪个模型服务。该服务是 OpenAI 兼容、且与厂商无关的——可指向 DeepSeek、OpenAI、自建端点或任何兼容服务。其中 MODEL_API_KEY 与 MODEL_BASE_URL 必填，AGENTCORE_DEFAULT_MODEL 需填写该服务提供的模型名。
| 字段（界面显示） | 是否必填 | 默认值 | 作用 |
|---|---|---|---|
| MODEL_BASE_URL | 是 | https://api.deepseek.com/v1 | 你的 Agent 对话请求被转发到的 OpenAI 兼容基础地址。 |
| MODEL_API_KEY | 是 | （空） | 发给模型服务的 API Key——即 MODEL_BASE_URL 所指端点的鉴权令牌（例如你的 DeepSeek 或 OpenAI key）。 |
| AGENTCORE_DEFAULT_MODEL | 是 | deepseek-chat | 向服务请求的默认模型 id（如 deepseek-chat、gpt-4o、claude-sonnet-4-5-…）。 |
| LINK_FILE_DEFAULT_MODEL | 否 | deepseek-chat | 当某个 Agent 未单独配置模型时，抽取上传文件元信息所用的兜底模型。 |
| EMBEDDING_BASE_URL | 否 | https://api.siliconflow.cn/v1 | 用于知识库 / RAG 的 OpenAI 兼容 embedding 端点。 |
| EMBEDDING_MODEL | 否 | bge-m3 | 向 embedding 端点请求的模型 id。 |
key / base URL / model 三者如何协作。 你的 Agent 通过一个代理运行，代理把它们的请求转换为标准 OpenAI Chat Completions，转发到
MODEL_BASE_URL，用MODEL_API_KEY鉴权、请求AGENTCORE_DEFAULT_MODEL。切换模型服务只需改这三个值，无需其他设置。（embedding 端点的密钥在单独的 Embedding 分组里配置。）
其他分组（默认即可）
首次安装时，其余分组保持默认即可。可能需要留意的有：
| 分组 | 用途 | 你可能需要修改的项 |
|---|---|---|
| Passwords & secrets | 各内置服务的凭据 | 生产环境请设置强 DEPLOY_PASSWORD（Postgres/Redis/MinIO/Keycloak 管理员共用）、INTERNAL_SERVICE_TOKEN、KEYCLOAK_ADMIN_CLIENT_SECRET。 |
| MinIO / object storage | 本地文件存储 | S3_PUBLIC_URL 必须能被用户浏览器访问（如 http://<服务器IP>:30900）。 |
| External ports | 主机端口映射 | 各 *_NODEPORT（backend 30300、Keycloak 30080、MinIO 30900/30901、AgentCore 30800）。 |
| PostgreSQL / Keycloak / Backend / Proxy / Embedding / AgentCore | 各后端服务的连接配置 | 一般保持默认。 |
| Fixed settings（只读） | 命名空间、CPU/内存/存储/副本数上限 | 只读，保持不变。 |
编辑完成后点击 Save & redeploy（写入 env_local.sh），再进入 Install。
2.4 安装 Docker
Deployer 通过 Docker Compose 部署，因此需要 Docker Desktop。在 Install 步骤它会检查环境；若未检测到 Docker，会显示 Ready to install: No 并给出 Install Docker 按钮（以及安装指引）。
2.5 部署（Install）
当 Docker 已运行，Install 步骤会显示 Ready to install: Yes。点击 Install（或 Redeploy）用 Docker Compose 拉起整个服务栈。
请保持窗口开启直到完成；实时日志会滚动显示进度——加载镜像、逐个启动服务——并报告成功或错误。
2.6 查看状态（Status）
进入 Status 步骤查看各服务的运行状态——可按容器启动、停止、重启或查看日志，横幅还会显示门户地址。安装正常时各服务显示 Running。任何时候可点击刷新图标重新检查。
2.7 打开门户并登录
点击 Deployer 最右侧的访问图标，或在浏览器中打开门户地址（如 http://localhost:30088）查看智能体列表。
点击右上角 Login 登录：
- 用户名：
agentweave - 密码：
agentweave
要管理智能体，点击右上角的 agentweave 菜单并选择 Admin Console。
3. 场景一：在本地运行你自己的 Agent
用你在 2.3 节配置的模型，Agent 完全在本地部署内运行：对话请求由本地运行时处理，并转发到你自己的模型服务。
3.1 导入 Agent
在 Admin Console 中打开 Agents 分区。
这里的本地智能体文件是从云端 AgentWeave 平台导出的部署包：在云端打开该 Agent 的 Manage → Local Deployment 标签页，点击 Export Local Deployment Package 下载一个 .zip，其中打包了该 Agent 的配置（与场景三用的是同一个导出动作；也可能是同事分享给你的文件）。
然后点击 Import Agent，选择该文件并导入。导入成功后，列表中会新增一条记录。
对话框里还有两个可选的模型设置。留空则该 Agent 使用部署的默认模型（AGENTCORE_DEFAULT_MODEL，安装时在 2.3 节设置）。只有当你想让这个 Agent 使用你 LLM 支持的其它模型时才填——例如默认是 deepseek-chat，但想让该 Agent 跑在 deepseek-reasoner 上：
- Model ID —— 发给模型服务的模型标识（如
deepseek-reasoner），仅对该 Agent 覆盖默认值。 - Model Name —— 该模型的显示名称。
这两项之后也可以通过编辑该 Agent 修改。
3.2 与 Agent 对话
回到 AgentWeave 门户首页，选择一个智能体进入对话页并发送消息——它会返回生成内容，而这些内容由你的本地部署产生。
3.3 （进阶）把外部对话服务或智能体注册为 Self-hosted Agent
如果你已经自建了兼容 OpenAI 的对话服务或智能体，可以将其注册为 Self-hosted Agent：AgentWeave 仅负责对话的转发与存储，实际的执行逻辑完全由你自己的智能体完成。在 Admin Console → Agents 点击 Create Agent，保持默认的 Self-hosted Agent 类型（公共字段见 6.1 节），然后填写 Local service config：
| 字段 | 是否必填 | 作用 |
|---|---|---|
| Service URL | 是 | 你的 OpenAI 兼容对话服务的完整基础地址，必须包含端口，例如 http://192.168.1.50:8000。AgentWeave 会以 OpenAI 格式向此地址发送对话请求。 |
| Model | 否 | 你的服务期望的模型 id（作为 model 字段发送）。 |
| API Key (optional) | 否 | 你的服务如需鉴权则填写，加密存储。 |
除非你还想做云端绑定（即场景三），否则 Cloud Agent Key 留空即可。点击 Save，该智能体会以 External Agent 类型徽章出现在列表中，并可像其他智能体一样在门户中使用。
4. 场景二：外链到外部 Agent（网页跳转）
**Web-redirect Agent（网页跳转智能体）**是一个快捷方式：它出现在你的门户中，但点击后会打开外部网址、离开平台。它没有对话功能——用于把你已在别处使用的 Agent 呈现出来。
4.1 创建 Web-redirect Agent
在 Admin Console → Agents 点击 Create Agent，把 Agent type 切换为 Web-redirect Agent（公共字段见 6.1 节）。
| 字段 | 是否必填 | 作用 |
|---|---|---|
| External URL | 是 | 点击该智能体时打开的网址，必须是合法的 http 或 https URL。 |
点击 Save，该智能体会以 External 类型徽章出现在列表中。
4.2 使用
在门户中点击该智能体（或其 Enter 按钮），浏览器不会进入对话页，而是打开你配置的 External URL。
5. 场景三：经云端使用本地算力（Edge Agent）
本场景横跨两个系统：在云端 AgentWeave 平台构建的 Agent，由你的本地部署来提供服务。用户在云端与它对话，但请求被下发（隧道）到你的本地部署，由本地运行模型并返回答案。云端只负责转发对话——Agent 与算力都在你本地。
5.1 工作原理
你在云端生成一个标识某个云端 Agent 的密钥，把它粘贴到本地 Agent 的 Cloud Agent Key 字段。本地部署随即向云端建立一条安全的边缘隧道；此后该 Agent 在云端的对话都会经隧道路由到你的本地运行时。
运维提示。 边缘隧道需要部署知道云端地址（
EDGE_TUNNEL_ENABLED、EDGE_WS_BASE、EDGE_REST_BASE这几个环境值）。它们由安装部署的人一次性设置；下述步骤假设隧道已可用。
5.2 云端：开启本地直连并生成密钥
- 登录云端 AgentWeave 平台，打开（或 Build 构建）要绑定的 Agent。云端绑定由 AgentCore 类型的 Agent 支持。
- 打开该 Agent 的 Manage 页 → Local Deployment 标签页。
- 打开 Enable Local Direct Connection 并点击 Save。
- 点击 Generate API Key。密钥（以
agentweave-…为前缀）只显示一次——请立即复制。丢失可用 Regenerate 重新生成。
5.3 导出并导入 Agent
在同一个 Local Deployment 标签页点击 Export Local Deployment Package，下载该 Agent 配置的 .zip。然后在本地部署的 Admin Console → Agents 点击 Import Agent，选择该 .zip 导入（与 3.1 节流程相同）。它会以 Imported 类型出现，并运行在你的本地运行时上——无需填写 Service URL。
5.4 用 Cloud Agent Key 绑定
在这个导入的 Agent 上点击 Edit，把 5.2 节的 API Key 粘贴到 Cloud Agent Key，保存。几秒后该行会显示 Connected 徽章——边缘隧道已建立。
5.5 从云端对话，由本地算力应答
回到云端平台，打开该 Agent 并发送一条消息。你会在云端对话中收到正常回复——但这个请求已经过边缘隧道下发到你的本地部署，由本地运行模型并生成答案。此时你使用的正是本地的 Agent 与本地算力，云端只作为对话前端。
排查。 若云端对话无法到达本地 Agent，请确认：云端 Enable Local Direct Connection 已保存、本地 Agent 行显示 Connected、且本地部署能通过网络访问云端。
6. Agent 管理参考
6.1 Create Agent 对话框
Admin Console → Agents → Create Agent 用同一个对话框创建两种外链 Agent。在顶部选择 Agent type：
- Self-hosted Agent（列表显示为
External Agent）—— 你自部署的 OpenAI 兼容服务（见场景一 §3.3，也可在场景三中做云端绑定）。 - Web-redirect Agent（列表显示为
External）—— 指向外部站点的链接（见场景二）。
两种类型通用的字段：
| 字段 | 是否必填 | 作用 |
|---|---|---|
| Agent ID | 否 | 唯一标识。留空则自动生成，创建后不可修改。 |
| Name | 是 | 门户和列表中显示的名称。 |
| Description | 否 | 显示在智能体卡片上。 |
| Avatar | 否 | 上传图片（PNG / JPG / WEBP，≤ 20 MB）或粘贴 Avatar URL。 |
| Category | 否 | 将智能体归入门户的某个分类标签。 |
| Visibility | 否 | Public、Private 或 Hidden，默认 Private。 |
类型专属字段见各场景说明：Local service config 与 Cloud Agent Key 见 §3.3 / §5，External URL 见 §4.1。
6.2 编辑 Agent
点击任意行的 Edit 重新打开表单。顶部横幅会提示当前 Agent 的类型及可修改内容；Agent ID 变为只读，编辑模式还会多出一个 Sort Order（排序值，留空则保持当前顺序）字段。
6.3 连接状态徽章
已绑定云端（填了 Cloud Agent Key）的 Agent 会在列表中显示实时边缘隧道状态：
- Connected —— 隧道已建立。
- Connecting —— 隧道正在建立。
- Disconnected —— 隧道未连接（检查 Cloud Agent Key、云端开关，以及到云端的网络连通性）。
状态会自动刷新，你也可以点击刷新图标手动重新检查。