Pibox

docker-pibox

在 aicodebox 容器中运行 pi-coding-agent。一个镜像，多种接入方式：交互式 shell、单次提示词、HTTP API（带有 OpenAI 兼容端点）、MCP 服务、Telegram 机器人，以及可按需定时运行 pi 的 cron 调度器。

你与 pibox 对话。pibox 与 pi 对话。pi 与你指定的任意大模型对话。没人关心中间发生了什么。

目录

• 快速开始
• 使用 pibox 包装器
• 镜像变体
• 模式
  • API 模式
  • Telegram 模式
  • Cron 模式
  • MCP 模式
• 配置
• 大模型提供商
• 身份验证
• Agent 集成
• GitHub Action
• 开发
• 测试
• 许可证

快速开始

安装主机包装器。

curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-pibox/main/install.sh | bash

# Install the full image as the wrapper default.
curl -fsSL https://raw.githubusercontent.com/psyb0t/docker-pibox/main/install.sh | PIBOX_FULL=1 bash

安装程序会创建 Pi、pibox 状态和 SSH 目录，拉取所选镜像，并将 pibox 安装到 PATH。默认使用最小镜像。在管道的 bash 端设置 PIBOX_FULL=1 可选择完整镜像，并将此选择写入已安装的包装器。

如果你希望一个容器启动另一个容器，请在同一个命令目录（通常为 /usr/local/bin）中安装 pibox、codexbox 和 claudebox。每个包装器都会在该目录中查找同级包装器文件，并以只读方式挂载到自己的容器中。同级容器随后会通过主机 Docker 守护进程运行，并挂载自己的主机数据目录。

使用 pibox 包装器

从你希望 Pi 操作的目录运行 pibox。包装器会将该目录挂载到容器内相同的绝对路径，持久保存 ~/.pi、~/.aicodebox 和 ~/.ssh/pibox，转发 PIBOX_* 配置，并原样传递 Pi 参数。

# interactive Pi in the current directory
pibox

# one prompt, then exit
pibox -p "list the files in this workspace"

# use an Anthropic-compatible provider for this run
ANTHROPIC_AUTH_TOKEN=your-token \
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
ANTHROPIC_MODEL=glm-4.6 \
pibox -p "explain this project"

# inspect Pi's native command surface
pibox --help

# temporarily use the full image instead of the installed default
PIBOX_FULL=1 pibox -p "run the test suite"

包装器也是启动长期运行模式的常规方式。设置 PIBOX_DETACH=1 可让命名容器在后台运行。

PIBOX_DETACH=1 \
PIBOX_API_MODE=1 \
PIBOX_API_MODE_TOKEN=your-secret \
PIBOX_AVAILABLE_MODELS=glm-4.6,glm-4.5-air \
ANTHROPIC_AUTH_TOKEN=your-token \
ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic \
ANTHROPIC_MODEL=glm-4.6 \
pibox

只有在明确不想使用主机包装器时，才使用原始的 docker run。包装器是常规的交互式和服务入口。

Agent 使用与嵌套启动

对于用户和 Agent，已安装的包装器是常规接口。Agent 应从指定的工作区运行 pibox，而不是自行拼装新的 docker run 命令。包装器会保留工作区路径、Pi 状态、aicodebox 状态、SSH 状态、镜像选择和容器生命周期。

pibox -p "inspect this workspace and report the failing tests"
PIBOX_FULL=1 pibox -p "run the full test suite"
pibox -p "list the files" --thinking high

当一个容器需要启动另一个容器时，请在同一个命令目录中安装 pibox、codexbox 和 claudebox。运行中的容器可以直接调用同级命令。父包装器会传递主机启动上下文，并且只挂载同级包装器文件。不要设置 AICODEBOX_HOST_*、复制包装器，或手动挂载其他容器的状态目录。

镜像变体

• psyb0t/pibox:latest 是最小镜像。
• psyb0t/pibox:latest-full 基于共享的 aicodebox:latest-full，然后添加 Pi 和 pibox。它包含共享的开发工具链，无需在此仓库中重新构建。

模式

前台模式（API / Telegram / Cron）互斥，但 PIBOX_TELEGRAM_MODE=1 + PIBOX_CRON_MODE=1 除外，两者可同时运行（Cron 在线程内运行于 Telegram 中）。如果 API 与其他模式同时设置，则以 API 为准。

MCP 模式（PIBOX_MCP_MODE=1）独立运行，可与任何正在运行的前台模式共存。在 API 模式下，它挂载于 API 端口的 /mcp/ 上（不带末尾斜杠的 /mcp 也会访问同一处理程序）；在其他模式下，它会作为 sidecar uvicorn 运行在独立端口上，并在该端口的根路径提供服务。

每种模式都有单独的页面，包含完整的设置说明、环境变量和示例。

API 模式 →

长时间运行的 FastAPI 服务，监听 :8080。提供 Agent 运行（同步、带运行 ID 轮询的异步运行、可取消运行）、带路径遍历检查的工作区文件上传/下载/列表/删除，以及支持流式传输和客户端执行工具调用的 OpenAI 兼容 chat/completions 端点。

environment:
  - PIBOX_API_MODE=1
  - PIBOX_API_MODE_TOKEN=your-secret
  - PIBOX_AVAILABLE_MODELS=glm-4.6,glm-4.5-air

Telegram 模式 →

在 Telegram 中与 pi 对话。每个聊天都有隔离的工作区，可通过允许的聊天列表和每个聊天的允许用户设置进行访问控制，支持文件导入、通过 [SEND_FILE: path] 取回文件，以及可跨重启保留的每聊天 /model、/effort、/system_prompt、/append_system_prompt 覆盖设置。

environment:
  - PIBOX_TELEGRAM_MODE=1
  - PIBOX_TELEGRAM_MODE_TOKEN=123456:ABC

Cron 模式 →

使用 6 字段 croniter 计划、以 YAML 定义的定时任务。每次运行都会有历史目录，其中包含 meta.json、stdout.log、stderr.log、result.txt，并提供“上次运行”提示，以便任务引用自身的历史记录。

environment:
  - PIBOX_CRON_MODE=1
  - PIBOX_CRON_MODE_FILE=/home/aicode/.aicodebox/cron.yaml

MCP 模式 →

通过可流式传输的 HTTP 暴露 run_prompt 以及受工作区限制的文件工具，让其他 Agent 能够将 pi 作为工具使用。可与任何前台模式共存：在 API 模式下挂载于 API 端口的 /mcp/ 上，在其他模式下则作为 sidecar 运行于独立端口。

environment:
  - PIBOX_MCP_MODE=1
  - PIBOX_MCP_MODE_TOKEN=your-secret

配置

在主机上设置 PIBOX_GIT_NAME 和 PIBOX_GIT_EMAIL，以便在启动钩子运行前配置运行时用户的全局 Git 身份。直接部署容器时也可使用相同名称。在容器内设置非空的 AICODEBOX_GIT_NAME 和 AICODEBOX_GIT_EMAIL 时，它们具有更高优先级；通过封装脚本时，请将这些共享值设置为 AICODEBOX_ENV_AICODEBOX_GIT_NAME 和 AICODEBOX_ENV_AICODEBOX_GIT_EMAIL。空设置会保留现有 Git 配置。不接受多行值。

make version V=X.Y.Z 会同步软件包元数据、锁文件、Codex 插件清单和安装程序的封装脚本版本引用，但不会提交或打标签。远程安装会下载匹配的发行版封装脚本，除非设置了 PIBOX_INSTALL_REF 覆盖它。更新镜像不会更新已安装的封装脚本。

命名约定：PIBOX_<MODE>_MODE=1 是开关标志，PIBOX_<MODE>_MODE_<KNOB>=... 是对应的配置。非模式专属变量（工作区、容器名称、可用模型）不带模式前缀。

该镜像基于 aicodebox 构建，因此对应的 AICODEBOX_* 名称也可用——当只设置带 pibox 前缀的变量时，入口点会将 PIBOX_X 转换为 AICODEBOX_X。如果两者都设置，则以 AICODEBOX_* 为准。

使用 LLM 提供商设置上游端点 URL、协议、API 密钥或令牌，以及模型。PIBOX_PROVIDER_* 支持 Pi 文档中所述的 OpenAI、Anthropic 和 Google 自定义 HTTP API。下面的 ANTHROPIC_* 变量仍作为兼容方式保留，供现有的 Anthropic 兼容部署使用。

模式标志

变量	默认值	作用
PIBOX_API_MODE	0	启动 HTTP API 服务（前台运行）
PIBOX_TELEGRAM_MODE	0	启动 Telegram 机器人（前台运行）
PIBOX_CRON_MODE	0	启动 cron 调度器（前台运行；Telegram 也启用时在线程中运行）
PIBOX_MCP_MODE	0	暴露 MCP——在 API 模式下挂载到 /mcp/，否则作为边车运行

各模式的专属配置项（端口、令牌、配置路径、历史记录目录）请参阅对应模式页面：api.md、telegram.md、cron.md、mcp.md。

工作区与运行时

变量	默认值	作用
PIBOX_WORKSPACE	/workspace	容器内的根工作区目录
PIBOX_CONTAINER_NAME	aicodebox	用于限定每个容器的状态文件（身份验证等）
PIBOX_AVAILABLE_MODELS	—	API 模式必需。 以 CSV 格式列出由 /openai/v1/models 返回并显示在 Telegram /model 选择器中的模型。pibox 会通过 PIBOX_PROVIDER_API 将列出的每个模型注册到上游提供方。若未设置此变量，API 模式将拒绝启动；Telegram /model 选择器则会退化为回复“设置此环境变量”。
PIBOX_AVAILABLE_EFFORTS	适配器列表	覆盖 Telegram /effort 选择器中显示的 effort/--thinking 列表（以逗号分隔）
PIBOX_DATA_DIR	~/.pi	主机上的 Pi 配置、身份验证、扩展和会话目录
PIBOX_STATE_DIR	~/.aicodebox	主机上的 pibox 模式配置和历史记录目录
PIBOX_SSH_DIR	~/.ssh/pibox	挂载到容器中的主机 SSH 目录
PIBOX_IMAGE	已安装的镜像	覆盖已安装包装器选用的镜像
PIBOX_FULL	已安装的选项	0 选择精简版，1 选择完整版
PIBOX_DETACH	0	1 启动命名的后台容器，而不是一次性前台容器
PIBOX_ENV_*	无	将 pibox 环境变量传递到容器中
PIBOX_MOUNT_*	无	添加同路径或 host:container 绑定挂载
AICODEBOX_ENV_*	无	将共享环境变量传递到启动的容器中，并去掉前缀
AICODEBOX_MOUNT_*	无	为启动的容器添加共享的同路径或 host:container 绑定挂载

自动化可以通过 PIBOX_INSTALL_DIR 和 PIBOX_BIN_NAME 将包装器安装到其他命令目录。已安装的包装器支持带版本的 AICODEBOX_HOST_* 嵌套启动上下文。它会将这些主机路径用作 Docker 绑定挂载源，提供同级包装器，并将共享的 AICODEBOX_ENV_* 和 AICODEBOX_MOUNT_* 值应用到子容器。

在 PIBOX_STATE_DIR 下（默认为 ~/.aicodebox）：

• 放在 bin/ 中的可执行文件会优先于其他所有路径加入 PATH，适用于所有模式下的 pi、初始化脚本以及 docker exec shell。
• 放在 init.d/*.sh 中的脚本会在每个容器启动后运行一次，执行时间在镜像自带的初始化脚本之后；运行用户为 aicode，并拥有免密码 sudo 权限。脚本失败时会记录日志，但其余脚本仍会继续运行。新容器会再次运行这些脚本，因此请确保它们可安全重复执行。

身份验证

对于兼容 Anthropic 的端点，请使用以下兼容性变量。对于 LiteLLM 或其他兼容 OpenAI 的端点，请使用通用提供商配置。

变量	用途
ANTHROPIC_AUTH_TOKEN	Bearer 令牌（Z.AI、直接使用 Anthropic 等）
ANTHROPIC_API_KEY	同上 — pi 会读取这两项
ANTHROPIC_BASE_URL	端点覆盖值（默认值：https://api.anthropic.com）
ANTHROPIC_MODEL	调用方未指定模型时使用的默认模型

对于大多数任务，Z.AI 的 GLM 模型速度快、成本低 — 推荐的默认设置是 ANTHROPIC_BASE_URL=https://api.z.ai/api/anthropic + ANTHROPIC_MODEL=glm-4.6。

pi 的思考级别（--thinking）：off、minimal、low、medium、high、xhigh。在 telegram 模式下以 /effort 命令的形式提供，在 API 请求中则以 thinking 的形式提供。

Agent 集成

技能适用于任何会读取 .agents/skills/ 的 Agent（例如 peen）。它会指示 Agent 本地工作时使用已安装的封装程序，只有在远程服务已运行时才使用 MCP。它可原生安装到以下客户端中。

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install pibox@psyb0t

Claude Code 会提示输入 pibox URL；如果启用了身份验证，还会提示输入 API 和 MCP 令牌 — 敏感值会存储在你的操作系统钥匙串中。

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add pibox@psyb0t

通过市场安装后，技能以 $pibox:pibox 的形式调用。在任何包含 .agents/skills/ 的仓库中，Codex 也会自动发现该技能，无需安装，并以普通的 $pibox 形式调用。

OpenClaw

每次发布时，都会将该技能发布到 ClawHub：

openclaw skills install @psyb0t/pibox

对于使用本地 stdio 的 MCP 客户端，@psyb0t/pibox 插件可桥接到服务的 /mcp/ 端点：

openclaw plugins install clawhub:@psyb0t/pibox

然后设置 PIBOX_URL（如果启动服务时启用了 MCP 身份验证，还要设置 PIBOX_MCP_MODE_TOKEN）。

开发

如需了解如何在只读上下文中运行一次性 GitHub 任务、查看实时工具日志并收集输出文件，请参阅 GitHub Action。

make help   # list targets
make build      # build the minimal image
make build-full # build the full image from aicodebox full
make build-all  # build both variants
make test   # run the full e2e suite (needs .env.test)
make test-action # test the GitHub Action contract without credentials
make clean  # remove built images

VERSION 从 pibox/pyproject.toml 读取。make build 会拉取 Dockerfile 中固定版本的已发布 psyb0t/aicodebox 基础镜像；设置 SKIP_BASE_PULL=1 可改用本地构建的基础镜像（例如来自同级的 ../docker-aicodebox 检出），也可以通过 make build BASE_IMAGE=... 覆盖。

测试

端到端测试会构建镜像，并针对真实的大模型端点运行。Telegram 测试使用 psyb0t/telethon-plus 作为真实的 MTProto 用户机器人。

cp .env.test.example .env.test
$EDITOR .env.test   # fill in ANTHROPIC_* and optionally Coding Plan or Telegram creds
make test

如果 AICODEBOX_TELEGRAM_MODE_TOKEN 为空，Telegram 测试会自动跳过。通用提供商测试会使用 Z.AI Coding Plan 的两个端点；除非设置了 ZAI_CODING_AUTH_TOKEN，否则会复用 ANTHROPIC_AUTH_TOKEN。

许可证

WTFPL — 参见 LICENSE。想做什么就做什么。