---
import DocsLayout from '../../layouts/DocsLayout.astro'
import { settingsFiles, settingOptions, envVars } from '../../data/configuration'

const toc = [
  { id: 'settings-files', label: 'settings files' },
  { id: 'common-options', label: 'common options' },
  { id: 'environment-variables', label: 'environment variables' },
  { id: 'project-instructions', label: 'project instructions' },
]
---

<DocsLayout
  title="openclaude configuration — settings.json & env vars"
  description="Configure openclaude with settings.json files, project profiles, and environment variables like ANTHROPIC_API_KEY and OPENAI_API_KEY. Full options reference."
  heading="configuration"
  lede="Layered settings files for defaults, environment variables for auth and CI, and project instructions for context."
  toc={toc}
>
  <h2 id="settings-files">settings files</h2>
  <p>
    Settings merge in order: user → project → local, with later layers overriding earlier
    ones. Open the interactive panel with <code>/config</code>, or edit the files directly.
  </p>
  <div class="table-wrap">
    <table>
      <thead>
        <tr>
          <th scope="col">file</th>
          <th scope="col">scope</th>
          <th scope="col">notes</th>
        </tr>
      </thead>
      <tbody>
        {settingsFiles.map(f => (
          <tr>
            <td><code>{f.path}</code></td>
            <td>{f.scope}</td>
            <td>{f.notes}</td>
          </tr>
        ))}
      </tbody>
    </table>
  </div>

  <h2 id="common-options">common options</h2>
  <p>A few of the most-used keys in <code>settings.json</code>:</p>
  <div class="table-wrap">
    <table>
      <thead>
        <tr>
          <th scope="col">key</th>
          <th scope="col">what it does</th>
        </tr>
      </thead>
      <tbody>
        {settingOptions.map(o => (
          <tr>
            <td><code>{o.key}</code></td>
            <td>{o.description}</td>
          </tr>
        ))}
      </tbody>
    </table>
  </div>
  <p>
    One-off overrides beat files: <code>--settings</code> accepts a path or inline JSON,
    and <code>--setting-sources</code> restricts which layers load — see the
    <a href="/docs/cli-reference/#config">CLI reference</a>.
  </p>

  <h2 id="environment-variables">environment variables</h2>
  <p>Auth and transport are driven by environment variables, which makes CI and <code>--print</code> scripting straightforward:</p>
  <div class="table-wrap">
    <table>
      <thead>
        <tr>
          <th scope="col">variable</th>
          <th scope="col">purpose</th>
        </tr>
      </thead>
      <tbody>
        {envVars.map(v => (
          <tr>
            <td><code>{v.name}</code></td>
            <td>{v.description}</td>
          </tr>
        ))}
      </tbody>
    </table>
  </div>
  <p>Provider-specific setup recipes live on the <a href="/docs/providers/">providers page</a>.</p>

  <h2 id="project-instructions">project instructions</h2>
  <p>
    <code>CLAUDE.md</code> (or <code>.claude/CLAUDE.md</code>) is loaded into context at
    session start — build commands, conventions, and anything the agent should always
    know about the repo. Generate a starting point with <code>/init</code>, and edit
    persistent memory with <code>/memory</code>.
  </p>
</DocsLayout>
