Skip to content

windows-setup.md

Latest commit

 

History

History
214 lines (151 loc) · 8.51 KB

windows-setup.md

File metadata and controls

214 lines (151 loc) · 8.51 KB
Raw

Windows + WSL 安装指南

中文 | English · 文档与语言设置

除另有说明外，本文中的项目命令在仓库根目录运行。

本项目在 Windows 上采用：

  • Windows PowerShell 作为控制入口
  • WSL2 (Ubuntu + systemd) 作为执行内核
  • WSL systemd --user 提供守护与崩溃自拉起
  • Windows scripts/windows/awake-guardian-win.ps1 提供运行时防睡眠
  • Windows scripts/windows/wsl-anchor-win.ps1 提供 WSL 会话保活（防止空闲退出）

1. 一次性安装（WSL 内）

在 Ubuntu 终端执行：

sudo apt update
sudo apt install -y git make python3 curl

# 安装 Node.js（推荐 LTS）
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt install -y nodejs

# 安装 Claude Code（默认引擎）
npm install -g @anthropic-ai/claude-code

# 可选：安装 Codex CLI（用于 ENGINE=codex）
npm install -g @openai/codex

2. 一次性自检（WSL 内）

make --version
claude --version
codex --version
python3 --version
systemctl --user --version
ps -p 1 -o comm=

判定标准：

  • Python 3.10+，WSL Linux 内核 5.3+（进程身份校验需要 pidfd）
  • systemctl --user --version 成功
  • ps -p 1 -o comm= 输出 systemd
  • CLI 的 --version 成功只证明安装，不代表已经登录；首次实际 Cycle 会使用订阅额度或 API 计费

建议额外检查引擎路径（至少检查你要使用的引擎）：

bash -lc 'command -v claude; claude --version'
bash -lc 'command -v codex; codex --version'
bash -ic 'command -v claude; claude --version'
bash -ic 'command -v codex; codex --version'

应优先命中 WSL 本地路径（/home/<user>/...），避免 /mnt/c/...。

建议一次性启用 linger（提高 user service 持续性）：

wsl -d Ubuntu -u root loginctl enable-linger <your-user>

3. 前置事项（每次开始前）

  1. WSL 内 Git、make、Python 3.10+、claude、systemctl --user 可用（如需 codex，再确认 codex）。
  2. 目标引擎在 WSL 内已登录且可用（默认 claude）。
  3. 建议确认目标引擎路径优先是 WSL 本地路径（/home/...）。

可选快速检查（PowerShell）：

wsl -d Ubuntu bash -lc 'make --version; python3 --version; claude --version; systemctl --user --version'
wsl -d Ubuntu bash -lc 'command -v claude'
# Optional (for ENGINE=codex):
wsl -d Ubuntu bash -lc 'codex --version; command -v codex'

4. 推荐操作（标准）

在仓库根目录运行：

# Claude：先在没有密钥的一次性克隆中试运行
.\scripts\windows\start-win.ps1 -Engine claude -ClaudePermissionMode acceptEdits -CycleTimeoutSeconds 1800 -LoopInterval 30

# 切换 Codex
.\scripts\windows\start-win.ps1 -Engine codex -SandboxMode workspace-write -CycleTimeoutSeconds 1800 -LoopInterval 30

.\scripts\windows\status-win.ps1
.\scripts\windows\monitor-win.ps1
.\scripts\windows\last-win.ps1
.\scripts\windows\cycles-win.ps1
.\scripts\windows\stop-win.ps1
.\scripts\windows\dashboard-win.ps1

说明：

  • .\scripts\windows\start-win.ps1 只更新 .auto-loop.env 中显式传入的设置，保留已有预算等其他设置，并启动 autonomous-company.service + awake guardian + wsl anchor
  • 启停前会校验服务绑定的仓库；若它属于其他 worktree，会拒绝操作。请先人工确认应该使用哪个工作目录，不要为绕过提示而直接重新绑定现有服务
  • .\scripts\windows\stop-win.ps1 会停止 autonomous-company.service 并关闭 awake guardian + wsl anchor
  • .\scripts\windows\dashboard-win.ps1 与 center-win.ps1 启动同一产品中心（默认 http://127.0.0.1:8810/center），从中心进入产品详情
  • 也可在 WSL 仓库目录执行 make dashboard 或 make center。网页启动不会自动接管或启动旧运行；使用界面的“接入已有产品”或 -Source <完整运行目录> 只读接入历史记录。需要执行工作时，在中心明确选择执行环境并授权对应产品；底层服务命令仍校验原服务归属

推荐参数：

  • CycleTimeoutSeconds：900-1800
  • LoopInterval：30-60
  • Engine：claude（默认）或 codex
  • SandboxMode：仅在 ENGINE=codex 时生效（兼容旧参数 CodexSandboxMode）
  • ClaudePermissionMode：为兼容保留 bypassPermissions 默认；首次试运行显式使用 acceptEdits，可能因需要交互确认而失败。放宽权限前先评估仓库、网络和凭据风险

脚本定位说明：

  • 所有脚本实现位于 scripts/windows/、scripts/core/、scripts/wsl/、scripts/macos/
  • 日常执行入口也统一使用 scripts/ 下脚本
  • 如需维护逻辑，请直接修改 scripts/ 下对应实现文件

运行与界面语言

产品中心的“设置”分别保存界面语言与新工作的默认产品语言。界面语言控制中心、详情标签和本地帮助；首次默认读取 Windows 显示语言，中文使用 zh-CN，其他语言使用 en。新建工作时确认产品语言，已有产品继续使用原语言。底层独立循环的语言在其运行目录另行配置，例如：

python scripts/core/localization.py set --language en

启动参数 ./scripts/windows/start-win.ps1 -Language en 也保存该运行目录的循环语言偏好。这些命令不修改已保存的中心偏好；首次建立中心时可读取安装配置作为新工作初始默认值。独立循环已有产品周期保持原语言，暂停、重启不会改变，新偏好从下一个产品周期生效。所有技能统一英文，面向用户的结果跟随产品语言。完整说明见语言设置。

5. 可选：登录后自启

默认不启用。需要时执行：

.\scripts\windows\enable-autostart-win.ps1
.\scripts\windows\autostart-status-win.ps1

关闭：

.\scripts\windows\disable-autostart-win.ps1

自启任务名：AutonomousCompany-WSL-Start（触发器：At logon）。 若提示 Access is denied，请使用管理员 PowerShell 重新执行。

6. Chat-first 模式（和 Claude/Codex 对话）

如果你不想手动执行命令，可直接在 Windows 里和 Claude/Codex 对话，让它代你操作。

底层链路：

scripts/windows/start-win.ps1 -> WSL systemd --user -> scripts/core/auto-loop.sh

与手动命令的核心行为一致，差异只在入口方式。

7. 常见问题

bad interpreter: /bin/bash^M

  • 原因：文件是 CRLF
  • 处理：
git config core.autocrlf false
git config core.eol lf

claude/codex 命令不存在（或 node not found）

  • 原因：WSL 中缺 Node 或缺目标引擎 CLI
  • 处理：回到第 1 步重新安装

Claude 运行时卡在权限确认

  • 原因：CLAUDE_PERMISSION_MODE 设置过严，导致非交互流程被阻塞
  • 处理：先检查需要批准的操作；只有确认能够信任工作目录与执行内容后，才考虑显式传 -ClaudePermissionMode bypassPermissions。它会跳过权限保护，不是通用修复
  • 排查：查看 logs/auto-loop.log 中 Engine: claude | ... | PermissionMode: ...

systemctl --user 不可用

  • 原因：WSL 未启用 systemd 或会话未正确初始化
  • 处理：
    • 先确认 ps -p 1 -o comm= 是 systemd
    • 再验证 systemctl --user --version
    • 必要时重开 WSL 会话后重试

日志显示 Engine bin 在 /mnt/c/...

  • 原因：PATH 先命中 Windows 侧 CLI
  • 影响：版本和行为可能与 WSL 本地终端不一致
  • 处理：在 WSL 内安装并优先使用本地 CLI（/home/<user>/...）

guardian 启动失败

  • 现象：scripts/windows/start-win.ps1 提示 daemon 已启动，但 guardian 启动失败并返回非零
  • 处理：先执行 .\scripts\windows\status-win.ps1 确认服务状态，再手动执行 .\scripts\windows\awake-guardian-win.ps1 -Action start

频繁出现 Cycle #1 START 且伴随 Auto Loop Shutting Down

  • 原因：WSL 会话被回收（常见于 linger 未开启或缺少 keepalive）
  • 处理：
    • 确认 wsl-anchor 为 RUNNING：.\scripts\windows\status-win.ps1
    • 一次性启用 linger：wsl -d Ubuntu -u root loginctl enable-linger <your-user>
    • 重启服务：.\scripts\windows\stop-win.ps1 然后 .\scripts\windows\start-win.ps1

自启脚本提示 Access is denied

  • 原因：当前 PowerShell 权限不足以写入计划任务
  • 处理：使用管理员 PowerShell 执行：
    • .\scripts\windows\enable-autostart-win.ps1
    • .\scripts\windows\disable-autostart-win.ps1