Admin Quickstart.zh CN
本文按管理后台的实际操作顺序，带你从系统初始化走到浏览器对话、兼容 API 调用和站点嵌入。示例截图来自 Agent4API 演示环境，截图中的来源名、模型名和业务 Tool 仅用于说明；请替换成你自己的配置。
建议顺序：系统设置 → 大模型供应商 → API 来源 → Tools → Skills → Agent → 对话验证。
请先准备：
- 一个可用的 OpenAI 兼容或 Anthropic 兼容模型服务；
- 模型服务的 Base URL、模型名和 API Key；
- 一份 Swagger 2.0 或 OpenAPI 3.x 文档，文件或可访问 URL 均可；
- 如果业务 API 需要登录：OAuth 2.0 客户端信息，或一个可返回 Token 的登录接口；
- 生产环境使用的 HTTPS 公网地址。
特别注意：
- 不要把模型 API Key、OAuth Client Secret、业务账号密码写进 Wiki、截图或聊天消息。
- 先确认 OpenAPI 文档中的
servers、host、basePath是否指向正确环境。 - 建议先在测试环境用只读接口完成全流程，再开放写入、删除等高风险 Tool。
- 打开
https://你的域名/admin。 - 输入管理员用户名和密码登录。
- 如需中文界面，点击左下角语言按钮并切换为“简体中文”。
- 检查页面左上方状态是否为“系统运行正常”。
- 在“平台概览”确认左侧菜单包含“系统设置、用户、大模型供应商、APIs、工具、技能、Agents、对话”。
成功标志：页面显示“系统运行正常”，且没有跳回登录页。
特别注意：
- 管理员会话和普通对话会话彼此独立；能打开“对话”不代表具有后台管理权限。
- 公共电脑上不要勾选浏览器保存密码，操作完成后应退出登录。
- 若首次运行显示初始化向导，请先创建管理员；管理员用户名为 3–128 个字符，密码为 6–256 个字符。
- 点击左侧“系统设置”。
- 在“本系统 Base URL”填写外部用户实际访问 Agent4API 的地址，例如
https://agent.example.com。 - 地址只填写协议、域名和可选端口，不要填写
/admin、查询参数或片段。 - 点击“保存设置”。
成功标志：刷新页面后，输入框仍显示保存后的公网地址。
特别注意：
- 生产环境应使用 HTTPS；同时建议设置
CHAT4OPENAPI_SECURE_COOKIES=true。 - 反向代理必须把前端、
/api/*、/v1/*、/anthropic/*、/embed/*转发到同一个 Agent4API 服务。 - Base URL 会用于生成嵌入脚本和 OAuth 回调地址。域名变更后，应重新复制嵌入脚本，并检查 OAuth 提供方登记的回调地址。
- 末尾
/会自动移除。
管理员可创建只能访问 Build 域功能的普通用户。
- 点击左侧“用户”。
- 填写“用户名”。
- 填写并再次确认密码。
- 选择用户默认界面语言。
- 保持“允许登录”勾选。
- 点击“创建用户”。
成功标志：用户卡片出现在下方列表中，并显示“已启用”。
特别注意：
- 普通用户只应获得完成日常构建所需的权限；系统配置和账号治理仍由管理员负责。
- 不要多人共用同一账号。独立账号更便于停用和审计。
- “重置密码”会替换旧密码；应通过安全渠道把临时密码交给用户。
- 删除前先确认该账号不再需要。短期离岗优先使用“停用”。
- 点击左侧“大模型供应商”。
- 填写“供应商名称”，例如
Production OpenAI。 - 在“协议”选择：
-
OpenAI compatible：OpenAI 兼容接口； -
Anthropic compatible：Anthropic 兼容接口。
-
- 填写“基础 URL”。示例：
https://api.openai.com/v1。 - 填写“默认模型”，必须是供应商实际支持的模型标识。
- 填写 API Key。
- 点击“添加供应商”。
- 在新供应商卡片上点击“测试”。
成功标志：测试成功，供应商卡片显示“已启用”。
特别注意：
- Base URL 是否包含
/v1取决于兼容服务的约定，请以该服务文档为准。 - “显示名称”和“模型标识”不是一回事；默认模型必须填写接口接受的精确值。
- 编辑供应商时，密钥输入框为空通常表示保留现有加密密钥，不代表密钥已被清空。
- 测试失败时依次检查网络连通性、Base URL、协议、模型名、额度和 API Key 权限。
- 删除供应商前先确认没有 Agent 依赖它。需要临时维护时优先“停用”。
Agent4API 支持文件上传和 URL 导入两种方式。
- 点击左侧“APIs”。
- 选择“文件上传”。
- 填写容易识别的“来源名称”。
- 如文档没有正确声明服务地址，填写“基础 URL（可选）”进行覆盖。
- 点击“OpenAPI 文档”，选择
.json、.yaml或.yml文件。 - 仅在目标确实位于受信任内网时，勾选“允许访问私有网络目标”。
- 点击“导入来源”。
- 选择“URL 导入”。
- 填写“来源名称”。
- 按需填写“基础 URL（可选）”。
- 在“OpenAPI URL”填写文档的完整地址，例如
https://api.example.com/openapi.json。 - 按需设置“允许访问私有网络目标”。
- 点击“从 URL 导入”。
成功标志：页面下方出现来源卡片，且“查看 Tools”可用。
特别注意：
- 文档最大 5 MiB。过大的文档应先按业务域拆分。
- URL 必须直接返回 OpenAPI 文档，不能是 Swagger UI 的 HTML 页面。
- 私网访问是 SSRF 安全边界，不要为了绕过错误而随意开启。确认域名、IP 和重定向目标均可信后再启用。
- 同名
operationId会影响 Tool 名称可读性；导入前最好在 OpenAPI 文档中保证其稳定且唯一。 - 导入不会自动开放所有接口。Tool 默认应经过人工审核后再启用。
如果业务 API 不需要身份凭据，可跳到第 7 步。需要认证时，在来源卡片点击“认证配置”，然后选择 OAuth 2.0 或 Tool 认证。
- 打开“OAuth 2.0”页签。
- 填写 Client ID。
- 填写 Client Secret；公共客户端可按提供方要求留空。
- 选择“OAuth 授权模式”：
- “授权码”：浏览器用户交互登录，支持 PKCE；
- “客户端凭证”：服务到服务调用，也适用于无交互的 OpenAI/Anthropic 兼容调用。
- 选择 Token 端点认证方式。没有明确要求时可先用“自动”。
- 按提供方要求填写 Token 请求头和额外参数，必须是合法 JSON 对象。
- 填写授权地址、Token 地址和可选的设备授权地址。
- 填写 Scopes，使用空格或逗号分隔。
- 检查“推荐回调地址”和“实际回调地址”。
- 将实际回调地址登记到 OAuth 提供方。
- 点击“保存 OAuth 配置”，再点击“测试认证”。
成功标志：配置保存成功；测试流程能进入提供方授权或成功取得凭据。
特别注意：
- 用兼容 API 调用 Agent 时没有浏览器可完成授权码跳转，通常应使用“客户端凭证”或预先创建 Tool Session。
- 回调地址必须与 OAuth 提供方登记值完全一致，包括协议、域名、端口和路径。
- Client Secret 会加密保存。编辑时留空表示保留已有 Secret。
- Token 请求头/参数只发送到 Token 端点，不要在这里放与认证无关的业务数据。
- Scopes 遵循最小权限原则，只申请 Agent 实际需要的范围。
- 打开“Tool 认证”页签。
- 从“登录 Tool”选择已经启用的登录接口。
- 填写“Token JSON 路径”，例如响应为
{"data":{"accessToken":"..."}}时填写data.accessToken。 - 填写登录接口接收的“用户名字段”和“密码字段”。
- 按需填写额外登录参数和请求头，内容必须是合法 JSON 对象。
- 设置“空闲过期”和“绝对过期”。
- 仅在测试区域输入测试账号和密码。
- 点击“保存认证配置”，再点击“测试认证”。
成功标志：测试认证成功，系统能从登录响应指定路径中取得凭据。
特别注意：
- 登录 Tool 必须先在 Tools 页面启用，否则不能选择。
- 测试账号密码只用于当前测试，不要把生产高权限账号用于联调。
- 额外登录参数不会覆盖用户名和密码字段。
- CAPTCHA、MFA、人工同意页等交互不能由登录 Tool 绕过；这类场景应使用 OAuth 授权码、设备流或外部凭据注入。
- 过期时间应尽量短，并符合上游 Token 的真实有效期。
- 点击来源卡片的“查看 Tools”，或从左侧进入“工具”。
- 通过来源分组和 Swagger Tag 找到目标接口。
- 核对每个 Tool 的 HTTP 方法、名称、描述和参数数量。
- 对描述不清的 Tool 点击“编辑描述”，补充用途、适用条件和关键限制。
- 对单个 Tool 点击“启用”；需要批量操作时：
- 勾选目标 Tool；
- 检查顶部“已选择 N 个 Tools”；
- 点击“启用所选项”。
- 使用“已启用”筛选器再次核对最终白名单。
成功标志：目标 Tool 显示“已启用”，并出现在“已启用”筛选结果中。
特别注意：
- 首次联调优先启用
GET查询接口；写入、删除、导出、上传和触发任务类 Tool 需单独评估。 - “选择可见项”只选择当前已渲染的行，不等于选择该来源的所有 Tool。
- 批量操作一次最多接受 200 个唯一 Tool ID。
- Tool 参数覆盖只能改描述和示例，不能改变导入文档定义的类型、必填状态、参数位置和执行映射。
- 停用来源会使其所有 Tool 在运行时不可用，即使 Tool 卡片本身仍显示为已启用。
- 删除为高风险操作；仅需临时下线时使用“停用”。
- 点击左侧“技能”。
- 填写“Skill 名称”，使用能表达业务能力的名称，例如“订单查询”。
- 填写“描述”，说明 Agent 在什么问题下应加载这个 Skill。
- 在“系统提示词”中写清执行规则、输入要求、输出格式和禁止事项。
- 在右侧 Tool 目录通过搜索、API 来源、Swagger 标签和启用状态缩小范围。
- 勾选需要绑定的 Tool。
- 在提示词中输入
@，或点击 Tool 旁的@按钮，插入规范的{{tool:名称}}引用。 - 确认“已绑定 N 个 Tool”数量正确。
- 点击“保存 Skill”。
成功标志：下方出现 Skill 卡片，且绑定数量正确、状态为运行中。
特别注意：
- Skill 描述决定 Agent 的路由判断。不要只写“用于查询”，应说明对象、场景和边界。
- 只有已启用、来源已启用且非登录专用的 Tool 才能新绑定或引用。
- 每个 Skill 最多绑定 128 个 Tool。大而全的 Skill 会降低路由准确性，应按业务域拆分。
- 提示词中的 Tool 引用应通过
@插入，避免手写错别字或引用不存在的 Tool。 - 已停止的 Skill 可以继续显示在 Agent 绑定列表中，但运行时不会加载。
- 点击左侧“Agents”。
- 点击“新建 Agent”。
- 填写“Agent 名称”。
- 选择已启用且测试通过的供应商。
- “模型覆盖”留空时使用供应商默认模型；仅在确有需要时填写另一个有效模型标识。
- 选择运行模式：
- “人工参与”：缺少重要业务信息时先向用户确认；
-
ReAct：用于无交互执行，会基于已知信息继续推理并披露必要假设。
- 设置最大迭代次数，允许范围为 2–32。
- 编写 Agent 系统提示词，至少说明角色、语言、Tool 使用原则和失败处理。
- 搜索并绑定 Skill。
- 使用上下箭头调整 Skill 顺序。
- 点击“保存 Agent”。
- 检查配置无误后启用 Agent；如需作为默认对话 Agent，再设置为默认。
成功标志：Agent 卡片显示“已启用”，需要时同时显示“默认”。
特别注意：
- Agent 至少需要一个可用供应商和一个运行中的已绑定 Skill 才能启用。
- Skill 顺序会影响评估次序，应把更具体、更常用的 Skill 放在前面。
- 最大迭代次数越高，延迟和模型费用可能越高；建议从 8 开始，根据实际 Tool 链路调整。
- 当前默认 Agent 不能直接停用或删除，应先把另一个可用 Agent 设为默认。
- 系统提示词不要要求模型伪造 Tool 结果；明确规定未观察到结果时必须说明失败。
- 在 Agent 列表点击目标 Agent 旁的“Chat”，或点击左侧“对话”。
- 新对话开始前确认 Agent 下拉框选中了目标 Agent。
- 先发送一个最小、只读且参数明确的问题。
- 检查回答底部或运行状态中是否显示已加载的 Skill。
- 检查回答内容是否来自真实 Tool 结果，而不是模型自行编造。
- 再测试以下情况：
- 缺少必填参数；
- 上游返回空列表；
- 上游返回 4xx/5xx；
- 需要登录或 OAuth；
- 多轮对话继续使用前文条件。
- 完成一个 Agent 的验证后，点击“新建对话”再测试另一个 Agent。
成功标志：Agent 加载了预期 Skill，调用了正确 Tool，并能对成功、空结果和失败给出符合提示词的响应。
特别注意：
- 第一条消息发送后，当前会话的 Agent 会被锁定。切换 Agent 必须新建对话。
-
human_in_loop只用于补充缺失或含糊的业务输入，不是 Tool 调用审批机制。 - 测试数据应脱敏；不要把患者、客户、员工等真实个人信息放进截图或 Wiki。
- 如果回答看似合理但没有 Tool 结果证据，应视为失败并检查 Skill 描述、Tool 绑定和 Agent 提示词。
- 在 Agents 页面选中目标 Agent。
- 在“API 密钥”区域填写密钥标签，例如
production-backend。 - 按需设置到期时间。
- 点击“创建 API 密钥”。
- 立即复制完整的
c4o_...密钥并保存到密钥管理系统。 - 使用页面提供的 OpenAI 或 Anthropic 示例进行调用。
OpenAI 兼容示例：
curl "https://agent.example.com/v1/chat/completions" \
-H "Authorization: Bearer <AGENT_API_KEY>" \
-H "Content-Type: application/json" \
-d '{
"model": "agent-default",
"messages": [
{"role": "user", "content": "查询项目列表"}
],
"stream": false
}'成功标志：返回正常的兼容响应，并包含 Agent 的实际回答。
特别注意：
- 完整密钥只显示一次；Agent4API 只保留哈希和短前缀，丢失后只能新建并撤销旧密钥。
- 不要把密钥提交到 Git、前端代码、日志或截图中。
- API Key 只授权其所属 Agent，不能跨 Agent 选择 Skill。
- 需要上游用户身份时，应先创建 Tool Session，再按接口约定传递 Tool Session ID 或请求头。
- 密钥应设置用途明确的标签和合理到期时间，并定期轮换。
更多参数与 Tool Session 示例见 Compatible APIs 和 Tool Session Authentication。
- 确认第 2 步已配置可访问的 HTTPS Base URL。
- 在 Agents 页面选中目标 Agent。
- 滚动到“嵌入式对话”。
- 填写配置名称。
- 选择 Logo 位于右下角或左下角。
- 每行填写一个允许嵌入的精确 Origin，例如
https://portal.example.com。 - 点击“创建嵌入配置”。
- 点击“复制脚本”，把生成的
<script>放到宿主页面。 - 点击“预览”或在真实宿主页面验证。
成功标志：宿主页面出现 Agent4API Logo，点击后能打开绑定到固定 Agent 的对话面板。
特别注意：
- Origin 只能包含协议、主机和可选端口；不能包含路径、通配符、用户名密码、查询参数或片段。
- 允许来源留空表示任何站点都可嵌入，仅适用于有意公开的 Agent。
- 宿主站点的 CSP 需要允许加载脚本和 iframe。
- 禁用 Embed 或 Agent 会阻止新会话，但不会把现有会话切换到其他 Agent。
完整说明见 Embedding Agents。
- 管理页面显示“系统运行正常”。
- Base URL 是真实 HTTPS 公网地址。
- 模型供应商测试通过，没有在文档中暴露 API Key。
- OpenAPI 文档和基础 URL 指向正确环境。
- 仅启用了经过审核的 Tool。
- 写入、删除、上传、导出等高风险 Tool 已单独评估。
- Skill 描述能准确触发，Tool 引用通过
@插入。 - Agent 至少绑定一个运行中的 Skill。
- 浏览器对话完成成功、空结果、缺参和失败场景测试。
- Agent API Key 已保存到密钥管理系统并设置轮换策略。
- OAuth 回调地址与提供方登记值完全一致。
- 嵌入配置使用精确 Origin，CSP 和反向代理规则已验证。
- 数据库和加密密钥已作为同一备份集保存。
依次检查供应商是否启用、Skill 是否运行、Agent 是否至少绑定一个 Skill，以及当前配置是否已经保存。
检查 API 来源和 Tool 是否都已启用、Tool 是否被标记为登录 Tool，以及目录筛选条件是否过窄。
检查来源认证配置、Tool Session 状态和上游 Token 是否过期。兼容 API 调用不会自动打开 OAuth 登录窗口。
复制后台显示的“实际回调地址”，不要凭经验手写。检查 Base URL、反向代理协议头和提供方登记值。
缩小 Skill 范围，重写 Skill 描述使触发条件更明确，在提示词中用 @ 插入 Tool 引用，并确认 Tool 处于启用状态。
检查脚本 URL、Embed 和 Agent 状态、精确 Origin、CSP、广告拦截器以及反向代理对 /embed/* 的转发。