KOPI AI AGENT —— Docker
Docker 与 KOPI AI AGENT 的交集有两种不同方式:
- 在 Docker 中运行 Kopi Agent —— agent(智能体)本身运行在容器内(本页的主要内容)
- Docker 作为终端后端 —— agent 运行在你的主机上,但每条命令都在单个持久的 Docker 沙箱容器中执行,该容器在 Kopi Agent 进程的整个生命周期内跨工具调用、
/new和 subagent(子智能体)持续存在(参见配置 → Docker 后端)
本页介绍选项 1。容器将所有用户数据(config、API 密钥、会话、skill(技能)、记忆)存储在从主机挂载到 /opt/data 的单个目录中。镜像本身是无状态的,可以通过拉取新版本来升级,而不会丢失任何配置。
快速开始
如果这是你第一次运行 KOPI AI AGENT,请在主机上创建一个数据目录,并以交互方式启动容器来运行安装向导:
某些 VPS provider(Hetzner Cloud 及其他几家)提供基于浏览器的
主机管理控制台。这些控制台传输特殊字符时会出错——
: 可能变成 ;,@ 可能被错误渲染,非英文
键盘布局的情况更糟——这会悄无声息地破坏 docker run 参数
以及 -v ~/.kopi:/opt/data、-e KEY=value,还有粘贴的 API 密钥 / token。
请改为通过 SSH 连接(ssh root@<host>),以获得可安全复制粘贴的命令
输入方式。如果你必须使用浏览器控制台,请手动输入命令而
不要粘贴,并在按下 Enter 前仔细检查结果中的每一个 :、@、= 和 /。
mkdir -p ~/.kopi
docker run -it --rm \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent setup
这会带你进入安装向导,它会提示你输入 API 密钥并将其写入 ~/.kopi/.env。你只需要执行一次。强烈建议此时为 gateway(网关)配置一个可使用的聊天系统。
在容器内运行一次 kopi setup --portal——refresh token 会保存在挂载的 ~/.kopi 卷中。参见 KOPI Proxy。
以 gateway 模式运行
配置完成后,将容器作为持久 gateway(Telegram、Discord、Slack、WhatsApp 等)在后台运行:
docker run -d \
--name kopi \
--restart unless-stopped \
-v ~/.kopi:/opt/data \
-p 8642:8642 \
nousresearch/kopi-ai-agent gateway run
端口 8642 暴露 gateway 的 OpenAI 兼容 API 服务器和健康检查端点。如果你只使用聊天平台(Telegram、Discord 等),它是可选的;但如果你希望 dashboard(仪表板)或外部工具能访问 gateway,则必须设置。
在官方 Docker 镜像中,gateway run 由 s6-overlay 自动监督:如果 gateway 进程崩溃,它会在几秒内重启而不会丢失容器;dashboard(当设置了 KOPI_DASHBOARD=1 时)也会随之一同受到监督。gateway run CMD 进程本身是一个 sleep infinity 心跳进程,在 s6 管理实际 gateway 进程的同时保持容器存活——因此 docker stop 仍会干净地关闭所有内容,而 docker logs 则显示受监督的 gateway 的输出。
你会在 docker logs 中看到一行确认升级的日志提示。如果要退出此行为——并恢复历史上“gateway 是容器的主进程,容器退出 = gateway 退出”的语义——请传入 --no-supervise 或设置 KOPI_GATEWAY_NO_SUPERVISE=1。该退出选项适用于希望容器以 gateway 的状态码退出的 CI 冒烟测试;对于生产部署,受监督的默认行为严格更优。
此行为仅适用于基于 s6 的镜像。较早的(基于 tini 的)镜像仍然将 gateway run 作为前台主进程运行。
有关完整的路由映射(各 profile 的 gateway、dashboard、启动协调器、容器级 docker logs),请参阅下文的日志去向一节。
tool_loop_guardrails.hard_stop_enabled 设置默认为 false,这对于有人能看到重复工具调用警告的交互式 CLI 和 TUI 会话来说是合理的。在无人值守的 gateway 或服务器部署中,仅靠警告可能无法阻止陷入重复工具调用循环的 agent。希望获得熔断行为的运维人员应在 profile 的 config.yaml 中显式启用硬性中断:
tool_loop_guardrails:
hard_stop_enabled: true
hard_stop_after:
exact_failure: 5
idempotent_no_progress: 5
注意:API 服务器受 API_SERVER_ENABLED=true 限制。要将其暴露到容器内 127.0.0.1 之外,还需要设置 API_SERVER_HOST=0.0.0.0 和一个 API_SERVER_KEY(至少 8 个字符——可用 openssl rand -hex 32 生成)。示例:
docker run -d \
--name kopi \
--restart unless-stopped \
-v ~/.kopi:/opt/data \
-p 8642:8642 \
-e API_SERVER_ENABLED=true \
-e API_SERVER_HOST=0.0.0.0 \
-e API_SERVER_KEY="$(openssl rand -hex 32)" \
-e API_SERVER_CORS_ORIGINS='*' \
nousresearch/kopi-ai-agent gateway run
在面向互联网的机器上开放任何端点都存在安全风险。除非你了解相关风险,否则不应这样做。
运行仪表板
内置 Web 仪表板以受 s6-rc 监管(supervised)的服务形式运行,与网关位于同一容器中。设置 KOPI_DASHBOARD=1 即可将其启动:
docker run -d \
--name kopi \
--restart unless-stopped \
-v ~/.kopi:/opt/data \
-p 8642:8642 \
-p 9119:9119 \
-e KOPI_DASHBOARD=1 \
nousresearch/kopi-ai-agent gateway run
仪表板由 s6 监管——如果它崩溃,s6-supervise 会在短暂的退避(backoff)后自动重启它。仪表板的 stdout/stderr 会被转发到 docker logs <container>(无前缀;网关自身的输出现在写入按 profile 划分的 s6-log 文件——参见下文的日志输出位置——因此两个输出流不会互相冲突)。
| 环境变量 | 说明 | 默认值 |
|---|---|---|
KOPI_DASHBOARD | 设为 1(或 true / yes)即可启用受监管的仪表板服务 | (未设置——服务已注册但保持停止状态) |
KOPI_DASHBOARD_HOST | 仪表板 HTTP 服务器的绑定地址 | 0.0.0.0 |
KOPI_DASHBOARD_PORT | 仪表板 HTTP 服务器的端口 | 9119 |
KOPI_DASHBOARD_INSECURE | **已弃用 / 无效(no-op)。**此前用于绕过认证闸门;自 2026 年 6 月的安全加固起,它不再禁用身份验证。非回环绑定始终需要一个 auth provider(身份验证服务提供商) | (忽略——请改为配置 provider) |
容器内的仪表板默认绑定到 0.0.0.0——若非如此,所发布的 -p 9119:9119 端口将无法从宿主机访问。若要将绑定限制为容器回环地址(用于 sidecar / 反向代理场景),请设置 KOPI_DASHBOARD_HOST=127.0.0.1。
当下列两个条件同时满足时,仪表板的认证闸门会自动启用:
- 绑定主机为非回环地址(例如容器内的默认值
0.0.0.0),并且 - 已注册
DashboardAuthProvider插件。
有三种内置方式可以满足第二个条件:
- 用户名/密码——对于位于受信任网络或 VPN 之后的自托管 / 本地部署 / 家庭实验室容器来说,这是最简单的方式:设置
KOPI_DASHBOARD_BASIC_AUTH_USERNAME+KOPI_DASHBOARD_BASIC_AUTH_PASSWORD(以及KOPI_DASHBOARD_BASIC_AUTH_SECRET以获得重启后仍稳定的会话)。不适用于直接暴露到公共互联网的场景。 - OAuth(KOPI Proxy)——适用于托管 / 公开部署:只要设置了
KOPI_DASHBOARD_OAUTH_CLIENT_ID,dashboard_auth/nousprovider 就会激活。 - 自托管 OIDC——通过标准 OpenID Connect 对接你自己的身份提供商(identity provider):当设置了
KOPI_DASHBOARD_OIDC_ISSUER+KOPI_DASHBOARD_OIDC_CLIENT_ID时,dashboard_auth/self_hostedprovider 会被激活。
无论你选择哪一种,闸门都会在调用方访问任何受保护路由之前将其重定向到登录页面。有关全部三个 provider 的说明,请参阅 Web 仪表板 → 身份验证。
如果未注册任何 provider 且绑定为非回环地址,仪表板会在启动时失败关闭(fail closed),并给出指向缺失环境变量的明确错误。已不再存在任何可以在公开绑定上以未认证方式提供仪表板的后门:KOPI_DASHBOARD_INSECURE=1 现在是一个已弃用的无效设置(会记录一条警告并被忽略)。请配置一个 provider,或者绑定 KOPI_DASHBOARD_HOST=127.0.0.1,改用 SSH 隧道 / Tailscale 访问仪表板。
--insecure未认证的公开仪表板是 2026 年 6 月 MCP 配置持久化攻击活动的入口:互联网扫描器找到了暴露的仪表板(以及 OpenAI API 服务器),并诱导 agent 植入 SSH 密钥后门。现在,任何非回环绑定都必须启用认证闸门。对于受信任局域网 / 家庭实验室的机器,内置的用户名/密码 provider(KOPI_DASHBOARD_BASIC_AUTH_USERNAME + _PASSWORD)是零额外基础设施的满足方式。
当该容器与宿主机共享 PID 和网络命名空间时(例如 network_mode: host,本仓库自身的 docker-compose.yml 就是这么做的——参见其中的 dashboard 服务),将仪表板作为独立容器运行是受支持的。其网关存活性检测要求与网关进程共享 PID 命名空间,因此该限制仅适用于运行在隔离的 bridge 网络容器中、且未共享 PID 命名空间的仪表板。
交互式运行(CLI 聊天)
要针对一个正在运行的数据目录开启交互式聊天会话:
docker run -it --rm \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent
或者,如果你已经在运行中的容器里打开了一个终端(例如通过 Docker Desktop),直接运行:
/opt/kopi/.venv/bin/kopi
持久化卷
/opt/data 卷是所有 Kopi Agent 状态的唯一真实来源(single source of truth)。它映射到宿主机的 ~/.kopi/ 目录,包含:
| 路径 | 内容 |
|---|---|
.env | API keys 和 secrets |
config.yaml | 所有 Kopi Agent 配置 |
SOUL.md | Agent 个性/身份 |
sessions/ | 会话历史 |
memories/ | 持久化记忆存储 |
skills/ | 已安装的 skills |
home/ | Kopi Agent 工具子进程的每配置文件 HOME(git、ssh、gh、npm 以及各 skill CLI) |
cron/ | 定时任务定义 |
hooks/ | 事件钩子 |
logs/ | 运行时日志 |
skins/ | 自定义 CLI 主题 |
不可变的安装目录树
在托管和发布的 Docker 镜像中,/opt/kopi 是已安装的应用目录树。它由 root 所有,对运行时 kopi 用户只读,因此 agent 的轮次、gateway 会话、仪表板操作以及常规 docker exec kopi kopi ... 命令都无法就地修改核心源码、内置的 .venv、node_modules 或 TUI bundle。
所有可变的 Kopi Agent 状态都位于 /opt/data 之下:config、.env、profiles、skills、memories、sessions、logs、仪表板上传文件、plugins 以及其他用户管理的文件。该镜像还禁用了运行时 .pyc 写入以及 Kopi Agent 向 /opt/kopi 的懒加载依赖安装;发布镜像所需的可选平台依赖应当固化到镜像中,或通过重新构建镜像来安装。
在托管/发布的镜像上,agent 的自我改进范围仅限于 /opt/data 下的 skills、memory、plugins 和 config。/opt/kopi 下已安装的核心源码是不可变的;核心变更需要通过对仓库提交 PR 并更新镜像来发布,而不是直接在运行中的安装上编辑。
如果运维人员需要修复或检查 /opt/data 之外的文件,请有意使用 root shell。kopi shim 通常会将 docker exec kopi kopi ... 降权回运行时用户;当你明确需要 root 权限时,可设置 KOPI_DOCKER_EXEC_AS_ROOT=1 进行一次性的 root 调用。
将凭据存储在 ~ 下的 skill CLI 必须针对子进程 HOME 进行初始化,而不仅仅是数据卷的根目录。例如,xurl skill 将 OAuth 状态存储在 ~/.xurl 中;在官方 Docker 布局下,Kopi Agent 的工具调用会将其读取为 /opt/data/home/.xurl,因此请使用 HOME=/opt/data/home 手动运行 xurl 认证,并用 HOME=/opt/data/home xurl auth status 验证。
切勿让两个 Kopi Agent gateway 容器同时指向同一个数据目录运行 —— 会话文件和记忆存储并非为并发写入访问而设计。
多 profile 支持
Kopi Agent 支持多 profile —— 即相互独立的 ~/.kopi/ 子目录,让你能在单个安装中运行彼此独立的 agent(不同的 SOUL、skill、memory、session、凭据)。在官方 Docker 镜像中,s6 监督树将每个 profile 视为一等的受监督服务,因此推荐的部署方式是用一个容器承载所有 profile。
通过 kopi profile create <name> 创建的每个 profile 都会获得:
- 一个专属的 s6 服务槽位(位于
/run/service/gateway-<name>/),由运行时动态注册 —— 无需重建容器。 - 崩溃后自动重启,退避策略由
s6-supervise管理。 - 每个 profile 的轮转日志位于
${KOPI_HOME}/logs/gateways/<name>/current(10 个归档 × 各 1 MB)。 - 容器重启后的状态持久化:启动时的协调器会读取每个 profile 目录中的
gateway_state.json,并且仅为最后记录状态为running的 profile 重新拉起槽位。只有你显式停止过的网关(kopi gateway stop)才会在重启后保持停止状态 —— 容器重启、镜像升级或意外退出都会将记录的状态保留为running,因此网关会在下次启动时自动运行。
你在宿主机上运行的那些生命周期命令,在容器内部的用法完全相同:
# Create a profile — registers the gateway-<name> s6 slot.
docker exec kopi kopi profile create coder
# Start / stop / restart — dispatches s6-svc; the gateway lifecycle survives docker restart.
docker exec kopi kopi -p coder gateway start
docker exec kopi kopi -p coder gateway stop
docker exec kopi kopi -p coder gateway restart
# Status — reports `Manager: s6 (container supervisor)` inside the container.
docker exec kopi kopi -p coder gateway status
# Remove a profile — tears down the s6 slot too.
docker exec kopi kopi profile delete coder
其底层机制是,容器内的 kopi gateway start/stop/restart 会被拦截并路由到针对相应服务目录执行的 s6-svc;你无需直接学习 s6 命令。若要查看原始 supervisor 状态,请使用 /command/s6-svstat /run/service/gateway-<name>(注意 /command/ 只对由监督树派生的进程在 PATH 中可用 —— 从 docker exec 调用时,请传入绝对路径)。
从容器外部访问多个 profile
有两种不同的途径可以从外部访问某个 profile 的网关,且它们的行为不同 —— 不要混淆:
Kopi Agent Desktop(以及 web 仪表盘)。 Desktop 应用的 Remote Gateway 连接使用的是 kopi dashboard 后端(默认端口 9119,由 KOPI_DASHBOARD=1 启用)—— 而不是 OpenAI API server。一个仪表盘后端会服务所有同处一地的 profile:应用中的 profile 切换器会在每个请求中发送目标 profile,后端会打开磁盘上该 profile 的 KOPI_HOME。因此,对于 Desktop,你不需要为每个 profile 准备第二个端口 —— 或第二个连接;一个 :9119 连接即可通过切换器覆盖所有 profile。
OpenAI 兼容的 API 客户端(Open WebUI、LobeChat、/v1/...)。 这些客户端访问的是各 profile 的 API server,它为每个 profile 绑定端口 8642(从 API_SERVER_PORT / platforms.api_server.extra.port 解析得到 —— 没有自动分配,也没有 config.yaml/gateway.port 键)。如果你希望某个客户端访问特定的第二个 profile,请在该 profile 自己的 .env 中为其设置一个不同的 API_SERVER_PORT,否则它的网关也会尝试绑定 8642,从而与默认 profile 冲突:
# Create the profile (registers its gateway-<name> s6 slot)
docker exec kopi kopi profile create work
# Point its API server at a free port (write to the profile's own .env)
cat >> /opt/data/profiles/work/.env <<'EOF'
API_SERVER_ENABLED=true
API_SERVER_PORT=8643
EOF
docker exec kopi kopi -p work gateway restart
请把 API_SERVER_PORT 放在每个 profile 自己的 .env 中,绝不要放在容器级别的 environment: 块中 —— 全局值会迫使每个 profile 使用同一个端口,从而发生冲突。使用 bridge 网络时,在 docker-compose.yml 中发布额外端口(- "8643:8643");使用 network_mode: host 时,该端口在宿主机上已经可访问。默认 profile 的 8642 连接不受影响。
为什么要一个容器承载多个 profile,而不是多个容器
在迁移到 s6 之前,"每个 profile 一个容器"是推荐模式,因为当时容器内没有 supervisor 来管理多个网关。有了 s6 作为 PID 1 后,这已不再必要,而且单容器布局几乎在所有维度上都更简单:
| 一个容器,多个 profile | 每个 profile 一个容器 | |
|---|---|---|
| 磁盘开销 | 一个镜像、一个内置 venv、一个 Playwright 缓存 | N 个镜像 / N 个缓存 |
| 内存开销 | 共享的 Python 解释器缓存、共享的 node_modules | 每个容器各一份 |
| Profile 创建 | docker exec ... kopi profile create <name>(数秒) | 新的 docker run 调用 + 端口分配 + bind-mount 配置 |
| 单 profile 崩溃恢复 | s6-supervise 自动重启 | Docker 的 --restart unless-stopped(更慢,且会终止同级工作负载) |
| 日志 | 通过 s6-log 实现的每 profile 轮转文件,外加容器启动审计日志 | 每个容器的 docker logs <name> —— 没有内置轮转 |
| 备份 | 一个 ~/.kopi 目录 | 需要协调的 N 个目录 |
默认 profile(default)总是在首次启动时注册,因此全新的容器开箱即带一个受监督的网关。额外的 profile 纯粹是运行时添加。
何时确实需要独立的容器
"容器内多 profile"是默认做法。只有在有明确理由时,才为每个 profile 运行单独的容器:
- 按工作负载隔离资源 —— 例如,profile A 中失控的浏览器工具会话不应导致 profile B 发生 OOM。容器可为每个 profile 提供
--memory/--cpus。 - 独立的镜像版本固定 —— 不同工作负载使用不同的上游镜像 tag。
- 网络分段 —— 每个 profile 使用不同的 Docker 网络(例如一个面向客户、一个内部使用)。
- 合规 / 爆炸半径 —— 不同的凭据绝不在同一个 OS 级进程树中共享。
在这些情况下,为每个 profile 声明一个服务,并使用不同的 container_name、volumes 和 ports:
services:
kopi-work:
image: nousresearch/kopi-ai-agent:latest
container_name: kopi-work
restart: unless-stopped
command: gateway run
ports:
- "8642:8642"
volumes:
- ~/.kopi-work:/opt/data
kopi-personal:
image: nousresearch/kopi-ai-agent:latest
container_name: kopi-personal
restart: unless-stopped
command: gateway run
ports:
- "8643:8642"
volumes:
- ~/.kopi-personal:/opt/data
持久化卷中的警告依然适用:绝不要让两个容器同时指向同一个 ~/.kopi 目录。每个容器内的 s6 supervisor 管理各自的 profile 集合;跨容器共享数据卷会损坏 session 文件和 memory 存储。
日志输出位置
s6 容器有四个不同的日志输出面,"为什么我的 gateway 在 docker logs 里什么都没有显示" 是一个常见的困惑。速查表:
| 来源 | 输出位置 | 如何读取 |
|---|---|---|
每个 profile 的 gateway(kopi gateway run 以及 s6 下的各 profile gateway) | 同时输出到两个位置:docker logs <container>(实时,无额外前缀)和 ${KOPI_HOME}/logs/gateways/<profile>/current(带轮转,ISO-8601 时间戳,10 个存档 × 每个 1 MB) | 在宿主机上执行 docker logs -f hermes 或 tail -F ~/.kopi/logs/gateways/default/current |
Dashboard(当 KOPI_DASHBOARD=1 时) | docker logs <container>(无前缀) | docker logs -f hermes — 与 gateway 的日志行交错混排 |
| 启动协调器(记录每次容器启动时恢复了哪些 profile gateway) | ${KOPI_HOME}/logs/container-boot.log(仅追加的审计日志) | tail -F ~/.kopi/logs/container-boot.log |
通用 Kopi Agent 日志(agent.log、errors.log) | ${KOPI_HOME}/logs/(可识别 profile) | docker exec kopi kopi logs --follow [--level WARNING] [--session <id>] |
有两个值得了解的实际影响:
logs/gateways/<profile>/current处的文件副本是在容器重启后仍然保留下来的内容。docker logs只保留当前容器生命周期内的输出(并在docker rm时被清除);而轮转后的文件会持久保存在绑定挂载的 volume 上。- 启动协调器的审计行格式是
<iso-timestamp> profile=<name> prior_state=<state> action=<registered|started>,因此通过一次简单的grep profile=coder ~/.kopi/logs/container-boot.log就能查到某个 profile 最近一次恢复的时间,以及 s6 是否自动启动了它。
环境变量转发
API 密钥从容器内的 /opt/data/.env 读取。你也可以直接传递环境变量:
docker run -it --rm \
-v ~/.kopi:/opt/data \
-e ANTHROPIC_API_KEY="sk-ant-..." \
-e OPENAI_API_KEY="sk-..." \
nousresearch/kopi-ai-agent
直接的 -e 标志会覆盖 .env 中的值。这在 CI/CD 或 secrets manager 集成中很有用,可以避免密钥写入磁盘。
本页介绍的是将 Kopi Agent 本身运行在 Docker 中。如果你希望 Kopi Agent 在 Docker 沙箱容器内执行 agent 的 terminal / execute_code 调用(一个由多个 Kopi Agent 进程共享的长生命周期容器——参见 issue #20561),那属于另一套配置项 —— terminal.backend: docker 加上 terminal.docker_image、terminal.docker_volumes、terminal.docker_forward_env、terminal.docker_env、terminal.docker_run_as_host_user、terminal.docker_extra_args、terminal.docker_persist_across_processes 和 terminal.docker_orphan_reaper。完整的配置项(包括容器生命周期规则)请参见 Configuration → Docker Backend。
Docker Compose 示例
对于同时包含 gateway 和 dashboard 的持久化部署,使用 docker-compose.yaml 会很方便:
services:
hermes:
image: nousresearch/kopi-ai-agent:latest
container_name: kopi-agent
restart: unless-stopped
command: gateway run
ports:
- "8642:8642" # gateway API
- "9119:9119" # dashboard (only reached when KOPI_DASHBOARD=1)
volumes:
- ~/.kopi:/opt/data
environment:
- KOPI_DASHBOARD=1
# Uncomment to forward specific env vars instead of using .env file:
# - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
# - OPENAI_API_KEY=${OPENAI_API_KEY}
# - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
deploy:
resources:
limits:
memory: 4G
cpus: "2.0"
使用 docker compose up -d 启动,并通过 docker compose logs -f 查看日志。受监管的 gateway 的 stdout 也会同时输出到 volume 上的 ${KOPI_HOME}/logs/gateways/<profile>/current —— 完整的路由映射请参见 日志输出位置。
可选:Linux 桌面音频桥接
Docker 中的语音模式需要满足两个独立条件才能工作:必须允许 Kopi Agent 在容器内探测音频设备,并且容器必须能够访问你的宿主机音频服务器。下面的设置涵盖了为暴露 PulseAudio 兼容套接字的 Linux 桌面配置宿主机音频管道,包括许多 PipeWire 的配置场景。
这是一个 Linux 桌面的变通方案,不是通用的 Docker Desktop 功能。当你已经在宿主机上正常启用了音频,并希望在 Kopi Agent 容器内使用 CLI 语音模式时,它会很有用。如果 Kopi Agent 仍然报告 Running inside Docker container -- no audio devices,请使用包含 Docker 音频探测支持的构建版本,以支持 PULSE_SERVER / PIPEWIRE_REMOTE。
首先,在你的 Compose 文件旁边创建一个 ALSA 配置:
pcm.!default {
type pulse
hint {
show on
description "Default ALSA Output (PulseAudio)"
}
}
pcm.pulse {
type pulse
}
ctl.!default {
type pulse
}
然后构建一个安装了 ALSA PulseAudio 插件的小型派生镜像:
FROM nousresearch/kopi-ai-agent:latest
USER root
RUN apt-get update \
&& apt-get install -y --no-install-recommends libasound2-plugins \
&& rm -rf /var/lib/apt/lists/*
在 Compose 中使用该镜像,并传入宿主机用户的 PulseAudio 套接字和 cookie:
services:
hermes:
build:
context: .
dockerfile: Dockerfile.audio
image: kopi-ai-agent-audio
container_name: kopi-agent
restart: unless-stopped
command: gateway run
volumes:
- ~/.kopi:/opt/data
- /run/user/${KOPI_UID}/pulse:/run/user/${KOPI_UID}/pulse
- ~/.config/pulse/cookie:/tmp/pulse-cookie:ro
- ./asound.conf:/etc/asound.conf:ro
environment:
- KOPI_UID=${KOPI_UID}
- KOPI_GID=${KOPI_GID}
- XDG_RUNTIME_DIR=/run/user/${KOPI_UID}
- PULSE_SERVER=unix:/run/user/${KOPI_UID}/pulse/native
- PULSE_COOKIE=/tmp/pulse-cookie
以你的宿主机 UID/GID 启动它,以便容器进程能够访问按用户区分的音频套接字:
export KOPI_UID="$(id -u)"
export KOPI_GID="$(id -g)"
docker compose up -d --build
要验证 PortAudio 在容器内识别到的内容:
docker exec kopi /opt/kopi/.venv/bin/python -c "import sounddevice as sd; print(sd.query_devices())"
资源限制
Kopi Agent 容器需要中等规模的资源。推荐的最低配置:
| 资源 | 最低 | 推荐 |
|---|---|---|
| 内存 | 1 GB | 2–4 GB |
| CPU | 1 核 | 2 核 |
| 磁盘(数据 volume) | 500 MB | 2+ GB(随会话/skill 增长) |
浏览器自动化(Playwright/Chromium)是内存消耗最大的功能。如果你不需要浏览器工具,1 GB 就足够了。启用浏览器工具时,至少分配 2 GB。
在 Docker 中设置限制:
docker run -d \
--name kopi \
--restart unless-stopped \
--memory=4g --cpus=2 \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent gateway run
Dockerfile 的作用
官方镜像基于 debian:13.4,并包含:
- Python 3.13,依赖通过
uv sync --frozen --no-install-project从 lockfile 同步,用于内置的 extras(all、messaging、Anthropic/Bedrock/Azure identity、Hindsight、Matrix),随后以无依赖的 editable install 方式安装 Kopi Agent 本体。 - Node.js 22 + npm(用于浏览器自动化、WhatsApp 桥接、TUI/Desktop 打包,以及 workspace 构建工具)
- 带 Chromium 的 Playwright(
npx playwright install --with-deps chromium --only-shell) - ripgrep、ffmpeg、git 和
xz-utils等系统工具 docker-cli—— 使容器内运行的 agent 能够驱动宿主机的 Docker daemon(绑定挂载/var/run/docker.sock即可启用),用于docker build、docker run、容器检查等操作。openssh-client—— 在容器内部启用 SSH terminal backend。SSH backend 会调用系统ssh二进制文件;没有它,在容器化安装中会静默失败。- WhatsApp 桥接(
scripts/whatsapp-bridge/) s6-overlayv3 作为 PID 1(取代旧的tini)—— 监督 dashboard 和各个 profile 的 gateway,崩溃时自动重启,回收僵尸子进程,并转发信号。
该镜像在运行时将 /opt/kopi 视为不可变的安装树。需要在 Docker 内部可用的可选 Python extras、Node workspaces 和 TUI 资源必须在镜像构建阶段内置;运行时的懒加载安装被禁用,以避免受监督的 gateway 和 docker exec kopi … 命令将依赖产物写回只读的源码树。
容器的 ENTRYPOINT 是 s6-overlay 的 /init。启动时它会:
- 以 root 身份运行
/etc/cont-init.d/01-kopi-setup(即docker/stage2-hook.sh):执行可选的 UID/GID 重映射、修复卷的所有权、在首次启动时初始化.env/config.yaml/SOUL.md、除非设置了KOPI_SKIP_CONFIG_MIGRATION=1否则执行非交互式 config-schema 迁移、同步内置 skills。 - 运行
/etc/cont-init.d/02-reconcile-profiles(即kopi_cli.container_boot):遍历$KOPI_HOME/profiles/<name>/,在/run/service/gateway-<profile>/下重建每个 profile 的 gateway s6 service slot,并仅自动启动那些最后记录状态为running的服务(参见按 profile 的 gateway 监督)。 - 启动静态的
main-kopi和dashboards6-rc 服务。 - 将容器的 CMD 作为主程序执行(
/opt/kopi/docker/main-wrapper.sh),由它将用户传入docker run的参数路由到:- 无参数 →
kopi(默认) - 第一个参数是 PATH 中的可执行文件(例如
sleep、bash)→ 直接执行它 - 其他情况 →
KOPI_SKIP_CONFIG_MIGRATION=1(子命令透传)→kopi <args>(子命令透传) 当该主程序退出时容器随之退出,并返回其退出码。
- 无参数 →
容器 ENTRYPOINT 现在是 /init(s6-overlay),而不是 /usr/bin/tini。文档中记录的全部五种 docker run 调用方式(无参数、chat -q "…"、sleep infinity、bash、--tui)的行为与基于 tini 的镜像完全一致。如果你的下游封装依赖 tini 特有的信号行为,或硬编码了 /usr/bin/tini -- 调用,请固定使用之前的镜像 tag。
除非你在命令链中保留 /init(或者等价地,转发到 stage2 hook 的旧版 docker/entrypoint.sh shim),否则请不要覆盖镜像的 entrypoint。s6-overlay 的 /init 以 root 运行,以便在首次启动时 chown 卷,随后通过 s6-setuidgid 降权到 kopi 用户,对每个受监督的服务以及主程序都如此。在官方镜像中以 root 启动 kopi gateway run 默认会被拒绝,因为它可能在 /opt/data 中留下 root 所有的文件,导致后续 dashboard 或 gateway 启动失败。只有在你有意接受该风险时,才设置 KOPI_ALLOW_ROOT_GATEWAY=1。
docker exec 会自动降权到 kopi 用户
docker exec kopi <cmd> 默认在容器内以 root 身份运行,但镜像在 /opt/kopi/bin/kopi(PATH 中最靠前的位置)提供了一个轻量 shim,它会检测 root 调用者并通过 s6-setuidgid hermes 透明地重新执行。因此 docker exec kopi login、docker exec kopi profile create …、docker exec kopi setup 等命令写入的文件都归 UID 10000 所有——也就是说受监督的 gateway 可以读取——无需额外的 --user 标志。非 root 调用者(受监督的进程本身、docker exec --user hermes、容器内的 kanban 子 agent)会命中短路分支,直接执行 venv 中的二进制文件,因此在热路径上没有额外开销。
如果你确实需要一个保留 root 语义的 docker exec(诊断会话、查看仅 root 可访问的状态、/opt/data 之外恰好由 root 拥有的文件),可以按次调用选择退出:
docker exec -e KOPI_DOCKER_EXEC_AS_ROOT=1 kopi <cmd>
该 shim 接受 1 / true / yes(不区分大小写)。其他任何值——包括 =0 这类拼写错误——都会回退到降权,因此不存在静默退出的情况。如果 s6-setuidgid 不可用(裁剪掉 s6-overlay 的自定义构建),shim 会拒绝以 root 运行并以退出码 126 退出,从而显式暴露被破坏的权限模型,而不是倒退到历史上那个陷阱:docker exec kopi login 会以 root:root 身份写入 auth.json,并在每条聊天平台消息时破坏受监督 gateway 的认证。
按 profile 的 gateway 监督
用 kopi profile create <name> 创建的每个 profile 都会自动在 /run/service/gateway-<name>/ 注册一个受 s6 监督的 gateway 服务,并在容器重启时保持状态并自动重启。面向用户的流程和生命周期命令请参见上文的多 profile 支持。
相比 pre-s6 镜像的监督优势:
- gateway 崩溃后由
s6-supervise在约 1 秒的退避后自动重启。 - 当通过
KOPI_DASHBOARD=1启用 dashboard 时,它会在同一监督树上被监督,并获得同样的自动重启保障。 docker restart、镜像升级(docker compose up -d --force-recreate)以及意外退出都不会影响正在运行的 gateway:cont-init 协调器会读取$KOPI_HOME/profiles/<name>/gateway_state.json,如果最后记录的状态是running,就重新拉起该 slot。只有显式的kopi gateway stop才会记录stopped并在重启后保持 gateway 停止;重启或升级时发送的容器/s6 SIGTERM 会被视为"仍在运行"并自动启动。- 按 profile 的 gateway 日志持久化在
$KOPI_HOME/logs/gateways/<profile>/current下(由s6-log轮转),协调器的操作每次启动都会追加到$KOPI_HOME/logs/container-boot.log。完整的路由映射请参见日志去向。
容器内的 kopi status 会报告 Manager: s6 (container supervisor)。使用 /command/s6-svstat /run/service/gateway-<name> 可查看原始的 supervisor 视图(注意 /command/ 仅对监督树中的进程在 PATH 上可用;从 docker exec 调用时请传入绝对路径)。
升级
拉取最新镜像并重新创建容器。你的数据目录会被保留,容器会在启动 gateway 之前,对挂载的 $KOPI_HOME/config.yaml 执行非交互式的 config-schema 迁移。
当需要执行迁移时,Kopi Agent 会先在 config.yaml 和 .env 旁写入带时间戳的备份。
docker pull nousresearch/kopi-ai-agent:latest
docker rm -f kopi-agent
docker run -d \
--name kopi \
--restart unless-stopped \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent gateway run
或者使用 Docker Compose:
docker compose pull
docker compose up -d
仅当需要在新镜像重写持久化 config 之前手动检查或迁移它时,才设置 KOPI_SKIP_CONFIG_MIGRATION=1。
Skills 与凭据文件
当使用 Docker 作为执行环境时(不是上面的那些方法,而是指 agent 在 Docker sandbox 内部运行命令的情况——参见配置 → Docker Backend),Kopi Agent 会为所有工具调用复用同一个长期存在的容器,并自动将 skills 目录(~/.kopi/skills/)以及 skills 声明的任何凭据文件以只读 volume 的方式绑定挂载到该容器中。Skill 脚本、模板和引用在 sandbox 内部无需手动配置即可使用,并且由于容器的生命周期与 Kopi Agent 进程一致,你安装的任何依赖或写入的任何文件都会保留到下一次工具调用。
对于 SSH 和 Modal backend 也会执行同样的同步操作——skills 和凭据文件会在每条命令执行前通过 rsync 或 Modal mount API 上传。
在容器中安装更多工具
官方镜像附带了一组精选的实用工具(参见 Dockerfile 的作用),但 agent 可能需要的工具并非全部预装。下面推荐五种方法,按所需工作量和持久性递增排列。
npm 或 Python 工具 —— 使用 npx 或 uvx
对于任何发布到 npm 或 PyPI 的工具,指示 Kopi Agent 通过 npx(npm)或 uvx(Python)来运行它,并将该命令记录到其持久化记忆中。如果工具需要配置文件或凭据,指示它将这些内容放到 /opt/data 下(例如 /opt/data/<tool>/config.yaml)。
依赖按需获取并缓存,缓存有效期为容器的整个生命周期。写入 /opt/data 下的配置能在容器重启后继续存在,因为它位于绑定挂载的宿主目录中。包缓存本身会在 docker rm 后重建,但 npx 和 uvx 会在下次运行该工具时透明地重新获取。
其他工具(apt 包、二进制文件)—— 安装并记住
对于 npm 或 PyPI 之外的任何内容——apt 包、预编译二进制文件、镜像中尚未包含的语言运行时——指示 Kopi Agent 如何安装它(例如 apt-get update && apt-get install -y <package>),并让它记住安装命令。该工具会在容器剩余的生命周期内持续存在,并且当 Kopi Agent 在容器重启后下次需要该工具时,会重新运行安装命令。
这种方式适合安装速度快且偶尔使用的工具。对于频繁使用的工具,建议采用下一种方法。
持久化安装 —— 构建派生镜像
当某个工具必须在每次容器启动时立即可用、不能接受重新安装的延迟时,可以构建一个继承自 nousresearch/kopi-ai-agent 的新镜像,并在某个层中安装该工具:
FROM nousresearch/kopi-ai-agent:latest
USER root
RUN apt-get update \
&& apt-get install -y --no-install-recommends <your-package> \
&& rm -rf /var/lib/apt/lists/*
USER kopi-agent
构建它并用它替代官方镜像:
docker build -t my-hermes:latest .
docker run -d \
--name kopi \
--restart unless-stopped \
-v ~/.kopi:/opt/data \
-p 8642:8642 \
my-hermes:latest gateway run
entrypoint 脚本和 /opt/data 语义均原样继承,因此本页其余内容仍然适用。请记得在拉取更新的上游 nousresearch/kopi-ai-agent 后重新构建镜像。
复杂工具或多服务栈 —— 运行 sidecar 容器
对于自带服务的工具(数据库、Web 服务器、消息队列、无头浏览器集群),或者对于过于笨重而不适合放进 Kopi Agent 容器的工具,可以将它们作为单独的容器运行在共享的 Docker 网络上。Kopi Agent 通过容器名访问 sidecar,就像访问本地推理服务器一样(参见连接到本地推理服务器)。
services:
hermes:
image: nousresearch/kopi-ai-agent:latest
container_name: kopi-agent
restart: unless-stopped
command: gateway run
ports:
- "8642:8642"
volumes:
- ~/.kopi:/opt/data
networks:
- kopi-net
my-tool:
image: example/my-tool:latest
container_name: my-tool
restart: unless-stopped
networks:
- kopi-net
networks:
kopi-net:
driver: bridge
在 Kopi Agent 容器内部,可以通过 http://my-tool:<port>(或该服务提供的任何协议)访问 sidecar。这种模式使每个服务的生命周期、资源限制和升级节奏相互独立,并避免因仅为某个工具所需的依赖而使 Kopi Agent 镜像变得臃肿。
广泛有用的工具 —— 提交 issue 或 pull request
如果某个工具可能对大多数 KOPI AI AGENT 用户都有用,建议将其贡献到上游,而不是仅保留在私有的派生镜像中。请在 kopi-ai-agent 仓库 上提交 issue 或 pull request,描述该工具及其使用场景。被纳入官方镜像的工具能让所有用户受益,并避免维护下游 fork 的额外开销。
连接本地推理服务器(vLLM、Ollama 等)
当 Kopi Agent 在 Docker 中运行,而你的推理服务器(vLLM、Ollama、text-generation-inference 等)也运行在宿主机上或另一个容器中时,网络配置需要额外注意。
Docker Compose(推荐)
将两个服务放在同一个 Docker 网络中。这是最可靠的方式:
services:
vllm:
image: vllm/vllm-openai:latest
container_name: vllm
command: >
--model Qwen/Qwen2.5-7B-Instruct
--served-model-name my-model
--host 0.0.0.0
--port 8000
ports:
- "8000:8000"
networks:
- kopi-net
deploy:
resources:
reservations:
devices:
- capabilities: [gpu]
hermes:
image: nousresearch/kopi-ai-agent:latest
container_name: kopi-agent
restart: unless-stopped
command: gateway run
ports:
- "8642:8642"
volumes:
- ~/.kopi:/opt/data
networks:
- kopi-net
networks:
kopi-net:
driver: bridge
然后在你的 ~/.kopi/config.yaml 中,使用容器名称作为主机名:
model:
provider: custom
model: my-model
base_url: http://vllm:8000/v1
api_key: "none"
- 使用容器名称(
vllm)作为主机名——而不是localhost或127.0.0.1,它们指向 Kopi Agent 容器自身。 model的值必须与你传递给 vLLM 的--served-model-name一致。- 将
api_key设置为任意非空字符串(vLLM 需要该 header,但默认不对其进行验证)。 base_url中不要包含末尾的斜杠。
独立运行 Docker(不使用 Compose)
如果你的推理服务器直接运行在宿主机上(不在 Docker 中),在 macOS/Windows 上使用 host.docker.internal,在 Linux 上使用 --network host:
macOS / Windows:
docker run -d \
--name kopi \
-v ~/.kopi:/opt/data \
-p 8642:8642 \
nousresearch/kopi-ai-agent gateway run
# config.yaml
model:
provider: custom
model: my-model
base_url: http://host.docker.internal:8000/v1
api_key: "none"
Linux(host 网络模式):
docker run -d \
--name kopi \
--network host \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent gateway run
# config.yaml
model:
provider: custom
model: my-model
base_url: http://127.0.0.1:8000/v1
api_key: "none"
--network host 时,-p 标志会被忽略——所有容器端口都会直接暴露在宿主机上。验证连接
在 Kopi Agent 容器内部,确认推理服务器可达:
docker exec kopi curl -s http://vllm:8000/v1/models
你应该能看到一个列出你所服务模型的 JSON 响应。如果失败,请检查:
- 两个容器位于同一个 Docker 网络(
docker network inspect kopi-net) - 推理服务器正在
0.0.0.0上监听,而不是127.0.0.1 - 端口号是否一致
Ollama
Ollama 的使用方式相同。如果 Ollama 运行在宿主机上,使用 host.docker.internal:11434(macOS/Windows)或 127.0.0.1:11434(Linux 上配合 --network host)。如果 Ollama 运行在同一 Docker 网络上的独立容器中:
model:
provider: custom
model: llama3
base_url: http://ollama:11434/v1
api_key: "none"
故障排查
容器立即退出
查看日志:docker logs hermes。常见原因:
.env文件缺失或无效——请先以交互方式运行以完成初始设置- 如果以暴露端口的方式运行,可能存在端口冲突
"Permission denied" 错误
容器的 stage2 hook 会通过每个受监管服务内部的 s6-setuidgid,将权限降级到非 root 的 kopi 用户(UID 10000)。如果你的宿主机 ~/.kopi/ 由不同的 UID 拥有,请将 KOPI_UID/KOPI_GID(或其 PUID/PGID 别名,以兼容 LinuxServer.io 和 NAS 镜像)设置为与你的宿主机用户匹配,或者确保数据目录可写:
chmod -R 755 ~/.kopi
在 NAS(UGOS、Synology、unRAID)上,数据目录通常是绑定挂载(bind mount),由一个容器无法 chown 的宿主机 UID 拥有。将 PUID/PGID(或 KOPI_UID/KOPI_GID)设置为该宿主机用户,这样运行时就会以挂载点的所有者身份运行,而不是 UID 10000:
docker run -d \
--name kopi \
-e PUID=1000 -e PGID=10 \
-v /volume1/docker/kopi:/opt/data \
nousresearch/kopi-ai-agent gateway run
docker exec kopi <cmd> 同样会自动降权到 UID 10000——详情及按次调用的退出方式请参阅docker exec 会自动降权到 kopi 用户。
浏览器工具无法工作
Playwright 需要共享内存。请在你的 Docker run 命令中添加 --shm-size=1g:
docker run -d \
--name kopi \
--shm-size=1g \
-v ~/.kopi:/opt/data \
nousresearch/kopi-ai-agent gateway run
网络问题后 Gateway 无法重新连接
--restart unless-stopped 标志可处理大多数瞬时故障。如果 Gateway 卡住,请重启容器:
docker restart kopi
检查容器健康状态
docker logs --tail 50 kopi # Recent logs
docker run -it --rm nousresearch/kopi-ai-agent:latest version # Verify version
docker stats kopi # Resource usage