快速上手

标准的 “立刻试一试” 路径：安装 Takuto CLI，运行 takuto setup 再 takuto start，然后到仪表盘里收尾。大约花几分钟。

推荐的设置方式。 有几个选择能让运行最为顺畅、也最贴近生产就绪：

  • 用 GitHub App 来认证 GitHub，而不是个人访问令牌（PAT）。这样 PR 就会以一个专用的 bot 身份开启，而非你的个人账号 —— 作者归属更清爽，访问权限也始终 被收敛在该 app 所授予的范围内。
  • 保护好 agent 会作为目标的那些分支。 一个自主运行的 agent 能做它的 token 所允许的任何 事，所以请在 main（以及任何目标分支）上开启 branch protection：合并前必须经过 PR、 必须有一个批准评审，并禁止直接推送。再搭配一个 bot 身份，即便你单干也能拥有一道强制的评审 关卡。
  • 使用外部数据库（Postgres / MySQL / MariaDB），让你的数据 存放在 container 之外，并且可以备份。

下面的一切即便没有这些也能照常工作，但它们值得你尽早配置好。

更想不借助 CLI、自己跑引擎？关于自建 container 的路径，参见 安装 Takuto Core。

1. 创建你将需要的 token

开始之前先把这些准备好 —— 你会在仪表盘里把它们填进去（第 6 步）：

  • 一份 AI 提供商凭据 —— 以下之一：用于 Claude Code 的 Anthropic API key（或一个 Claude Pro/Max 登录）、用于 Codex 的 OpenAI API key、用于 Cursor Agent 的 Cursor API key —— 或者，如果你通过 OpenCode 跑自托管模型，则无需任何凭据。
  • GitHub 访问权限 —— 一个细粒度个人访问令牌，限定到 Takuto 将要处理的那些仓库 （Contents 和 Pull requests：read & write；Metadata：read；如果你轮询 GitHub Issues， 则 Issues：read & write）。更好的做法是配置一个 GitHub App， 让 PR 来自一个限定范围的 bot 身份，而非你的个人账号。
  • Jira（仅当你将轮询 Jira 时） —— 一个 Atlassian API token，对应 Takuto 应当 以其身份行事的那个账户。

把每个 token 都收敛到它所需的最小范围 —— 它们框定了一个自主运行的 agent 能触及的边界。

2. 安装 CLI

Homebrew（macOS / Linux —— 推荐）：

brew install takuto-team/tap/takuto

手动下载二进制文件（包括 Windows），请参见 Releases 页面 和 CLI 参考。

3. 前置条件

你只需装好 Docker 或 Podman —— CLI 会自动识别你装的是哪一个。

你不必自己拉取 Takuto Core 镜像：takuto start 会在首次运行时替你拉取（离线时则回退 到本地缓存的副本）。该镜像以公开方式发布，拉取时无需对 registry 进行认证 —— 不过如果 你愿意，也可以用 docker pull ghcr.io/takuto-team/takuto-core:latest 预先手动拉好。

4. 生成你的配置

takuto setup

这个向导很短：如今大部分配置都交由仪表盘处理，所以它只会询问仪表盘端口 —— 以及，如果你使用外部数据库（Postgres / MySQL / MariaDB），它的连接信息（否则默认 使用内置的 SQLite）。其余一切 —— 工单系统、AI 提供商和模型、轮询、workflow —— 都留到 之后在仪表盘里设置。它会生成 takuto.yml，外加一个含 config.toml、密钥（takuto.env） 和一个起步流水线定义文件夹 workflows/ 的 .takuto/ 文件夹：

takuto.yml                  # Docker Compose 编排
.takuto/
  config.toml                # bootstrap 配置
  takuto.env                # 密钥和 API token
  workflows/                 # 流水线步骤定义
    implement_ticket.toml
    merge_base.toml
    address_pr_comments.toml

这个 .takuto/ 文件夹在你运行命令的任意位置被创建 —— 它不一定得是某个项目目录。 在不同的文件夹里运行 takuto setup/takuto start，就能让多个相互隔离的 Takuto 实例并存：每个都有自己独立的配置、认证、workspace 和数据库，无需任何额外配置。

想用外部的 PostgreSQL、MariaDB 或 MySQL（用于多用户或生产部署）而非内置的 SQLite？参见 外部数据库。

5. 启动 Takuto

takuto start

然后在浏览器中打开仪表盘 —— 默认是 http://localhost:8080， 或你在 takuto setup 时所选的端口。takuto start 会拉取镜像（首次运行时）并把整个技术栈 启动起来。首次启动时，仪表盘会提示你创建初始的 admin 账号。

6. 认证并添加一个项目

把第 1 步里的那些 token 加进来，然后把 Takuto 指向一个仓库：

  • 推荐 —— 第 1 步里的那些 token： 从仪表盘的 Configuration 界面填入你的提供商 key 和 GitHub token（ANTHROPIC_API_KEY、CURSOR_API_KEY、OPENAI_API_KEY、一个限定 范围的 GH_TOKEN……），或在启动前把它们放进 .takuto/takuto.env（参见 配置）。
  • 在仪表盘里点击 “Setup a New Project”，克隆你想让 Takuto 干活的那个仓库。
  • 如果你配置了 Jira 或 GitHub Issues，轮询会自动开始并领取 “To Do” 工单。否则 点击 + 粘贴一段描述，手动启动一个 workflow。

可选 —— takuto auth（不推荐）。 takuto auth 会在 CLI 里跑交互式的 OAuth 登录（GitHub + 你的 AI 提供商）。OAuth 会授予宽泛的账号访问权限，因此我们更推荐改用上面 那种限定范围的 API key / token。只有在你确实需要交互式登录流程时，才使用 takuto auth。

接下来会发生什么

每个 workflow 都会从你的 base 分支创建一个 git worktree，运行你的 worktree 初始化 命令（例如 npm ci），然后执行你 TOML workflow 定义中的 agent 步骤。在每张 workflow 卡片上观看实时终端输出，并可用 Open editor 在任意 worktree 上打开基于浏览器的 VS Code 编辑器。

关于完整的 workflow 生命周期，参见 工作原理；关于 stop、 restart 和多项目隔离，参见 CLI 参考。

停止与重启

takuto stop       # 停止 Takuto 服务
takuto restart    # 重启 Takuto 服务

所有认证状态、workflow 快照和缓存都存放在命名的 Docker 卷里，所以 workflow 能挺过 一次重启 —— 暂停的或进行中的运行会自动恢复。