AI教程

如何部署 Agentbox 并在浏览器中运行 Claude Code 或 Codex

本教程介绍如何安装 Agentbox、连接 Claude Code 或 Codex 账号、创建持久化 Docker 工作区、完成编码任务、审查更改并监控使用情况。还将介绍源码构建、安全远程访问、私有网络隧道、备份以及重要的运行限制。

AI我搜编辑部2026年9月29日阅读约 15 分钟

如何部署 Agentbox 并在浏览器中运行 Claude Code 或 Codex

什么是 Agentbox？

Agentbox 是一个自托管环境，可通过浏览器运行 Claude Code 和 Codex CLI。它将 AI 聊天、终端、项目文件、Git 审查、账号管理和使用情况跟踪整合到托管在您自己服务器上的持久化工作区中。

服务器以单个 Go 二进制文件的形式发布，并内嵌 TypeScript 前端。它使用 SQLite 存储应用状态和聊天记录，并使用 Docker 容器隔离编码工作区。持久化目录独立于容器生命周期，用于保存项目文件、主目录配置和共享资源。

当您希望在一台设备上开始编码任务，并在其他设备上继续而无需重新构建环境时，Agentbox 尤其有用。您可以使用流式 Web 聊天处理面向任务的工作，也可以打开浏览器终端，直接使用原始的 Claude Code 或 Codex CLI。

主要功能

持久化工作区：项目文件、主目录配置、共享文件和聊天记录都会保留在您的服务器上。
两种智能体界面：在浏览器聊天和原始命令行工具之间切换。
集成交付工作流：上传或克隆项目、分配任务、检查文件、审查 Git 差异，并提交或下载结果。
集中式账号池：管理员可以配置 Claude 和 Codex OAuth 订阅、API 密钥、中继端点、访问范围和出口代理。
使用量和成本记录：按用户、模型和时间筛选使用情况，同时查看令牌数、定价来源、延迟和记录的成本。
可复用资源：每位用户都会获得一个共享目录，该目录以 /shared 的形式挂载到其所有工作区中。同时支持主目录模板、Claude 技能和 MCP 配置。
可选的私有网络访问：abox-link 客户端可以将明确获准的代码仓库、数据库和服务公开给云端工作区。
响应式界面：控制台支持深层链接、浅色和深色主题以及移动端布局。

了解架构

您的浏览器通过 HTTP 或 HTTPS 以及 WebSocket 连接到 Agentbox 服务器。服务器通过本地 Docker API 控制工作区容器，并将应用记录存储在 SQLite 中。每个工作区都有自己的容器和持久化目录。

一个工作区可以包含多个聊天线程，但该工作区一次只能运行一个 Web 聊天轮次。主要的持久化位置包括 /workspace、/home/agent 和 /shared。需要在容器替换后继续保留的文件，应存储在这些位置之一。

重要：持久化文件并不意味着进程会持久运行。终端网络中断后重新连接可以恢复 tmux 会话，但停止或重建容器会终止其中正在运行的进程。

前置条件

最快的安装方式面向使用 systemd 的 Linux 服务器。发布包支持 Linux x86_64 和 arm64。

Ubuntu 22.04 或更高版本，或 Debian 12 或更高版本，可以自动安装缺失的依赖和 Docker。
其他 Linux 发行版需要 Python 3.9 或更高版本、Git、curl、CA 证书、时区数据以及本地 Docker Engine。
首次构建工作区镜像时，需要访问容器注册表、Debian 软件包仓库和 npm。
如需远程访问，除非使用 SSH 转发或反向代理，否则必须通过服务器防火墙或安全组放行 TCP 端口 8180。

预构建安装不要求服务器安装 Go 或 Node.js。

使用发布安装程序安装 Agentbox

1. 运行安装程序

连接到 Linux 服务器并运行：

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash

安装程序默认选择最新的稳定版本。README 将 v0.1.5 标记为当前稳定版本。如需固定使用该版本，请运行：

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --version v0.1.5

安装过程会验证发布包，使用固定的工具版本构建工作区镜像，创建配置，生成随机管理员密码，并启动 agentbox.service。首次构建镜像可能需要几分钟。

2. 打开控制台

安装完成后，记下终端中显示的管理员密码。打开以下地址，并将占位符替换为服务器地址：

http://YOUR_SERVER_IP:8180

使用用户名 boxadmin 和生成的密码登录。在持续对外公开 Agentbox 之前，请配置 HTTPS。

3. 将 Agentbox 限制在反向代理后

如果 Agentbox 只应接受本地连接，请在安装时追加监听选项：

curl -fsSL https://raw.githubusercontent.com/devilcoolyue/agentbox/main/install.sh | sudo bash -s -- --listen 127.0.0.1:8180

然后，您可以在服务前配置支持 WebSocket 的 HTTPS 反向代理。发布版安装会将配置存储在 /etc/agentbox，并将应用数据存储在 /var/lib/agentbox。

配置 Claude 或 Codex 账号

登录后，打开系统设置 → 账号池。添加 Claude 或 Codex 账号。

Agentbox 支持以下连接方式：

Claude 订阅：选择“订阅 OAuth”，然后粘贴授权码。
Codex 订阅：选择“订阅 OAuth”，然后粘贴完整的回调 URL。
API 或中继账户：输入提供商端点和密钥。Codex 中继必须匹配提供商所要求的协议。

设置一个易于识别的账户名称、其所需的出口代理以及访问范围。账户可以对所有用户、指定用户或仅管理员可用。管理员可以使用所有已配置的账户。

拥有终端访问权限的工作区用户可以读取传递给其容器内命令行工具的凭据。因此，共享账户池应仅限受信任的用户使用。撤销访问权限会阻止新的操作和凭据同步，但要完全撤销权限，可能还需要停止受影响的容器并轮换上游凭据。

创建您的第一个工作区

创建一个工作区，并为其设置描述性名称。
选择 Claude Code 或 Codex CLI 作为代理。
选择您的用户有权使用的账户。
通过文件上传项目，或在终端中克隆项目。
打开聊天并提交一项明确的编码任务。
检查已编辑的文件，并在更改下查看 Git diff。
在本地提交更改，或下载项目文件。

上传并检查项目文件

文件界面为项目目录和共享目录提供目录树、上传、编辑、预览和归档下载功能。源代码查看器包含行号、语法高亮、行列导航、当前行高亮和全屏模式。

Web 文件操作使用受限的目录句柄，不会跟随符号链接。上传内容会在临时目录中验证，编辑器保存使用原子替换。容器内的命令行工具仍可以使用模板提供的链接。

从终端克隆仓库

打开终端并运行常规 shell 命令。例如：

cd /workspace
git clone https://github.com/OWNER/PROJECT.git
cd PROJECT
git status

Agentbox 在其工作区镜像中包含原始代理 CLI 和常用开发工具。终端会话使用 tmux，因此即使浏览器或网络断开，您也可以重新连接。

在 Web 聊天中分配任务

打开聊天，描述所需的更改、相关约束以及您期望执行的验证。例如：

检查此项目，并为用户注册端点添加输入验证。保留现有的 API 响应格式，为无效电子邮件地址添加测试，并运行相关测试套件。

聊天支持选择模型和推理强度。每个响应都会记录其时间、模型、设置快照和成本。Claude 运行流式无头会话。Codex 优先使用其 app-server 集成；如果握手失败，则回退到执行模式。

检查并交付结果

代理完成后，打开“更改”以检查修改的文件和彩色差异。当 diff 缺少足够上下文时，请查看完整文件。

Web 提交仅在本地执行，不会自动推送到远程仓库，也不会运行 Git hooks 或签名。需要使用 hooks 或签名提交时，请使用终端。

Agentbox 还提供 Git 管理功能，包括仓库连接、克隆、获取、快进拉取、预览推送、分支操作，以及创建 GitHub 或 GitLab 拉取请求和合并请求。仓库连接可以使用 HTTPS 令牌或 SSH 私钥。

从源代码构建并运行

如果您计划修改 Agentbox 或为项目贡献代码，请使用源代码工作流。文档中的构建环境使用 Linux、Docker、Go 1.26.6 或兼容的自动工具链、Git、Python 3、curl、iproute2 和 OpenSSL。只有编辑主要 TypeScript 控制台时才需要 Node.js 22 和 npm。

1. 克隆并构建

git clone https://github.com/devilcoolyue/agentbox.git
cd agentbox

go build -o agentbox ./cmd/agentbox
./scripts/build-image.sh

运行镜像构建的用户需要具备 Docker 访问权限。启动时，服务器还必须将挂载目录的所有权设置为 1000:1000；随附的 systemd 服务以 root 身份运行。

2. 创建配置

cp config.example.json config.json
openssl rand -hex 24

将生成的随机值复制到 auth_token 中。首次测试时，将 accounts 和 proxies 保持为空，稍后再通过 Web 界面添加真实账户。

{
  "listen": "127.0.0.1:8180",
  "auth_token": "CHANGE_ME_TO_A_LONG_RANDOM_TOKEN",
  "data_dir": "data",
  "agent_image": "agentbox-agent:latest",
  "accounts": [],
  "proxies": []
}

启动前请替换占位值，否则配置验证会拒绝该配置。

3. 启动服务器

sudo ./agentbox -config config.json

对于仅监听 localhost 的服务器，请从您的计算机创建 SSH 隧道：

ssh -N -L 8180:127.0.0.1:8180 user@your-server

在本地打开 http://127.0.0.1:8180，并使用 boxadmin 和已配置的 auth_token 登录。创建管理员账户后，其密码会存储在 SQLite 中；之后更改 auth_token 不会重置该密码。

4. 安装 systemd 服务

停止前台进程后，从仓库安装并部署服务：

sudo ./deploy/install.sh
sudo ./deploy/deploy.sh

第一个脚本会安装服务和定时器。第二个脚本会构建并替换二进制文件、重启服务并执行健康检查。

监控用量和成本

Usage 页面会记录模型活动，并允许管理员按用户、模型和时间筛选。单条记录包括令牌用量、成本来源和延迟。普通用户可以查看自己的记录，管理员则可以查看所有用户的记录。

定价目录可以使用 models.dev 来源预设，也可以使用自定义 HTTPS 来源。价格更新会保留历史快照，自定义价格仍会受到保护。Web 回合会按照回合开始时固定的价格表计费。

额度限制并不是实时硬上限。Web 回合会在结束后结算，因此耗尽余额的回合可能会超额使用。回填的终端用量会被记录，但不会扣除额度。

高级提示

在工作区之间使用共享资源

每位用户的共享目录都会挂载到该用户所有工作区中的 /shared。将可复用的脚本、参考文件或构建产物存放在那里，无需复制到每个项目中。Agentbox 还支持系统级和按用户设置的主目录模板。

使用 abox-link 访问私有服务

可选的 abox-link 客户端允许云端工作区访问计算机或其他私有机器上可用且已加入允许列表的服务。它可以通过本地面板运行，也可以使用 --server 以命令行服务器模式运行。

请使用范围较窄的允许列表，只公开工作区所需的仓库、数据库或服务。Agentbox 会显示客户端和工作区的连接就绪状态。普通浏览器使用不需要 abox-link。

规划容器容量

每个工作区容器默认使用2048 MiB 内存、2 个 CPU 和 512 个进程。请根据预计同时运行的工作区数量规划服务器容量。管理员还可以配置全局和按用户设置的容器限制以及预留磁盘空间。

备份正确的数据

默认系统备份包括数据库、配置、账户凭据和模板层，但不包括工作区数据。当还需要捕获用户文件和历史记录时，请使用 agentbox backup --full。完整备份前必须先停止服务和相关容器。使用 backup-verify 验证归档，并使用 restore --to 将其恢复到新目录。

了解安全边界

代理可以在工作区容器内执行代码。默认权限模式为 bypassPermissions。容器以非 root 用户运行，并受到资源限制及 no-new-privileges 保护，但 Agentbox 服务器本身拥有 Docker 访问权限。因此，部署和管理应始终由受信任的操作员负责。

谨慎使用可选的远程浏览器

Agentbox 可以在工作区内提供完整的桌面浏览器，包括持久化登录状态、标签页、全屏、可调图像质量、剪贴板支持和下载功能。管理员必须构建并选择可选的 agentbox-agent:browser 镜像。网站身份验证与 Claude 或 Codex CLI 授权相互独立。

需要记住的运行限制

特定的 data_dir 只能由一个 Agentbox 进程使用。
当前生产架构使用一台机器、一个服务器进程和一个本地 Docker 守护进程。
部署和重启会使已连接的客户端短暂断开。
刷新远程 Git 状态不会执行 fetch；ahead 和 behind 值来自本地缓存。
撤销账户不会删除已交付给正在运行的容器的凭据。
停止或重建工作区容器会终止其中的进程，但持久化文件仍会保留。
Git 审查可能会启动已停止的工作区，并执行与终端访问相同的额度准入检查。

结语

Agentbox 可将 Linux 服务器变成持久化的基于浏览器的编码环境，用于运行 Claude Code 和 Codex CLI。首先使用发行版安装程序，添加账户并创建工作区，然后通过集成的 Files、Terminal 和 Changes 视图，从聊天任务推进到经过审查的代码。用于生产环境时，请添加 HTTPS，谨慎控制账户访问权限，监控资源使用情况，并在需要时建立包含工作区数据的备份方案。

如需更深入的配置和运行指导，请参阅 Agentbox 仓库、文档索引以及部署和运维指南。