09 / HELP

常见问题

按症状查找处理方式。多数情况可以先用 /status 或 siada-cli --daemon-status 确认当前状态，再按步骤排查；拿不准时，也可以直接在会话里输入 /siada-help 描述问题。

启动与安装

输入 siada-cli 提示 command not found

安装后命令目录可能还没有进入当前终端的环境变量。让 uv 更新 shell 配置，然后重新打开一个终端窗口再试。

TERMINAL
uv tool update-shell
siada-cli --version

仍然找不到时，确认安装目录（通常是 ~/.local/bin）已加入 PATH。改动 shell 配置后重新打开终端；需要重新安装时参考 项目仓库的说明。

想确认有没有新版本

用 siada-cli --just-check-update 只做一次检查并返回结果，不会安装；需要立即升级时执行 uv tool upgrade siada-cli，或使用 siada-cli --upgrade。后台自动更新的开关见 版本自动更新。

模型与登录

回答中断、提示模型不可用或请求被拒绝

先确认当前会话用的是哪个模型和哪个工作区，再逐步排除：

  1. 输入 /status 查看当前模型、Agent、会话 ID 与工作区。
  2. 输入 /model 切换到已经配置好、确认可用的模型。
  3. 提示未登录或密钥无效时，输入 /configure 重新选择服务并填写 API Key。
  4. 使用自备服务时，检查 ~/.siada-cli/conf.yaml 的 llm_config：模型名称、服务地址与密钥要与服务商提供的一致。
交互输入
/status
/model
/configure

模型名称、地址与可用范围取决于你的服务配置，可选项以 /model 列表和 siada-cli --list-models 的输出为准。配置项的写法见 配置自己的模型服务。

浏览器连接

siada-browser status 显示代理在运行，但扩展没有连上

状态输出里 running 表示本机代理是否运行，extensionConnected 表示扩展是否已经连上。代理在运行而扩展未连接时，按顺序检查：

  1. 在 chrome://extensions 确认 Siada 扩展已启用；刚更新过扩展时，点一次重新加载。
  2. 打开扩展侧边栏的设置，确认连接地址与端口和本机一致，并粘贴安装时输出的 token。安装命令会打印 token 并自动复制到剪贴板；需要再次查看时，重新运行同一条安装命令会打印同一个 token（不会变化）。
  3. 重启代理后再看一次状态：
TERMINAL
siada-browser status
siada-browser restart
siada-browser status

确认扩展与命令使用的是同一个 Chrome 用户。连接正常后，页面任务的操作方式见 浏览器协作。

命令行与非交互任务

--prompt 里写 /model 这类命令没有反应

--prompt 的文本会直接交给 Agent 执行，不解析交互界面的内置斜杠命令。需要切换模型等效果时，改用对应的启动参数：

TERMINAL
siada-cli --model MODEL_ID -p "梳理这个目录的测试入口"
siada-cli -p "使用 siada-help 说明如何设置定时任务"

技能不同：把技能名写进提示内容可以直接调用，因为技能由 Agent 按描述执行。命令与参数的完整对照见 启动时传入参数。

改了 conf.yaml，但配置没有生效

配置在进程启动时读取，后台守护进程也需要重启：先停止守护进程，再重新启动 Siada。想知道后台进程当前的运行状态，用 --daemon-status 查看。

TERMINAL
siada-cli --stop-daemon
siada-cli --daemon-status
siada-cli

不确定配置项是否写对时，可以输入 /siada-help 帮我检查 conf.yaml 的语法与配置项，让它先核对再生效。

会话与输入

想在另一个目录继续之前的会话

在会话里输入 /resume --all 查看所有项目的会话。选中另一项目的会话时，Siada 会提示其原始目录；先切回该目录再恢复。

交互输入 · 查看所有项目会话
/resume --all

斜杠命令和启动参数恢复都有目录要求：当前目录需要与该会话所属项目一致。

TERMINAL · 目录不符时按提示切换
cd ~/projects/my-project
siada-cli --resume SESSION_ID -p "继续上次的任务"

更多说明见 会话恢复。

输入多行内容时，换行按键没有反应

换行是否可用取决于终端对按键的解析方式：Ctrl+J 在多数终端都能插入换行，最稳妥；Shift+Enter 需要终端支持相应的按键协议（如 iTerm2 等），Alt+Enter 在部分终端有效，行为可能不一致。

内容较长时，也可以先粘贴多行文本，或按 Ctrl+X 在外部编辑器里写好再回到 Siada。完整快捷键列表见 输入与快捷键。

文件检查点

/undo、/restore 提示没有可用的检查点

文件检查点默认关闭，需要显式开启：交互模式用 siada-cli --checkpointing 启动，或在 ~/.siada-cli/conf.yaml 中设置 checkpoint_config.enable: true。开启后，Agent 在修改文件和执行命令时会自动记录检查点。

~/.siada-cli/conf.yaml · 示例
checkpoint_config:
  enable: true
TERMINAL · 临时开启
siada-cli --checkpointing

两点限制：非交互的 --prompt 运行不支持检查点；工作区是主目录时会自动关闭检查点，以保证安全。另外，恢复对话本身用的是 /resume，不需要检查点；检查点用于回滚文件改动。用法见 文件检查点。