故障排查

常见问题及其修复办法，汇集自 Takuto Core 引擎和 Takuto CLI 两边。自托管模型的 问题参见 自托管模型；provisioning 的问题参见 扩展 Takuto Core。

网络与 egress

npm ci 失败 / “Exit handler never called”

你的 npm registry 被 egress 防火墙拦住了。查看调试日志：

docker exec -u takuto <container> tail -30 /home/takuto/.npm/_logs/*-debug-0.log

把该 registry 域名加进 config.toml 的 [network] extra_egress_hosts 并重启。

Claude Code “api_retry error: unknown”

提供商的 API 端点被拦住了。egress 防火墙会自动放行 [agent].available_providers 中每一个 提供商的主机，所以先确认你正在使用的提供商已列在那里。然后从 container 内部验证可达性：

docker exec -u takuto <container> curl -s -o /dev/null -w "%{http_code}" https://api.anthropic.com

如果某个主机仍然访问不到（例如某个会轮换 IP 的厂商端点，或一个自托管网关），把它加进 [network] extra_egress_hosts。

数据库

“Database backend unreachable” / pool timed out

[database] connection 里的外部数据库无法从 Takuto container 内部访问到，于是它回退 到旧版 SQLite（或者，若 fail_fast = true，则中止）。常见原因出在连接主机上：如果数据库 跑在某个 container 里，连接串必须使用数据库的 container 名及其内部端口（例如 takuto_db:5432）—— 而不是 localhost 或宿主发布的端口（例如 localhost:5433），并且 两个 container 必须共享一个网络。完整的操作指引以及各引擎的连接串见 外部数据库。

认证

重新构建或重启后找不到认证

认证存在 Docker 卷里。如果卷被删了，重新跑一遍 setup 流程：

# With the CLI
takuto auth

# Running the engine directly
docker compose run --rm -it takuto setup

takuto start / docker compose up 在 “Egress rules applied” 之后卡住

认证预检正在运行。卡在这里通常是 agent status 在没有 TTY 的情况下阻塞。对 Cursor， 在 takuto.env 里设置 CURSOR_API_KEY 以跳过交互式检查；否则重新构建镜像。

Cursor Agent 登录错误

这些都意味着你停在了一个过时的镜像层上。重新构建：

# With the CLI
docker compose -f takuto.yml build --no-cache

# Running the engine directly
docker compose build --no-cache

重新构建能修复的症状：

  • bad option: --use-system-ca（旧层用的是 Node 20；当前镜像带的是更新的 Node）。
  • /usr/local/bin/node: No such file or directory（旧层里的 Node 二进制被移除了）。
  • Cannot find module '/usr/local/bin/index.js'（cursor-agent 目录树不完整）。

项目工具版本（mise）

镜像会安装 mise，并在首次运行时构建工具；安装内容会持久保留在 mise-data 和 mise-cache 卷里。用 .mise.toml 或 .tool-versions 文件按仓库锁定 运行时（例如 Node、Python、Ruby）。

Podman

带 SELinux 的 Linux

docker-compose.yml 设了 security_opt: [label=disable]。如果你必须保留 SELinux 标签，就从宿主用 bind mount 上的 :z / :Z 给卷重新打标签。

container 名称冲突

podman stop -a && podman rm -f $(podman ps -aq) 2>/dev/null
podman pod rm -f $(podman pod ls -q) 2>/dev/null

macOS 内存耗尽

Podman 的 VM 在 workflow 之外还需要分走自己的一份内存。启动前给它多一点：

podman machine stop && podman machine set --memory 12288 --cpus 4 && podman machine start

日志

按 workflow 的日志文件存在 container 内部：

docker exec <container> cat /workspace/logs/<TICKET-KEY>.log

仪表盘也会在每张 workflow 卡片上实时输出终端日志，按条目的日志保留时长由 [general] work_item_log_retention_days 控制。

还是卡住？

Takuto Core 处于 beta 阶段 —— 如果你撞上了这里没覆盖的问题，我们真心欢迎你的 反馈。如何联系作者参见 FAQ，某项设置背后的确切键则查阅 配置参考。