常见问题
把用户群和 issue 里反复出现的问题整理到这里。如果你遇到的问题不在列表里，欢迎在终端内直接运行 /issue 反馈，或到 AtomGit 仓库 提 issue。
安装与启动
安装脚本失败、网络超时怎么办？
一键安装脚本默认从 GitCode release 拉二进制。如果网络不通，可以：
- 直接到 releases 页面 手动下载对应平台的压缩包，解压后把
atomcode放进PATH； - 或者从源码构建：
cargo install --path crates/atomcode（需要 Rust 1.80+）。
执行 atomcode 报 "command not found"
说明安装目录不在 PATH 里。默认安装路径是 ~/.atomcode/bin，把它加到 shell 启动脚本里即可：
export PATH="$HOME/.atomcode/bin:$PATH"macOS 提示"无法打开，因为无法验证开发者"
在系统设置 → 隐私与安全性里点"仍要打开"，或在终端执行：
xattr -d com.apple.quarantine $(which atomcode)登录与模型
OAuth 登录时浏览器打不开
检查是否在无 GUI 的远程服务器上。远程环境推荐改用 API Key 登录（参见 登录方式），或在本地完成 OAuth 后把 ~/.atomcode/auth.json 拷贝到服务器同路径。
连不上模型 / 一直转圈 / 报 timeout
- 先确认
~/.atomcode/config.toml里的base_url是否可达，curl一下对应的/v1/models接口； - 企业网络里常见是代理问题，设置
HTTPS_PROXY环境变量后重试； - 国内访问境外模型需要确认出口网络；可以先用
/model切换到 AtomGit 官方通道确认整体链路是通的。
怎么切换模型？
会话内直接 /model，从菜单里选。如果想持久化，编辑 ~/.atomcode/config.toml 里的 model 字段。详见 配置文件。
上下文超限 / "context length exceeded"
- 运行
/compact让模型把已有对话压缩成摘要后再继续； - 或
/clear清空当前上下文重新开始（历史会作为 session 保留，可以随时/resume）； - 避免一次性把整个巨型文件贴进 prompt，让 AtomCode 用文件工具按需读取即可。
权限与安全
每次执行命令都要确认，太烦了
这是默认的安全策略。你可以：
- 临时放行：弹出确认时选"一直允许此类操作"；
- 配置级放行：在
config.toml的[permissions]里加入白名单命令； - 完全自动：
atomcode --yes全局跳过确认（仅建议在沙箱或 CI 中使用）。
AtomCode 会把我的代码发到哪里？
只发到你在 config.toml 里配置的模型 endpoint。项目文件由本地的工具读取后作为 prompt 一部分发送，AtomCode 本身不会额外上传或遥测代码内容。
能禁用某些工具吗？
可以。在 config.toml 的 [tools] 段里用 disabled = ["shell", "web_fetch"] 禁用不希望模型使用的工具。
使用与交互
怎么让它读某个文件？
在输入里用 @ 触发文件补全，例如 帮我看看 @src/main.rs 的入口逻辑。也可以直接描述路径，工具会自己调用 read_file。
如何换行输入多行 prompt？
Shift+Enter 换行，Enter 发送。完整快捷键见 快捷键。
改错了怎么回滚？
运行 /undo 把上一轮工具调用产生的文件改动回滚到修改前的状态。详见 会话与撤销。
上一次的会话还能继续吗？
能。启动时加 --resume 或在新会话里运行 /resume，从历史列表里挑一个继续。
Skills 与项目指令
我的 skill 没出现在菜单里
- 确认路径正确：全局在
~/.atomcode/skills/<name>/SKILL.md，项目在.atomcode/skills/<name>/SKILL.md； - 确认 frontmatter 格式正确，
name和description两个字段必填； - 重启 atomcode 或运行
/reload重新扫描。
.atomcode.md 和 skill 有什么区别？
前者是项目级的"始终生效"约定，后者是可被显式触发的流程。详见 Skills 扩展 · 与项目指令的分工。
Headless 与 Daemon
CI 里怎么跑 AtomCode？
用 atomcode -p "任务描述" --yes 非交互模式，结果输出到 stdout。注意在 CI 里要通过环境变量或 secret 提供 API Key。完整用法见 Headless 与 Daemon。
daemon 端口被占用 / 启动失败
默认端口 17890，可通过 atomcode-daemon --port 1234 改端口，或在 config 里配置。查看 ~/.atomcode/logs/daemon.log 定位具体错误。
排查思路
出任何问题第一步都是看 ~/.atomcode/logs/。启动时加 --log-level debug 可以打印更详细的请求/响应日志。
提 issue 时请附上
atomcode --version的输出；- 操作系统和架构；
- 报错时的最小复现步骤；
- 相关日志（记得脱敏 API Key）。