0
代码
代码
Issues
Pull Requests
讨论
Wiki
分析
0
saulcysaulcychore(release): bump version to v4.24.2
9eccc8f6创建于 1 天前历史提交
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1.0">
<title>常见问题 · AtomCode 文档</title>
<meta name="description" content="常见问题 — AtomCode 文档。">
<link rel="icon" type="image/png" href="https://cdn-static.gitcode.host/static/images/logo-favicon.png">
<link rel="stylesheet" href="../docs.css">
<script>(function(){try{var s=localStorage.getItem('atomcode_theme')||localStorage.getItem('atomcode-theme');if(s==='light'){document.documentElement.classList.add('light');document.documentElement.setAttribute('data-theme','light')}}catch(e){}})();</script>
</head>
<body data-page="faq">

<header class="dhdr" id="dhdr">
  <a class="dhdr-logo" href="../../index.html">
    <img src="https://cdn-news.gitcode.com/news/atomcode-icon1.png" alt="AtomCode">
    <span>AtomCode</span>
    <span class="dhdr-badge" data-i18n="badge.docs">DOCS</span>
    <span class="dhdr-ver">v4.24.2</span>
  </a>
  <div class="dhdr-right">
    <button class="search-trigger" data-open-search data-i18n-aria="aria.search" aria-label="搜索文档">
      <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3"/></svg>
      <span data-i18n="search.trigger.text">搜索文档…</span>
      <span class="kbd">⌘K</span>
    </button>
    <button class="icon-btn" id="themeBtn" data-i18n-aria="aria.theme" aria-label="切换主题"></button>
    <button class="icon-btn" id="langBtn" data-i18n-aria="aria.lang" aria-label="切换语言">中</button>
    <a class="dhdr-link" href="https://atomgit.com/atomgit_atomcode/atomcode" target="_blank" rel="noopener" data-i18n="hdr.repo">仓库 →</a>
    <button class="icon-btn sb-toggle" id="sbToggle" data-i18n-aria="aria.sidebar" aria-label="目录">☰</button>
  </div>
</header>

<div class="dlayout">
  <aside class="dside" id="dside">
  <div class="dside-group">
    <div class="dside-group-t" data-i18n="side.g.overview">概览</div>
    <a class="dside-link" href="./index.html" data-slug="index" data-i18n="side.index">文档首页</a>
  </div>

  <div class="dside-group">
    <div class="dside-group-t" data-i18n="side.g.start">开始</div>
    <a class="dside-link" href="./getting-started.html" data-slug="getting-started" data-i18n="side.getting-started">快速开始</a>
    <a class="dside-link" href="./login.html" data-slug="login" data-i18n="side.login">登录方式</a>
    <a class="dside-link" href="./configuration.html" data-slug="configuration" data-i18n="side.configuration">配置文件</a>
  </div>

  <div class="dside-group">
    <div class="dside-group-t" data-i18n="side.g.usage">使用</div>
    <a class="dside-link" href="./basic-usage.html" data-slug="basic-usage" data-i18n="side.basic-usage">基本使用</a>
    <a class="dside-link" href="./slash-commands.html" data-slug="slash-commands" data-i18n="side.slash-commands">斜杠命令</a>
    <a class="dside-link" href="./keybindings.html" data-slug="keybindings" data-i18n="side.keybindings">快捷键</a>
    <a class="dside-link" href="./sessions.html" data-slug="sessions" data-i18n="side.sessions">会话与撤销</a>
  </div>

  <div class="dside-group">
    <div class="dside-group-t" data-i18n="side.g.advanced">进阶</div>
    <a class="dside-link" href="./tools.html" data-slug="tools" data-i18n="side.tools">内置工具</a>
    <a class="dside-link" href="./skills.html" data-slug="skills" data-i18n="side.skills">Skills 扩展</a>
    <a class="dside-link" href="./mcp.html" data-slug="mcp" data-i18n="side.mcp">MCP 集成</a>
    <a class="dside-link" href="./plugins.html" data-slug="plugins" data-i18n="side.plugins">Plugin 系统</a>
    <a class="dside-link" href="./memory.html" data-slug="memory" data-i18n="side.memory">永久记忆</a>
    <a class="dside-link" href="./project-instructions.html" data-slug="project-instructions" data-i18n="side.project-instructions">项目指令文件</a>
    <a class="dside-link" href="./webui.html" data-slug="webui" data-i18n="side.webui">WebUI 界面</a>
    <a class="dside-link" href="./webui-remote-access.html" data-slug="webui-remote-access" data-i18n="side.webui-remote-access">远程访问指南</a>
  </div>

  <div class="dside-group">
    <div class="dside-group-t" data-i18n="side.g.ops">问题</div>
    <a class="dside-link" href="./faq.html" data-slug="faq" data-i18n="side.faq">常见问题</a>
  </div>
  </aside>

  <main class="dmain prose-docs">
<h1>常见问题</h1>
      <p class="lede">把用户群和 issue 里反复出现的问题整理到这里。如果你遇到的问题不在列表里，欢迎在终端内直接运行 <code>/issue</code> 反馈，或到 <a href="https://atomgit.com/atomgit_atomcode/atomcode" target="_blank">AtomGit 仓库</a> 提 issue。</p>

      <h2>安装与启动</h2>

      <h3>安装脚本失败、网络超时怎么办？</h3>
      <p>一键安装脚本默认从 GitCode release 拉二进制。如果网络不通，可以：</p>
      <ul>
        <li>直接到 <a href="https://atomgit.com/atomgit_atomcode/atomcode/releases" target="_blank">releases 页面</a> 手动下载对应平台的压缩包，解压后把 <code>atomcode</code> 放进 <code>PATH</code>；</li>
        <li>或者从源码构建：<code>cargo install --path crates/atomcode</code>（需要 Rust 1.80+）。</li>
      </ul>

      <h3>执行 <code>atomcode</code> 报 "command not found"</h3>
      <p>说明安装目录不在 <code>PATH</code> 里。默认安装路径是 <code>~/.atomcode/bin</code>，把它加到 shell 启动脚本里即可：</p>
      <pre><code>export PATH="$HOME/.atomcode/bin:$PATH"</code></pre>

      <h3>macOS 提示"无法打开，因为无法验证开发者"</h3>
      <p>在系统设置 → 隐私与安全性里点"仍要打开"，或在终端执行：</p>
      <pre><code>xattr -d com.apple.quarantine $(which atomcode)</code></pre>

      <h2>登录与模型</h2>

      <h3>OAuth 登录时浏览器打不开</h3>
      <p>检查是否在无 GUI 的远程服务器上。远程环境推荐改用 API Key 登录（参见 <a href="./login.html">登录方式</a>），或在本地完成 OAuth 后把 <code>~/.atomcode/auth.json</code> 拷贝到服务器同路径。</p>

      <h3>连不上模型 / 一直转圈 / 报 timeout</h3>
      <ul>
        <li>先确认 <code>~/.atomcode/config.toml</code> 里的 <code>base_url</code> 是否可达，<code>curl</code> 一下对应的 <code>/v1/models</code> 接口；</li>
        <li>企业网络里常见是代理问题，设置 <code>HTTPS_PROXY</code> 环境变量后重试；</li>
        <li>国内访问境外模型需要确认出口网络；可以先用 <code>/model</code> 切换到 AtomGit 官方通道确认整体链路是通的。</li>
      </ul>

      <h3>怎么切换模型？</h3>
      <p>会话内直接 <code>/model</code>，从菜单里选。如果想持久化，编辑 <code>~/.atomcode/config.toml</code> 里的 <code>model</code> 字段。详见 <a href="./configuration.html">配置文件</a>。</p>

      <h3>上下文超限 / "context length exceeded"</h3>
      <ul>
        <li>运行 <code>/compact</code> 让模型把已有对话压缩成摘要后再继续；</li>
        <li>或 <code>/clear</code> 清空当前上下文重新开始（历史会作为 session 保留，可以随时 <code>/resume</code>）；</li>
        <li>避免一次性把整个巨型文件贴进 prompt，让 AtomCode 用文件工具按需读取即可。</li>
      </ul>

      <h2>权限与安全</h2>

      <h3>每次执行命令都要确认，太烦了</h3>
      <p>这是默认的安全策略。你可以：</p>
      <ul>
        <li>临时放行：弹出确认时选"一直允许此类操作"；</li>
        <li>配置级放行：在 <code>config.toml</code> 的 <code>[permissions]</code> 里加入白名单命令。</li>
      </ul>

      <h3>AtomCode 会把我的代码发到哪里？</h3>
      <p>只发到你在 <code>config.toml</code> 里配置的模型 endpoint。项目文件由本地的工具读取后作为 prompt 一部分发送，AtomCode 本身不会额外上传或遥测代码内容。</p>

      <h3>能禁用某些工具吗？</h3>
      <p>可以。在 <code>config.toml</code> 的 <code>[tools]</code> 段里用 <code>disabled = ["shell", "web_fetch"]</code> 禁用不希望模型使用的工具。</p>

      <h2>使用与交互</h2>

      <h3>怎么让它读某个文件？</h3>
      <p>在输入里用 <code>@</code> 触发文件补全，例如 <code>帮我看看 @src/main.rs 的入口逻辑</code>。也可以直接描述路径，工具会自己调用 <code>read_file</code>。</p>

      <h3>如何换行输入多行 prompt？</h3>
      <p><kbd>Shift</kbd>+<kbd>Enter</kbd>、<kbd>Alt</kbd>+<kbd>Enter</kbd> 或 <kbd>Ctrl</kbd>+<kbd>Enter</kbd> 换行，<kbd>Enter</kbd> 发送。完整快捷键见 <a href="./keybindings.html">快捷键</a>。</p>

      <h3>改错了怎么回滚？</h3>
      <p>运行 <code>/undo</code> 把上一轮工具调用产生的文件改动回滚到修改前的状态。详见 <a href="./sessions.html">会话与撤销</a>。</p>

      <h3>上一次的会话还能继续吗？</h3>
      <p>能。启动时加 <code>--continue</code>（或 <code>-c</code>）继续上一次会话，或在新会话里运行 <code>/resume</code>，从历史列表里挑一个继续。</p>

      <h2>Skills 与项目指令</h2>

      <h3>我的 skill 没出现在菜单里</h3>
      <ul>
        <li>确认路径正确：全局在 <code>~/.atomcode/skills/&lt;name&gt;/SKILL.md</code>，项目在 <code>.atomcode/skills/&lt;name&gt;/SKILL.md</code>；</li>
        <li>确认 frontmatter 格式正确，<code>name</code> 和 <code>description</code> 两个字段必填；</li>
        <li>重启 atomcode 或运行 <code>/reload</code> 重新扫描。</li>
      </ul>

      <h3><code>.atomcode.md</code> 和 skill 有什么区别？</h3>
      <p>前者是项目级的"始终生效"约定，后者是可被显式触发的流程。详见 <a href="./skills.html#与项目指令的分工">Skills 扩展 · 与项目指令的分工</a>。</p>

      <h2>排查思路</h2>
      <div class="callout callout-tip">
        <strong>先看日志</strong>
        <p>出任何问题第一步都是看 <code>~/.atomcode/logs/</code>。启动时加 <code>--log-level debug</code> 可以打印更详细的请求/响应日志。</p>
      </div>

      <h3>提 issue 时请附上</h3>
      <ul>
        <li><code>atomcode --version</code> 的输出；</li>
        <li>操作系统和架构；</li>
        <li>报错时的最小复现步骤；</li>
        <li>相关日志（记得脱敏 API Key）。</li>
      </ul>

      <h2>下一步</h2>
      <ul>
        <li><a href="./index.html">返回概览</a></li>
        <li><a href="./getting-started.html">快速开始</a> —— 从零装一遍</li>
        <li><a href="./configuration.html">配置文件</a> —— 所有可调项</li>
      </ul>

    <footer class="dftr">
      <span data-i18n="ftr.copy">© 2026 AtomCode · MIT</span>
      <a href="https://atomgit.com/atomgit_atomcode/atomcode/issues" target="_blank" rel="noopener" data-i18n="ftr.issue">报告问题</a>
    </footer>
  </main>
</div>

<div class="search-modal" id="searchModal" role="dialog" data-i18n-aria="aria.search" aria-label="搜索文档">
  <div class="search-modal-bg"></div>
  <div class="search-modal-box">
    <div class="search-input-wrap">
      <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><circle cx="11" cy="11" r="7"/><path d="M21 21l-4.3-4.3"/></svg>
      <input id="searchInput" type="search" data-i18n-placeholder="search.placeholder" placeholder="搜索文档…" autocomplete="off">
      <span class="search-esc">ESC</span>
    </div>
    <div class="search-results" id="searchResults"></div>
  </div>
</div>

<script src="../docs.js"></script>
</body>
</html>