Optio 入门教程：在 Kubernetes 上部署你的 AI 编码工程平台

从 Issue 到合并 PR，中间要经历多少步？设计、编码、测试、CI、Code Review、修复、重新 CI……AI 编码 Agent 能帮写代码，却很难管理整个工程流程。你仍然需要手动创建分支、触发 Agent、等待 CI、检查 Review、合并。

Optio 填补了这个空白——一个自托管的 AI 工程平台，运行在你自己的 Kubernetes 集群上，支持 Claude Code、OpenAI Codex、GitHub Copilot、Google Gemini 和 OpenCode 五种 Agent 引擎。它的核心能力用一个流程图就能说明白：提交 Issue → Agent 写代码 → 开 PR → 等 CI → 等 Review → 自动修复 → 合并。全部自动完成。

项目在 GitHub 上拥有 993+ Star，MIT 开源许可证，由前 Google 工程师 Jon Wiggins 开发。本文带你从零开始部署 Optio，并完成第一个 Ticket-to-PR 任务。

安装准备

Optio 要求在你的 Kubernetes 集群上部署，本地开发可以用 Docker Desktop 自带的 K8s。

前置条件

• Kubernetes v1.33+（Docker Desktop 设置中启用 Kubernetes）
• Node.js 22+ 和 pnpm 10+
• Helm（包管理工具，brew install helm）

一键部署

git clone https://github.com/jonwiggins/optio.git && cd optio
./scripts/setup-local.sh

这个脚本会自动安装依赖、构建 Docker 镜像、通过 Helm 部署全部组件到本地集群。完成后：

Web UI ...... http://localhost:30310
API ......... http://localhost:30400

打开 Web UI，设置向导会引导你配置 GitHub 访问权限、Agent 凭据（API Key 或 Max/Pro 订阅），以及添加你的第一个仓库。

理解三层架构

Optio 把 Agent 工作分为三个层次：

Tasks（任务）——从 Issue/工单到合并 PR 的完整流水线。提交一个 GitHub Issue、Linear 工单、Jira 任务或 Notion 页面，Optio 自动创建隔离环境、运行 Agent、开 PR、监控 CI、触发 Code Review、自动修复失败，最后合并。

Jobs（作业）——不需要代码仓库的参数化 Agent 运行。生成报告、告警分类、依赖审计、查询数据库、发 Slack 消息——任何不需要落地为 PR 的工作。

Persistent Agents（持久 Agent）——长运行、消息驱动的 Agent 进程。每个 Agent 有固定的标识符、收件箱和循环状态机。Agent 之间可以通过 HTTP API 互相通信，形成多 Agent 团队。

三者的关系是：Tasks 和 Jobs 是「一次性运行」，运行结束就销毁；Persistent Agents 是「服务模式」，一直活着等消息。

生产部署

生产环境推荐从 Helm 仓库安装，而不是从源码构建：

helm repo add optio https://jonwiggins.github.io/optio
helm repo update
helm install optio optio/optio -n optio --create-namespace \
  --set encryption.key=$(openssl rand -hex 32) \
  --set postgresql.enabled=false \
  --set externalDatabase.url="postgres://..." \
  --set redis.enabled=false \
  --set externalRedis.url="redis://..." \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=optio.example.com

也支持从 OCI 仓库安装：

helm install optio oci://ghcr.io/jonwiggins/optio -n optio --create-namespace

生产环境中需要准备 PostgreSQL 16 和 Redis 7 作为外部依赖，它们分别负责任务状态存储和消息队列/实时流。

第一个 Task：从 Issue 到 PR

部署完成后，按以下步骤运行第一个 Task：

1. 在 GitHub 上创建一个 Issue，描述一个简单的功能（比如”给 README 加一个 Contribution 章节”）
2. 在 Optio Web UI 中导航到 “Tasks” → “New Task”
3. 选择仓库和对应的 Issue
4. 指定 Agent 引擎（如 Claude Code）和模型
5. 点击提交

Optio 会做以下事情：

• Provisioning：在 Kubernetes 中为这个仓库创建一个 Pod，用 Git Worktree 做隔离
• Execution：Agent 运行，写代码，开 PR
• PR Watcher：每 30 秒轮询 PR 状态
• Feedback Loop：如果 CI 失败 → 恢复 Agent 修复构建；如果有 Merge Conflict → 恢复 Agent 做 Rebase；如果 Reviewer 要求修改 → 带着反馈恢复 Agent
• Completion：CI 通过 + Review 批准 → Squash-Merge 并关闭 Issue

整个过程在 Dashboard 上实时可见——日志流、Pipeline 进度、耗时和 Token 消耗全部实时展示。

Persistent Agents：长期运行的 Agent 服务

Tasks 适合一次性的编码任务，但有些工作模式不适合”一次运行”——比如一个监控告警 Agent，需要一直监听 Webhook，收到告警后自动分析日志并创建 Jira 工单。

Optio 的 Persistent Agents 就是为此设计的。每个 Agent 有一个系统提示词和一套唤醒源（用户消息、其他 Agent 消息、Cron 定时、Webhook、工单事件）。Agent 每次执行一个 Turn 就停下来等待下次唤醒。

Pod 生命周期有三种模式：

• always-on：延迟最低但成本最高
• sticky（默认）：每个 Turn 结束后保持 Warm 一段时间
• on-demand：每次 Turn 冷启动

多个 Persistent Agents 之间可以通过 /api/internal/persistent-agents/ 接口互相发消息，形成多 Agent 协作团队。

集成外部服务

Optio 通过 Connections 系统注入外部服务的能力。配置一次提供方，分配给仓库或 Agent，Optio 会在 Agent Pod 启动时自动注入对应的 MCP 服务器。

内置提供方：GitHub、Slack、Linear、Notion、PostgreSQL、Sentry、文件系统，以及自定义 MCP 服务器和 HTTP API。

对于 GitHub 集成，推荐使用 GitHub App 而非 Personal Access Token。GitHub App 提供用户作用域的访问权限，自动刷新 Token，PR 和提交都有明确的归属人。在 Helm values 中配置：

github:
  app:
    id: "123456"
    clientId: "Iv1.abc123"
    clientSecret: "..."
    installationId: "789"
    privateKey: |
      [REDACTED PRIVATE KEY]

如果已有外部密钥管理（如 external-secrets-operator），可以用 existingSecret 引用现有 Secret。

技术栈一览

架构上采用 K8s 风格 Reconciliation 控制平面——纯决策加 CAS 执行器循环，配合定时重新同步，确保任务不会因为事件丢失而卡住。

使用场景

• 安全敏感的组织：不能把源代码发给第三方 SaaS 服务的团队。代码、密钥和 Agent 日志从不离开你的集群
• 受监管行业：金融、医疗、政务——数据驻留、可审计性和租户隔离是硬性要求
• 已运行 Kubernetes 的团队：Helm 一键部署，自带 PostgreSQL/Redis，集成现有监控和 Ingress
• 多 Agent 评估阶段：同时评估 Claude Code、Codex、Copilot 等多个 Agent，按仓库配置不同的引擎
• 平台工程团队：Optio 作为编排层，团队自配提示词、策略、集成和审查标准

总结

Optio 不是一个”AI 写代码工具”，而是一个”AI 工程平台”。它把 AI 编码 Agent 嵌入到完整的工程流程中——从 Issue 到合并，CI、Code Review、自动修复全部自动化。993+ GitHub Stars、MIT 许可证、自托管部署、多 Agent 支持，对于需要安全合规且不想被单一厂商锁定的团队来说，是一个值得认真评估的选择。

相关链接

• Optio GitHub 仓库
• 安装文档
• Helm Chart 配置
• Persistent Agents 文档