Windows(原生)指南
Kopi Agent 可在 Windows 10 和 Windows 11 上原生运行 —— 无需 WSL,无需 Cygwin,无需 Docker。本页是深入介绍:哪些功能原生可用、哪些仅限 WSL、安装脚本实际做了什么,以及你可能需要调整的 Windows 专属配置项。
如果你只是想安装,首页或安装页面上的一行命令就够了。等遇到意料之外的情况时再回来看这里。
如果你偏好真正的 POSIX 环境(例如面板内置终端、fork 语义、Linux 风格的文件监视器等),请参阅 Windows(WSL2)指南。两者可以干净共存:原生数据存放在 %LOCALAPPDATA%\kopi,WSL 数据存放在 ~/.kopi。
快速安装
打开 PowerShell(或 Windows Terminal)并运行:
iex (irm https://raw.githubusercontent.com/Kopi Ai Agent Pte Ltd/kopi-ai-agent/main/scripts/install.ps1)
无需管理员权限。安装程序会安装到 %LOCALAPPDATA%\kopi\,并把 kopi 添加到你的 用户 PATH —— 完成后请打开一个新的终端。
安装程序选项(需要使用 scriptblock 形式来传参):
& ([scriptblock]::Create((irm https://raw.githubusercontent.com/Kopi Ai Agent Pte Ltd/kopi-ai-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main
| 参数 | 默认值 | 用途 |
|---|---|---|
-Branch | main | 克隆指定分支(适用于测试 PR) |
-Commit | 未设置 | 固定安装到指定 commit SHA(覆盖 -Branch) |
-Tag | 未设置 | 固定安装到指定 git tag(例如 v0.14.0) |
-NoVenv | off | 跳过 venv 创建(高级用法 —— 自行管理 Python) |
-SkipSetup | off | 跳过安装后的 kopi setup 向导 |
-HermesHome | %LOCALAPPDATA%\kopi | 覆盖数据目录 |
-InstallDir | %LOCALAPPDATA%\kopi\kopi-ai-agent | 覆盖代码位置 |
安装程序会自动重试不稳定的 git fetch,并去除下载的 install.ps1 载荷中的 BOM,这样 HTTP 传输过程中带上的 UTF-8 BOM 就不会再破坏 [scriptblock]::Create((irm ...)) 形式。
桌面安装程序(替代方案)
还提供了一个轻量的 GUI 安装程序 —— 如果你更愿意双击 .exe 而不是打开 PowerShell,它会很有用。下载 Kopi Agent Desktop,运行安装程序,首次启动时 GUI 会在底层调用 install.ps1 来配置 Python(通过 uv)、Node、PortableGit,以及下文所述的其余依赖引导流程。首次运行之后,桌面应用与通过 PowerShell 安装的 kopi CLI 共用同一个 %LOCALAPPDATA%\kopi\kopi-ai-agent 安装目录和 %LOCALAPPDATA%\kopi 数据目录 —— 可以在 GUI 和 CLI 之间自由切换。
当你想要熟悉的 Windows 安装体验,或者要把 Kopi Agent 交给非开发者使用时,请使用桌面安装程序;当你已经身处终端时,请使用 PowerShell 一行命令。
依赖引导(dep_ensure)
首次启动时(以及检测到缺失工具时按需执行),Kopi Agent 会运行一个小型 Python 引导程序 —— kopi_cli/dep_ensure.py —— 检查并惰性安装所需的非 Python 依赖。在 Windows 上,相关的依赖有:
| 依赖 | Kopi Agent 需要它的原因 |
|---|---|
| PortableGit | 为终端工具提供 bash.exe,为会话内克隆提供 git。在安装时配置,而非由 dep_ensure 负责。 |
| Node.js 22 | 浏览器工具(agent-browser)、TUI 的 web bridge 以及 WhatsApp bridge 都需要它。 |
| ffmpeg | 用于 TTS / 语音消息的音频格式转换。 |
| ripgrep | 快速文件搜索 —— 不可用时回退到 grep。 |
| npm 包 | agent-browser、Playwright Chromium 以及各工具集的 Node 依赖会在首次使用浏览器工具时一次性安装。 |
每个依赖都有 shutil.which(...) 风格的检查;如果某个二进制缺失且当前为交互式运行,dep_ensure 会询问是否安装(实际安装逻辑交由 scripts\install.ps1 -ensure <dep> 执行)。非交互式运行(gateway、cron、无头桌面启动)会跳过提示,改为给出清晰的 this feature needs <dep> 错误。
安装程序实际做了什么
从头到尾,按顺序:
- 引导安装
uv—— Astral 的快速 Python 管理器。安装到%USERPROFILE%\.local\bin。 - 安装 Python 3.11,通过
uv。无需已有 Python。 - 安装 Node.js 22(优先用 winget,否则使用便携版 Node tarball 解压到
%LOCALAPPDATA%\kopi\node)。用于浏览器工具和 WhatsApp bridge。 - 安装便携版 Git —— 如果
git已在 PATH 上,安装程序会直接使用它;否则会下载一个精简、自包含的 PortableGit(约 45 MB,来自官方git-for-windowsrelease)到%LOCALAPPDATA%\kopi\git。无需管理员权限,不写 Windows installer 注册表,不会干扰机器上的其他任何东西。 - 克隆仓库到
%LOCALAPPDATA%\kopi\kopi-ai-agent,并在其中创建 virtualenv。 - 分层
uv pip install—— 先尝试.[all],如果某个git+https依赖在受速率限制的 GitHub 上失败,则回退到逐级精简的集合([messaging,dashboard,ext]→[messaging]→.)。避免了"单次失败就导致仅基础安装"的失败模式。 - 根据
.env自动安装消息 SDK —— 如果存在TELEGRAM_BOT_TOKEN/DISCORD_BOT_TOKEN/SLACK_BOT_TOKEN/SLACK_APP_TOKEN/WHATSAPP_ENABLED,则运行python -m ensurepip --upgrade和针对性的pip install调用,确保每个平台的 SDK 真正可导入。 - 将
KOPI_GIT_BASH_PATH设置为解析出的bash.exe,让 Kopi Agent 在全新 shell 中都能确定地找到它。 - 将
%LOCALAPPDATA%\kopi\kopi-ai-agent\venv\Scripts添加到用户 PATH 并设置KOPI_HOME=%LOCALAPPDATA%\kopi—— 打开新终端后即可使用kopi命令(并将其指向你的数据目录)。 - 运行
kopi setup—— 常规的首次运行向导(模型、provider、工具集)。可用-SkipSetup跳过。
在 Windows 上,逐个工具配置 API key(Firecrawl、FAL、Browser Use、OpenAI TTS)是让 agent 真正好用过程中最繁琐的部分。一个 KOPI Proxy 订阅通过一次 OAuth 登录即可覆盖模型以及上述全部工具。安装程序完成后,运行 kopi setup --portal 即可完成全部接线配置。
功能矩阵
除仪表板的嵌入式终端窗格外,其他所有功能均可在 Windows 上原生运行。
| 功能 | 原生 Windows | WSL2 |
|---|---|---|
CLI(kopi chat、kopi setup、kopi gateway 等) | ✓ | ✓ |
交互式 TUI(kopi --tui) | ✓ | ✓ |
| 消息网关(Telegram、Discord、Slack、WhatsApp 等 15+ 平台) | ✓ | ✓ |
| Cron 调度器 | ✓ | ✓ |
| 浏览器工具(通过 Node 运行 Chromium) | ✓ | ✓ |
| MCP 服务器(stdio 和 HTTP) | ✓ | ✓ |
| 本地 Ollama / LM Studio / llama-server | ✓ | ✓(通过 WSL 网络) |
| Web 仪表板(会话、任务、指标、配置) | ✓ | ✓ |
仪表板 /chat 嵌入式终端窗格 | ✗(需要 POSIX PTY) | ✓ |
| 登录时自动启动 | ✓(schtasks) | ✓(systemd) |
仪表板的 /chat 标签页通过 POSIX PTY(ptyprocess)嵌入了一个真实终端。原生 Windows 没有等价的原语;Python 的 pywinpty / Windows ConPTY 可以胜任,但那是一套独立的实现 —— 将其视为后续工作。仪表板的其余部分可原生运行 —— 只有那一个标签页会显示“请为此使用 WSL2”的横幅。
Kopi Agent 如何在 Windows 上运行 shell 命令
Kopi Agent 的终端工具通过 Git Bash 运行命令,与 Claude Code 采用的策略相同。这样可以在不重写每个工具的情况下绕过 POSIX 与 Windows 之间的差异。
bash.exe 的解析顺序:
- 如果设置了
KOPI_GIT_BASH_PATH环境变量,则使用它。 %LOCALAPPDATA%\kopi\git\usr\bin\bash.exe(安装程序管理的 PortableGit)。%LOCALAPPDATA%\kopi\git\bin\bash.exe(较旧的 Git for Windows 目录布局)。- 系统安装的 Git for Windows(
%ProgramFiles%\Git\bin\bash.exe等)。 - 作为最后手段,使用 PATH 上的 MSYS2、Cygwin 或任何
bash.exe。
安装程序会显式设置 KOPI_GIT_BASH_PATH,这样新的 PowerShell 会话无需重新探测。如果你想让 Kopi Agent 使用特定的 bash,可以覆盖它 —— 例如系统 Git Bash,或通过符号链接指向的 WSL 中的 bash。
陷阱: MinGit 的目录结构与完整的 Git for Windows 安装程序不同 —— bash 位于 usr\bin\bash.exe 下,而非 bin\bash.exe。Kopi Agent 会检查这两个位置。如果你手动解压 MinGit 的 zip 包,请确保选择 非 busybox 版本(MinGit-*-64-bit.zip,而非 MinGit-*-busybox*.zip)—— busybox 构建版提供的是 ash 而不是 bash,而且缺少大多数 coreutils。
Windows 上的 UTF-8 控制台
Python 在 Windows 上的默认 stdio 使用控制台的活动代码页(通常是 cp1252 或 cp437)。Kopi Agent 的横幅、斜杠命令列表、工具输出流、Rich 面板和 skill 描述都包含 Unicode。若不加处理,其中任何一项都会因 UnicodeEncodeError: 'charmap' codec can't encode character… 而崩溃。
修复位于 kopi_cli/stdio.py::configure_windows_stdio(),它会在每个入口点(cli.py::main、kopi_cli/main.py::main、gateway/run.py::main)的早期被调用。它会:
- 通过
kernel32.SetConsoleCP/SetConsoleOutputCP将控制台代码页切换为 CP_UTF8(65001)。 - 使用
errors='replace'将sys.stdout/sys.stderr/sys.stdin重新配置为 UTF-8。 - 设置
PYTHONIOENCODING=utf-8和PYTHONUTF8=1(通过setdefault,以便用户的显式设置优先生效),使子 Python 进程继承 UTF-8。 - 如果既未设置
EDITOR也未设置VISUAL,则设置EDITOR=notepad(参见下文的编辑器一节)。
该操作是幂等的,在非 Windows 平台上不执行任何操作。
选择退出: 在环境中设置 KOPI_DISABLE_WINDOWS_UTF8=1 会回退到传统的 cp1252 stdio 路径。这在二分定位编码 bug 时很有用;在正常使用中通常不是正确的设置。
编辑器(Ctrl-X Ctrl-E、/edit)
在 #21561 之前,在 Windows 上按 Ctrl-X Ctrl-E 或输入 /edit 会静默地毫无反应。prompt_toolkit 有一个硬编码的 POSIX 绝对路径回退列表(/usr/bin/nano、/usr/bin/pico、/usr/bin/vi 等),在 Windows 上永远无法解析 —— 即使安装了完整的 Git for Windows 也是如此。
Kopi Agent 的 Windows stdio shim 现在将 EDITOR=notepad 设为默认值。记事本随每个 Windows 安装附带,并且可以作为阻塞式编辑器工作 —— subprocess.call(["notepad", file]) 会阻塞直到窗口关闭。
用户覆盖仍然优先生效(在 setdefault 之前会先检查这些值):
| 编辑器 | PowerShell 命令 |
|---|---|
| VS Code | $env:EDITOR = "code --wait" |
| Notepad++ | $env:EDITOR = "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -nosession" |
| Neovim | $env:EDITOR = "nvim" |
| Helix | $env:EDITOR = "hx" |
VS Code 上的 --wait 标志至关重要 —— 没有它,编辑器会立即返回,Kopi Agent 会得到一个空白缓冲区。
在你的 PowerShell profile 中永久设置它:
# In $PROFILE
$env:EDITOR = "code --wait"
或者在系统设置中将其设为用户环境变量,让每个新 shell 都能读取到。
在 CLI 中用 Ctrl+Enter 换行
Windows Terminal 会把 Ctrl+Enter 作为专用按键序列传递。Kopi Agent 将其绑定为“插入换行符”,这样你可以在 CLI 中编写多行提示词,而无需退回到先 Esc 再 Enter 的方式。在 Windows Terminal、VS Code 集成终端以及任何遵循 VT 转义序列的现代 Windows 控制台宿主中都可以使用。
在传统的 cmd.exe 控制台上,Ctrl+Enter 会退化为普通的 Enter —— 这时请改用 Esc Enter,或者升级到 Windows Terminal(它免费,且在 Windows 11 上默认安装)。
在 Windows 登录时运行网关
kopi gateway install 在 Windows 上使用**计划任务(Scheduled Tasks)**并以启动文件夹作为回退方案——无需管理员权限。
安装
kopi gateway install
底层的实际执行过程:
schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway— 注册一个在你登录时运行的任务,使用标准(非提权)权限。不会弹出 UAC 提示。- 如果 schtasks 被组策略阻止,则回退为向
%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup写入一个start /min cmd.exe /d /c <wrapper>快捷方式。效果相同,只是略显粗糙。 - 通过
pythonw.exe以分离方式派生网关——而不是python.exe。pythonw.exe没有关联的控制台,因此它可以免疫来自同级进程的CTRL_C_EVENT广播(这是一个真实存在过的问题:以前在同一进程组中按 Ctrl+C 时会误杀网关)。
派生时使用的标志:DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB。
管理
kopi gateway status # Merged view: schtasks + Startup folder + running PID
kopi gateway start # Starts the scheduled task now
kopi gateway stop # Graceful SIGTERM equivalent (TerminateProcess via psutil)
kopi gateway restart
kopi gateway uninstall # Removes schtasks entry, Startup shortcut, pid file
kopi gateway status 是幂等的——哪怕连续调用一千次,也绝不会意外杀掉网关。(在 PR #21561 之前它会悄悄地杀掉网关,原因是 os.kill(pid, 0) 在 C 层面与 CTRL_C_EVENT 冲突——如果你对这段历史感兴趣,可以参见下文的"进程管理内部机制"。)
为什么不用 Windows Service?
Service 需要管理员权限来安装,并且会把网关的生命周期绑定到机器启动,而非用户登录。典型的 Kopi Agent 用户期望是:登录 → 网关可用,登出 → 网关消失。计划任务无需提权就能精确做到这一点。如果你确实需要一个 service,可以手动使用 nssm 或 sc create——但你大概率并不需要。
数据布局
| 路径 | 内容 |
|---|---|
%LOCALAPPDATA%\kopi\kopi-ai-agent\ | Git checkout + venv。venv\Scripts\kopi-agent.exe 是添加到用户 PATH 的命令。可以安全地 Remove-Item -Recurse 后重新安装。 |
%LOCALAPPDATA%\kopi\git\ | PortableGit(仅当安装器配置了它时才有)。 |
%LOCALAPPDATA%\kopi\node\ | Portable Node.js(仅当安装器配置了它时才有)。 |
%LOCALAPPDATA%\kopi\bin\ | Kopi Agent 托管的 uv.exe(它用于更新的 Python 管理器)。 |
%LOCALAPPDATA%\kopi\(根目录) | 你的配置、认证信息、skills、会话、日志(config.yaml、.env、skills\、sessions\、logs\ 等)。重装后仍会保留。 |
在原生 Windows 上,安装器会设置 KOPI_HOME=%LOCALAPPDATA%\kopi,因此你的数据与一次性安装内容位于同一个 %LOCALAPPDATA%\kopi 根目录下:安装/运行时内容位于 kopi-ai-agent\、git\、node\ 和 bin\ 子目录,而你的数据文件直接位于 %LOCALAPPDATA%\kopi 中。重装只会替换 kopi-ai-agent\ checkout,因此你的数据会保留——但由于两者共用同一个根目录,如果你想保留数据,就不要 Remove-Item -Recurse %LOCALAPPDATA%\kopi;而应删除 kopi-ai-agent\ 子目录。你的数据目录结构与 Linux 上的 ~/.kopi 完全一致,因此可以在多台机器之间镜像同步。
覆盖 KOPI_HOME: 设置该环境变量以指向不同的数据目录(例如 %USERPROFILE%\.kopi,以匹配 Linux/WSL 的布局)。其工作方式与 Linux 上完全相同。
浏览器工具
浏览器工具使用 agent-browser(一个 Node 辅助程序)来驱动 Chromium。在 Windows 上:
- 安装器通过 npm 将
agent-browser加入 PATH。 shutil.which("agent-browser", path=...)会自动识别.cmdshim——CreateProcessW无法执行没有扩展名的 shebang 脚本,因此 Kopi Agent 始终解析到.CMD包装器。不要手动调用 shebang 脚本;始终通过.cmd来使用。- Playwright Chromium 会在首次运行时自动安装(
npx playwright install chromium)。如果安装失败,kopi doctor会将其暴露出来并给出修复提示。
在 Windows 上运行 Kopi Agent——实用说明
安装后的 PATH
安装器通过 [Environment]::SetEnvironmentVariable 将 %LOCALAPPDATA%\kopi\kopi-ai-agent\venv\Scripts 添加到你的用户 PATH。已打开的终端不会感知到这一变化——安装后请打开一个新的 PowerShell 窗口(或 Windows Terminal 标签页)。请关闭后重新打开,除非你清楚自己在做什么,否则不要手动 $env:PATH += …。
验证:
Get-Command kopi # should print C:\Users\<you>\AppData\Local\hermes\kopi-ai-agent\venv\Scripts\kopi-agent.exe
kopi --version
环境变量
Kopi Agent 同时支持 $env:X(进程作用域)和用户环境变量(永久生效,在"系统属性 → 环境变量"中设置)。在 %LOCALAPPDATA%\kopi\.env(你的 KOPI_HOME)中设置 API key 是常规做法——与 Linux 上一致:
OPENROUTER_API_KEY=sk-or-...
TELEGRAM_BOT_TOKEN=...
除非你确实希望所有 Windows 进程都能看到这些密钥,否则不要把机密信息放在用户环境变量里(那通常并不是你想要的效果)。
Windows 专属环境变量
以下变量只影响原生 Windows 安装:
| 变量 | 作用 |
|---|---|
KOPI_GIT_BASH_PATH | 覆盖 bash.exe 的发现逻辑。可指向任意 bash——完整的 Git for Windows、通过符号链接指向的 WSL bash、MSYS2、Cygwin。安装器会自动设置此项。 |
KOPI_DISABLE_WINDOWS_UTF8 | 设置为 1 可禁用 UTF-8 stdio shim,回退到区域设置代码页。在二分定位编码问题时很有用。 |
EDITOR / VISUAL | 用于 /edit 和 Ctrl-X Ctrl-E 的编辑器。如果两者都未设置,Kopi Agent 默认使用 notepad。 |
卸载
在 PowerShell 中:
kopi uninstall
这是干净的卸载路径——移除 schtasks 条目、启动文件夹快捷方式、kopi-agent.cmd shim,删除 %LOCALAPPDATA%\kopi\kopi-ai-agent\,并清理用户 PATH。它会保留 %LOCALAPPDATA%\kopi\ 的其余内容(你的配置、认证信息、skills、会话、日志),以防你需要重新安装。
如果要彻底清除所有内容:
kopi uninstall
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes"
# Also remove a legacy CLI/WSL data dir if you ever used one:
Remove-Item -Recurse -Force "$env:USERPROFILE\.kopi"
kopi uninstall CLI 子命令还能处理 schtasks 条目以不同任务名注册的情况(旧版安装)——它按安装路径而非硬编码的任务名进行搜索。
进程管理内部机制
以下为背景资料——除非你正在排查"它自己把自己杀掉了"这类诡异问题,否则可跳过。
在 Linux 和 macOS 上,POSIX 惯用法 os.kill(pid, 0) 是一次空操作的权限检查:"这个 PID 是否存活、我能否向它发送信号?"在 Windows 上,Python 的 os.kill 将 sig=0 映射为 CTRL_C_EVENT——二者在整数值 0 上发生冲突——并通过 GenerateConsoleCtrlEvent(0, pid) 传递,后者会将 Ctrl+C 广播给包含目标 PID 的整个控制台进程组。这就是 bpo-14484,自 2012 年起一直悬而未决。它不会被修复,因为改动会破坏依赖当前行为的脚本。
后果是:在 Windows 上,任何通过 os.kill(pid, 0) 表示"检查该 PID 是否存活"的代码路径,实际上都在悄悄杀掉目标进程。Kopi Agent 已将所有此类调用点(分布在 11 个文件中共 14 处)迁移到 gateway.status._pid_exists(),后者使用 psutil.pid_exists()(而它在 Windows 上又使用 OpenProcess + GetExitCodeProcess——不发送信号)。如果你在编写插件或补丁,请直接使用 psutil.pid_exists() 或 gateway.status._pid_exists()——绝不要使用 os.kill(pid, 0)。
scripts/check-windows-footguns.py 在 CI 中强制执行这一规则:任何新增的 os.kill(pid, 0) 调用都会导致 Windows footguns (blocking) 检查失败,除非该行带有 # windows-footgun: ok — <reason> 标记。
常见问题
安装后立即出现 hermes: command not found。
请打开一个新的 PowerShell 窗口。安装程序已将 %LOCALAPPDATA%\kopi\bin 添加到用户 PATH,但已有 shell 需要重启才能生效。在此之前,你可以运行 & "$env:LOCALAPPDATA\hermes\bin\kopi-agent.cmd"。
运行工具时出现 WinError 193: %1 is not a valid Win32 application。
你遇到的是一次绕过了 .cmd shim 的 shebang 脚本调用。Kopi Agent 通过 shutil.which(cmd, path=local_bin) 解析命令,从而让 PATHEXT 能够识别 .CMD——如果你是通过硬编码路径调用该工具,请改用 .cmd 形式(例如 npx.cmd,而非 npx)。
[scriptblock]::Create(...) 失败并报 The assignment expression is not valid。
你下载的 install.ps1 带有 UTF-8 BOM。irm | iex 形式会自动去除 BOM;[scriptblock]::Create((irm ...)) 则不会。请使用简单的 irm | iex 形式重新运行,或者手动下载脚本并通过 [IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false)) 保存为不含 BOM 的文件。
重启后 Gateway 无法保持运行。
请检查 kopi gateway status——它会合并 schtasks 条目、启动文件夹快捷方式(如果使用了的话)以及当前运行的 PID。如果 schtasks 已注册但未运行,可能是组策略阻止了 ONLOGON 触发器。运行 schtasks /Query /TN HermesGateway /V /FO LIST 查看任务失败原因,或者卸载后使用 KOPI_GATEWAY_FORCE_STARTUP=1 重新安装,以回退到启动文件夹方案。
设置 $env:EDITOR 后 /edit 仍然没有任何效果。
你只是在当前进程中设置了它;请关闭并重新打开 shell,或者在"系统属性 → 环境变量"中以用户作用域设置。可在新的 PowerShell 窗口中用 echo $env:EDITOR 验证。
浏览器工具能启动,但工具调用超时。
Chromium 会在首次运行时自动安装。如果安装失败(GitHub 限流、Playwright CDN 抖动),请运行 kopi doctor——它会提示缺失的 Chromium,并打印出用于修复的确切 npx playwright install chromium 命令。
agent-browser 失败,并出现奇怪的 Node 版本错误。
安装程序会将 Node 22 部署到 %LOCALAPPDATA%\kopi\node,但你的 PATH 中可能把较旧的系统 Node 18 排在前面。要么把 Kopi Agent 的 node 目录在 PATH 中前移,要么如果你在别处不使用 Node,就删除系统安装的版本。
中文 / 日文 / 阿拉伯文字符在 CLI 中显示为 ?。
UTF-8 stdio shim 没有激活。请确认 KOPI_DISABLE_WINDOWS_UTF8 未被设置(Get-ChildItem env:KOPI_DISABLE_WINDOWS_UTF8)。如果它为空而你仍看到 ?,则可能是控制台宿主(非常旧的 cmd.exe)完全不支持 UTF-8——请改用 Windows Terminal。
Gateway 无法发送 Telegram 图片——"BadRequest: payload contains invalid characters"。
这与 Windows 无关,但有时会最先在 Windows 上暴露出来。通常这意味着你的文件路径在 JSON 正文中包含未转义的反斜杠。Telegram 应该收到的是 Kopi Agent 归一化后的路径,而不是原始 Windows 路径——如果你在自定义插件中遇到此问题,请确保传入的是 Kopi Agent 提供的路径,而不是来自用户输入的 str(Path(...))。
git pull 之后出现"在我的另一台机器上是好的"这类编码怪异问题。
如果你在 Windows 上使用非 UTF-8 编辑器(旧版 Windows 的记事本、某些中文输入法)编辑过 Kopi Agent 配置或某个 skill,文件可能已带有 BOM 保存。Kopi Agent 在大多数配置读取中能容忍 utf-8-sig,但折叠 YAML 标量(description: >)内部的 BOM 会在不知不觉中破坏 YAML 解析。请将文件重新保存为不含 BOM 的纯 UTF-8 格式。
下一步阅读
- 安装 ——完整的安装页面,涵盖 Linux/macOS/WSL2/Termux。
- Windows (WSL2) 指南 ——如果你需要 POSIX 语义或仪表盘的终端面板。
- CLI 参考 ——所有
kopi子命令。 - FAQ ——常见的非 Windows 特有问题。
- 消息网关 ——在 Windows 上运行 Telegram/Discord/Slack。