Admin Companion - Dokumentation

Dies ist die aktuellste version der Dokumentation für Client-Versionen 5.4+

Klicken Sie auf die Versionsnummern, um zur Dokumentation älterer Versionen zu gelangen.: 5.0 - 5.3 4.0 3.1 - 3.2 3.0 2.3 2.0 - 2.2 1.x

Inhalt

Netzwerk-Flow

Der Admin-Companion-Client muss in der Lage sein, POST-Anfragen an diese beiden Admin-Companion-API-Endpunkte zu senden und Antworten von ihnen zu empfangen:

  • https://api.admin-companion.ai:443/dialogue/*
  • https://api.admin-companion.ai:443/search/*

Stellen Sie sicher, dass Ihre Firewalls diesen Datenverkehr nicht blockieren.

Vereinfachter Netzwerkablauf:

Schnellstart

  1. Registrieren Sie ein Admin-Companion-Konto.
  2. Erstellen Sie einen API-Key auf der API-Keys-Seite in der Web-Konsole (Sie müssen sich anmelden, um dorthin zu gelangen).
  3. Installieren Sie die Client-Software auf Ihrem System. Folgen Sie dazu den Anweisungen auf der Download-Seite für Ihr Betriebssystem.
  4. Konfigurieren Sie den Client mit dem API-Key. Es gibt drei Stellen, an denen Sie den API-Key setzen können. Wählen Sie eine der folgenden Optionen:
    • Umgebungsvariable (benutzerspezifisch)
      Setzen Sie eine Umgebungsvariable ADMIN_COMPANION_KEY auf den Wert des API-Keys:
      export ADMIN_COMPANION_KEY="<Your API key>"
      Damit dies dauerhaft ist, fügen Sie den Befehl in Ihre Shell-Konfigurationsdatei ein, zum Beispiel $HOME/.bashrc für bash. Verwenden Sie die Resource-Datei Ihrer eigenen Shell.
      Denken Sie daran, Ihre Shell neu zu starten oder source $HOME/.bashrc nach dem Ändern der Datei auszuführen.
      Sie können prüfen, ob die Umgebungsvariable gesetzt ist, indem Sie echo $ADMIN_COMPANION_KEY in Ihrer Shell ausführen. Es sollte den Wert des API-Keys zurückgeben.
    • Datei $HOME/.admin-companion/api-key (benutzerspezifisch)
      Fügen Sie eine Zeile im Format
      ADMIN_COMPANION_KEY="<Your API key>"
      in die Datei $HOME/.admin-companion/api-key
      Sie können zusätzliche Zeilen hinzufügen, die mit einem Rautenzeichen (#) beginnen. Diese Zeilen werden von der Client-Software ignoriert.
      Stellen Sie sicher, dass die Datei nur von Ihnen lesbar ist, zum Beispiel mit chmod 600 $HOME/.admin-companion/api-key.
    • Datei /etc/admin-companion/api-key (systemweit)
      Achtung: Diese Option kann ein Sicherheitsrisiko sein, da jeder Benutzer auf dem System den API-Key sehen kann.
      Fügen Sie eine Zeile im Format
      ADMIN_COMPANION_KEY="<Your API key>"
      in die Datei /etc/admin-companion/api-key
      Sie können zusätzliche Zeilen hinzufügen, die mit einem Rautenzeichen (#) beginnen. Diese Zeilen werden von der Client-Software ignoriert.
      Die Datei muss für alle lesbar sein, sollte aber nur für root schreibbar sein, zum Beispiel mit:
      chown root:root /etc/admin-companion/api-key
      chmod 644 /etc/admin-companion/api-key

  5. Rufen Sie zum Beispiel auf:
    ai "Are you there?"
    um zu prüfen, dass Admin Companion antwortet.
    Versuchen Sie, Ihre Anfrage in Ihrer eigenen Sprache zu stellen. Es funktioniert genauso:
    ai "¿Estás ahí?"
    ai "Est-ce que tu es là?"
    ai "Bist du da?"
  6. Wenn es nicht korrekt funktioniert, prüfen Sie die Admin-Companion-Logdatei unter $HOME/.admin-companion/admin-companion.log für Details.

Sicherheitsschicht

Die Client-Software verfügt über eine integrierte Sicherheitsschicht, die sicherstellt, dass nur vom Benutzer freigegebene Befehle ausgeführt werden können.
Die Künstliche Intelligenz interagiert niemals direkt mit dem System. Sie kann nur mit der Sicherheitsschicht der Client-Software kommunizieren. Diese Sicherheitsschicht stellt die Zustimmung des Benutzers vor jeder Befehlsausführung sicher.

Verwendung des Clients

Sie können den Admin-Companion-Client mit dem Befehl ai aufrufen.

Verwendung: ai [options] | [max request token size] [model] [natural language request]
Sie können entweder eine Option oder eine Anfrage in natürlicher Sprache angeben, aber niemals beides gleichzeitig.

[options]: Siehe Kommandozeilenparameter unten

[max request token size]: -s <number of tokens>  oder  --size <number of tokens>:

Admin Companion arbeitet mit der „max request token size“ (auch Kontextfenster genannt), die in Tokens gezählt wird (ein Token entspricht ca. 0,75 Wörtern).
Der gemerkte Dialog kann nicht länger sein als die „max request token size“. Wenn er länger wird, „verblassen“ ältere Nachrichten im Dialog aus dem Speicher.
Die Standard-„max request token size“ ist in der Konfigurationsdatei festgelegt.
Mit diesem Parameter können Sie optional für diese einzelne Anfrage eine andere „max request token size“ setzen.
Sie möchten möglicherweise eine kleinere „max request token size“ wählen, um Tokens zu sparen (die Abrechnung basiert auf der Anzahl der Eingabe-Tokens und Completion-Tokens pro Anfrage).
Sie möchten möglicherweise eine größere „max request token size“ wählen, wenn Sie vorübergehend mehr Informationen verarbeiten müssen oder einen längeren Dialogverlauf behalten möchten.

[model]: -m <model-name>  oder  --model <model-name>:

Sie können auswählen, welches Modell Ihre Anfrage beantwortet. Die Liste der verfügbaren Modelle wird in der Kopfzeile jeder Antwort angezeigt.
Wenn Sie kein Modell angeben, wird das Standardmodell des Backends verwendet. In der Kopfzeile der Antwort sehen Sie, welches Modell verwendet wurde.
Beispiel: ai -m gpt-5-mini "Are you there?"

[natural language request]:

Um Admin Companion zu instruieren, haben Sie zwei Möglichkeiten für die Anfrage in natürlicher Sprache:
  1. Geben Sie Ihre Anweisung als Klartext in der Kommandozeile ein
    • Der sauberste Weg ist, Anführungszeichen um Ihre Anweisung zu setzen:
      ai "I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data"
      So können Sie alle Zeichen in Ihrer Anweisung ohne Probleme verwenden.
    • Wenn Sie die Anfrage nicht in Anführungszeichen setzen, beachten Sie bitte, dass die Shell Ihre Eingabe als Parameter für den Befehl interpretiert.
      Das bedeutet zum Beispiel:
      • Sie müssen Klammern escapen:
        Nicht: ai find and list the configuration files of the application xyz (you find the application in /usr/xyz)
        Sondern: ai find and list the configuration files of the application xyz \(you find the application in /usr/xyz\)

      • Beachten Sie, dass Anführungszeichen von der Shell als Anführungszeichen interpretiert werden und daher wieder geschlossen werden müssen:
        Nicht: ai I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data
        Sondern: ai I would like to create a backup script with 10 rotating files for the content of the path /mnt/data

        ...oder schließen Sie das Anführungszeichen einfach am Ende der Zeile. Nicht schön, aber funktioniert:
        ai I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data'

        ...oder setzen Sie einfach alles in Anführungszeichen:
        ai "I'd like to create a backup script with 10 rotating files for the content of the path /mnt/data"

      • Beachten Sie, dass * und ? von der Shell durch die jeweils gefilterten Inhalte des aktuellen Verzeichnisses ersetzt werden.

  2. Starten Sie ai ohne Parameter und geben Sie Ihre Anweisung interaktiv ein:
    • In diesem Fall fordert der Admin-Companion-Client Sie auf, Ihre Anweisungen einzugeben; diese können mehrzeilig sein (drücken Sie einfach „Enter“, um zur nächsten Zeile zu wechseln). Hier können Sie sogar Dateien als Teil der Anweisungen hineinkopieren. Wenn Sie Ihre Anweisung beenden möchten, senden Sie einfach ein EOF (End-Of-File), indem Sie „Strg-D“ am Anfang einer Zeile drücken.
      $ ai
      Edit your input below. Submit with Alt+Enter:
      Ich möchte ein Backup-Skript erstellen.
      Ich möchte sichern: /mnt
      Bitte packe die Dateien als tar.gz
      Das Tarball soll nach /backup geschrieben werden
      <Alt-Enter>

Beispiele:

  • ai "Are you there?"
  • ai -s 100000 "Are you there?"
    Admin Companion arbeitet mit der „max request token size“, die in Tokens gezählt wird (ein Token entspricht ca. 0,75 Wörtern).
    Der gemerkte Dialog kann nicht länger sein als die „max request token size“. Wenn er länger wird, „verblassen“ ältere Nachrichten im Dialog aus dem Speicher.
    Die Standard-„max request token size“ ist in der Konfigurationsdatei festgelegt.
    Mit -s können Sie für diese einzelne Anfrage eine andere „max request token size“ setzen.
    Sie möchten möglicherweise eine kleinere „max request token size“ wählen, um Tokens zu sparen (die Abrechnung basiert auf der Anzahl der Ein- und Ausgabe-Tokens pro Anfrage).
    Sie möchten möglicherweise eine größere „max request token size“ wählen, wenn Sie vorübergehend viele Informationen verarbeiten müssen oder einen längeren Dialogverlauf behalten möchten.
  • ai -v
  • ai -t "We analyze an issue with our web server not reacting to requests on port 443."
    Damit wird ein Thema gesetzt, das gespeichert wird und nicht aus dem Speicher „verblasst“, bis Sie es mit dem Parameter -rt löschen.
  • ai
    Damit können Sie die Anfrage interaktiv eingeben.

Kommandozeilenparameter

  • -h or --help
    Hilfetext anzeigen
  • -l or --list
    Gespeicherten Dialogverlauf anzeigen
  • -c or --clear-messages
    Dialogverlauf löschen. Das ist sinnvoll, um ein neues Thema zu beginnen und Admin Companion die vorherige Konversation vergessen zu lassen. Außerdem reduziert es die Anzahl der Tokens und damit die Kosten der Anfrage.
  • -b [<background>] / --set-background [<background>]
    Damit setzen Sie Hintergrundinformationen über Ihr System für Admin Companion.
    Admin Companion weiß (fast) alles über Linux, kennt jedoch Ihr konkretes System oder Setup nicht. Wenn Admin Companion bestimmte Informationen über Ihr System oder Setup kennen soll, können Sie diese mit dieser Option als Hintergrundinformation setzen.
    Die Informationen werden in jede Anfrage eingebunden, die Sie an Admin Companion senden.
    Sie könnten zum Beispiel angeben, ob Sie apache2 oder nftables statt nginx oder iptables verwenden. Oder wenn Sie für bestimmte Logdateien nicht standardmäßige Verzeichnisse nutzen. Dann muss Admin Companion das System nicht erst untersuchen, wenn Sie in diesem Bereich arbeiten.
    Hinweis: Wenn Sie diese Option verwenden, muss sie die letzte Option in der Kommandozeile sein. Der Hintergrund kann in der Kommandozeile angegeben werden oder Sie lassen ihn leer; dann werden Sie aufgefordert, die Eingabe interaktiv zu machen. Nehmen Sie die <>-Klammern nicht in den Hintergrund auf.
  • -rb or --remove-background
    Entfernt die Hintergrundinformationen dauerhaft, die zuvor mit -b oder --set-background gesetzt wurden.
  • -sb or --show-background
    Zeigt die aktuell gesetzten Hintergrundinformationen an.
  • -t [<topic>] / --set-topic [<topic>]
    Setzt ein Thema für Admin Companion.
    Das Thema „verblasst“ nicht aus dem Dialog, sondern bleibt im Speicher von Admin Companion. So bleibt bei längeren Aufgaben der Fokus auf diesem Thema.
    Hinweis: Wenn Sie diese Option verwenden, muss sie die letzte Option in der Kommandozeile sein. Das Thema kann in der Kommandozeile angegeben werden oder Sie lassen es leer; dann werden Sie aufgefordert, die Eingabe interaktiv zu machen. Nehmen Sie die <>-Klammern nicht in das Thema auf.
  • -rt or --remove-topic
    Entfernt das allgemeine Thema, das zuvor mit -t oder --set-topic gesetzt wurde.
  • -st or --show-topic
    Zeigt das aktuell gesetzte Thema an.
  • -rm or --remove-memory
    Entfernt alle Informationen aus dem Langzeitspeicher.
  • -sm or --show-memory
    Zeigt den Inhalt des aktuellen Langzeitspeichers an.
  • -er or --enable-use-release
    Aktiviert das Auslesen und Senden der OS-Release-Nummer, damit Admin Companion die Antworten besser an Ihr OS-Release anpassen kann. Diese Einstellung wird dauerhaft gespeichert und für zukünftige Anfragen verwendet.
  • -dr or --disable-use-release
    Deaktiviert das Auslesen und Senden der OS-Release-Nummer. Mit dieser Einstellung sind die Antworten von Admin Companion allgemeiner. Diese Einstellung wird dauerhaft gespeichert und für zukünftige Anfragen verwendet.
  • -ek or --enable-knowledge
    Verwendung des internen Wissens aktivieren. [Standard]
  • -dk or --disable-knowledge
    Verwendung des internen Wissens deaktivieren.
  • -ec or --enable-citations
    Zitate im Fazit anzeigen (internes Wissen) aktivieren. [Standard]
  • -dc or --disable-citations
    Zitate im Fazit nicht anzeigen.
  • -v or --version
    Version und Revision der Client-Software anzeigen.

Vom Admin-Companion-Client verwendete Dateien

Die folgenden Dateien werden im Kontext des Admin-Companion-Clients verwendet:

  • Ordner: $HOME/.admin-companion/
    • api-key: Der vom Admin-Companion-Client verwendete API-Key. Diese Datei ist optional, da es andere Möglichkeiten gibt, den API-Key zu speichern.
    • admin-companion.log: Logdatei des Admin-Companion-Clients. Die Datei wird rotiert; es werden zwei Dateien mit jeweils etwa 1 MB Größe vorgehalten.
    • admin-companion.bill: Diese Datei protokolliert für jede Anfrage die Anzahl der verbrauchten Tokens. Die Datei wird rotiert; es werden zwei Dateien mit jeweils etwa 1 MB Größe vorgehalten.
    • conversation_history.pickle: Diese Datei speichert den Gesprächsverlauf des Benutzers dauerhaft, auch über einen Systemneustart hinweg.
  • Ordner: /etc/admin-companion/
    • admin-companion.cfg: Admin-Companion-Konfigurationsdatei.
    • api-key: Der vom Admin-Companion-Client verwendete API-Key. Diese Datei ist optional, da es andere Möglichkeiten gibt, den API-Key zu speichern.
    • symlink_name: Interne Datei für Installation/Deinstallation. Ändern Sie diese Datei niemals.
  • Ordner: /usr/bin/
    Dieser Ordner enthält die ausführbare Datei admin-companion und den Symlink auf ai.

Web-Konsole – Dashboard

Im Dashboard der Web-Konsole sehen Sie eine Übersicht über Ihre Guthaben und Ihre Nutzung auf Monatsbasis (6 Monate) sowie auf Tagesbasis (aktueller Kalendermonat).

Web-Konsole – Anfragen

Auf dieser Seite sehen Sie die Metadaten der neuesten Anfragen, die über einen Ihrer API-Keys gestellt wurden (ohne den Inhalt der Anfrage).

Web-Konsole – API-Keys

API-Keys werden zur Authentifizierung der Anfragen des Admin-Companion-Clients verwendet. Behandeln Sie Ihre API-Keys wie ein Passwort und halten Sie sie geheim!

Sie können Ihre API-Keys auf der API-Keys Seite in der Web-Konsole erstellen, verwalten und löschen.
Sie haben folgende Optionen:

  • Einen neuen API-Key erstellen.
    Sie müssen dem API-Key einen Namen geben, um ihn später identifizieren zu können.
    Der API-Key wird nur einmal bei der Erstellung angezeigt. Stellen Sie sicher, dass Sie ihn an einem sicheren Ort aufbewahren. Wenn Sie den API-Key verlieren, können weder Sie noch wir ihn wiederherstellen!
    Sie können API-Keys jedoch jederzeit löschen und neu erstellen. Beachten Sie, dass der Key auf dem Bildschirm angezeigt wird. Stellen Sie sicher, dass keine unbefugte Person Ihren Bildschirm sehen kann.
  • Deaktivieren Sie einen API-Key vorübergehend, indem Sie auf sein Statussymbol klicken.
  • Benennen Sie einen API-Key um, indem Sie auf das Stiftsymbol am Ende der Zeile des API-Keys klicken.
  • Einen API-Key dauerhaft löschen
    Ein gelöschter API-Key kann nicht wiederhergestellt werden. Sie können jedoch jederzeit neue API-Keys erstellen.
Sobald Sie einen API-Key erstellt haben, können Sie ihn im Admin-Companion-Client verwenden. Siehe oben, wie Sie den API-Key für Ihren Admin-Companion-Client setzen.

Web-Konsole – Mein Profil

Auf der Seite „Mein Profil“ in der Web-Konsole können Sie Ihren Namen, Ihre USt-IdNr. und Ihre Adresse ändern. Land, Firmenname oder E-Mail-Adresse können Sie nicht ändern.

Web-Konsole – Konto

Diese Seite zeigt Ihre Kontoguthaben. Es gibt zwei Guthaben:

  • Ablaufendes Guthaben: Dieses Guthaben verfällt am Ende eines Abrechnungszeitraums. Zu Beginn jedes Abrechnungszeitraums, wenn Sie die wiederkehrende Gebühr bezahlen, wird dieser Betrag auf den Wert der wiederkehrenden Zahlung zurückgesetzt.
    Sie können diesen Betrag dann innerhalb des Abrechnungszeitraums durch die Nutzung von Admin Companion verwenden.
  • Nicht ablaufendes Guthaben: Dieses Guthaben verfällt erst, wenn Ihr Abonnement gekündigt wird. Solange Sie ein Abo haben, wird ein verbleibender Betrag dieses Guthabens in den nächsten Abrechnungszeitraum übertragen.
    Wenn Sie die automatische Aufladefunktion verwenden (siehe unten), fließen alle darauf basierenden Zahlungen in das nicht verfallende Guthaben.
    Wenn Sie Ihren Tarif wechseln, wird Ihnen sofort die neue wiederkehrende Gebühr berechnet (ohne das Datum der Abrechnungszeiträume zu ändern). Diese Gebühr fließt ebenfalls in das nicht verfallende Guthaben.
Wenn Sie ein verfallendes und ein nicht verfallendes Guthaben haben, wird die Nutzung von Admin Companion immer zuerst vom verfallenden Guthaben abgezogen, bis dieses vollständig verbraucht ist. Erst danach wird das nicht verfallende Guthaben verwendet.

Automatische Aufladefunktion: Standardmäßig lehnt der Admin-Companion-Client bei vollständigem Verbrauch aller Guthaben weitere Anfragen mit der Meldung „Account limit reached“ ab.
Wenn Sie die automatische Aufladefunktion aktivieren, belastet Admin Companion Ihre Zahlungsmethode automatisch erneut, sobald Sie alle Guthaben innerhalb eines Abrechnungszeitraums verbraucht haben. Alle Aufladungen fließen in das nicht verfallende Guthaben und folgen den oben beschriebenen Mechanismen.
Die Aufladung erfolgt immer in derselben Höhe wie die wiederkehrende Gebühr.
Vergessen Sie nicht, nach dem Ändern der automatischen Aufladung auf „Kontoeinstellungen aktualisieren“ zu klicken, damit die Änderung wirksam wird.

Transaktionen: Auf der Kontoseite sehen Sie außerdem Ihre letzten 30 Transaktionen (z. B. wiederkehrende Zahlungen, Aufladungen, Änderungen der Zahlungsmethode usw.).

Mein Abo

Auf der Abonnement-Seite sehen Sie, welchen Tarif Sie aktuell abonniert haben. Sie können ein Abonnement aktivieren, zu einem anderen Abonnement wechseln oder Ihr Abonnement kündigen.

Tarif wechseln: Wenn Sie zwischen den Tarifen S, M, L wechseln, wird die wiederkehrende Gebühr des neuen Tarifs sofort über Ihre hinterlegte Zahlungsmethode abgerechnet und dem nicht verfallenden Guthaben gutgeschrieben (siehe „Konto“ für Details). Ihre weitere Nutzung wird dann sofort zum Stückpreis des neuen Tarifs abgerechnet.

Zahlungsmethode aktualisieren: Auf dieser Seite können Sie auch Ihre Zahlungsmethode aktualisieren.

Abo kündigen: Die Kündigung wird zum Ende des Abrechnungszeitraums eingeplant. Sie können Admin Companion bis zum Ende des Abrechnungszeitraums weiter nutzen.
Wenn die Aufladefunktion aktiviert ist, wird Ihre Zahlungsmethode weiterhin für mögliche Aufladungen belastet.
Wenn Sie ein Abonnement kündigen, verfällt das gesamte nicht verfallende Guthaben am Ende des Abrechnungszeitraums.
In der letzten etwa eine Stunde vor dem Ende eines Abrechnungszeitraums sind keine Änderungen am Abonnement möglich.
Ihr Konto bleibt mindestens ein Jahr verfügbar, sodass Sie sich später entscheiden können, erneut einen Tarif zu abonnieren.