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 | 默认值 | 说明 |
|---|---|---|
--port | 9119 | Web 服务器运行的端口 |
--host | 127.0.0.1 | 绑定地址 |
--no-open | — | 不自动打开浏览器 |
--insecure | off | 允许绑定到非 localhost 的主机(危险——会在网络上暴露 API key;请配合防火墙和强认证使用) |
--isolated | off | 当从具名 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—— 由ptyextra 安装(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 dashboardDesktop 连接的"远程后端"就是运行在远程机器上的一个 kopi dashboard 进程 —— 也就是本页所描述的同一个服务器。它必须先启动并可被访问,然后下面的步骤才有意义;Desktop 只是连接到它,而不会替你启动它。请让它在 systemd/tmux 等下持续运行,以便它在注销和重启后依然存活。gateway(Telegram/Discord/Slack 等)是一个独立的长期运行进程 —— 如果你依赖消息渠道,请单独启动它;桌面应用连接的并不是它。
Desktop 的"远程后端已就绪"探测只请求 GET /api/status,这是一个公开端点 —— 只要主机上运行着任意仪表板,它就会返回响应。实时聊天连接则是一个独立的、指向 /api/ws(以及 /api/pty)的 WebSocket,而该 socket 受两项额外检查的限制,状态探测从不涉及这两项检查:
- 你必须完成认证。 当仪表板绑定到非回环地址时,它会启用认证闸门。请使用用户名和密码保护它(内置的 username/password provider);Desktop 登录一次,并通过一次性 ticket 将生成的 session 复用于 WebSocket。如果没有配置 provider,非回环的仪表板会在启动时失败关闭(fail closed)。
- 绑定主机必须允许客户端访问并匹配 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) 部分,了解完整的配置内容。
在任意机器上,检查仪表盘是否宣告了用户名/密码 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 自动发现,并按带标签页的分类组织:

- 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 — 使用垃圾桶图标删除会话及其消息历史。

日志
查看 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。

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 使用的目录相同。

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

Pairing(配对)
无需 CLI 即可批准和撤销消息用户 — 远程管理员将 Telegram/Discord 等平台用户接入已配对网关的方式。与 kopi 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;网关会在下次重启时连接每个已启用的渠道,而你可以直接在该页面触发重启。

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 — 查看
/rollbackshadow store 的大小并进行清理 - Shell hooks — 列出已配置的 hooks 及其 consent + 可执行状态,创建 hook(事件、命令、matcher、超时,以及可选的 consent 授权),并移除某个 hook。Hook 会运行任意命令,因此创建表单带有安全警告,且只有在授予 consent 后 hook 才会触发。



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

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,供前端消费。你也可以直接调用这些端点来实现自动化:
管理端点系列 —— /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 · /restart | Gateway 生命周期(后台执行) |
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 .../run | Skill-curator 状态 + 暂停/恢复 + 运行 |
GET /api/portal | KOPI Proxy 认证 + Tool Gateway 路由(只读) |
POST /api/ops/prompt-size · /dump · /config-migrate | 诊断(后台执行) |
PUT /api/webhooks/{name}/enabled | 启用 / 禁用一个 webhook route |
POST /api/skills/hub/install · /uninstall · /update | Skills hub 操作(后台执行) |
GET /api/skills/hub/search | 跨所有来源搜索 skill hub |
GET /api/sessions/stats | Session-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 进行保护 |
当且仅当满足以下条件时,网关才会启用:
- 绑定主机不是
127.0.0.1、::1、localhost或0.0.0.0,并且 - 未设置
--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_ID | dashboard.oauth.client_id | agent:{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_USERNAME | dashboard.basic_auth.username | 激活所必需 |
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD_HASH | dashboard.basic_auth.password_hash | 推荐(静态存储中无明文) |
KOPI_DASHBOARD_BASIC_AUTH_PASSWORD | dashboard.basic_auth.password | 明文;优先于配置中的 password_hash,以便通过环境变量轮换 |
KOPI_DASHBOARD_BASIC_AUTH_SECRET | dashboard.basic_auth.secret | token 签名密钥 |
KOPI_DASHBOARD_BASIC_AUTH_TTL_SECONDS | dashboard.basic_auth.session_ttl_seconds | access 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_ISSUER | dashboard.oauth.self_hosted.issuer | OIDC issuer URL —— 必需 |
KOPI_DASHBOARD_OIDC_CLIENT_ID | dashboard.oauth.self_hosted.client_id | 公共 client id —— 必需 |
| uired | ||
KOPI_DASHBOARD_OIDC_SCOPES | dashboard.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_id | sub(必填) |
email | email |
display_name | name → preferred_username → nickname → email |
org_id | org_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_url | KOPI_DASHBOARD_PUBLIC_URL | 本地开发 / 本地部署(推荐方式) |
KOPI_DASHBOARD_PUBLIC_URL 环境变量 | — | 托管平台 secrets / CI |
| (未设置) | — | 默认 —— 从 X-Forwarded-* 头重建 |
校验会拒绝没有 http:// / https:// scheme、没有主机名,或包含引号 / 尖括号 / 空白 / 控制字符的值。格式错误的值会静默回退到头重建方式,从而让登录流程继续工作,而不是把用户送到恶意 URL。
注意:
public_url只覆盖 OAuth 回调 URL。Securecookie 标志仍由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) 的授权码授权流程:
- 用户在没有会话 cookie 的情况下访问
/→ 闸门将其重定向到/login。 - 登录页显示 "Continue with Kopi Ai Agent Pte Ltd" 按钮 →
/auth/login?provider=nous。 - 服务器把 PKCE state 暂存在一个短生命周期的 cookie 中,并将用户重定向到
https://kopiaiagent.com/portal/oauth/authorize?…。 - 用户在 KOPI Proxy 完成认证,落到
/auth/callback?code=…&state=…。 - 服务器在
POST /api/oauth/token用授权码换取 access token,通过 KOPI Proxy 的 JWKS(/.well-known/jwks.json)验证 JWT 签名,并设置kopi_session_atcookie。 - 用户被重定向到
/(或通过next=查询参数回到原始的深层链接路径)。
access token 的 TTL 为 15 分钟。contract v1 中没有 refresh token —— 当 token 过期时,SPA 的 fetch 包装器会检测到 401 响应包,并整页导航回 /login 以重新运行该流程。
设置的 Cookie
| 名称 | 生命周期 | 说明 |
|---|---|---|
kopi_session_at | Token TTL(15 分钟) | HttpOnly、SameSite=Lax、HTTPS 时为 Secure |
kopi_session_pkce | 10 分钟 | HttpOnly;在往返过程中保存 PKCE verifier 与 provider 提示 |
kopi_session_rt | v1 中未使用 | 为向前兼容保留;当 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_URL | http://<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:3000http://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 座舱演示)
- 发现、重载与故障排查