openchamber 详细介绍：开源项目架构、功能与实践指南

项目速览（TL;DR）

OpenChamber 是一个基于 OpenCode AI agent 的开源开发工作空间，用于在桌面端、Web、VS Code、iOS 和 Android 等界面中启动、观察、审查和继续人工智能编码任务。仓库采用 TypeScript，默认分支为 main，许可证为 MIT。

根据仓库元信息，项目当前有 10084 个 Star 和 1108 个 Fork；根目录 package.json 的版本为 1.24.2，包管理器声明为 Bun 1.4.2，Node.js 要求为 >=22.0.0。这些数据会随仓库和平台状态变化，阅读或部署时应以 GitHub 页面和最新提交为准。

定位与目标用户

OpenChamber 的核心定位不是单次代码补全，而是围绕“启动任务、持续执行、查看变化、人工审查和发布”组织开发工作的工作空间。README 将其描述为用于运行和审查 AI coding work 的开源 workspace，并强调项目与会话在切换设备或暂时离开后仍可继续使用。

目标用户包括需要在多个项目间管理编码会话的个人开发者、希望从 GitHub issue 或 pull request 进入开发流程的团队，以及需要从桌面或移动设备查看任务进展的维护者。是否适合企业级生产环境，取决于组织对身份认证、网络暴露、密钥管理、数据留存和审计的具体要求；仓库资料没有提供 SLA、合规认证或企业支持承诺。

“Run agent work. Keep control. Ship from anywhere.”
来源：README

核心功能

OpenChamber 的功能围绕会话状态和代码变更展开：用户可以启动编码任务，查看代理产生的修改，并在不同设备上继续处理。下列机制均来自 README 的功能说明；对于底层实现细节，官方仓库在给定资料中未完整展开。

Session Goals：让会话围绕目标持续执行

Session Goals 为一次会话设置明确的完成条件。根据 README，OpenChamber 会在每一轮交互后检查结果，并在目标未完成、任务未被阻塞且没有达到用户设置的限制时继续工作；应用关闭后，会话仍可继续。

输入是用户定义的任务目标和限制条件，处理主体是 OpenCode agent，会话过程产生代码修改、状态和完成结果。仓库资料没有给出目标格式、检查器接口、最大轮数参数名称或失败重试策略，因此这些细节应以最新 README 和实际界面为准。

Multi-run 与 Fusion：并行比较多个模型结果

Multi-run 可以把同一个任务交给最多五个模型，每个模型运行在独立会话中，也可以选择独立 worktree。用户可以比较各个会话实际产生的结果，再选择其中一个，或者使用 Fusion 把较强的部分组合到新的会话中。

其工作输入是相同任务、模型选择和可选 worktree 隔离设置，输出是多个会话及其代码变更。README 没有说明模型供应商列表、并发调度实现、冲突合并算法或 Fusion 的具体提示词，因此不能据此推断其结果等同于自动化的无冲突合并。

Changes Walkthrough：按逻辑步骤审查大型差异

Changes Walkthrough 面向较大的 diff，将相关编辑归并为多个步骤，并按照更容易理解变更关系的顺序展示。它还会解释不同修改之间如何配合，适用于需要先建立整体理解、再定位具体文件的代码审查过程。

输入是会话产生的代码差异，输出是由 AI 引导的变更浏览过程。给定资料没有披露分组依据、支持的文件类型、是否执行测试或是否替代人工代码审查，因此该功能不应被当作自动批准机制。

Preview：在运行中的应用旁边检查界面

Preview 将应用预览和对话并列展示。用户可以指向页面元素，把元素截图、样式、位置和浏览器错误发送给 agent，从而把“页面上的这个东西”转换成更具体的调试上下文。

桌面应用还可以在内置浏览器中对任意网页进行同类检查。README 没有提供浏览器内核版本、支持的框架、截图存储位置或浏览器错误的具体字段，因此使用时需要按照当前版本界面验证。

GitHub issue 与 pull request 上下文

用户可以从 GitHub issue 或 pull request 启动会话，并将对应上下文附加到任务中。失败检查结果和审查评论可以回传给 agent，随后在 OpenChamber 中更新或合并 pull request。

这条流程的输入包括 issue、pull request、失败检查或评论，输出是新的编码会话以及后续仓库操作。资料没有列出所需的 GitHub 权限范围、令牌保存方式或合并保护规则，因此接入前应在授权范围内配置最小权限，并以项目文档为准。

跨设备会话与工作状态

Desktop、Web/PWA、VS Code、iOS 和 Android 可以访问相同项目与会话。用户可以查看进度、回答 agent 的问题、审查修改，并重新连接正在运行的终端。

README 还列出会话状态、审批、计划任务、提供商限制、令牌使用量和成本等工作信息，并支持文件夹、笔记、待办事项和可复用项目操作。资料没有说明这些统计的计费口径、刷新周期和持久化格式，不能将界面中的成本数据视为任何模型服务商的最终账单。

计划任务与远程访问

Scheduled tasks 可以一次执行，也可以按日、周或 cron 计划执行；它们还可以结合 Session Goals，使任务持续朝某个结果推进，而不是在一次响应后停止。远程访问方面，设备可以通过一次性二维码配对，再通过 Private Relay 连接，README 将该连接描述为端到端加密且可随时撤销。

README 同时列出直接连接、LAN/VPN、Cloudflare/Ngrok 隧道和 SSH 等方式。不同方式会改变网络边界和凭据管理责任；仓库资料没有给出每种方式的完整配置协议，部署时应优先使用本地或受控网络进行验证。

系统架构与关键模块

从根目录配置和 Dockerfile 可以确认，OpenChamber 是一个由多个 workspace 包组成的 TypeScript monorepo，至少包含 UI、Web、Electron、VS Code、Mobile 和 SDK 包。给定资料没有提供完整架构图，下面的模块关系仅对仓库文件中明确出现的构建边界进行说明。

Monorepo 与运行表面

• packages/ui：根脚本包含构建、类型检查、测试和设置注册表生成命令。
• packages/web：提供 Web 构建、开发服务器、启动、打包和服务器运行文件，Dockerfile 会复制其 dist、server 和 bin 目录。
• packages/electron：对应桌面端构建、开发、类型检查、测试和打包流程。
• packages/mobile：包含移动端构建、资源构建、同步以及 iOS、Android 模拟器相关脚本。
• packages/vscode：包含 VS Code 扩展的开发、构建、打包、类型检查和测试脚本。
• packages/sdk：在安装后和 Docker 构建阶段被单独构建，Web 服务器运行时会使用其构建产物。

Web 容器链路

Dockerfile 使用 oven/bun:1.4.2 作为构建和运行阶段的基础镜像。依赖阶段以 bun install --frozen-lockfile --ignore-scripts 安装依赖，构建阶段先执行 SDK 构建，再执行 Web 构建；运行阶段复制 Web 与 SDK 产物，并暴露容器端口 3000。

运行镜像还安装了 Git、OpenSSH 客户端、Python 3、Node.js、npm 和其他命令行工具，并通过 npm 全局安装 opencode-ai。Dockerfile 将运行用户设置为 UID 和 GID 均为 1000 的 openchamber，这意味着挂载卷的宿主机权限应与该 UID/GID 配合检查。

数据与工作区挂载

docker-compose.yml 将 OpenChamber 配置、OpenCode 的共享数据和状态、OpenCode 配置、SSH 目录以及工作区分别挂载到宿主机的 data 和 workspaces 目录。该布局把应用状态与项目文件从容器生命周期中分离出来，便于容器重建后继续使用。

这不是对备份能力的保证。资料没有给出数据库迁移、备份策略、锁机制或多实例一致性说明；如果需要长期保存会话和凭据，应自行建立受控备份与恢复测试。

依赖与运行环境

仓库已经声明了构建环境的关键版本，部署前应优先保持这些版本一致。当前资料没有提供操作系统矩阵、最低内存、CPU、磁盘、浏览器版本或模型服务商兼容性清单，因此不能根据项目规模推导资源门槛。

• 包管理器：Bun 1.4.2，来自根目录 package.json 的 packageManager 字段。
• Node.js：要求 >=22.0.0，来自根目录 package.json 的 engines 字段。
• 主要语言：TypeScript，来自仓库元信息。
• 容器基础镜像：构建阶段和运行阶段均使用 oven/bun:1.4.2。
• 运行容器中的附加工具：bash、git、less、nodejs、npm、openssh-client、python3。
• AI agent 依赖：Dockerfile 通过 npm 安装 opencode-ai；其独立版本在给定资料中未提供。

快速开始：最小可运行示例

给定资料中最完整且可复现的本地服务路径是 Docker Compose；它明确映射了宿主机端口 3000，并要求设置 OPENCHAMBER_UI_PASSWORD。以下命令只面向本地或测试环境，运行前应确认 Docker Compose 已安装；Docker 版本要求未在仓库资料中提供。

安装：获取仓库并准备依赖

下面的源码路径使用仓库给出的公开地址，依赖安装命令来自根目录脚本和 Dockerfile 中使用的 Bun 工作流。若只测试容器，不需要在宿主机执行 Bun 构建；若需要修改源码，则应保留完整仓库目录。

git clone https://github.com/openchamber/openchamber.git
cd openchamber
bun install --frozen-lockfile

--frozen-lockfile 用于按照锁文件安装依赖；根目录的 postinstall 会构建 SDK、构建内置扩展并尝试准备 Electron。首次安装所需时间、磁盘空间和外部网络依赖，官方仓库未提供该信息，建议以最新 README 为准。

运行：使用 Docker Compose 启动 Web 服务

Compose 配置要求显式提供 UI 密码，因为 Docker 会将服务绑定到 0.0.0.0 并映射到宿主机。以下示例在当前 Shell 中生成随机密码，再构建并后台启动服务。

export OPENCHAMBER_UI_PASSWORD="$(openssl rand -base64 24)"
docker compose up -d --build

这里的密码仅用于本地测试示例，不应写入公开仓库、镜像层或共享终端历史；生产部署应使用组织批准的密钥管理方式。Compose 文件还会把宿主机的 ./data 和 ./workspaces 挂载到容器，启动前应检查这些目录中是否包含敏感数据。

验证：确认端口和容器状态

服务端口映射来自 docker-compose.yml 的 3000:3000，因此可以检查容器状态并访问本地地址。由于 UI 需要认证，HTTP 返回状态不能单独证明登录后的页面可用，最终仍应在浏览器中使用刚才设置的密码完成验证。

docker compose ps
curl -I http://localhost:3000

如果容器没有运行，先查看日志定位构建、权限或环境变量问题：

docker compose logs --tail=100 openchamber

官方仓库给定资料没有提供健康检查端点、默认登录页路径或成功响应码，因此不应把某个固定 HTTP 状态码作为项目级健康标准。

配置说明

配置项主要出现在 docker-compose.yml 的环境变量注释中。下表只列出资料中真实出现的字段；“默认值”严格按 Compose 注释或资料状态填写，未声明的值不作推断。

在不需要远程访问的本地测试中，可以只设置 OPENCHAMBER_UI_PASSWORD，不要启用隧道和外部 OpenCode 连接。隧道 token、SSH 私钥和模型服务凭据的具体来源在资料中没有展开，不能将示例值直接用于生产环境。

进阶用法

进阶用法主要分为源码开发、桌面端构建、VS Code 扩展、移动端构建和外部 OpenCode 连接。根目录脚本已经给出相应入口，但各子包的完整参数、平台签名要求和发布流程并未出现在给定资料中。

源码开发与质量检查

根目录提供 Web 热更新、完整 Web 开发、类型检查、Lint 和测试命令。以下命令名称均来自 package.json，适合在本地修改后进行基础验证。

bun run dev
bun run type-check
bun run lint
bun run test

dev 调用 scripts/dev-web-hmr.mjs，type-check、lint 和 test 会覆盖多个 workspace。具体开发服务器地址、测试数量和执行耗时，官方仓库未提供该信息，建议以当前终端输出为准。

桌面端与 VS Code

桌面端提供 Electron 开发和打包脚本，包括 electron:dev、electron:dev:bundled 和 electron:build。VS Code 扩展提供开发、构建、打包和类型检查命令，适合希望把会话贴近编辑器的人使用。

bun run electron:dev
bun run vscode:dev
bun run vscode:build
bun run vscode:package

这些命令可能触发扩展构建或 Electron 依赖准备。资料没有提供桌面安装包名称、签名证书要求、VS Code 扩展市场发布状态或移动端应用商店信息，因此不能据此推断可直接分发的二进制产物。

移动端构建入口

移动端脚本包含资源构建、同步、iOS 和 Android 模拟器操作。仓库列出了 mobile:build、mobile:sync、mobile:build:android:debug 和 mobile:build:ios:simulator 等命令。

bun run mobile:build
bun run mobile:sync
bun run mobile:build:android:debug
bun run mobile:build:ios:simulator

操作系统、SDK、模拟器和签名工具的最低版本未在资料中给出。需要移动端发布时，应依据当前 packages/mobile 配置和官方文档补齐平台依赖，而不是仅凭根目录脚本推断发布条件。

可观测性与运维

OpenChamber 在产品界面层面提供会话状态、审批、计划任务、提供商限制、令牌使用量和成本等信息；Docker 部署则提供标准容器日志查看路径。资料没有描述 Prometheus 指标、结构化日志格式、分布式追踪、告警规则或可用性目标。

• 容器状态：使用 docker compose ps 检查服务是否处于运行状态。
• 启动与运行日志：使用 docker compose logs --tail=100 openchamber 查看最近日志。
• 服务入口：Compose 将宿主机 3000 映射到容器 3000。
• 数据持久化：检查 data/openchamber、data/opencode、data/ssh 和 workspaces 挂载目录。
• 升级检查：构建前核对锁文件、包版本、Dockerfile 基础镜像和最新 README。

根据本文作者的经验判断，运行代理编码任务时，日志和会话状态不足以替代代码审查与测试结果；上线前至少应确认工作区变更、依赖变更和凭据挂载范围。仓库没有给出自动备份、回滚和数据库迁移命令，因此运维方案需要由部署方自行建立。

安全与合规边界

OpenChamber 会接触代码仓库、GitHub 上下文、终端、SSH 目录、模型服务和可能的远程访问通道，因此部署边界应由授权范围决定。以下内容只讨论个人或组织明确授权的开发环境，不提供面向未授权目标的访问、攻击或绕过检测方法。

网络暴露与认证

Compose 注释明确指出，Docker 会将 OpenChamber 绑定到 0.0.0.0 以便端口映射，因此需要 UI 认证，并要求设置 OPENCHAMBER_UI_PASSWORD。不要在未配置认证的情况下把服务暴露到公共网络；私有 Relay、LAN/VPN、Cloudflare/Ngrok 和 SSH 的实际安全性仍取决于凭据、访问控制、网络策略和运行环境。

凭据、代码和隐私数据

Compose 会挂载 data/ssh，Dockerfile 还安装 OpenSSH 客户端；这表示部署者应将 SSH 私钥视为高敏感数据，限制宿主机权限并避免把挂载目录提交到版本控制。GitHub token、隧道 token、模型服务密钥和 UI 密码不应写入公开配置或日志。

README 提到端到端加密的 Private Relay，但给定资料没有提供加密实现、密钥轮换、数据留存期限或隐私政策。涉及个人数据、客户代码、受监管数据或跨境传输时，应由组织完成授权、数据分类、处理者评估和审计，不应仅以项目的开源许可证替代合规审查。

代理执行与隔离

OpenChamber 面向编码任务，并支持终端、工作区、GitHub 操作和计划任务。建议只在明确授权的仓库和隔离工作区运行，并为代理使用最小权限；资料没有提供沙箱、默认拒绝策略、命令审批模型或多租户隔离保证。

如果使用 Multi-run 的独立 worktree，应在合并前逐一审查变更、测试结果和依赖修改。Session Goals 可以继续执行任务，但不等于自动验证业务正确性，也不等于可以跳过人工批准、分支保护或组织发布流程。

许可证与商用条款

仓库采用 MIT License，许可证文件版权标注为 Copyright（c）2025 Bohdan Triapitsyn。MIT 文本授予获得软件者使用、复制、修改、合并、出版、分发、再许可和销售软件副本的许可，具体边界以仓库中的 LICENSE 为准。

按照 LICENSE 文本，分发软件或其重要部分时必须保留版权声明和许可声明。许可证同时明确软件按“现状”提供，不提供适销性、特定用途适用性和不侵权保证，作者不承担因软件使用产生的相关责任。

因此，基于 MIT 条款可以进行商业使用，但商业产品仍需单独核查依赖许可证、OpenCode、模型服务、GitHub API、Cloudflare 或其他外部服务的条款。第三方服务费用、数据处理义务、商标使用和企业合同不由本仓库的 MIT License 自动覆盖；不确定的部分以仓库 LICENSE 和相关服务条款为准。

局限性与已知限制

给定仓库资料足以说明功能范围和构建入口，但不足以形成完整的生产级能力清单。部署决策时应把“资料未提供”视为需要验证的项目，而不是默认为已具备。

• 官方资料未提供性能基准、并发会话上限、资源消耗、响应延迟或吞吐数据。
• 未提供 SLA、灾备目标、备份恢复流程、数据库迁移说明或多实例部署方案。
• 未提供完整的认证授权模型、组织级 RBAC、审计日志格式和密钥轮换策略。
• 未提供模型供应商兼容矩阵、模型成本计算规则、上下文限制或失败重试接口。
• 未提供 Preview 的浏览器内核版本、支持范围和数据留存细节。
• 未提供各桌面系统和移动平台的最低版本、签名、发布渠道及安装包清单。
• README 资料在“Quick start”段落处被截断，完整安装说明官方仓库未提供该信息，建议以最新 README 为准。

根据本文作者的经验判断，如果目标是高合规、多租户或高并发平台，不能只依据 Star 数、Fork 数和功能列表完成技术选型；应先在隔离环境验证权限边界、数据流、成本、故障恢复和代码审查流程。

适合谁

以下信号可以帮助判断 OpenChamber 是否贴合实际工作流，判断依据来自其多端会话、GitHub 上下文、工作区和任务调度能力。

• 团队需要把编码 agent 的任务、差异审查和继续执行统一放在一个工作空间中，而不是只接受一次性文本建议。
• 开发者需要从桌面、浏览器、VS Code 或移动设备查看同一项目和会话，并在离开电脑后继续处理工作。
• 团队经常从 GitHub issue 或 pull request 开始开发，并希望把失败检查和审查评论带回编码会话。
• 项目需要比较最多五个模型或独立 worktree 的任务结果，再由开发者选择或融合结果。
• 维护任务具有明确目标，适合使用 Session Goals 或按日、周、cron 调度重复执行。

不适合谁

以下情况不一定意味着项目不能使用，但表示需要额外验证或选择更适合自身约束的方案。

• 组织要求仓库提供已声明的 SLA、合规认证、企业支持合同或官方多租户隔离保证，而给定资料没有这些承诺。
• 团队需要明确的高并发容量、延迟、成本上限或稳定性基准，但官方资料没有提供 Benchmark、容量和性能数据。
• 环境禁止代理访问终端、SSH、GitHub 或工作区，或者无法为其建立授权、隔离和人工审批边界。
• 项目需要完整的企业级审计、细粒度 RBAC、密钥轮换和集中身份系统，而仓库资料没有列出这些能力。
• 团队只需要编辑器内的单次补全，不需要会话持续执行、跨设备访问、任务调度和变更审查工作流。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分依赖安装、容器启动、认证、挂载权限和外部 OpenCode 连接问题。以下问题只使用仓库资料中已经出现的命令、端口和字段。

Q：Docker Compose 启动前为什么必须设置密码？

A：Compose 注释明确说明，Docker 会把 OpenChamber 绑定到 0.0.0.0 并映射端口，因此要求设置 OPENCHAMBER_UI_PASSWORD。未设置时，Compose 文件中的必填变量表达式会阻止启动。

Q：如何确认服务是否启动？

A：执行 docker compose ps 查看容器状态，再执行 curl -I http://localhost:3000 检查本地端口。认证可能影响 HTTP 返回结果；若状态异常，使用 docker compose logs --tail=100 openchamber 查看日志。

Q：容器能启动但看不到项目文件怎么办？

A：检查宿主机的 ./workspaces 是否挂载到容器的 /home/openchamber/workspaces，并确认目录权限与容器用户 UID/GID 1000 兼容。Dockerfile 明确将运行用户设为 openchamber，但资料未提供自动修复宿主机权限的命令。

Q：为什么需要单独构建 SDK？

A：Dockerfile 注释说明，服务器运行时会导入 @openchamber/sdk，而依赖阶段使用 --ignore-scripts，所以根目录 postinstall 不会构建 SDK。构建阶段因此显式执行 bun run --cwd packages/sdk build，并将 packages/sdk/dist 复制到运行镜像。

Q：是否可以连接外部 OpenCode 服务？

A：Compose 注释提供了 OPENCODE_HOST 和 OPENCODE_SKIP_START，前者用于连接外部 OpenCode 服务，后者设置为 true 时跳过启动 OpenCode。连接地址、网络可达性、认证和兼容版本的完整要求，官方仓库未提供该信息，建议以最新 README 为准。

Q：能否把 UI 直接暴露到公网？

A：资料只说明了 Docker 端口映射、UI 密码和多种远程连接方式，没有给出公网部署的安全基线。未经组织授权和安全评估，不应直接暴露；应先确认认证、凭据、隧道、SSH、工作区和日志中是否存在敏感数据。

项目地址与资源

以下链接均来自项目元信息、README 或仓库资料中的官方入口，版本、功能和部署要求应以这些页面的最新内容为准。

• OpenChamber GitHub 仓库
• OpenChamber 官网与文档
• OpenChamber 最新 GitHub Release
• OpenChamber GitHub Star 列表
• OpenChamber Discord 社区
• OpenChamber 项目支持页面