跳到主要内容

Web Dashboard

Web Dashboard 是基于浏览器的 UI,用于管理你的 KOPI AI AGENT 安装。你无需编辑 YAML 文件或运行 CLI 命令,即可通过简洁的 Web 界面配置设置、管理 API key 并监控会话。

提示

托管模式的认证使用 KOPI Proxy OAuth;如果你还希望 dashboard 与真实后端通信,kopi setup --portal 也会接入模型和工具网关。参见 KOPI Proxy。

快速开始​

kopi dashboard

这会启动一个本地 Web 服务器,并在浏览器中打开 http://127.0.0.1:9119。dashboard 完全在你的机器上运行——数据不会离开 localhost。

选项​

Flag默认值说明
--port9119Web 服务器运行的端口
--host127.0.0.1绑定地址
--no-open—不自动打开浏览器
--insecureoff允许绑定到非 localhost 的主机(危险——会在网络上暴露 API key;请配合防火墙和强认证使用)
--isolatedoff当从具名 profile (worker dashboard) 启动时,运行专用的按 profile 服务器,而不是路由到机器级 dashboard
# Custom port
kopi dashboard --port 8080

# Bind to all interfaces (use with caution on shared networks)
kopi dashboard --host 0.0.0.0

# Start without opening browser
kopi dashboard --no-open

管理多个 profile​

dashboard 是一个机器级的管理界面:一个服务器管理机器上的每个 profile。侧边栏中的 profile 切换器(只要存在多个 profile 就会显示)决定各管理页面读写哪个 profile——Config、API Keys、Skills、MCP、Models 以及 Chat 标签页都遵循该选择。当选择了非 dashboard 自身的 profile 时,会显示一个琥珀色横幅标明被管理的 profile,因此写入目标始终明确无误。

该选择保存在 URL 中 (?profile=<name>),因此像 http://127.0.0.1:9119/skills?profile=worker 这样的深度链接会带上预选的切换器,并在刷新后保持不变。

从 profile 别名启动 dashboard 时,会路由到机器级 dashboard,而不是启动第二个服务器:

worker dashboard
# → already running: opens the browser at ?profile=worker
# → not running: starts the machine dashboard with "worker" preselected

传入 --isolated 可选择退出,改为运行限定在该 profile 范围内的专用服务器(即统一前的行为——适用于你有意用不同认证暴露不同 profile 的 dashboard 的情况)。

Chat 标签页同样遵循切换器:限定范围的聊天会以所选 profile 的 KOPI_HOME 启动其 PTY 子进程,因此对话会使用该 profile 的模型、skill、记忆和会话历史。切换 profile 会启动一个全新的终端会话。

保持按 profile 存在且不会被切换器吸收的部分包括:gateway 进程(通过 kopi -p <name> gateway … 管理)、每个 profile 的会话数据库,以及 cron 调度器(Cron 页面已通过其自身的过滤器跨 profile 聚合)。

前提条件​

默认的 kopi-ai-agent 安装不包含 HTTP 栈或 PTY 辅助工具——它们是可选的额外组件。Web dashboard 需要 FastAPI 和 Uvicorn(web extra)。Chat 标签页还需要 ptyprocess 来在伪终端后启动嵌入式 TUI(POSIX 上为 pty extra)。使用以下命令安装两者:

cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[web,pty]"

web extra 会引入 FastAPI/Uvicorn;pty 会引入 ptyprocess(POSIX)或 pywinpty(原生 Windows——注意嵌入式 TUI 本身仍需要 WSL)。cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[all]" 包含这两个 extra,如果你还需要消息/语音等功能,这是最简单的路径。

当你在缺少依赖的情况下运行 kopi dashboard 时,它会告知你需要安装什么。如果前端尚未构建且 npm 可用,首次启动时会自动构建。

Chat 标签页是每次 kopi dashboard 启动的一部分——嵌入式浏览器聊天面板(通过 PTY/WebSocket 运行 TUI)始终可用,无需任何额外 flag。

页面​

Status(状态)​

首页展示安装环境的实时概览:

  • Agent 版本及发布日期
  • Gateway 状态 — 运行中/已停止、PID、已连接的平台及其状态
  • Active sessions(活跃会话) — 最近 5 分钟内处于活跃状态的会话数量
  • Recent sessions(最近会话) — 最近 20 个会话的列表,包含模型、消息数、token 用量以及对话预览

状态页每 5 秒自动刷新一次。

Chat(聊天)​

Chat 标签页将完整的 Kopi Agent TUI(与你通过 kopi --tui 获得的界面完全相同)直接嵌入浏览器中。你在终端 TUI 中能做的一切 —— 斜杠命令、模型选择器、工具调用卡片、markdown 流式输出、clarify/sudo/审批提示、皮肤主题 —— 在这里都能完全一致地工作,因为仪表板运行的是真正的 TUI 二进制程序,并通过 xterm.js 及其 WebGL 渲染器来呈现其 ANSI 输出,实现像素级精确的单元格布局。

工作原理:

  • /api/pty 打开一个使用仪表板 session token 完成认证的 WebSocket
  • 服务器在 POSIX 伪终端(PTY)后面启动 kopi --tui
  • 按键输入传输到 PTY;ANSI 输出流式回传到浏览器
  • xterm.js 的 WebGL 渲染器将每个单元格绘制到整数像素网格上;鼠标跟踪(SGR 1006)、宽字符(Unicode 11)以及制表符图形字形都能原生渲染
  • 调整浏览器窗口大小时,会通过 @xterm/addon-fit 插件同步调整 TUI 大小

恢复已有会话: 在 Sessions 标签页中,点击任意会话旁的播放图标(▶)。这会跳转到 /chat?resume=<id> 并使用 --resume 启动 TUI,加载完整的会话历史。

会话切换器(右侧栏): Chat 标签页在终端旁的窄右侧栏中自带一个 ChatGPT 风格的会话列表,让你无需离开页面即可切换对话。该栏顶部堆叠模型选择器,其下方直接是会话列表;终端占据屏幕的大部分区域。列表显示当前 profile 的最近会话 —— 标题(缺失时回退为消息预览)、最后活跃的相对时间、消息数,以及非 CLI 会话的来源渠道。点击任意一行即可就地恢复该会话(终端会以该对话的历史重新启动);当前活跃会话会高亮显示。New chat(新建聊天) 会启动一个全新会话,刷新控件会重新拉取列表。该侧栏仅用于只读切换 —— 删除、重命名、导出和批量清理仍位于 Sessions 标签页中。在窄屏上它会折叠为一个滑出式面板。

前置条件:

  • Node.js(与 kopi --tui 的要求相同;TUI bundle 会在首次启动时构建)
  • ptyprocess —— 由 pty extra 安装(cd ~/.kopi/kopi-ai-agent && uv pip install -e ".[web,pty]",或 [all] 同时覆盖两者)
  • POSIX 内核(Linux、macOS 或 WSL2)。/chat 终端面板特别需要 POSIX PTY —— 原生 Windows Python 没有等价物,因此在原生 Windows 安装中,仪表板的其余部分(sessions、jobs、metrics、config 编辑器)都能工作,但 /chat 标签页会显示一条横幅,提示你需要使用 WSL2 才能使用该功能。

关闭浏览器标签页后,PTY 会在服务器上被干净地回收。重新打开会启动一个全新会话。

要让 Kopi Agent Desktop 指向运行在另一台机器上的仪表板,而不是其自带的本地后端,请参阅下文的 remote-backend 一节。

将 Kopi Agent Desktop 连接到远程后端​

Kopi Agent Desktop 通常会启动自己的本地后端,但它也可以通过 Settings → Gateway → Remote gateway 连接到运行在远程机器(虚拟机、家庭实验室主机等)上的仪表板。这是"Desktop 显示后端已就绪但聊天始终无法工作"这类报告最常见的来源,因为 Desktop 的就绪检查所验证的内容少于实时聊天连接实际所需的内容。

前置条件:远程主机上必须运行着一个 kopi dashboard

Desktop 连接的"远程后端"就是运行在远程机器上的一个 kopi dashboard 进程 —— 也就是本页所描述的同一个服务器。它必须先启动并可被访问,然后下面的步骤才有意义;Desktop 只是连接到它,而不会替你启动它。请让它在 systemd/tmux 等下持续运行,以便它在注销和重启后依然存活。gateway(Telegram/Discord/Slack 等)是一个独立的长期运行进程 —— 如果你依赖消息渠道,请单独启动它;桌面应用连接的并不是它。

Desktop 的"远程后端已就绪"探测只请求 GET /api/status,这是一个公开端点 —— 只要主机上运行着任意仪表板,它就会返回响应。实时聊天连接则是一个独立的、指向 /api/ws(以及 /api/pty)的 WebSocket,而该 socket 受两项额外检查的限制,状态探测从不涉及这两项检查:

  1. 你必须完成认证。 当仪表板绑定到非回环地址时,它会启用认证闸门。请使用用户名和密码保护它(内置的 username/password provider);Desktop 登录一次,并通过一次性 ticket 将生成的 session 复用于 WebSocket。如果没有配置 provider,非回环的仪表板会在启动时失败关闭(fail closed)。
  2. 绑定主机必须允许客户端访问并匹配 Host header。 回环绑定(127.0.0.1)只接受回环客户端,因此无论凭据如何,远程机器都会在 socket 层被拒绝。请绑定到非回环地址(--host 0.0.0.0),这样对端 IP 防护才会放行远程客户端。你在 Desktop 中输入的远程 URL 必须能通过仪表板绑定时所用的同一 host 访问到它 —— DNS rebinding 防护要求 Host header 必须匹配。

远程仪表板设置​

设置用户名和密码,然后将仪表板绑定到一个可访问的地址上运行。对于一个 systemd 服务:

[Service]
EnvironmentFile=%h/.kopi/.env
ExecStart=/path/to/venv/bin/python -m kopi_cli.main dashboard \
--host 0.0.0.0 --port 9119 --no-open

其中 ~/.kopi/.env 包含:

KOPI_DASHBOARD_BASIC_AUTH_USERNAME=admin
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
KOPI_DASHBOARD_BASIC_AUTH_SECRET=<32+ random bytes; openssl rand -base64 32>

然后在 Desktop 中输入 Remote URL(例如 http://VM_IP:9119),并使用该用户名和密码Sign in。请参阅 [username/password provider](#usernamepassword-provider-no-oauth-id p) 部分,了解完整的配置内容。

重试 Desktop 前,请先确认 gate 已启用

在任意机器上,检查仪表盘是否宣告了用户名/密码 provider:

curl -s http://VM_IP:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["basic"]
  • providers 列表中出现 auth_required: true 和 "basic" → Desktop 的 Sign in 流程可以正常工作。
  • auth_required: false → 绑定地址是 loopback,或者 gate 未生效。请绑定到非 loopback 地址。
  • 有 auth_required: true 但没有 "basic" provider → 用户名/密码的环境变量未加载。请先修复这些问题。

如果 /api/status 显示 gate 已启用并带有 "basic" provider,而 Desktop 在登录后仍然无法连接,那么问题已经超出了基础配置的范围——请获取一份全新的 desktop.log(Settings → Gateway → Open logs),以及同一重试时间段内仪表盘的日志,并查找 /api/ws 关闭代码(4403 = chat WS 被 request guard 拒绝,例如 Host/peer 不匹配;4401 = WS ticket 未通过身份验证)。

配置​

一个基于表单的 config.yaml 编辑器。全部 150 多个配置字段都会从 DEFAULT_CONFIG 自动发现,并按带标签页的分类组织:

Config admin page — section filters on the left, auto-discovered fields on the right

  • model — 默认模型、provider、base URL、reasoning 设置
  • terminal — 后端(local/docker/ssh/modal)、超时、shell 偏好
  • display — skin、工具进度、resume 显示、spinner 设置
  • agent — 最大迭代次数、gateway 超时、service tier
  • delegation — subagent 限制、reasoning effort
  • memory — provider 选择、context 注入设置
  • approvals — 危险命令审批模式(ask/yolo/deny)
  • 还有更多——config.yaml 的每个部分都有对应的表单字段

已知有效值的字段(terminal 后端、skin、审批模式等)会渲染为下拉框。布尔值渲染为开关。其余的都是文本输入框。

操作:

  • Save — 立即把更改写入 config.yaml
  • Reset to defaults — 将所有字段恢复为默认值(在点击 Save 之前不会保存)
  • Export — 将当前配置下载为 JSON
  • Import — 上传 JSON 配置文件以替换当前值
提示

配置更改会在下一个 agent 会话或 gateway 重启时生效。Web 仪表盘编辑的是 kopi config set 和 gateway 读取的同一个 config.yaml 文件。

API 密钥​

管理存储 API 密钥和凭据的 .env 文件。密钥按类别分组:

  • LLM Providers — OpenRouter、Anthropic、OpenAI、DeepSeek 等。
  • Tool API Keys — Browserbase、Firecrawl、Tavily、ElevenLabs 等。
  • Messaging Platforms — Telegram、Discord、Slack bot token 等。
  • Agent Settings — 非机密的环境变量,如 API_SERVER_ENABLED

每个密钥会显示:

  • 当前是否已设置(并对值进行脱敏预览)
  • 用途说明
  • 指向 provider 注册/密钥页面的链接
  • 用于设置或更新值的输入框
  • 用于删除它的删除按钮

高级/不常用的密钥默认隐藏在开关之后。

会话​

浏览并检查所有 agent 会话。每一行会显示会话标题、来源平台图标(CLI、Telegram、Discord、Slack、cron)、模型名称、消息数、工具调用数,以及距上次活跃的时间。活跃会话会带有脉动徽章标记。

  • Search — 使用 FTS5 对所有消息内容进行全文搜索。结果会显示高亮片段,展开后自动滚动到第一条匹配的消息。
  • Stats — 汇总栏会显示总会话数、存储中处于活跃状态的数量、已归档数量、总消息数,以及按来源的分布。
  • Expand — 点击某个会话可加载其完整的消息历史。消息按角色(user、assistant、system、tool)着色,并以带语法高亮的 Markdown 渲染。
  • Tool calls — 带工具调用的 assistant 消息会显示可折叠区块,包含函数名和 JSON 参数。
  • Rename — 内联设置或清除会话标题(铅笔图标)。
  • Export — 将会话(元数据 + 完整消息历史)下载为 JSON(下载图标)。
  • Prune — 标题栏中的“Prune old sessions”按钮会删除结束时间超过 N 天的会话。
  • Delete — 使用垃圾桶图标删除会话及其消息历史。

Sessions admin page — stats bar, prune, and per-row rename / export / delete

日志​

查看 agent、gateway 和错误日志文件,支持过滤和实时跟踪。

  • File — 在 agent、errors 和 gateway 日志文件之间切换
  • Level — 按日志级别过滤:ALL、DEBUG、INFO、WARNING 或 ERROR
  • Component — 按来源组件过滤:all、gateway、agent、tools、cli 或 cron
  • Lines — 选择显示的行数(50、100、200 或 500)
  • Auto-refresh — 开启实时跟踪,每 5 秒轮询一次新的日志行
  • Color-coded — 日志行按严重程度着色(红色为错误,黄色为警告,暗色为 debug)

分析​

基于会话历史计算的用量和成本分析。选择时间范围(7、30 或 90 天)可查看:

  • Summary cards — 总 token(输入/输出)、缓存命中率百分比、估算或实际总成本,以及总会话数和日均值
  • Daily token chart — 按天展示输入和输出 token 用量的堆叠柱状图,悬停时显示明细和成本
  • Daily breakdown table — 每天的日期、会话数、输入 token、输出 token、缓存命中率和成本
  • Per-model breakdown — 表格展示每个已使用模型的会话数、token 用量和估算成本

Cron​

创建并管理定时 cron 任务,按周期性调度运行 agent prompt。

  • Create — 填写名称(可选)、prompt、cron 表达式(例如 0 9 * * *),以及投递目标(local、Telegram、Discord、Slack 或 email)
  • Job list — 每个任务会显示其名称、prompt 预览、调度表达式、状态徽章(enabled/paused/error)、deliv ery 投递目标、上次运行时间和下次运行时间
  • 暂停 / 恢复 — 在活动与暂停状态之间切换任务
  • 编辑 — 打开预填充的模态框,修改任务的 prompt、调度计划、名称或投递目标
  • 立即触发 — 脱离正常调度计划立即执行任务
  • 删除 — 永久移除 cron 任务

Profiles(配置档案)​

创建和管理 profiles — 彼此隔离的 Kopi Agent 实例,各自拥有独立的 config、skill 和会话。

  • Profile 卡片 — 每张卡片显示其 model/provider、skill 数量、网关状态、描述以及徽章(active、default、alias)
  • 创建 — 名称 + 可选的 clone-from-default / clone-everything / no-bundled-skills、描述和 model;专用的 Profile Builder 页面(/profiles/new)提供完整流程(model、MCP、skill)
  • 管理 skill 和工具 — 跳转到限定于该 profile 的 Skills 页面(同时设置侧边栏的 profile 切换器)
  • 设为活动 — 切换固定的默认值,后续的 CLI/网关运行会采用该值(与 kopi profile use 相同)。这并不会改变 dashboard 当前管理的对象 — 那是 profile 切换器的职责
  • 编辑 model / 描述 / SOUL — 内联编辑器,直接写入该 profile
  • 重命名 / 删除 — 仅限已命名的 profile

Skills​

浏览、搜索和切换已安装的 skill 与工具集,并从 hub 安装新的内容。skill 从 ~/.kopi/skills/ 加载,并按类别分组。

  • 搜索 — 按名称、描述或类别筛选已安装的 skill 和工具集
  • 类别筛选 — 点击类别标签缩小列表范围(例如 MLOps、MCP、Red Teaming、AI)
  • 切换 — 用开关启用或停用单个 skill。更改在下次会话时生效。
  • 工具集 — 单独的视图显示内置工具集(文件操作、网页浏览等)及其活动/非活动状态、配置要求和包含的工具列表
  • 浏览 hub — 第三个视图跨所有来源搜索 skill hub(与 kopi skills search 相同),可按标识符安装任意结果并显示实时安装日志,还提供“全部更新”按钮以刷新已安装的 skill。

Skills 管理页面 — Browse hub 视图:搜索、安装和更新

MCP​

无需 CLI 即可管理 MCP server。它操作的是 config.yaml 中 kopi mcp 所读取的同一个 mcp_servers 块。

你的 MCP server:

  • 添加 — 注册 HTTP/SSE server(URL)或 stdio server(命令 + 参数),stdio server 可选填 KEY=VALUE 环境变量
  • 启用 / 停用 — 无需删除即可开关 server。停用的 server 仍保留在 config 中,之后可以重新启用。下次网关重启时生效。
  • 测试 — 连接到 server、列出其工具并断开连接 — 在 agent 依赖它之前先验证连接
  • 移除 — 从 config 中删除 server
  • 类似密钥的环境变量值在列表视图中会被脱敏显示

Catalog: 浏览 Nous 认可的 MCP server(随附的 optional-mcps/ 目录),并一键安装其中任意一个。需要 API key 的条目会在行内提示输入;这些值会写入 .env。这与 kopi mcp catalog / kopi mcp install 使用的目录相同。

MCP 管理页面 — 你的 server 及启用/停用开关,以及安装目录

Webhooks​

管理动态 webhook 订阅。 webhook 平台必须先在消息设置中启用;若未启用,该页面会显示 提示。

  • 创建 — 名称、描述、事件过滤器、投递目标、可选的直接投递模式,以及 agent prompt。创建后页面会显示路由 URL 和一次性 HMAC secret,供你复制。
  • 启用 / 停用 — 切换订阅的开关。停用的路由仍保留在订阅文件中,但网关会拒绝其传入事件(403)。网关会热加载该文件,因此更改在下一个事件时生效 — 无需重启。
  • 列表 — 每个订阅显示其 URL、事件和投递目标
  • 删除 — 移除订阅

Webhooks 管理页面 — 带启用/停用开关的订阅列表

Pairing(配对)​

无需 CLI 即可批准和撤销消息用户 — 远程管理员将 Telegram/Discord 等平台用户接入已配对网关的方式。与 kopi pairing 完全等价。

  • 待处理请求 — 每条显示平台、代码、用户和等待时长,并带有“批准”按钮
  • 已批准用户 — 每条显示平台和用户,并带有“撤销”按钮
  • 清除待处理 — 丢弃所有未处理的配对代码

Pairing 管理页面

Channels(渠道)​

在浏览器中将 Kopi Agent 连接到任意消息平台 — 与 kopi setup gateway 完全等价。该页面列出所有受支持的渠道(Telegram、 Discord, Slack, Matrix, Mattermost, WhatsApp, Signal, BlueBubbles/iMessage, Email, SMS/Twilio, DingTalk, Feishu/Lark, WeCom, WeChat, QQ Bot, Yuanbao, 以及 API server 和 webhook 端点)及其实时连接状态。

  • 配置 — 打开按平台区分的表单,其中仅包含该渠道所需的字段(bot token、app token、server URL、白名单等)。密钥会以密码输入框呈现,并以脱敏形式存储;留空某个字段则保留现有值。必填字段会明确标注并校验。“设置指南”链接指向该平台的凭据文档。
  • 启用 / 停用 — 切换渠道的开关。凭据仍保留在磁盘上;仅活动状态会改变。
  • 测试 — 检查该渠道是否已配置、已启用,并从网关报告实时连接。
  • 重启网关 — 凭据会写入 ~/.kopi/.env,启用标志写入 config.yaml;网关会在下次重启时连接每个已启用的渠道,而你可以直接在该页面触发重启。

Channels 管理页面 — 所有消息平台的状态、启用开关以及各平台的配置表单

System(系统)​

一个整合的管理面板,f 或安装级别的操作:

  • Host — 实时系统状态:OS / 内核、架构、主机名、Python 和 Kopi Agent 版本、CPU 核心数 + 利用率、内存、Kopi Agent 主目录的磁盘使用情况、运行时间和平均负载。(CPU/内存/磁盘数据在安装了 psutil 时提供;标识字段始终显示。)Kopi Agent 版本会显示一个更新状态徽章(已是最新 / 落后 N 个提交)和一个Check for updates 按钮。当 git 或 pip 安装有可用更新时,Update now 按钮会打开一个确认对话框 —— 显示将要拉取的提交数量 —— 然后在后台运行 kopi update。在 Docker/Nix/Homebrew 安装中,dashboard 无法就地应用更新,因此会显示正确的带外(out-of-band)命令。
  • KOPI Proxy — 登录状态、当前活跃的推理 provider,以及 Tool Gateway 路由表(哪些工具通过 KOPI Proxy 运行、哪些在本地运行),并附有管理订阅的链接。是 kopi portal 的只读镜像。
  • Skill curator — 后台 skill 维护状态(活跃 / 已暂停、间隔、上次运行时间),提供暂停/继续和立即运行按钮。镜像自 kopi curator。
  • Gateway — 启动、停止和重启消息网关,并显示实时状态(运行中/已停止、PID、状态)
  • Memory — 选择外部 memory provider(或仅使用内置),并重置内置的 MEMORY.md / USER.md 存储
  • Credential pool — 添加和移除 agent 以轮询(round-robin)方式使用的轮换 API key(按 provider 划分)。列表中的 key 会被脱敏;原始值只会传递给 agent。
  • Operations — 运行 doctor、安全审计、创建备份、从备份归档恢复、更新 skill、显示系统提示词大小分解、生成支持转储(support dump),或迁移已弃用设置的 config。每一项都会启动一个后台操作,其实时日志会流式传输到页面中。
  • Checkpoints — 查看 /rollback shadow store 的大小并进行清理
  • Shell hooks — 列出已配置的 hooks 及其 consent + 可执行状态,创建 hook(事件、命令、matcher、超时,以及可选的 consent 授权),并移除某个 hook。Hook 会运行任意命令,因此创建表单带有安全警告,且只有在授予 consent 后 hook 才会触发。

系统管理页面 — 主机统计和 KOPI Proxy 状态

系统管理页面 — skill curator、gateway、memory 和 credential pool

系统管理页面 — operations、checkpoints 和 shell hooks

创建 shell hook(注意 consent 复选框和运行任意命令的警告):

新建 shell hook 模态框

安全

web dashboard 会读写你的 .env 文件,其中包含 API key 和密钥。它默认绑定到 127.0.0.1 —— 只能从你的本机访问。如果你绑定到 0.0.0.0,网络上的任何人都可以查看和修改你的凭据。dashboard 本身没有任何身份验证。

/reload 斜杠命令​

该 dashboard PR 还为交互式 CLI 新增了 /reload 斜杠命令。通过 web dashboard(或直接编辑 .env)修改 API keys 后,可在活动的 CLI 会话中使用 /reload,无需重启即可使更改生效:

You → /reload
Reloaded .env (3 var(s) updated)

该命令会将 ~/.kopi/.env 重新读取到运行中进程的环境里。当你通过 dashboard 新增了 provider key 并希望立即使用时,这个命令非常有用。

REST API​

Web dashboard 暴露了一个 REST API,供前端消费。你也可以直接调用这些端点来实现自动化:

Profile 作用域端点

管理端点系列 —— /api/config、/api/env、/api/skills、 /api/tools/toolsets、/api/mcp 和 /api/model/{info,options,auxiliary,set} —— 接受一个可选的 ?profile=<name> query 参数(写入时也可在 JSON body 中使用 "profile"),用于将读写操作限定到该 profile 的 KOPI_HOME。省略时 = dashboard 自身的 profile。未知的 profile 名称 返回 404。/api/pty WebSocket 接受相同的参数,以便在 所选 profile 下启动一个 chat。

GET /api/status​

返回 agent 版本、gateway 状态、platform 状态以及活跃 session 数量。

GET /api/sessions​

返回最近 20 个 session 及其 metadata(model、token 数量、时间戳、预览)。

GET /api/config​

以 JSON 形式返回当前 config.yaml 的内容。

GET /api/config/defaults​

返回默认配置值。

GET /api/config/schema​

返回描述每个配置字段的 schema —— 类型、描述、category,以及在适用时的可选值。前端使用它来为每个字段渲染正确的输入控件。

PUT /api/config​

保存新的配置。Body:{"config": {...}}。

GET /api/env​

返回所有已知的环境变量及其已设置/未设置状态、脱敏后的值、描述和 category。

PUT /api/env​

设置一个环境变量。Body:{"key": "VAR_NAME", "value": "secret"}。

DELETE /api/env​

移除一个环境变量。Body:{"key": "VAR_NAME"}。

GET /api/sessions/{session_id}​

返回单个 session 的 metadata。

GET /api/sessions/{session_id}/messages​

返回某个 session 的完整消息历史,包括 tool 调用和时间戳。

GET /api/sessions/search​

对消息内容进行全文搜索。Query 参数:q。返回匹配的 session ID,并附带高亮摘要片段。

DELETE /api/sessions/{session_id}​

删除一个 session 及其消息历史。

GET /api/logs​

返回日志行。Query 参数:file(agent/errors/gateway)、lines(数量)、level、component。

GET /api/analytics/usage​

返回 token 用量、成本和 session 分析。Query 参数:days(默认 30)。响应包含按日明细和按 model 汇总。

GET /api/cron/jobs​

返回所有已配置的 cron job 及其状态、调度计划和运行历史。

POST /api/cron/jobs​

创建一个新的 cron job。Body:{"prompt": "...", "schedule": "0 9 * * *", "name": "...", "deliver": "local"}。

POST /api/cron/jobs/{job_id}/pause​

暂停一个 cron job。

POST /api/cron/jobs/{job_id}/resume​

恢复一个已暂停的 cron job。

POST /api/cron/jobs/{job_id}/trigger​

在调度计划之外立即触发一个 cron job。

DELETE /api/cron/jobs/{job_id}​

删除一个 cron job。

GET /api/skills​

返回所有 skill 及其名称、描述、category 和启用状态。

PUT /api/skills/toggle​

启用或禁用一个 skill。Body:{"name": "skill-name", "enabled": true}。

GET /api/tools/toolsets​

返回所有 toolset 及其标签、描述、tools 列表,以及 active/configured 状态。

管理端点​

这些端点支撑 MCP、Channels、Webhooks、Pairing 和 System 页面。它们与 /api/ 的其他部分一样,都位于同一认证门禁之后。

方法与路径用途
GET /api/mcp/servers列出已配置的 MCP server(env 值已脱敏)
POST /api/mcp/servers添加一个 server。Body:{name, url?, command?, args?, env?, auth?}
POST /api/mcp/servers/{name}/test连接、列出 tools、断开连接
PUT /api/mcp/servers/{name}/enabled启用 / 禁用一个 server
DELETE /api/mcp/servers/{name}移除一个 server
GET /api/mcp/catalog浏览 Nous 批准的 MCP catalog
POST /api/mcp/catalog/install安装一个 catalog 条目(含必需的 env)
GET /api/messaging/platforms列出每个 messaging channel 的状态 + 各 platform 的设置字段
PUT /api/messaging/platforms/{id}配置一个 channel。Body:{enabled?, env?, clear_env?}(env 写入 .env,enabled 写入 config.yaml)
POST /api/messaging/platforms/{id}/test报告某个 channel 是否已配置、已启用且已连接
GET /api/pairing列出待批准 + 已批准的 messaging 用户
POST /api/pairing/approve批准一个 code。Body:{platform, code}
POST /api/pairing/revoke吊销一个用户。Body:{platform, user_id}
POST /api/pairing/clear-pending清除所有待处理 code
GET /api/webhooks列出 subscription + platform 启用状态
POST /api/webhooks创建一个 subscription(返回一次性 secret)
DELETE /api/webhooks/{name}移除一个 subscription
GET /api/credentials/pool列出池化的 rotation key(已脱敏)
POST /api/credentials/pool添加一个 key。Body:{provider, api_key, label?}
DELETE /api/credentials/pool/{provider}/{index}移除一个 key(基于 1 的索引)
GET /api/memory当前 provider + 可用 provider + 内置文件大小
PUT /api/memory/provider选择一个 provider(为空 = 仅内置)
POST /api/memory/reset重置内置 memory。Body:{target: all|memory|user}
POST /api/gateway/start · /stop · /restartGateway 生命周期(后台执行)
POST /api/ops/doctor · /security-audit · /backup · /import诊断与维护(后台执行;通过 /api/actions/{name}/status 获取尾部输出)
GET /api/ops/hooks已配置的 shell hook + allowlist 状态
GET /api/ops/checkpoints · POST .../prune查看 / 清理 /rollback 存储
POST /api/ops/hooks · DELETE /api/ops/hooks创建 / 移除一个 shell hook(需同意授权)
GET /api/system/stats主机统计 —— OS、CPU、内存、磁盘、运行时长
GET /api/kopi/update/check报告更新可用性(落后的 commit 数、安装方式)但不执行更新。对于落后的 git/pip 安装,还会返回一个 commits 列表(sha、summary、author、at),说明变更内容。?force=1 可清除 6 小时缓存
GET /api/curator · PUT .../paused · POST .../runSkill-curator 状态 + 暂停/恢复 + 运行
GET /api/portalKOPI Proxy 认证 + Tool Gateway 路由(只读)
POST /api/ops/prompt-size · /dump · /config-migrate诊断(后台执行)
PUT /api/webhooks/{name}/enabled启用 / 禁用一个 webhook route
POST /api/skills/hub/install · /uninstall · /updateSkills hub 操作(后台执行)
GET /api/skills/hub/search跨所有来源搜索 skill hub
GET /api/sessions/statsSession-store 统计信息
PATCH /api/sessions/{id}重命名 / 归档一个 session
GET /api/sessions/{id}/export将一个 session(metadata + 消息)导出为 JSON
POST /api/sessions/prune删除超过 N 天的已结束 session
PUT /api/cron/jobs/{id}编辑一个 cron job 的 prompt / schedule / name / deliver

身份验证(门控模式)​

当仪表板绑定到公共地址或非 loopback 地址 —— 即 127.0.0.1 / localhost 之外的任何地址时 —— KOPI AI AGENT 会启用身份验证网关。每个请求都必须携带已验证的 session cookie,否则会被弹回登录页面。内置三种 provider(服务提供商):

  • 用户名/密码 —— 在自托管 / 本地部署 / 家庭实验室仪表板上启用身份验证的最简单方式。无需外部身份提供商。仅在可信网络或 VPN 后使用 —— 不要暴露到公共互联网。
  • OAuth(KOPI Proxy) —— 适用于托管部署以及任何可通过公共互联网访问的仪表板,也是远程 Kopi Agent Desktop 连接的推荐方式。每次登录都会通过你的 Nous 账户进行验证,因此该 provider 适合暴露在互联网上使用。
  • 自托管 OIDC —— 用于通过标准 OpenID Connect 接入你自己的身份提供商(Keycloak、Auth0、Okta、Google、经由 OIDC bridge 的 GitHub 等)。不涉及 KOPI Proxy;在由符合规范的 OIDC 服务器前置时,适合暴露到公共互联网。

绑定到 loopback 的运维人员自用仪表板不受影响 —— 无需身份验证,也没有登录页面。

网关何时启用​

标志身份验证网关使用场景
kopi dashboard(默认 —— 绑定到 127.0.0.1)关闭本地开发
kopi dashboard --host 0.0.0.0开启远程 / 生产环境 —— 使用用户名/密码 provider 或 OAuth 进行保护

当且仅当满足以下条件时,网关才会启用:

  1. 绑定主机不是 127.0.0.1、::1、localhost 或 0.0.0.0,并且
  2. 未设置 --insecure 标志。
--insecure 会完全禁用身份验证

--insecure 会跳过网关,提供一个无需身份验证的仪表板,该仪表板可以读写你的 .env(API 密钥、机密),并能运行 agent 命令。不要将其用于远程连接。 若要将仪表板暴露给其他机器,请配置用户名/密码 provider(或 OAuth),并保持 --insecure 关闭。该标志仅作为最后手段的逃生舱,用于完全可信、有防火墙保护的单主机网络。

失败即关闭(fail-closed)语义​

如果本应启用网关,但没有注册任何 DashboardAuthProvider(既没有 Nous plugin,也没有自定义 plugin),kopi dashboard 将拒绝绑定,并给出明确的错误消息。不存在“默认拒绝但又接受一切”的回退行为 —— 配置错误的门控仪表板永远不会启动。

当你在交互式(真实终端)环境下运行 kopi dashboard --host 0.0.0.0 且尚未配置任何 provider 时,Kopi Agent 不会直接失败 —— 它会提议现场完成设置:选择 username & password(将 dashboard.basic_auth 写入 config.yaml,几秒内即可运行)或 OAuth(引导你前往 kopi dashboard register)。非交互式调用方 —— Docker/s6、CI、管道运行 —— 则会跳过提示并触发上述 fail-closed 错误,因此无人值守的部署同样永远不会在没有身份验证的情况下启动。

默认 provider:Kopi Ai Agent Pte Ltd​

内置的 plugins/dashboard_auth/nous plugin 始终已安装并自动加载。当配置了 client ID 时,它会自动注册一个名为 nous 的 DashboardAuthProvider。

由于每次登录都通过 KOPI Proxy 验证,并受你的 Nous 账户保护,只有 Nous provider 适合将仪表板暴露到公共互联网。

注册仪表板​

要使用 Nous provider,你需要一个 OAuth client ID(格式为 agent:{id})。有两种获取方式:

  • CLI — kopi dashboard register。 在运行仪表板的主机上执行它。它会解析你现有的 Nous 登录状态(如果尚未登录,请先运行 kopi setup),向 KOPI Proxy 注册一个自托管 OAuth client,并为你将 KOPI_DASHBOARD_OAUTH_CLIENT_ID 写入 ~/.kopi/.env。可选标志:--name(人类可读的标签,否则自动生成)和 --redirect-uri(面向互联网主机的公共 HTTPS 回调 URL)。

    kopi dashboard register
    # ✓ Registered dashboard "swift_falcon"
    # …writes KOPI_DASHBOARD_OAUTH_CLIENT_ID to ~/.kopi/.env
  • GUI —— Local Dashboards 页面。 在 KOPI Proxy 中打开 /local-dashboards,即可在浏览器中注册、命名、管理并吊销自托管仪表板。将生成的 agent:{id} client ID 复制到 KOPI_DASHBOARD_OAUTH_CLIENT_ID(env)或 dashboard.oauth.client_id(config.yaml)中。这里也是吊销通过 CLI 注册的仪表板的地方。

配置​

该 plugin 从两个层面读取配置,当环境变量设置了非空值时以环境变量为准:

config.yaml —— 规范配置层面:

dashboard:
oauth:
client_id: agent:01HXYZ… # required to engage the gate

环境变量 —— 运维人员的覆盖项:

环境变量覆盖项格式由谁配置
KOPI_DASHBOARD_OAUTH_CLIENT_IDdashboard.oauth.client_idagent:{instance_id}kopi dashboard register

按照 KOPI AI AGENT 的约定(~/.kopi/.env 仅用于 API 密钥 / 机密),对于本地开发、本地部署以及任何你直接控制的部署,推荐在 config.yaml 中设置这些值。环境变量这条途径存在的意义,是让托管平台的机密注入能够按部署推送各自的 client_id,而无需任何人去编辑镜像内的 config.yaml —— 这才是它的主要用途。

空的环境变量值会被视为未设置,因此已预置但未填充的平台机密不会意外遮蔽 config.yaml 中的有效条目。

如果两个来源都没有提供 client_id,该 plugin 会报告具体原因,而仪表板 fail-closed 的绑定错误会准确告诉你需要修复什么:

Refusing to bind dashboard to 0.0.0.0 — the OAuth auth gate engages on
non-loopback binds, but no auth providers are registered.

Bundled providers reported these issues:
• nous: KOPI_DASHBOARD_OAUTH_CLIENT_ID is not set (and
dashboard.oauth.client_id in config.yaml is empty). The KOPI Proxy
provisions this env var (shape 'agent:{instance_id}') when it
deploys a KOPI AI AGENT instance — set it to your provisioned
client id (either as an env var or under dashboard.oauth.client_id
in config.yaml), or pass --insecure to skip the OAuth gate entirely.

Or pass --insecure to skip the auth gate (NOT recommended on untrusted
networks).

实操示例:Kopi Ai Agent Pte Ltd​

从已登录的 Kopi Agent 安装到一个受 Nous 门控的仪表板,只需三步。

1. 登录并注册仪表板。 kopi dashboard register 会使用你现有的 Nous 登录状态来预置一个 OAuth client,并为你将 KOPI_DASHBOARD_OAUTH_CLIENT_ID 写入 ~/.kopi/.env:

kopi setup            # if you're not already logged into KOPI Proxy
kopi dashboard register
# ✓ Registered dashboard "swift_falcon"
# …writes KOPI_DASHBOARD_OAUTH_CLIENT_ID to ~/.kopi/.env

2. 在可访问的地址上运行仪表板。 在没有 --insecure 的情况下绑定到非 loopback 地址会启用 OAuth 网关,刚写入的 client_id 会激活 nous provider:

kopi dashboard --host 0.0.0.0 --port 9119 --no-open

3. 登录。 打开 http://<host>:9119/ 后,你将被跳转到 CODE_27 6. 点击 Sign in with Kopi Ai Agent Pte Ltd → 在 KOPI Proxy 完成认证 → 返回已认证的控制面板。从任意机器验证访问门控:

curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["nous"]

GET /api/auth/me 随后返回已验证的会话(provider: nous)。对于面向公网的主机,请使用 --redirect-uri https://kopi.example.com/auth/callback 注册,并设置 KOPI_DASHBOARD_PUBLIC_URL,使 OAuth 回调解析到你的公网 URL(参见 Public URL override)。

用户名/密码 provider(无 OAuth IDP)​

如果你不想接入 OAuth 身份提供商(identity provider,IDP)——例如一个自托管的「只是想给我的控制面板加个密码」部署——内置的 plugins/dashboard_auth/basic 插件会注册一个名为 basic 的 DashboardAuthProvider,它使用用户名和密码而非 OAuth 重定向来完成认证。

它接入与 OAuth provider 相同的门控:在非回环地址绑定且未设置 --insecure 时门控启用,登录页会为该 provider 渲染一个凭据表单(而不是「使用 X 登录」按钮),登录下游的一切——session cookie、透明刷新、WS ticket、注销、审计日志——都与 OAuth 路径完全一致。会话是 provider 自行签发的无状态 HMAC 签名 token,因此没有数据库,也没有外部 IDP。密码哈希使用标准库 scrypt(无第三方依赖)。

仅在可信网络中使用 —— 不要暴露到公共互联网

用户名/密码 provider 适用于位于可信网络中、或只能通过 VPN 访问的自托管 / 本地 / 家庭实验室控制面板。它只保护一个共享凭据,背后没有外部身份提供商、MFA 或按用户账号体系,因此不适合将控制面板直接暴露到公共互联网。对于面向公网的控制面板,请改用 Kopi Ai Agent Pte Ltd provider(或你自己的自托管 OIDC / 自定义 OAuth provider)。

配置​

与 Nous provider 一样,它从 config.yaml(权威配置面)读取,环境变量在设置为非空时优先。仅当同时配置了 username 以及 password_hash(推荐)或 password 时才会激活——否则它不做任何事,因此 OAuth 用户和回环/--insecure 操作者不受影响。

config.yaml:

dashboard:
basic_auth:
username: admin
# Preferred — no plaintext at rest. Compute with:
# python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))"
password_hash: "scrypt$16384$8$1$…$…"
# ...or a plaintext password (hashed in-memory at load; less safe at rest):
# password: "s3cret"
secret: "<32+ random bytes, base64 or hex>" # token-signing key
session_ttl_seconds: 43200 # optional; access-token lifetime (default 12h)

环境变量覆盖:

环境变量覆盖项说明
KOPI_DASHBOARD_BASIC_AUTH_USERNAMEdashboard.basic_auth.username激活所必需
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD_HASHdashboard.basic_auth.password_hash推荐(静态存储中无明文)
KOPI_DASHBOARD_BASIC_AUTH_PASSWORDdashboard.basic_auth.password明文;优先于配置中的 password_hash,以便通过环境变量轮换
KOPI_DASHBOARD_BASIC_AUTH_SECRETdashboard.basic_auth.secrettoken 签名密钥
KOPI_DASHBOARD_BASIC_AUTH_TTL_SECONDSdashboard.basic_auth.session_ttl_secondsaccess token 有效期
为获得稳定的会话,请显式设置 secret

当 secret 为空时,会生成一个每次进程随机的签名密钥。这对单进程没问题,但这意味着每次重启都会使所有会话失效,且会话无法跨多个 worker。对于需要在重启后保持有效 / 多 worker 的部署,请显式设置 secret。

/auth/password-login 端点按客户端 IP 进行速率限制(默认 10 次尝试/分钟 → HTTP 429),并对未知用户和错误密码统一返回同一个通用的 401 Invalid credentials,因此无法被用作用户名枚举的探测工具。

实操示例:用户名/密码​

三步搞定:从零开始,在可信网络上部署一个受密码保护的控制面板。

1. 在 ~/.kopi/.env 中设置凭据。 对密码进行哈希,确保静态存储中没有明文,并设置稳定的签名密钥使会话在重启后依然有效:

# Compute a scrypt hash of your chosen password:
HASH=$(python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('choose-a-strong-password'))")

cat >> ~/.kopi/.env <<EOF
KOPI_DASHBOARD_BASIC_AUTH_USERNAME=admin
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD_HASH=$HASH
KOPI_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.kopi/.env

2. 在可访问的地址上运行控制面板。 不带 --insecure 的非回环绑定会启用门控,用户名 + 哈希则激活 basic provider:

kopi dashboard --host 0.0.0.0 --port 9119 --no-open

3. 登录。 打开 http://<host>:9119/,你会被跳转到 /login —— 一个凭据表单(而非「使用 X 登录」按钮)。输入 admin / 你的密码 → 进入已认证的控制面板。从任意机器验证门控:

curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["basic"]

GET /api/auth/me 随后返回已验证的会话(provider: basic)。请将其置于 VPN 之后——参见上方的警告;对于公网主机,请改用 Kopi Ai Agent Pte Ltd 或自托管 OIDC provider。

编写你自己的 password provider​

basic 只是某个扩展点的一种实现。任何插件都可以注册 password provider:在你的 DashboardAuthProvider 子类上设置 supports_password = True,并实现 complete_password_login(*, username, password) -> Session(拒绝时抛出 InvalidCredentialsError,后备存储不可用时抛出 ProviderError)。对于纯密码 provider,OAuth 的 start_login / complete_login 方法可以保留为 NotImplementedError 桩实现。这条路径适用于 LDAP-bind、凭据数据库或任何其他非重定向认证方案——框架会为你处理表单、路由、cookie 和刷新。

自托管 OIDC provider​

如果你运行自己的身份提供商,内置的 plugins/dashboard_auth/self_hosted 插件会使用标准 OpenID Connect 让控制面板对其进行认证——无需针对每个 IDP 编写代码,也不涉及 KOPI Proxy。它经过验证,可与任何符合规范的 OIDC 服务器配合工作:

Authentik · Keycloak · Zitadel · Authelia · Auth0 · Okta · Google · …

与 Nous provider 一样,它会自动加载,并且只在完成配置后才注册自身,因此对回环 / --insecure 控制面板而言是无操作的。

配置​

配置一个 issuer 和一个 client_id(一个公共 PKCE client —— 不需要 client secret)。插件会从 {issuer}/.well-known/openid-configuration 获取 IDP 的 authorization_endpoint、token_endpoint 和 jwks_uri,因此你无需硬编码端点 URL。

config.yaml —— 权威配置面:

dashboard:
oauth:
provider: self-hosted
self_hosted:
issuer: https://auth.example.com/application/o/kopi/ # required
client_id: kopi-dashboard # required
scopes: "openid profile email" # optional (this is the default)

环境变量 —— 操作者覆盖项(设置为非空时环境变量优先于 config.yaml;空值视为未设置):

环境变量覆盖项说明
KOPI_DASHBOARD_OIDC_ISSUERdashboard.oauth.self_hosted.issuerOIDC issuer URL —— 必需
KOPI_DASHBOARD_OIDC_CLIENT_IDdashboard.oauth.self_hosted.client_id公共 client id —— 必需
uired
KOPI_DASHBOARD_OIDC_SCOPESdashboard.oauth.self_hosted.scopes默认值为 openid profile email

在你的 IDP 中,注册一个公开(public)应用/客户端,使用授权码 + PKCE (S256) 授权流程,并把仪表板的回调地址添加为允许的 redirect URI。该回调地址为 <dashboard public URL>/auth/callback(关于仪表板在反向代理之后如何推导其公开 URL,请参阅公开 URL 覆盖)。

验证内容​

provider(服务提供商)会依据发现的 jwks_uri 验证 OpenID Connect ID token(RS256/ES256),并将 iss 和 aud claim 与你配置的 issuer 和 client_id 固定比对。标准 OIDC claim 映射到仪表板会话:

会话字段Claim
user_idsub(必填)
emailemail
display_namename → preferred_username → nickname → email
org_idorg_id / organization,否则为拼接后的 groups

建立身份的是 ID token —— access token 被视为不透明值(OIDC 规范并不要求它是 JWT)。Endpoint URL 必须使用 HTTPS(本地开发用 IDP 允许回环 http://),且 discovery 文档中公布的 issuer 必须与你配置的一致(尾部斜杠差异可以容忍)。当 IDP 签发 refresh token 时,它们用于通过标准 refresh_token 授权流程进行静默重新认证;登出时会在 IDP 公布 RFC 7009 revocation_endpoint 的情况下调用它。

尚不支持机密客户端(即带有 client_secret 的客户端)—— 请配置 public + PKCE 客户端,这也是面向浏览器的仪表板的典型选择。

实战示例:Keycloak​

Keycloak 是最容易搭建用于本地测试的自托管 OIDC 服务器之一 —— 它以单容器的开发模式运行(内存数据库),并提供教科书式的 OIDC discovery。本演练将在几分钟内带你从零搭建到可用的仪表板登录。

1. 运行带有预配置 realm 的 Keycloak。 将此 realm 导出保存为 realm-kopi-agent.json —— 其中定义了一个 kopi realm、一个 public PKCE 客户端(kopi-dashboard)以及一个测试用户,全部在启动时导入,因此无需在管理界面中点击任何东西:

{
"realm": "hermes",
"enabled": true,
"clients": [
{
"clientId": "kopi-dashboard",
"name": "KOPI AI AGENT Dashboard",
"enabled": true,
"publicClient": true,
"standardFlowEnabled": true,
"protocol": "openid-connect",
"redirectUris": ["http://localhost:9119/auth/callback"],
"webOrigins": ["http://localhost:9119"],
"attributes": { "pkce.code.challenge.method": "S256" }
}
],
"users": [
{
"username": "testuser",
"enabled": true,
"emailVerified": true,
"email": "testuser@example.com",
"firstName": "Test",
"lastName": "User",
"credentials": [
{ "type": "password", "value": "testpassword", "temporary": false }
]
}
]
}

启动它(Keycloak 26+),将该文件挂载到导入目录:

docker run --rm -p 8080:8080 \
-e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
-e KC_BOOTSTRAP_ADMIN_PASSWORD=admin \
-v "$PWD/realm-kopi-agent.json:/opt/keycloak/data/import/realm-kopi-agent.json:ro" \
quay.io/keycloak/keycloak:26.0 \
start-dev --import-realm

一旦启动,该 realm 会在 http://localhost:8080/realms/kopi/.well-known/openid-configuration(issuer http://localhost:8080/realms/kopi)发布标准 OIDC discovery。管理控制台位于 http://localhost:8080/(admin / admin)。

2. 将仪表板指向它。 自托管插件允许回环 http:// issuer(任何非回环 issuer 都必须使用 HTTPS),因此本地的 Keycloak 可以直接使用:

export KOPI_DASHBOARD_OIDC_ISSUER="http://localhost:8080/realms/kopi"
export KOPI_DASHBOARD_OIDC_CLIENT_ID="kopi-dashboard"
export KOPI_DASHBOARD_PUBLIC_URL="http://localhost:9119"
kopi dashboard --host 0.0.0.0 --port 9119 --no-open

KOPI_DASHBOARD_PUBLIC_URL 告知仪表板它的 OAuth 回调地址是 http://localhost:9119/auth/callback —— 即上面 realm 注册的 redirect URI。绑定到 0.0.0.0(非回环绑定)而不设置 --insecure 正是 启用 OAuth 闸门的触发条件。

3. 登录。 打开 http://localhost:9119/,你会被跳转到 /login。点击 Sign in with Self-Hosted OIDC → 在 Keycloak 以 testuser / testpassword 完成认证 → 回到已认证的仪表板。侧边栏会显示 Logged in as Test User via self-hosted,而 GET /api/auth/me 会返回已验证的会话(provider: self-hosted、email: testuser@example.com)。

如果你在不同的主机/端口上绑定或浏览,请把该来源的 …/auth/callback 添加到 Keycloak 管理控制台中客户端的 Valid redirect URIs(Clients → kopi-dashboard → Settings)。同样的模式适用于 Authentik、Zitadel、Authelia 以及其他 OIDC 服务器 —— 只是 issuer URL 与客户端注册界面有所不同。

公开 URL 覆盖​

默认情况下,仪表板会根据请求重建 OAuth 回调 URL —— X-Forwarded-Host + X-Forwarded-Proto + X-Forwarded-Prefix(当 uvicorn 配置了 proxy_headers=True 时,start_server 会在闸门下启用它)。对于正确设置这三个头的反向代理,这开箱即用。

对于无法可靠转发这些头的反向代理部署(手工 nginx 配置、本地 ingress、代理链不完整的自定义域名部署),请把 dashboard.public_url(或 KOPI_DASHBOARD_PUBLIC_URL)设置为访问仪表板所用的完整公开 URL:

dashboard:
public_url: "https://dashboard.example.com/kopi"

设置之后,OAuth 回调 URL 就会原样变为 <public_url>/auth/callback —— 在这条代码路径上 X-Forwarded-Prefix 会被忽略,因为运维人员已经明确声明了公开 URL。这是有意为之:在常见情况下前缀已经包含在 public_url 中,再叠加前缀会导致前缀重复。

与其他仪表板设置相同的优先级 —— 环境变量优先于 config.yaml:

配置面覆盖路径使用场景
config.yaml 中的 dashboard.public_urlKOPI_DASHBOARD_PUBLIC_URL本地开发 / 本地部署(推荐方式)
KOPI_DASHBOARD_PUBLIC_URL 环境变量—托管平台 secrets / CI
(未设置)—默认 —— 从 X-Forwarded-* 头重建

校验会拒绝没有 http:// / https:// scheme、没有主机名,或包含引号 / 尖括号 / 空白 / 控制字符的值。格式错误的值会静默回退到头重建方式,从而让登录流程继续工作,而不是把用户送到恶意 URL。

注意: public_url 只覆盖 OAuth 回调 URL。Secure cookie 标志仍由 request.url.scheme 控制(在 proxy_headers 下即 X-Forwarded-Proto),因此在 TLS 终止的公开部署上使用 http:// public_url 会产生非 Secure 的 cookie。这是运维人员容易踩的坑 —— 请将 public_url 与上游正确的 TLS 终止配合使用。

OAuth 流程​

provider 实现了 KOPI Proxy OAuth contract v1 —— 带 PKCE (S256) 的授权码授权流程:

  1. 用户在没有会话 cookie 的情况下访问 / → 闸门将其重定向到 /login。
  2. 登录页显示 "Continue with Kopi Ai Agent Pte Ltd" 按钮 → /auth/login?provider=nous。
  3. 服务器把 PKCE state 暂存在一个短生命周期的 cookie 中,并将用户重定向到 https://kopiaiagent.com/portal/oauth/authorize?…。
  4. 用户在 KOPI Proxy 完成认证,落到 /auth/callback?code=…&state=…。
  5. 服务器在 POST /api/oauth/token 用授权码换取 access token,通过 KOPI Proxy 的 JWKS(/.well-known/jwks.json)验证 JWT 签名,并设置 kopi_session_at cookie。
  6. 用户被重定向到 /(或通过 next= 查询参数回到原始的深层链接路径)。

access token 的 TTL 为 15 分钟。contract v1 中没有 refresh token —— 当 token 过期时,SPA 的 fetch 包装器会检测到 401 响应包,并整页导航回 /login 以重新运行该流程。

名称生命周期说明
kopi_session_atToken TTL(15 分钟)HttpOnly、SameSite=Lax、HTTPS 时为 Secure
kopi_session_pkce10 分钟HttpOnly;在往返过程中保存 PKCE verifier 与 provider 提示
kopi_session_rtv1 中未使用为向前兼容保留;当 refresh_token 为空时不写入

三者均为 Path=/ 和 SameSite=Lax。当通过 HTTPS 访问仪表板时会设置 Secure 标志(通过请求 URL scheme 检测 —— 在 proxy_headers=True 下会遵循来自上游 TLS 终止器的 X-Forwarded-Proto)。

登出​

侧边栏组件会显示 Logged in as <user_id…> via nous 以及一个登出图标。点击它会 POST /auth/logout,该操作会清除所有仪表板认证 cookie 并重定向回 /login。

审计日志​

每次登录的开始、成功、失败以及会话验证失败都会以 JSON 行的形式写入 $KOPI_HOME/logs/dashboard-auth.log。敏感字段(access_token、refresh_token、code、code_verifier、state、Authorization 头)在记录前会被脱敏。

自定义 provider​

要接入非 Nous 的 OAuth provider(例如 Google、GitHub、自定义 OIDC),请创建一个插件来注册 DashboardAuthProvider:

# ~/.kopi/plugins/dashboard-auth-myidp/__init__.py
from kopi_cli.dashboard_auth import DashboardAuthProvider, Session, LoginStart

class MyIdPProvider(DashboardAuthProvider):
name = "myidp"
display_name = "My Identity Provider"

def start_login(self, *, redirect_uri): ...
def complete_login(self, *, code, state, code_verifier, redirect_uri): ...
def verify_session(self, *, access_token): ...
def refresh_session(self, *, refresh_token): ...
def revoke_session(self, *, refresh_token): ...

def register(ctx):
ctx.register_dashboard_auth_provider(MyIdPProvider())

登录页会列出所有已注册的 provider;可以叠加多个 provider,用户在 /login 处选择其中一个。

非交互式(bearer token)认证​

除了交互式的人工登录(会话 cookie + 刷新)之外,DashboardAuthProvider ABC 还通过 supports_token = True + verify_token(token=...) 支持非交互式、服务对服务的能力。当 provider 选择启用时,会验证传入的 Authorization: Bearer <token>,验证成功后会把 TokenPrincipal 附加到请求上(request.state.token_principal),供该 provider 标记为可使用 token 认证的端点使用 —— 无 cookie、无重定向、无刷新。

内置的第一个使用方是 drain provider(plugins/dashboard_auth/drain):nous-account-service 通过 KOPI_DASHBOARD_DRAIN_SECRET 为每个 agent 签发一个 secret,provider 使用常量时间比较来验证传入的 bearer token,并把 /api/gateway/drain 注册为可使用 token 认证的端点。它采用失败关闭策略 —— 弱/过短的 secret(< 256 位)会在注册时被拒绝,该端点保持禁用;当环境变量未设置时则不执行任何操作。行为开关(scope、min_secret_chars)位于 config.yaml 的 dashboard.drain_auth 之下。

自定义 provider 可以用同样的方式实现 supports_token/verify_token,以暴露自己可进行机器认证的端点。

验证访问闸门已启用​

# Quick env-var path.
KOPI_DASHBOARD_OAUTH_CLIENT_ID=agent:test \
kopi dashboard --host 0.0.0.0

# Or the equivalent via config.yaml (recommended for local dev / on-prem):
#
# dashboard:
# oauth:
# client_id: agent:test
#
# then just:
kopi dashboard --host 0.0.0.0

# Hit /api/status to see the gate state:
curl -s http://127.0.0.1:9119/api/status | jq '.auth_required, .auth_providers'
# true
# ["nous"]

仪表板的 React StatusPage 会在 "Web server" 下显示相同的字段。登录后,侧边栏的 AuthWidget 会显示当前身份。

将 Kopi Agent Desktop 连接到远程后端​

Kopi Agent Desktop 可以驱动运行在另一台机器上的 Kopi Agent 后端(VPS、家庭服务器、位于 Tailscale 之后的 Mini)。在应用中,该功能位于 Settings → Gateway → Remote gateway 下,需要填写 Remote URL 并完成 Sign in。(关于桌面应用本身 —— 安装、设置、聊天 —— 请参阅 Kopi Agent Desktop 页面。)

你可以使用内置的 auth provider(身份验证提供方)之一来保护远程 dashboard,桌面应用会针对后端所声明的那一个进行登录。对于可在你自己机器之外访问的后端 —— VPS、公共主机、任何面向互联网的服务 —— 推荐的 provider 是 OAuth (KOPI Proxy)(使用 kopi dashboard register 注册,并以 Sign in with Kopi Ai Agent Pte Ltd 登录)。内置的 username/password provider 是后端位于可信局域网内或只能通过 VPN 访问时最快的方案,但不适合直接暴露到公共互联网。将 dashboard 绑定到非 loopback 地址会启用其身份验证网关;登录后,Desktop 会自动为聊天 WebSocket 复用该会话 —— 无需复制或粘贴任何 token。

下面的操作步骤使用 username/password 路径,因为它在可信网络上搭建最快;OAuth 路径请参阅 Default provider: Kopi Ai Agent Pte Ltd。

在后端(远程机器)上​

# 1. Set the dashboard login credentials in ~/.kopi/.env (secrets file, 0600).
cat >> ~/.kopi/.env <<'EOF'
KOPI_DASHBOARD_BASIC_AUTH_USERNAME=admin
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
KOPI_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.kopi/.env

# 2. Run the dashboard bound to a reachable address. The non-loopback bind
# engages the auth gate; the username/password provider handles login.
kopi dashboard --no-open --host 0.0.0.0 --port 9119

如果希望磁盘上不保存明文?可以改用 KOPI_DASHBOARD_BASIC_AUTH_PASSWORD_HASH 搭配 scrypt 哈希 —— 完整功能请参阅 Username/password provider。

如果你将 dashboard 作为 systemd 服务运行,只要单元设置了 EnvironmentFile=%h/.kopi/.env,~/.kopi/.env 就会被自动读取,因此凭据在启动时就已存在于环境中。

注意

Dashboard 会读写你的 .env(API keys、secrets),并能运行 agent 命令。此处展示的 username/password 配置适用于可信网络 —— 切勿将受密码保护的 dashboard 直接暴露到开放互联网。请将其放在 VPN 之后。Tailscale 是最简洁的方案:绑定到机器的 tailscale IP(--host <tailscale-ip>),并将 http://<tailscale-ip>:9119 用作 Remote URL。只有你的 tailnet 中的设备才能访问它。要通过公共互联网访问后端,请改用 OAuth (KOPI Proxy) provider。

在 Kopi Agent Desktop 中​

Settings → Gateway → Remote gateway:

  • Remote URL —— http://<backend-host>:9119(如果你在前面加了反向代理,也支持 /kopi 这样的路径前缀)
  • Sign in —— 应用会检测到 username/password gateway 并显示 Sign in 按钮;点击它并输入第 1 步中的凭据
  • Save and reconnect —— 将桌面 shell 切换到远程后端

当后端设置了 KOPI_DASHBOARD_BASIC_AUTH_SECRET 时,会话会自动刷新,并能在重启后保持。

环境变量覆盖​

除了应用内设置,你也可以在启动前通过环境变量将桌面应用指向某个后端。当设置了 KOPI_DESKTOP_REMOTE_URL 时,它会覆盖已保存的应用内 URL(Gateway 设置面板会显示 "env override" 徽章并禁用编辑);你仍需在面板中登录,输入用户名和密码。

环境变量值
KOPI_DESKTOP_REMOTE_URLhttp://<backend-host>:9119

故障排查​

  • "Remote gateway incomplete" —— 你尚未输入远程 URL。
  • 登录失败并显示 401 / "Invalid credentials" —— 用户名或密码与后端的 KOPI_DASHBOARD_BASIC_AUTH_USERNAME / KOPI_DASHBOARD_BASIC_AUTH_PASSWORD 不匹配。后端对未知用户和错误密码返回相同的通用错误,因此两者都要检查。用 curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers' 确认网关 —— 它应报告 true 并包含 "basic"。
  • 没有 "Sign in" 按钮 —— 而是要求输入 session token —— username/password provider 未激活(/api/status 不会列出 "basic")。请确保已设置用户名和密码(或密码哈希),并且 dashboard 进程已加载它们。
  • 每次重启后都退出登录 —— 将 KOPI_DASHBOARD_BASIC_AUTH_SECRET 设置为一个稳定值;否则签名密钥会在每次启动时重新生成。
  • Connection refused / 超时 —— 后端绑定到了 127.0.0.1(默认值)而非可访问的地址,或者防火墙/VPN 阻止了该端口。请绑定到 0.0.0.0 或 tailscale IP,并向你的可信网络开放该端口。

CORS​

Web 服务器将 CORS 限制为仅允许 localhost 来源:

  • http://localhost:9119 / http://127.0.0.1:9119(生产环境)
  • http://localhost:3000 / http://127.0.0.1:3000
  • http://localhost:5173 / http://127.0.0.1:5173(Vite dev server)

如果你在自定义端口上运行服务器,该来源会被自动添加。

开发​

如果你要为 web dashboard 前端贡献代码:

# Terminal 1: start the backend API
kopi dashboard --no-open

# Terminal 2: start the Vite dev server with HMR
cd web/
npm install
npm run dev

位于 http://localhost:5173 的 Vite dev server 会将 /api 请求代理到位于 http://127.0.0.1:9119 的 FastAPI 后端。

前端使用 React 19、TypeScript、Tailwind CSS v4 和 shadcn/ui 风格组件构建。生产构建输出到 kopi_cli/web_dist/,FastAPI 服务器将其作为静态 SPA 提供。

更新时自动构建​

当你运行 kopi update 时,如果 npm 可用,web 前端会自动重新构建。这样可以让 dashboard 与代码更新保持同步。如果未安装 npm,更新会跳过前端构建,kopi dashboard 将在首次启动时构建它。

主题与插件​

Dashboard 内置六款主题,并支持通过用户自定义主题、插件标签页和后端 API 路由进行扩展 —— 全部即插即用,无需克隆仓库。

实时切换主题:在顶栏中点击语言切换器旁的调色板图标即可。所选主题会持久化保存到 config.yaml 中的 dashboard.theme,并在页面加载时恢复。

独立更改字体:在同一选择器中,主题列表下方的 Font 区域可覆盖当前激活主题的 UI 字体。该设置在切换主题后仍会保留(config.yaml → dashboard.font);选择 Theme default 即可清除自定义字体,恢复为激活主题自带的字体。

内置主题:

主题特点
Kopi Agent Teal (default)深青色 + 奶油色,系统字体,宽松的间距
Kopi Agent Teal (Large) (default-large)与默认主题相同,但正文为 18px,间距更宽敞
Midnight (midnight)深蓝紫色,Inter + JetBrains Mono
Ember (ember)暖绯红 + 古铜色,Spectral 衬线字体 + IBM Plex Mono
Mono (mono)灰度配色,IBM Plex,紧凑布局
Cyberpunk (cyberpunk)黑底霓虹绿,Share Tech Mono
Rosé (rose)粉色 + 象牙白,Fraunces 衬线字体,宽敞布局

若要构建自己的主题、添加插件标签页、注入 shell 插槽,或暴露插件专属的 REST 端点,请参阅 扩展 Dashboard —— 完整指南涵盖:

  • 主题 YAML schema —— palette、typography、layout、assets、componentStyles、colorOverrides、customCSS
  • 布局变体 —— standard、cockpit、tiled
  • 插件 manifest、SDK、shell 插槽、页面级插槽(在不覆盖内置页面的前提下向其中注入组件)、后端 FastAPI 路由
  • 一套完整主题 + 插件组合实战教程(Strike Freedom 座舱演示)
  • 发现、重载与故障排查