常见问题

Q: 我可以自由使用 Takuto 吗？

可以。 自托管 Takuto Core 供你自己使用 —— 在你的机器上，或在你公司内部 —— 是免费的： 不向项目付费，没有席位限制，它也不会对你施加任何用量上限。引擎以 FSL-1.1-ALv2 源码可得， Takuto CLI 采用 MIT，所以你可以出于任何非竞争目的自由地运行、修改和自托管它。没有 遥测，也不会有任何东西 phone home。 唯一值得了解的一条限制：FSL 禁止竞争性使用 —— 你不能用 Takuto Core 去提供一个有竞争 关系的产品或托管服务。内部使用、评估，以及通过专业服务为客户开展的工作都没问题，而且每个版本 都会在发布两年后转为 Apache-2.0。如果这些条款不符合你的需求，请 联系我。

Q: 运行它要花多少钱？

Takuto Core 本身不向你收费 —— 收费的是你的 AI 提供商。 agent 用你的账号运行 Claude Code、Cursor Agent、Codex 或自托管模型，每个工单消耗的 token 量与代码库规模、 prompt 上下文以及你 workflow 的步骤数成正比。 具体花费完全取决于你选择的提供商和模型 —— 请查阅它们的当前价格，并留意最初几次运行，以摸清自己的实际用量。 省钱的抓手： 对确定性工作（lint、测试）使用命令步骤 —— 它们不消耗 AI token。 用 [jira] ticket_context_max_description_bytes 给上下文设上限。 在指向真实待办之前，先用 [general] dry_mode = true 预演。 通过 OpenCode 使用自托管模型可完全免去按 token 计费（你只为硬件买单）—— 参见 自托管模型。

Q: 它能用于生产了吗？

Takuto Core 处于 beta 阶段。它今天就能用，已经有人在用它跑真实的 workflow —— 但难免有粗糙之处，欢迎一切反馈。beta 状态也正是本站文案为何更偏向 “试试看，告诉我们 哪里坏了”，而不是 “企业级就绪” 的原因。每一份报告都在帮助塑造项目接下来的走向。

Q: 我能贡献吗？为什么不接受 pull request？

Takuto Core 是源码可得的，但作者目前不接受 pull request。 这是出于法律原因的一个 有意为之的临时立场：项目需要时间被观察并妥善地理顺结构 —— 贡献者许可、治理和商标都 需要先就位，外部代码才能被负责任地合并。 这并不意味着不欢迎反馈 —— 恰恰相反。bug 报告、功能建议和一般反馈都非常欢迎。 提一个 issue，或通过 takuto-team@proton.me 联系。这项限制专门针对 合并外部代码，而非围绕项目的交流。

Q: 许可是怎样的？

两个组件，两种许可： Takuto Core（你自托管的那个引擎）以 Functional Source License 1.1（FSL-1.1-ALv2） 源码可得：可用于任何非竞争用途，且每个版本都会在发布两年后转为 Apache-2.0。你不能用它去 提供一个有竞争关系的产品或托管服务。如果这些条款不符合你的需求，欢迎通过 takuto-team@proton.me 联系 —— 很乐意聊聊。 Takuto CLI（配套的设置工具）采用 MIT 许可。 Takuto Core 源码在 https://github.com/takuto-team/takuto-core；CLI 在 https://github.com/takuto-team/takuto-cli。

Q: 你们会收集任何数据或遥测吗？

不会。Takuto Core 不收集也不传输任何遥测 —— 没有使用分析、没有崩溃上报、没有 phone-home。你可以自己在源码里核实。 所有出站流量都走一道 egress 防火墙：默认拦截一切，只放行一次执行所需的 —— 你的 AI 提供商、 GitHub/Jira 和 package registry（可用 [network] extra_egress_hosts 再添加）。你的工单内容、 源代码和 prompt 只会发往你选定的 AI 提供商 —— Takuto Core 本身从不看到它们 —— 而使用自托管模型时， 任何东西都不会离开你的基础设施。

Q: 它是如何隔离的？自主运行 agent 安全吗？

隔离是一个核心设计目标： 每个 agent 都跑在自己的 container 里，所以一次 prompt injection 攻击的影响范围 被限制在那个 container 内。 egress 防火墙限制任何 agent 能通过网络访问到什么。默认的允许清单会拦截除一次执行所需主机 以外的一切 —— 这是最严格的设置，但像 GitHub 这类有 CDN 的服务，逐一列举主机会很麻烦。当不便如此时， [network] allow_all_https 改为放行所有出站 HTTPS；配合上面的每容器隔离，这仍是一个稳妥的姿态。 必须开启分支保护 —— agent 推送分支、提交 PR，从不直接提交到 main。再结合 最小权限 token（一个细粒度的 GitHub PAT、一个权限受限的 Jira 服务账号），就框定 了一个被劫持的会话实际上能做什么。 Takuto Core 在工单文本周围加了显式的不可信内容框定，以及可选的字节上限，这能降低 prompt injection 的风险，但不能消除它 —— PR 上的人工代码评审仍是你的最后防线。

Q: 支持哪些 AI agent？

Claude Code Cursor Agent Codex OpenCode（仅限自托管模型） 你在 Configuration → AI Settings 中挑选提供商；每个都有自己的 [agent.providers. ] 设置。参见 配置参考。

Q: 我需要什么样的硬件？

下面这些数字是粗略估计，而非硬性要求 —— 你的真实需求取决于项目、你的提供商以及你的 并发数。作为参考，作者在一台 配 16 GiB 内存的 Apple M1 Pro 上开发并运行 Takuto Core。 内存： 单个 workflow ≥ 8 GiB；在 macOS 上用 Podman 时 ≥ 12 GiB（VM 需要分走 自己的一份）。用 [general] max_concurrent_workflows 来扩展。 磁盘： ≥ 30 GiB 可用 —— worktree、npm/cargo 缓存、mise 工具链以及可选的 Docker-in-Docker 层都存放在 Docker 卷里。 操作系统： 服务器部署推荐 Linux 主机；macOS 在本地使用时表现良好。 自托管模型所需要的要多得多 —— 按你打算服务的模型来配置 GPU/显存。

Q: 为什么我用 localhost 时数据库连接会失败？

Takuto 跑在一个 container 里，所以一个 localhost 连接串指回的是 Takuto 自己， 而不是你的数据库。请在共享的 Docker 网络上使用数据库 container 的服务名及其内部端口 （例如 postgres://…@postgres:5432/…）—— 而不是 localhost 或宿主机发布的端口。使用 CLI 时， 在 takuto setup 里选择 “一个跑在本机上的数据库 container”，它会替你接好这些。参见 外部数据库。

我可以自由使用 Takuto 吗？

可以。 自托管 Takuto Core 供你自己使用 —— 在你的机器上，或在你公司内部 —— 是免费的：不向项目付费，没有席位限制，它也不会对你施加任何用量上限。引擎以 FSL-1.1-ALv2 源码可得， Takuto CLI 采用 MIT，所以你可以出于任何非竞争目的自由地运行、修改和自托管它。没有遥测，也不会有任何东西 phone home。

唯一值得了解的一条限制：FSL 禁止竞争性使用 —— 你不能用 Takuto Core 去提供一个有竞争关系的产品或托管服务。内部使用、评估，以及通过专业服务为客户开展的工作都没问题，而且每个版本都会在发布两年后转为 Apache-2.0。如果这些条款不符合你的需求，请联系我。

运行它要花多少钱？

Takuto Core 本身不向你收费 —— 收费的是你的 AI 提供商。 agent 用你的账号运行 Claude Code、Cursor Agent、Codex 或自托管模型，每个工单消耗的 token 量与代码库规模、 prompt 上下文以及你 workflow 的步骤数成正比。

具体花费完全取决于你选择的提供商和模型 —— 请查阅它们的当前价格，并留意最初几次运行，以摸清自己的实际用量。

省钱的抓手：

对确定性工作（lint、测试）使用命令步骤 —— 它们不消耗 AI token。
用 [jira] ticket_context_max_description_bytes 给上下文设上限。
在指向真实待办之前，先用 [general] dry_mode = true 预演。
通过 OpenCode 使用自托管模型可完全免去按 token 计费（你只为硬件买单）—— 参见自托管模型。

它能用于生产了吗？

Takuto Core 处于 beta 阶段。它今天就能用，已经有人在用它跑真实的 workflow —— 但难免有粗糙之处，欢迎一切反馈。beta 状态也正是本站文案为何更偏向 “试试看，告诉我们哪里坏了”，而不是 “企业级就绪” 的原因。每一份报告都在帮助塑造项目接下来的走向。

我能贡献吗？为什么不接受 pull request？

Takuto Core 是源码可得的，但作者目前不接受 pull request。 这是出于法律原因的一个有意为之的临时立场：项目需要时间被观察并妥善地理顺结构 —— 贡献者许可、治理和商标都需要先就位，外部代码才能被负责任地合并。

这并不意味着不欢迎反馈 —— 恰恰相反。bug 报告、功能建议和一般反馈都非常欢迎。 提一个 issue，或通过 morphet.contact@gmail.com 联系。这项限制专门针对合并外部代码，而非围绕项目的交流。

许可是怎样的？

两个组件，两种许可：

Takuto Core（你自托管的那个引擎）以 Functional Source License 1.1（FSL-1.1-ALv2） 源码可得：可用于任何非竞争用途，且每个版本都会在发布两年后转为 Apache-2.0。你不能用它去提供一个有竞争关系的产品或托管服务。如果这些条款不符合你的需求，欢迎通过 morphet.contact@gmail.com 联系 —— 很乐意聊聊。
Takuto CLI（配套的设置工具）采用 MIT 许可。

Takuto Core 源码在 https://github.com/takuto-team/takuto-core；CLI 在 https://github.com/takuto-team/takuto-cli。

你们会收集任何数据或遥测吗？

不会。Takuto Core 不收集也不传输任何遥测 —— 没有使用分析、没有崩溃上报、没有 phone-home。你可以自己在源码里核实。

所有出站流量都走一道 egress 防火墙：默认拦截一切，只放行一次执行所需的 —— 你的 AI 提供商、 GitHub/Jira 和 package registry（可用 [network] extra_egress_hosts 再添加）。你的工单内容、源代码和 prompt 只会发往你选定的 AI 提供商 —— Takuto Core 本身从不看到它们 —— 而使用自托管模型时，任何东西都不会离开你的基础设施。

它是如何隔离的？自主运行 agent 安全吗？

隔离是一个核心设计目标：

每个 agent 都跑在自己的 container 里，所以一次 prompt injection 攻击的影响范围被限制在那个 container 内。
egress 防火墙限制任何 agent 能通过网络访问到什么。默认的允许清单会拦截除一次执行所需主机以外的一切 —— 这是最严格的设置，但像 GitHub 这类有 CDN 的服务，逐一列举主机会很麻烦。当不便如此时， [network] allow_all_https 改为放行所有出站 HTTPS；配合上面的每容器隔离，这仍是一个稳妥的姿态。
必须开启分支保护 —— agent 推送分支、提交 PR，从不直接提交到 main。再结合 最小权限 token（一个细粒度的 GitHub PAT、一个权限受限的 Jira 服务账号），就框定了一个被劫持的会话实际上能做什么。

Takuto Core 在工单文本周围加了显式的不可信内容框定，以及可选的字节上限，这能降低 prompt injection 的风险，但不能消除它 —— PR 上的人工代码评审仍是你的最后防线。

支持哪些 AI agent？

Claude Code
Cursor Agent
Codex
OpenCode（仅限自托管模型）

你在 Configuration → AI Settings 中挑选提供商；每个都有自己的 [agent.providers.<name>] 设置。参见配置参考。

我需要什么样的硬件？

下面这些数字是粗略估计，而非硬性要求 —— 你的真实需求取决于项目、你的提供商以及你的并发数。作为参考，作者在一台 配 16 GiB 内存的 Apple M1 Pro 上开发并运行 Takuto Core。

内存： 单个 workflow ≥ 8 GiB；在 macOS 上用 Podman 时 ≥ 12 GiB（VM 需要分走自己的一份）。用 [general] max_concurrent_workflows 来扩展。
磁盘： ≥ 30 GiB 可用 —— worktree、npm/cargo 缓存、mise 工具链以及可选的 Docker-in-Docker 层都存放在 Docker 卷里。
操作系统： 服务器部署推荐 Linux 主机；macOS 在本地使用时表现良好。
自托管模型所需要的要多得多 —— 按你打算服务的模型来配置 GPU/显存。

为什么我用 `localhost` 时数据库连接会失败？

Takuto 跑在一个 container 里，所以一个 localhost 连接串指回的是 Takuto 自己，而不是你的数据库。请在共享的 Docker 网络上使用数据库 container 的服务名及其内部端口 （例如 postgres://…@postgres:5432/…）—— 而不是 localhost 或宿主机发布的端口。使用 CLI 时，在 takuto setup 里选择 “一个跑在本机上的数据库 container”，它会替你接好这些。参见外部数据库。

保存我的 GitHub PAT 或 AI 密钥时报连接错误 —— 是我的 token 错了吗？

通常不是。校验 token 只会访问一个提供商端点，所以失败几乎总是指向网络/egress 问题，而非凭据有误 —— 往往是某个由 CDN 支撑、IP 会轮换的主机，比如 api.github.com。请检查 egress 允许清单能否解析到提供商当前的主机，并用 [network] extra_egress_hosts 把缺失的补上。参见配置 → network。

我的自托管模型返回 “Model not found” 或上下文错误。

两个常见原因：(1) 在你的服务器里以 Takuto 预期的上下文宽度加载模型 —— 把 [agent.providers.opencode] context_limit 设为与你服务器实际提供的相匹配（例如 LM Studio 默认是 4096，而不是 32768）；以及 (2) 模型 id 必须与提供商精确的 API 标识符相符。参见自托管模型。

重置某个 Docker 卷后，我保存的 API 密钥不再生效了。

凭据是用一个主密钥（secret.key）加密的，该密钥存放在 takuto-data 卷上。如果你删除或重建那个卷，用旧主密钥封存的密钥就再也无法解密 —— 表现出来的症状是一个令人困惑的 “authentication” 或 “not found” 错误，而非明显的加密失败。请重新打开提供商设置并逐一重新录入每个密钥。要让主密钥在多次重置之间保持稳定，请自行提供 TAKUTO_SECRET_KEY，而不要依赖自动生成。

agent CLI 在启动时安装失败或出问题 —— 我能怎么办？

agent CLI（claude / codex / opencode / cursor）并未烤进镜像里 —— Takuto 会在 container 首次启动时把它们安装进共享的工具卷，并在每次启动时刷新到 latest。因此一个刚发布的 CLI 版本可能会让原本正常的环境出问题：安装失败、CLI 无法再启动，或运行时行为发生变化。

如果你遇到这种情况，请在该提供商的子表里用 version 把 CLI 锁定到一个已知可用的版本，让它不再跟随 latest：

[agent.providers.claude]
version = "2.1.178"

四个提供商（claude、codex、opencode、cursor）都支持这样做。重启以让锁定的版本完成安装，之后在确认某个更新版本可用后再有意地提升锁定版本。参见 Configuration → agent CLI 的安装与版本锁定。

提交和 PR 归属到谁名下 —— 我还是某个机器人？

归属跟随你的凭据，对提交和 pull request 一视同仁：使用 GitHub PAT 时，两者都归属到你；仅使用 GitHub App（没有 PAT）时，两者都归属到那个机器人。没有按运行切换的开关。参见 GitHub App。

为什么 “Mark as Done” 没有移动我的 Jira 工单？

Mark as Done 会把工单流转到你的 [jira] done_status。当你 Jira 项目的工作流从工单当前状态到该状态没有任何流转，或者你的 token 缺少流转权限时，它就会失败。请把 done_status 设为你看板工作流中实际可达的状态。（状态名本身是按语言无关的方式匹配的，所以像 “Terminé(e)” 这样的本地化名称仍会解析为 “Done”。）

我能把 Takuto 部署在一个公开域名后面吗？

可以。把它放在一个带 TLS 的反向代理后面（参见安装 Takuto Core），并依靠内置的多用户认证。由于那道登录就是关卡，而 Takuto 尚不支持 2FA/OTP 或安全密钥（passkeys/WebAuthn），请为每个账号使用一个强且唯一的密码。内置的防护会有帮助 —— argon2 密码哈希、多次失败尝试后的账号锁定，以及登录时按 IP 的速率限制 —— 但目前密码才是你主要的防线。请把分支保护和最小权限 token 留作最后的后备。

接下来去哪儿？

新手？从 快速上手 开始。
在带团队？参见 安装 Takuto Core。
在调行为？配置参考 收录了每一个键。