English · 简体中文

任务进行到一半,Claude Code余额用完了,Codex在同一个对话直接接手。

同一个 Orbital 对话里,Claude Code 提示额度用完(You're out of usage credits);用户在 agent 选择器里切到 Codex,说「你继续吧」,Codex 读取同一份项目上下文直接接手

Orbital

Orbital

project agent(项目 agent)

Agent只负责一次会话,Orbital负责整个项目。

Orbital是一个agent上下文管家,帮助你维护项目上下文,让所有agent在同一份上下文上工作。任何agent的产出和沉淀,都会给所有agent复用。

上下文是你的,agent是可替换的。

下载 Windows 安装包 (.exe)    下载 macOS 安装包 (.dmg)

Orbital 使用教程。

1 分钟演示:切换agent,项目继续进行

https://github.com/user-attachments/assets/88cf118c-1dd9-4429-897d-f2003de3049d [![License: GPL-3.0](https://img.shields.io/badge/License-GPL--3.0-blue.svg)](#license) ![Platform: Windows](https://img.shields.io/badge/Platform-Windows-0078D6?logo=windows) ![Platform: macOS](https://img.shields.io/badge/Platform-macOS-000000?logo=apple) --- ## 为什么你需要一个“project” agent **你的上下文,是你的吗?** 你正在和 Claude Code 讨论一个方案,聊到第三轮,它弹出「You're out of usage credits」。Codex 的额度还在,但 Codex 对这个项目一无所知——目标、前两轮拍板的结论、改到一半的文件,都得你重讲一遍。

Orbital 对话里的 agent 选择器:每个 agent 旁边显示额度还剩多少(Claude Code 5 小时窗口剩余 57%,Codex 本周剩余 84%),换一个 agent 就在同一个对话里接着做

每个 agent 还剩多少额度,就写在选择器里。换一个,它从同一份项目上下文接着做。

不只是额度。在工作中,大家都已经在同时用好几个 agent —— 可能是因为新出的模型、剩余的额度,也可能是因为某个工具更擅长这类活。但 Claude Code 里定下的方案、Codex 改到一半的文件、Cursor 里拍板的取舍——各自锁在各自的会话里。会话一关、换个工具,上下文就无法使用。 于是把项目「搬运」过去的活就落到了你身上:重述目标、解释此前的决策、翻找产出的文件、确认还有什么没做完。 **你才是 agent 的实习生:复制粘贴、搬运上下文、记住杂七杂八的文件放在哪,让agent来做脑力活。** Orbital 把上下文从会话里拿出来,放回你的本地文件夹,把工作的单位从「会话」换成「项目」。 project agent记录下项目中所有agent的进度,保证下一个agent有充分的上下文接手任务。任何agent的产物和沉淀,都会被所有agent参考和复用。不需要重新发明轮子,所有agent在同一个项目上自进化。 单个 agent 完成任务。Orbital 推动整体项目进展。 --- ## 什么叫“对你的项目负责” Orbital将把重要的项目上下文组织起来,以普通文件的形式维护在你的本地文件夹里: - **状态** —— 项目现在是什么情况(`PROJECT_STATE.md`) - **决策** —— 决定了什么、为什么这么定(`DECISIONS.md`) - **经验教训** —— 项目一路上学到了什么(`LESSONS.md`) - **产出成果** —— agent 调研、撰写、构建出来的东西(工作空间本身,以及 `orbital/output/`) 这些都留会成为后续工作的上下文。每次任务开始前,Orbital 会先把它们组装进自己的系统提示词中,保证没有遗漏。 子agent也会读取同一批文件,不需要你记住项目的信息和文件架构。Agent会自己做笔记,保证下一次会话能无缝衔接。 Agent可以换。你的上下文资产一直在。 ---

微信二维码:加作者微信,拉你进 Orbital 用户反馈群
微信扫码加我,拉你进用户反馈群

加入 Orbital Discord

## 快速开始
展开 4 步上手流程(带截图) > 每一步都带截图的完整教程见 **[Orbital 使用教程](https://orbital.top/guide/)**:配置 API key、新建项目、切换子 Agent、任务队列、自动任务和项目设置。 1. **启动 Orbital** —— 设置向导依次引导你完成四步:先确认 Orbital 在本机找到的编码 agent,再把你和这些 agent 做过的项目导入进来(都可跳过),然后配置 API 密钥和关联账户。 **Step 3 — LLM Provider:** 中国大陆用户点「一键登录词元跳动」,授权后免费领取 Token,直接开始。也可以从预设卡片里选择服务商,点「获取 API 密钥」直达密钥控制台,粘贴即可——支持 DeepSeek、Moonshot (Kimi)、智谱、MiniMax、Anthropic、OpenAI 等十余家服务商。

设置向导第三步——选择 LLM provider 并配置 API key

**Step 4 — 关联账户:** 连接 API 连接器(Google Calendar、Drive),并提前登录 agent 需要访问的站点(Google、GitHub 等),防止它在浏览时被验证码挡住。这一步可跳过,之后随时可在设置中完成。

设置向导第四步——关联账户:API 连接器与 Agent 浏览器登录

2. **创建项目** —— 起个名字,选择本地的一个文件夹,设定 autonomy 等级

新建项目对话框:填写项目名称,选择一个新文件夹或已有文件夹,agent 就在里面工作

3. **开始对话** —— 在聊天框输入任务,管理 agent 自己处理 4. **走开** —— 把后续任务排进队列;每个完成项都会成为下一项的上下文
--- ## 项目始终由同一个管理 agent 负责

orbital/ 记忆文件:PROJECT_STATE.md、DECISIONS.md、LESSONS.md、INDEX.md、ASKS.md 由 agent 维护,每个会话读回

管理 agent 跨会话维护项目的状态、决策与经验

项目 agent 记录一个 bug 并派给 Claude Code,Claude Code 基于同一份项目上下文调查 12 分钟,把根因和 spec 写回工作空间

管理 agent 基于同一份项目上下文把任务派给 Claude Code、Codex 或 Gemini,再记录执行结果

工作空间文件树——agent 不断积累的产出与 orbital/ 记忆文件

在每个项目的工作空间里浏览、预览、上传文件——看着 agent 的产出不断积累

暂停中的任务队列——正在运行为空、需要关注里有一条受阻任务并附上 agent 给出的原因、两条排队中任务、以及已完成任务及其总结

把任务排进队列然后走开——agent 逐项处理,每个完成项都会成为下一项的上下文;随时可暂停介入引导,再继续

工作台——一个能发任何任务的输入框,带项目和 agent 选择,下方是一份卡片列表:进行中的任务、Codex 和 Claude Code 完成的回复、一条带一键选项的提问,每张卡都标明来源项目和接手的 agent

工作台(beta)——所有项目共用的一个入口:一句话交代任务,Orbital 带着该项目的上下文送到对的项目、交给对的 agent,也可以自己指定;下面是按时间排序的一份卡片,进行中的任务、待你查看的回复、agent 需要你拍板的提问,每条都标明来源项目。提问直接给出选项,点一下就答;详情按 markdown 渲染,回复框里还能附上文件

Skills 设置——agent 遵循的可复用操作模式

Skills——agent 从多步流程中沉淀出可复用的操作模式,下次遇到类似任务先查阅

定时 trigger 编辑:每周一上午 10 点梳理 backlog,含执行周期、时区、运行者和提示词

定时与文件监听 trigger——让管理 agent 定期检查并自动派发 sub-agent,无需你动手

预算设置——花费上限、重置周期、按模型的实时成本明细、可编辑的价格表

为每个项目设定预算上限和重置周期,实时查看按模型的花费与成本明细

凭据管理——网站密码存放在系统钥匙串中

网站凭据存放在系统钥匙串里,绝不暴露给聊天

手机端:agent 在浏览 Hacker News,每一步浏览和推理都显示在对话里    移动端审批卡片——在手机上批准 agent 动作

手机上监督:实时查看 agent 活动,带完整上下文批准关键动作(可附加指引)

--- ## 架构 Orbital 是绑定在一个**项目**上的持久管理 agent——而不是一个聊天会话。它是项目的本地 control plane,统一管理工作空间、instructions、状态、队列、预算和审批规则。管理 agent 负责规划、委派、监督并记录结果;worker agent 基于同一份项目上下文执行。你可以从任何地方监督。 ```mermaid flowchart TB UI["Frontend (React SPA)
Chat UI · Approval Cards · Settings · Files"] subgraph daemon["Daemon (FastAPI + uvicorn)"] direction TB AM["AgentManager
lifecycle"] SAM["SubAgentManager
delegation"] TM["TriggerManager
cron · file watch"] Loop["Agent Loop
streaming · safety guards"] TR["Worker Transports
Codex app-server · SDK · PTY · ACP · Pipe"] LLM["LLM Provider
OpenAI + Anthropic SDK"] Tools["Tool Registry
shell · file · browser · triggers"] Auto["Autonomy Interceptor
approve · deny · bypass"] AM --> Loop SAM --> TR TM --> AM Loop --> LLM Loop --> Tools Loop --> Auto end Platform["Platform Layer
Windows sandbox user · macOS Seatbelt · Linux bubblewrap (planned)"] Relay["Cloud Relay (Node.js, optional)
REST proxy · Event forwarding · Push notifications · Pairing"] Phone["Phone"] UI <-->|REST + WS| AM UI <-->|REST + WS| SAM Tools --> Platform AM -.WebSocket tunnel.-> Relay Relay -.WebSocket.-> Phone ``` **设计决策:** - **管理 agent 对项目负责**: agent 维护结构化的状态、决策、经验和会话历史,让规划与责任始终归于一处 - **Isolation**: OS 级别 sandbox(Windows sandbox user / macOS Seatbelt / Linux bubblewrap 在规划中) - **Fail-closed interceptor**: 审批系统出错后默认 DENY,绝不 ALLOW - **单 daemon**: PID 文件强制只能存在一个实例 - **Local-first**: 你的所有文件和项目状态都在你自己的硬盘上。Cloud relay 启用时只转发审批和事件,不转发你的文件。 --- ## 与同类产品对比 持久记忆、定时任务和 sub-agent 现在已经是标配 —— 下面每个工具都有。真正还有分歧的是这三个问题。 | 2026 年 7 月 | Orbital | [Claude Code](https://code.claude.com/docs/en/desktop) | [Codex](https://developers.openai.com/codex/) | [Hermes](https://github.com/NousResearch/hermes-agent) | [OpenClaw](https://docs.openclaw.ai/) | | --- | --- | --- | --- | --- | --- | | 下一个任务能换一个 agent 接手吗? | ✅ Claude Code、Codex、Gemini CLI、Cursor、任意 CLI | ❌ 只有 Claude worker | ❌ 只有 Codex worker | ❌ 只有 Hermes worker | 部分(通过 ACP 调用外部 agent) | | 靠什么防止队列任务悄悄漂走? | ✅ 强制以完成/受阻闭环 | ❌ | ❌ | ❌ | ❌ | | 预算、审批和审计属于谁? | ✅ 属于项目 | 部分(权限 + 运行历史) | 部分(审批 + 企业审计) | 部分(命令审批) | 部分(审批 + 日志) | **一句话总结:** 差异不在某一项能力,而在于承载状态、worker 和治理的单位是「项目」,不是「会话」。 --- ## 功能详解 完整的功能详解——项目与工作空间模型、管理 agent 的上下文维护与压缩、sub-agent 委派与传输层(Codex 原生 app-server JSON-RPC、Claude Code SDK、其他 worker PTY/ACP)、任务队列、Quick Tasks、自我改进的 skills、内置工具、浏览器自动化、triggers、LLM 路由与 BYOK、autonomy 与审批、预算控制、手机远程、凭据管理、agent loop 安全保护、桌面应用——以英文为准,见 [English README → Feature Deep Dives](README.md#feature-deep-dives),避免中英两份各自维护导致内容不同步。 --- ## 安装 ### Windows 1. 从 [Releases](https://github.com/zqiren/Orbital/releases/latest) 下载最新的 `Orbital-Setup-*.exe`(Windows 版本) 2. 运行安装程序,按提示完成 3. 从开始菜单或桌面快捷方式启动 Orbital
Windows SmartScreen 警告 Orbital 的 Windows 安装包暂未做代码签名,Windows 会提示安全警告: > **Windows 已保护你的电脑** —— Microsoft Defender SmartScreen 阻止了一个无法识别的应用启动。 点击 **「更多信息」**,然后点 **「仍要运行」**。代码签名会在后续版本加上。
AgentOS-Worker 账户 Orbital 会用一个独立的低权限本地 Windows 账户 **AgentOS-Worker** 来运行 agent 的命令,这样 agent 读不到你的用户配置、浏览器数据和各类凭据。安装程序会在写入任何文件之前先说明这一点。 - 该账户在安装过程中创建,不会出现在登录界面。 - 它的密码是随机生成的,没有人知道,也不需要有人知道。 - 卸载 Orbital 时会一并删除该账户。 - 让该账户能读取你的开发工具(npm、cargo、Python 等所在的目录)这一步,会在 Orbital 第一次启动时在后台完成,不会拖慢安装。 - 在项目目录里,该账户不能写入 `.git\config` 和 `.git\hooks`(这两处会在沙箱之外执行代码),因此 agent 执行 `git remote add`、`git config --local` 或修改 hook 会失败;其他 git 命令——`git status`、`git log`、`git add`、`git commit`、`git checkout`——都正常。 在「计算机管理 → 本地用户和组 → 用户」里看到的 AgentOS-Worker,描述栏会写明它属于 Orbital。
### macOS 1. 从 [Releases](https://github.com/zqiren/Orbital/releases/latest) 下载最新的 `Orbital-*-macOS.dmg` 2. 打开 DMG,把 Orbital 拖到 Applications 文件夹 3. 从启动台或 Spotlight 启动 Orbital 需要 macOS 13 (Ventura) 及以上,**仅支持 Apple Silicon(M1 及更新机型)**。本版本为 arm64 构建,**不支持 Intel Mac**。 正式发布版已完成 Developer-ID 签名和 Apple 公证(notarization),首次启动直接打开——没有 Gatekeeper 拦截,不需要任何「仍要打开」操作。(从源码自行构建或下载 CI 分支产物的版本仍是 ad-hoc 签名,macOS 会要求你右键 → 打开确认一次。) ### 从源码运行 ```bash git clone https://github.com/zqiren/Orbital.git && cd Orbital # 安装 Python 依赖(Python 3.11+) pip install -e ".[desktop]" # 安装前端依赖(Node.js 18+) cd web && npm install && cd .. # 启动 daemon python -m uvicorn agent_os.api.app:create_app --factory --port 8000 # 另开终端启动前端 cd web && npx vite --host 127.0.0.1 --port 5173 ``` 浏览器打开 `http://localhost:5173`,首次启动会进入设置向导。 ### 关于休眠 Agent 运行期间,Orbital 会通过系统级别的接口阻止机器进入休眠(Windows 和 macOS 都支持)。所有 agent 闲下来之后,会重新允许系统休眠。系统托盘图标会显示当前 agent 活动状态。 --- ## 开发与测试 后端、前端、测试相关命令、关键文件路径请参见 [English README](README.md#development) 中 **Development** 与 **Testing** 章节。这部分文档以英文为准,避免中英两份各自维护导致内容不同步。 --- ## Roadmap **已完成:** 多 LLM 路由 + 失败轮换、三档 autonomy preset(并向 sub-agent 级联)、流式 chat + WebSocket 实时事件、带反检测的浏览器自动化(Patchright)、定时 / 文件监听 trigger、自然语言创建 trigger、cloud relay + 推送通知 + 设备配对、上下文压缩 + 压缩前记忆记录回合、前缀缓存优化的 prompt 组装(v0.4.2)、按项目的预算上限和成本统计、凭据管理(API key + 网站登录)、桌面应用 + 系统托盘 + 原生窗口、agent loop 安全保护(迭代上限、重复检测、ping-pong、断路器)、agent 活动期间的系统休眠抑制、`@mention` 路由的 sub-agent 派发。 **接下来:** Webhook trigger、pipeline trigger(把一个项目的输出作为另一个的输入)、按项目的网络隔离(OS 级 domain allowlist)、Linux 上的 bubblewrap 沙箱、Windows 代码签名(消除 SmartScreen 警告)、daemon 重启后自动恢复进行中的会话。 --- ## 我为什么做 Orbital 我喜欢 Claude Projects,但受不了 agent 不能自己更新项目,也受不了它不在我自己的机器上。 我喜欢 OpenClaw,但受不了那种失控感——没有预算,没有 sandbox,人离开电脑就没法从手机上监督。 Orbital 就是我自己想要的那个东西:一个对整个项目负责的 agent——计划、决策、队列、预算和审批都归它管理。不在电脑前时用手机看一眼。Claude Code、Codex、Gemini CLI 是它可以按任务选择的 worker,但项目的上下文始终留在管理 agent 手里。 全职工作之余的晚上和周末做出来的,还很早期。欢迎反馈和 issue。 --- ## 赞助致谢

观猹 (Watcha)

Orbital 由 **[观猹 (Watcha)](https://watcha.cn)** 赞助支持。观猹是 Orbital 内置的中国大陆模型路由 **[词元跳动 (TokenDance)](https://tokendance.space)** 背后的团队。得益于这次赞助,中国大陆的新用户在引导页即可一键登录词元跳动、免费领取 Token、立即开始使用——无需手动配置 API Key。 --- ## Star History

Orbital 的 star 增长曲线

--- ## 遥测(Telemetry) Orbital 每天发送**一份匿名汇总**——仅包含计数、枚举和布尔值。绝不包含提示词、文件、路径、模型输出或任何项目/会话标识。在 **设置 → 数据与隐私** 中可逐字查看即将发送的完整 JSON,并可一键关闭。完整的公开 schema 见 [docs/TELEMETRY.md](docs/TELEMETRY.md)。 --- ## License Orbital 采用 [GNU General Public License v3.0](LICENSE) 协议开源。 ``` Orbital — Every agent owns a session. Orbital owns the project. Copyright (C) 2026 Orbital Contributors This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. ```