Compare commits
1 Commits
master
...
chore/ci-d
| Author | SHA1 | Date | |
|---|---|---|---|
|
541c357002 |
@ -1,12 +0,0 @@
|
||||
# cargo-audit configuration
|
||||
# https://rustsec.org/
|
||||
|
||||
[advisories]
|
||||
ignore = [
|
||||
# wasmtime vulns via extism 1.13.0 — no upstream fix; plugins feature-gated
|
||||
"RUSTSEC-2026-0006", # wasmtime f64.copysign segfault on x86-64
|
||||
"RUSTSEC-2026-0020", # WASI guest-controlled resource exhaustion
|
||||
"RUSTSEC-2026-0021", # WASI http fields panic
|
||||
# instant crate unmaintained — transitive dep via nostr; no upstream fix
|
||||
"RUSTSEC-2024-0384",
|
||||
]
|
||||
@ -2,7 +2,7 @@
|
||||
rustflags = ["-C", "link-arg=-static"]
|
||||
|
||||
[target.aarch64-unknown-linux-musl]
|
||||
rustflags = ["-C", "link-arg=-static", "-C", "link-arg=-Wl,-z,stack-size=8388608"]
|
||||
rustflags = ["-C", "link-arg=-static"]
|
||||
|
||||
# Android targets (NDK toolchain)
|
||||
[target.armv7-linux-androideabi]
|
||||
@ -10,4 +10,3 @@ linker = "armv7a-linux-androideabi21-clang"
|
||||
|
||||
[target.aarch64-linux-android]
|
||||
linker = "aarch64-linux-android21-clang"
|
||||
rustflags = ["-C", "link-arg=-Wl,-z,stack-size=8388608"]
|
||||
|
||||
@ -1,133 +0,0 @@
|
||||
# Skill: github-issue
|
||||
|
||||
File a structured GitHub issue (bug report or feature request) for ZeroClaw interactively from Claude Code.
|
||||
|
||||
## When to Use
|
||||
|
||||
Trigger when the user wants to file a GitHub issue, report a bug, or request a feature for ZeroClaw. Keywords: "file issue", "report bug", "feature request", "open issue", "create issue", "github issue".
|
||||
|
||||
## Instructions
|
||||
|
||||
You are filing a GitHub issue against the ZeroClaw repository using structured issue forms. Follow this workflow exactly.
|
||||
|
||||
### Step 1: Detect Issue Type and Read the Template
|
||||
|
||||
Determine from the user's message whether this is a **bug report** or **feature request**.
|
||||
- If unclear, use AskUserQuestion to ask: "Is this a bug report or a feature request?"
|
||||
|
||||
Then read the corresponding issue template to understand the required fields:
|
||||
|
||||
- Bug report: `.github/ISSUE_TEMPLATE/bug_report.yml`
|
||||
- Feature request: `.github/ISSUE_TEMPLATE/feature_request.yml`
|
||||
|
||||
Parse the YAML to extract:
|
||||
- The `title` prefix (e.g. `[Bug]: `, `[Feature]: `)
|
||||
- The `labels` array
|
||||
- Each field in the `body` array: its `type` (dropdown, textarea, input, checkboxes, markdown), `id`, `attributes.label`, `attributes.options` (for dropdowns), `attributes.description`, `attributes.placeholder`, and `validations.required`
|
||||
|
||||
This is the source of truth for what fields exist, what they're called, what options are available, and which are required. Do not assume or hardcode any field names or options — always derive them from the template file.
|
||||
|
||||
### Step 2: Auto-Gather Context
|
||||
|
||||
Before asking the user anything, silently gather environment and repo context:
|
||||
|
||||
```bash
|
||||
# Git context
|
||||
git log --oneline -5
|
||||
git status --short
|
||||
git diff --stat HEAD~1 2>/dev/null
|
||||
|
||||
# For bug reports — environment detection
|
||||
uname -s -r -m # OS info
|
||||
sw_vers 2>/dev/null # macOS version
|
||||
rustc --version 2>/dev/null # Rust version
|
||||
cargo metadata --format-version=1 --no-deps 2>/dev/null | jq -r '.packages[] | select(.name=="zeroclaw") | .version' 2>/dev/null # ZeroClaw version
|
||||
git rev-parse --short HEAD # commit SHA fallback
|
||||
```
|
||||
|
||||
Also read recently changed files to infer the affected component and architecture impact.
|
||||
|
||||
### Step 3: Pre-Fill and Present the Form
|
||||
|
||||
Using the parsed template fields and gathered context, draft values for ALL fields from the template:
|
||||
|
||||
- **dropdown** fields: select the most likely option from `attributes.options` based on context. For dropdowns where you're uncertain, note your best guess and flag it for the user.
|
||||
- **textarea** fields: draft content based on the user's description, git context, and the field's `attributes.description`/`attributes.placeholder` for guidance on what's expected.
|
||||
- **input** fields: fill with auto-detected values (versions, OS) or draft from user context.
|
||||
- **checkboxes** fields: auto-check all items (the skill itself ensures compliance with the stated checks).
|
||||
- **markdown** fields: skip these — they're informational headers, not form inputs.
|
||||
- **optional fields** (where `validations.required` is false): fill if there's enough context, otherwise note "(optional — not enough context to fill)".
|
||||
|
||||
Present the complete draft to the user in a clean readable format:
|
||||
|
||||
```
|
||||
## Issue Draft: [Bug]: <title> / [Feature]: <title>
|
||||
**Labels**: <from template>
|
||||
|
||||
### <Field Label>
|
||||
<proposed value or selection>
|
||||
|
||||
### <Field Label>
|
||||
<proposed value>
|
||||
...
|
||||
```
|
||||
|
||||
Use AskUserQuestion to ask the user to review:
|
||||
- "Here's the pre-filled issue. Please review and let me know what to change, or say 'submit' to file it."
|
||||
|
||||
If the user requests changes, update the draft and re-present. Iterate until the user approves.
|
||||
|
||||
### Step 4: Scope Guard
|
||||
|
||||
Before final submission, analyze the collected content for scope creep:
|
||||
- Does the bug report describe multiple independent defects?
|
||||
- Does the feature request bundle unrelated changes?
|
||||
|
||||
If multi-concept issues are detected:
|
||||
1. Inform the user: "This issue appears to cover multiple distinct topics. Focused, single-concept issues are strongly preferred and more likely to be accepted."
|
||||
2. Break down the distinct groups found.
|
||||
3. Offer to file separate issues for each group, reusing shared context (environment, etc.).
|
||||
4. Let the user decide: proceed as-is or split.
|
||||
|
||||
### Step 5: Construct Issue Body
|
||||
|
||||
Build the issue body as markdown sections matching GitHub's form-field rendering format. GitHub renders form-submitted issues with `### <Field Label>` sections, so use that exact structure.
|
||||
|
||||
For each non-markdown field from the template, in order:
|
||||
|
||||
```markdown
|
||||
### <attributes.label>
|
||||
|
||||
<value>
|
||||
```
|
||||
|
||||
For optional fields with no content, use `_No response_` as the value (this matches GitHub's native rendering for empty optional fields).
|
||||
|
||||
For checkbox fields, render each option as:
|
||||
```markdown
|
||||
- [X] <option label text>
|
||||
```
|
||||
|
||||
### Step 6: Final Preview and Submit
|
||||
|
||||
Show the final constructed issue (title + labels + full body) for one last confirmation.
|
||||
|
||||
Then submit using a HEREDOC for the body to preserve formatting:
|
||||
|
||||
```bash
|
||||
gh issue create --title "<title prefix><user title>" --label "<label1>,<label2>" --body "$(cat <<'ISSUE_EOF'
|
||||
<body content>
|
||||
ISSUE_EOF
|
||||
)"
|
||||
```
|
||||
|
||||
Return the resulting issue URL to the user.
|
||||
|
||||
### Important Rules
|
||||
|
||||
- **Always read the template file** — never assume field names, options, or structure. The templates are the source of truth and may change over time.
|
||||
- **Never include personal/sensitive data** in the issue. Redact secrets, tokens, emails, real names.
|
||||
- **Use neutral project-scoped placeholders** per ZeroClaw's privacy contract.
|
||||
- **One concept per issue** — enforce the scope guard.
|
||||
- **Auto-detect, don't guess** — use real command output for environment fields.
|
||||
- **Match GitHub's rendering** — use `### Field Label` sections so issues look consistent whether filed via web UI or this skill.
|
||||
@ -1,209 +0,0 @@
|
||||
# Skill: github-pr
|
||||
|
||||
Open or update a GitHub Pull Request for ZeroClaw. Handles creating new PRs with a fully filled-out template body, and updating existing PRs (title, body sections, labels, comments). Use this skill whenever the user wants to open a PR, create a pull request, update a PR, edit PR description, add labels to a PR, or sync a PR after new commits — even if they don't say "PR" explicitly (e.g., "submit this for review", "push and open for merge").
|
||||
|
||||
## Instructions
|
||||
|
||||
This skill supports two modes: **Open** (create a new PR) and **Update** (edit an existing PR). Detect the mode from context — if there's already an open PR for the current branch and the user didn't say "open a new PR", default to update mode.
|
||||
|
||||
The PR template at `.github/pull_request_template.md` is the source of truth for the PR body structure. Read it every time — never assume or hardcode section names, fields, or their order. The template may change over time and the skill should always reflect its current state.
|
||||
|
||||
---
|
||||
|
||||
## Shared: Read the PR Template
|
||||
|
||||
Before opening or updating a PR body, read `.github/pull_request_template.md` and parse it to understand:
|
||||
|
||||
- The `## ` section headers (these are the top-level sections of the PR body)
|
||||
- The bullet points, fields, and prompts within each section
|
||||
- Which sections are marked `(required)` vs optional/recommended
|
||||
- Any inline formatting conventions (backtick options, Yes/No fields, etc.)
|
||||
|
||||
This parsed structure drives how you fill, present, and edit the PR body.
|
||||
|
||||
---
|
||||
|
||||
## Mode: Open a New PR
|
||||
|
||||
### Step 1: Gather Context
|
||||
|
||||
Collect information to pre-fill the PR body. Run these in parallel:
|
||||
|
||||
```bash
|
||||
# Branch and commit context
|
||||
git branch --show-current
|
||||
git log master..HEAD --oneline
|
||||
git diff master...HEAD --stat
|
||||
|
||||
# Check if branch is pushed
|
||||
git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null
|
||||
|
||||
# Environment (for validation evidence)
|
||||
rustc --version 2>/dev/null
|
||||
```
|
||||
|
||||
Also review the changed files and commit messages to understand the nature of the change (bug fix, feature, refactor, docs, chore, etc.) and which subsystems are affected.
|
||||
|
||||
### Step 2: Pre-Fill the Template
|
||||
|
||||
Using the parsed template structure and gathered context, draft a complete PR body:
|
||||
|
||||
- For each `## ` section from the template, fill in the bullet points and fields based on context from the commits, diff, and changed files.
|
||||
- Use the field descriptions and placeholder text in the template as guidance for what each field expects.
|
||||
- For Yes/No fields, infer from the diff (e.g., if no files in `src/security/` changed, security impact is likely all No).
|
||||
- For required sections, always provide a substantive answer. For optional sections, fill if there's enough context, otherwise leave the template prompts in place.
|
||||
- Draft a conventional commit-style PR title based on the changes (e.g., `feat(provider): add retry budget override`, `fix(channel): handle disconnect gracefully`, `chore(ci): update workflow targets`).
|
||||
|
||||
### Step 3: Present Draft for Review
|
||||
|
||||
Show the user the complete draft:
|
||||
|
||||
```
|
||||
## PR Draft: <title>
|
||||
**Branch**: <head> -> master
|
||||
**Labels**: <suggested labels>
|
||||
|
||||
<full body with all sections filled>
|
||||
```
|
||||
|
||||
Ask the user to review: "Here's the pre-filled PR. Review and let me know what to change, or say 'submit' to open it."
|
||||
|
||||
Iterate on changes until the user approves.
|
||||
|
||||
### Step 4: Push and Create
|
||||
|
||||
1. If the branch isn't pushed yet, push it:
|
||||
```bash
|
||||
git push -u origin <branch>
|
||||
```
|
||||
|
||||
2. Create the PR using a HEREDOC for the body:
|
||||
```bash
|
||||
gh pr create --title "<title>" --base master --body "$(cat <<'PR_BODY_EOF'
|
||||
<full body>
|
||||
PR_BODY_EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. If labels were agreed on, add them:
|
||||
```bash
|
||||
gh pr edit <number> --add-label "<label1>,<label2>"
|
||||
```
|
||||
|
||||
4. Return the PR URL to the user.
|
||||
|
||||
---
|
||||
|
||||
## Mode: Update an Existing PR
|
||||
|
||||
### Step 1: Identify the PR
|
||||
|
||||
1. **If a PR number or URL is given**: use that directly.
|
||||
2. **If on a branch with an open PR**: auto-detect:
|
||||
```bash
|
||||
gh pr view --json number,title,body,labels,state,author,url,headRefName 2>/dev/null
|
||||
```
|
||||
3. **If neither**: ask the user for the PR number.
|
||||
|
||||
Verify the current user is the PR author:
|
||||
```bash
|
||||
CURRENT_USER=$(gh api user --jq '.login')
|
||||
PR_AUTHOR=$(gh pr view <number> --json author --jq '.author.login')
|
||||
```
|
||||
If not the author, stop and inform the user.
|
||||
|
||||
### Step 2: Fetch Current State
|
||||
|
||||
```bash
|
||||
gh pr view <number> --json number,title,body,labels,state,baseRefName,headRefName,url,author,reviewDecision,statusCheckRollup,commits
|
||||
```
|
||||
|
||||
Display a summary:
|
||||
```
|
||||
## PR #<number>: <title>
|
||||
**State**: <open/closed/merged>
|
||||
**Branch**: <head> -> <base>
|
||||
**Labels**: <label list>
|
||||
**Checks**: <pass/fail/pending>
|
||||
**URL**: <url>
|
||||
```
|
||||
|
||||
### Step 3: Determine What to Update
|
||||
|
||||
Support these operations:
|
||||
|
||||
| Operation | How |
|
||||
|---|---|
|
||||
| **Edit title** | `gh pr edit <number> --title "<new title>"` |
|
||||
| **Edit full body** | `gh pr edit <number> --body "<new body>"` |
|
||||
| **Add labels** | `gh pr edit <number> --add-label "<label1>,<label2>"` |
|
||||
| **Remove labels** | `gh pr edit <number> --remove-label "<label1>"` |
|
||||
| **Edit specific section** | Parse body by `## ` headers, modify target section, re-submit full body |
|
||||
| **Add a comment** | `gh pr comment <number> --body "<comment>"` |
|
||||
| **Link an issue** | Edit the linked-issue section in the body |
|
||||
| **Smart update after new commits** | Re-analyze and suggest section updates |
|
||||
|
||||
### Step 4: Handle Body Section Edits
|
||||
|
||||
When editing a specific section:
|
||||
|
||||
1. Parse the current PR body into sections by `## ` headers
|
||||
2. Match the user's request to the corresponding section from the template
|
||||
3. Show the current content of that section and the proposed replacement
|
||||
4. On confirmation, modify only that section, reconstruct the full body, and submit
|
||||
|
||||
### Step 5: Smart Update After New Commits
|
||||
|
||||
When the user wants to sync the PR description after pushing new changes:
|
||||
|
||||
1. Identify new commits:
|
||||
```bash
|
||||
gh pr view <number> --json commits --jq '.commits[].messageHeadline'
|
||||
git log <base>..<head> --oneline
|
||||
git diff <base>...<head> --stat
|
||||
```
|
||||
|
||||
2. Re-read the PR template. Analyze which sections are now stale based on the new changes — use the template's section names and field descriptions to identify what needs updating rather than relying on hardcoded assumptions.
|
||||
|
||||
3. Present proposed updates section-by-section and confirm before applying.
|
||||
|
||||
### Step 6: Apply Updates
|
||||
|
||||
For title/label changes, use direct `gh pr edit` flags.
|
||||
|
||||
For body edits, use a HEREDOC:
|
||||
```bash
|
||||
gh pr edit <number> --body "$(cat <<'PR_BODY_EOF'
|
||||
<full updated body>
|
||||
PR_BODY_EOF
|
||||
)"
|
||||
```
|
||||
|
||||
For comments:
|
||||
```bash
|
||||
gh pr comment <number> --body "$(cat <<'COMMENT_EOF'
|
||||
<comment text>
|
||||
COMMENT_EOF
|
||||
)"
|
||||
```
|
||||
|
||||
### Step 7: Confirm
|
||||
|
||||
Fetch and display the updated state:
|
||||
```bash
|
||||
gh pr view <number> --json number,title,labels,url
|
||||
```
|
||||
|
||||
Return the PR URL.
|
||||
|
||||
---
|
||||
|
||||
## Important Rules
|
||||
|
||||
- **Always read `.github/pull_request_template.md`** before filling or editing a PR body. Never assume section names, fields, or structure — derive everything from the template. It's the source of truth and may change.
|
||||
- **For updates, only modify requested sections.** Preserve everything else exactly as-is.
|
||||
- **Always show diffs before applying body edits.** Present current vs proposed for each changed section.
|
||||
- **Never include personal/sensitive data** in PR content per ZeroClaw's privacy contract.
|
||||
- **For label changes**, only use labels that exist in the repository. Check with `gh label list` if unsure.
|
||||
- **Fetch the latest body before editing** to avoid clobbering concurrent changes.
|
||||
- **For new PRs**, push the branch before creating (with `-u` to set upstream tracking).
|
||||
@ -1,202 +0,0 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@ -1,485 +0,0 @@
|
||||
---
|
||||
name: skill-creator
|
||||
description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
|
||||
---
|
||||
|
||||
# Skill Creator
|
||||
|
||||
A skill for creating new skills and iteratively improving them.
|
||||
|
||||
At a high level, the process of creating a skill goes like this:
|
||||
|
||||
- Decide what you want the skill to do and roughly how it should do it
|
||||
- Write a draft of the skill
|
||||
- Create a few test prompts and run claude-with-access-to-the-skill on them
|
||||
- Help the user evaluate the results both qualitatively and quantitatively
|
||||
- While the runs happen in the background, draft some quantitative evals if there aren't any (if there are some, you can either use as is or modify if you feel something needs to change about them). Then explain them to the user (or if they already existed, explain the ones that already exist)
|
||||
- Use the `eval-viewer/generate_review.py` script to show the user the results for them to look at, and also let them look at the quantitative metrics
|
||||
- Rewrite the skill based on feedback from the user's evaluation of the results (and also if there are any glaring flaws that become apparent from the quantitative benchmarks)
|
||||
- Repeat until you're satisfied
|
||||
- Expand the test set and try again at larger scale
|
||||
|
||||
Your job when using this skill is to figure out where the user is in this process and then jump in and help them progress through these stages. So for instance, maybe they're like "I want to make a skill for X". You can help narrow down what they mean, write a draft, write the test cases, figure out how they want to evaluate, run all the prompts, and repeat.
|
||||
|
||||
On the other hand, maybe they already have a draft of the skill. In this case you can go straight to the eval/iterate part of the loop.
|
||||
|
||||
Of course, you should always be flexible and if the user is like "I don't need to run a bunch of evaluations, just vibe with me", you can do that instead.
|
||||
|
||||
Then after the skill is done (but again, the order is flexible), you can also run the skill description improver, which we have a whole separate script for, to optimize the triggering of the skill.
|
||||
|
||||
Cool? Cool.
|
||||
|
||||
## Communicating with the user
|
||||
|
||||
The skill creator is liable to be used by people across a wide range of familiarity with coding jargon. If you haven't heard (and how could you, it's only very recently that it started), there's a trend now where the power of Claude is inspiring plumbers to open up their terminals, parents and grandparents to google "how to install npm". On the other hand, the bulk of users are probably fairly computer-literate.
|
||||
|
||||
So please pay attention to context cues to understand how to phrase your communication! In the default case, just to give you some idea:
|
||||
|
||||
- "evaluation" and "benchmark" are borderline, but OK
|
||||
- for "JSON" and "assertion" you want to see serious cues from the user that they know what those things are before using them without explaining them
|
||||
|
||||
It's OK to briefly explain terms if you're in doubt, and feel free to clarify terms with a short definition if you're unsure if the user will get it.
|
||||
|
||||
---
|
||||
|
||||
## Creating a skill
|
||||
|
||||
### Capture Intent
|
||||
|
||||
Start by understanding the user's intent. The current conversation might already contain a workflow the user wants to capture (e.g., they say "turn this into a skill"). If so, extract answers from the conversation history first — the tools used, the sequence of steps, corrections the user made, input/output formats observed. The user may need to fill the gaps, and should confirm before proceeding to the next step.
|
||||
|
||||
1. What should this skill enable Claude to do?
|
||||
2. When should this skill trigger? (what user phrases/contexts)
|
||||
3. What's the expected output format?
|
||||
4. Should we set up test cases to verify the skill works? Skills with objectively verifiable outputs (file transforms, data extraction, code generation, fixed workflow steps) benefit from test cases. Skills with subjective outputs (writing style, art) often don't need them. Suggest the appropriate default based on the skill type, but let the user decide.
|
||||
|
||||
### Interview and Research
|
||||
|
||||
Proactively ask questions about edge cases, input/output formats, example files, success criteria, and dependencies. Wait to write test prompts until you've got this part ironed out.
|
||||
|
||||
Check available MCPs - if useful for research (searching docs, finding similar skills, looking up best practices), research in parallel via subagents if available, otherwise inline. Come prepared with context to reduce burden on the user.
|
||||
|
||||
### Write the SKILL.md
|
||||
|
||||
Based on the user interview, fill in these components:
|
||||
|
||||
- **name**: Skill identifier
|
||||
- **description**: When to trigger, what it does. This is the primary triggering mechanism - include both what the skill does AND specific contexts for when to use it. All "when to use" info goes here, not in the body. Note: currently Claude has a tendency to "undertrigger" skills -- to not use them when they'd be useful. To combat this, please make the skill descriptions a little bit "pushy". So for instance, instead of "How to build a simple fast dashboard to display internal Anthropic data.", you might write "How to build a simple fast dashboard to display internal Anthropic data. Make sure to use this skill whenever the user mentions dashboards, data visualization, internal metrics, or wants to display any kind of company data, even if they don't explicitly ask for a 'dashboard.'"
|
||||
- **compatibility**: Required tools, dependencies (optional, rarely needed)
|
||||
- **the rest of the skill :)**
|
||||
|
||||
### Skill Writing Guide
|
||||
|
||||
#### Anatomy of a Skill
|
||||
|
||||
```
|
||||
skill-name/
|
||||
├── SKILL.md (required)
|
||||
│ ├── YAML frontmatter (name, description required)
|
||||
│ └── Markdown instructions
|
||||
└── Bundled Resources (optional)
|
||||
├── scripts/ - Executable code for deterministic/repetitive tasks
|
||||
├── references/ - Docs loaded into context as needed
|
||||
└── assets/ - Files used in output (templates, icons, fonts)
|
||||
```
|
||||
|
||||
#### Progressive Disclosure
|
||||
|
||||
Skills use a three-level loading system:
|
||||
1. **Metadata** (name + description) - Always in context (~100 words)
|
||||
2. **SKILL.md body** - In context whenever skill triggers (<500 lines ideal)
|
||||
3. **Bundled resources** - As needed (unlimited, scripts can execute without loading)
|
||||
|
||||
These word counts are approximate and you can feel free to go longer if needed.
|
||||
|
||||
**Key patterns:**
|
||||
- Keep SKILL.md under 500 lines; if you're approaching this limit, add an additional layer of hierarchy along with clear pointers about where the model using the skill should go next to follow up.
|
||||
- Reference files clearly from SKILL.md with guidance on when to read them
|
||||
- For large reference files (>300 lines), include a table of contents
|
||||
|
||||
**Domain organization**: When a skill supports multiple domains/frameworks, organize by variant:
|
||||
```
|
||||
cloud-deploy/
|
||||
├── SKILL.md (workflow + selection)
|
||||
└── references/
|
||||
├── aws.md
|
||||
├── gcp.md
|
||||
└── azure.md
|
||||
```
|
||||
Claude reads only the relevant reference file.
|
||||
|
||||
#### Principle of Lack of Surprise
|
||||
|
||||
This goes without saying, but skills must not contain malware, exploit code, or any content that could compromise system security. A skill's contents should not surprise the user in their intent if described. Don't go along with requests to create misleading skills or skills designed to facilitate unauthorized access, data exfiltration, or other malicious activities. Things like a "roleplay as an XYZ" are OK though.
|
||||
|
||||
#### Writing Patterns
|
||||
|
||||
Prefer using the imperative form in instructions.
|
||||
|
||||
**Defining output formats** - You can do it like this:
|
||||
```markdown
|
||||
## Report structure
|
||||
ALWAYS use this exact template:
|
||||
# [Title]
|
||||
## Executive summary
|
||||
## Key findings
|
||||
## Recommendations
|
||||
```
|
||||
|
||||
**Examples pattern** - It's useful to include examples. You can format them like this (but if "Input" and "Output" are in the examples you might want to deviate a little):
|
||||
```markdown
|
||||
## Commit message format
|
||||
**Example 1:**
|
||||
Input: Added user authentication with JWT tokens
|
||||
Output: feat(auth): implement JWT-based authentication
|
||||
```
|
||||
|
||||
### Writing Style
|
||||
|
||||
Try to explain to the model why things are important in lieu of heavy-handed musty MUSTs. Use theory of mind and try to make the skill general and not super-narrow to specific examples. Start by writing a draft and then look at it with fresh eyes and improve it.
|
||||
|
||||
### Test Cases
|
||||
|
||||
After writing the skill draft, come up with 2-3 realistic test prompts — the kind of thing a real user would actually say. Share them with the user: [you don't have to use this exact language] "Here are a few test cases I'd like to try. Do these look right, or do you want to add more?" Then run them.
|
||||
|
||||
Save test cases to `evals/evals.json`. Don't write assertions yet — just the prompts. You'll draft assertions in the next step while the runs are in progress.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's task prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
See `references/schemas.md` for the full schema (including the `assertions` field, which you'll add later).
|
||||
|
||||
## Running and evaluating test cases
|
||||
|
||||
This section is one continuous sequence — don't stop partway through. Do NOT use `/skill-test` or any other testing skill.
|
||||
|
||||
Put results in `<skill-name>-workspace/` as a sibling to the skill directory. Within the workspace, organize results by iteration (`iteration-1/`, `iteration-2/`, etc.) and within that, each test case gets a directory (`eval-0/`, `eval-1/`, etc.). Don't create all of this upfront — just create directories as you go.
|
||||
|
||||
### Step 1: Spawn all runs (with-skill AND baseline) in the same turn
|
||||
|
||||
For each test case, spawn two subagents in the same turn — one with the skill, one without. This is important: don't spawn the with-skill runs first and then come back for baselines later. Launch everything at once so it all finishes around the same time.
|
||||
|
||||
**With-skill run:**
|
||||
|
||||
```
|
||||
Execute this task:
|
||||
- Skill path: <path-to-skill>
|
||||
- Task: <eval prompt>
|
||||
- Input files: <eval files if any, or "none">
|
||||
- Save outputs to: <workspace>/iteration-<N>/eval-<ID>/with_skill/outputs/
|
||||
- Outputs to save: <what the user cares about — e.g., "the .docx file", "the final CSV">
|
||||
```
|
||||
|
||||
**Baseline run** (same prompt, but the baseline depends on context):
|
||||
- **Creating a new skill**: no skill at all. Same prompt, no skill path, save to `without_skill/outputs/`.
|
||||
- **Improving an existing skill**: the old version. Before editing, snapshot the skill (`cp -r <skill-path> <workspace>/skill-snapshot/`), then point the baseline subagent at the snapshot. Save to `old_skill/outputs/`.
|
||||
|
||||
Write an `eval_metadata.json` for each test case (assertions can be empty for now). Give each eval a descriptive name based on what it's testing — not just "eval-0". Use this name for the directory too. If this iteration uses new or modified eval prompts, create these files for each new eval directory — don't assume they carry over from previous iterations.
|
||||
|
||||
```json
|
||||
{
|
||||
"eval_id": 0,
|
||||
"eval_name": "descriptive-name-here",
|
||||
"prompt": "The user's task prompt",
|
||||
"assertions": []
|
||||
}
|
||||
```
|
||||
|
||||
### Step 2: While runs are in progress, draft assertions
|
||||
|
||||
Don't just wait for the runs to finish — you can use this time productively. Draft quantitative assertions for each test case and explain them to the user. If assertions already exist in `evals/evals.json`, review them and explain what they check.
|
||||
|
||||
Good assertions are objectively verifiable and have descriptive names — they should read clearly in the benchmark viewer so someone glancing at the results immediately understands what each one checks. Subjective skills (writing style, design quality) are better evaluated qualitatively — don't force assertions onto things that need human judgment.
|
||||
|
||||
Update the `eval_metadata.json` files and `evals/evals.json` with the assertions once drafted. Also explain to the user what they'll see in the viewer — both the qualitative outputs and the quantitative benchmark.
|
||||
|
||||
### Step 3: As runs complete, capture timing data
|
||||
|
||||
When each subagent task completes, you receive a notification containing `total_tokens` and `duration_ms`. Save this data immediately to `timing.json` in the run directory:
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3
|
||||
}
|
||||
```
|
||||
|
||||
This is the only opportunity to capture this data — it comes through the task notification and isn't persisted elsewhere. Process each notification as it arrives rather than trying to batch them.
|
||||
|
||||
### Step 4: Grade, aggregate, and launch the viewer
|
||||
|
||||
Once all runs are done:
|
||||
|
||||
1. **Grade each run** — spawn a grader subagent (or grade inline) that reads `agents/grader.md` and evaluates each assertion against the outputs. Save results to `grading.json` in each run directory. The grading.json expectations array must use the fields `text`, `passed`, and `evidence` (not `name`/`met`/`details` or other variants) — the viewer depends on these exact field names. For assertions that can be checked programmatically, write and run a script rather than eyeballing it — scripts are faster, more reliable, and can be reused across iterations.
|
||||
|
||||
2. **Aggregate into benchmark** — run the aggregation script from the skill-creator directory:
|
||||
```bash
|
||||
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>
|
||||
```
|
||||
This produces `benchmark.json` and `benchmark.md` with pass_rate, time, and tokens for each configuration, with mean ± stddev and the delta. If generating benchmark.json manually, see `references/schemas.md` for the exact schema the viewer expects.
|
||||
Put each with_skill version before its baseline counterpart.
|
||||
|
||||
3. **Do an analyst pass** — read the benchmark data and surface patterns the aggregate stats might hide. See `agents/analyzer.md` (the "Analyzing Benchmark Results" section) for what to look for — things like assertions that always pass regardless of skill (non-discriminating), high-variance evals (possibly flaky), and time/token tradeoffs.
|
||||
|
||||
4. **Launch the viewer** with both qualitative outputs and quantitative data:
|
||||
```bash
|
||||
nohup python <skill-creator-path>/eval-viewer/generate_review.py \
|
||||
<workspace>/iteration-N \
|
||||
--skill-name "my-skill" \
|
||||
--benchmark <workspace>/iteration-N/benchmark.json \
|
||||
> /dev/null 2>&1 &
|
||||
VIEWER_PID=$!
|
||||
```
|
||||
For iteration 2+, also pass `--previous-workspace <workspace>/iteration-<N-1>`.
|
||||
|
||||
**Cowork / headless environments:** If `webbrowser.open()` is not available or the environment has no display, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Feedback will be downloaded as a `feedback.json` file when the user clicks "Submit All Reviews". After download, copy `feedback.json` into the workspace directory for the next iteration to pick up.
|
||||
|
||||
Note: please use generate_review.py to create the viewer; there's no need to write custom HTML.
|
||||
|
||||
5. **Tell the user** something like: "I've opened the results in your browser. There are two tabs — 'Outputs' lets you click through each test case and leave feedback, 'Benchmark' shows the quantitative comparison. When you're done, come back here and let me know."
|
||||
|
||||
### What the user sees in the viewer
|
||||
|
||||
The "Outputs" tab shows one test case at a time:
|
||||
- **Prompt**: the task that was given
|
||||
- **Output**: the files the skill produced, rendered inline where possible
|
||||
- **Previous Output** (iteration 2+): collapsed section showing last iteration's output
|
||||
- **Formal Grades** (if grading was run): collapsed section showing assertion pass/fail
|
||||
- **Feedback**: a textbox that auto-saves as they type
|
||||
- **Previous Feedback** (iteration 2+): their comments from last time, shown below the textbox
|
||||
|
||||
The "Benchmark" tab shows the stats summary: pass rates, timing, and token usage for each configuration, with per-eval breakdowns and analyst observations.
|
||||
|
||||
Navigation is via prev/next buttons or arrow keys. When done, they click "Submit All Reviews" which saves all feedback to `feedback.json`.
|
||||
|
||||
### Step 5: Read the feedback
|
||||
|
||||
When the user tells you they're done, read `feedback.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"reviews": [
|
||||
{"run_id": "eval-0-with_skill", "feedback": "the chart is missing axis labels", "timestamp": "..."},
|
||||
{"run_id": "eval-1-with_skill", "feedback": "", "timestamp": "..."},
|
||||
{"run_id": "eval-2-with_skill", "feedback": "perfect, love this", "timestamp": "..."}
|
||||
],
|
||||
"status": "complete"
|
||||
}
|
||||
```
|
||||
|
||||
Empty feedback means the user thought it was fine. Focus your improvements on the test cases where the user had specific complaints.
|
||||
|
||||
Kill the viewer server when you're done with it:
|
||||
|
||||
```bash
|
||||
kill $VIEWER_PID 2>/dev/null
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Improving the skill
|
||||
|
||||
This is the heart of the loop. You've run the test cases, the user has reviewed the results, and now you need to make the skill better based on their feedback.
|
||||
|
||||
### How to think about improvements
|
||||
|
||||
1. **Generalize from the feedback.** The big picture thing that's happening here is that we're trying to create skills that can be used a million times (maybe literally, maybe even more who knows) across many different prompts. Here you and the user are iterating on only a few examples over and over again because it helps move faster. The user knows these examples in and out and it's quick for them to assess new outputs. But if the skill you and the user are codeveloping works only for those examples, it's useless. Rather than put in fiddly overfitty changes, or oppressively constrictive MUSTs, if there's some stubborn issue, you might try branching out and using different metaphors, or recommending different patterns of working. It's relatively cheap to try and maybe you'll land on something great.
|
||||
|
||||
2. **Keep the prompt lean.** Remove things that aren't pulling their weight. Make sure to read the transcripts, not just the final outputs — if it looks like the skill is making the model waste a bunch of time doing things that are unproductive, you can try getting rid of the parts of the skill that are making it do that and seeing what happens.
|
||||
|
||||
3. **Explain the why.** Try hard to explain the **why** behind everything you're asking the model to do. Today's LLMs are *smart*. They have good theory of mind and when given a good harness can go beyond rote instructions and really make things happen. Even if the feedback from the user is terse or frustrated, try to actually understand the task and why the user is writing what they wrote, and what they actually wrote, and then transmit this understanding into the instructions. If you find yourself writing ALWAYS or NEVER in all caps, or using super rigid structures, that's a yellow flag — if possible, reframe and explain the reasoning so that the model understands why the thing you're asking for is important. That's a more humane, powerful, and effective approach.
|
||||
|
||||
4. **Look for repeated work across test cases.** Read the transcripts from the test runs and notice if the subagents all independently wrote similar helper scripts or took the same multi-step approach to something. If all 3 test cases resulted in the subagent writing a `create_docx.py` or a `build_chart.py`, that's a strong signal the skill should bundle that script. Write it once, put it in `scripts/`, and tell the skill to use it. This saves every future invocation from reinventing the wheel.
|
||||
|
||||
This task is pretty important (we are trying to create billions a year in economic value here!) and your thinking time is not the blocker; take your time and really mull things over. I'd suggest writing a draft revision and then looking at it anew and making improvements. Really do your best to get into the head of the user and understand what they want and need.
|
||||
|
||||
### The iteration loop
|
||||
|
||||
After improving the skill:
|
||||
|
||||
1. Apply your improvements to the skill
|
||||
2. Rerun all test cases into a new `iteration-<N+1>/` directory, including baseline runs. If you're creating a new skill, the baseline is always `without_skill` (no skill) — that stays the same across iterations. If you're improving an existing skill, use your judgment on what makes sense as the baseline: the original version the user came in with, or the previous iteration.
|
||||
3. Launch the reviewer with `--previous-workspace` pointing at the previous iteration
|
||||
4. Wait for the user to review and tell you they're done
|
||||
5. Read the new feedback, improve again, repeat
|
||||
|
||||
Keep going until:
|
||||
- The user says they're happy
|
||||
- The feedback is all empty (everything looks good)
|
||||
- You're not making meaningful progress
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Blind comparison
|
||||
|
||||
For situations where you want a more rigorous comparison between two versions of a skill (e.g., the user asks "is the new version actually better?"), there's a blind comparison system. Read `agents/comparator.md` and `agents/analyzer.md` for the details. The basic idea is: give two outputs to an independent agent without telling it which is which, and let it judge quality. Then analyze why the winner won.
|
||||
|
||||
This is optional, requires subagents, and most users won't need it. The human review loop is usually sufficient.
|
||||
|
||||
---
|
||||
|
||||
## Description Optimization
|
||||
|
||||
The description field in SKILL.md frontmatter is the primary mechanism that determines whether Claude invokes a skill. After creating or improving a skill, offer to optimize the description for better triggering accuracy.
|
||||
|
||||
### Step 1: Generate trigger eval queries
|
||||
|
||||
Create 20 eval queries — a mix of should-trigger and should-not-trigger. Save as JSON:
|
||||
|
||||
```json
|
||||
[
|
||||
{"query": "the user prompt", "should_trigger": true},
|
||||
{"query": "another prompt", "should_trigger": false}
|
||||
]
|
||||
```
|
||||
|
||||
The queries must be realistic and something a Claude Code or Claude.ai user would actually type. Not abstract requests, but requests that are concrete and specific and have a good amount of detail. For instance, file paths, personal context about the user's job or situation, column names and values, company names, URLs. A little bit of backstory. Some might be in lowercase or contain abbreviations or typos or casual speech. Use a mix of different lengths, and focus on edge cases rather than making them clear-cut (the user will get a chance to sign off on them).
|
||||
|
||||
Bad: `"Format this data"`, `"Extract text from PDF"`, `"Create a chart"`
|
||||
|
||||
Good: `"ok so my boss just sent me this xlsx file (its in my downloads, called something like 'Q4 sales final FINAL v2.xlsx') and she wants me to add a column that shows the profit margin as a percentage. The revenue is in column C and costs are in column D i think"`
|
||||
|
||||
For the **should-trigger** queries (8-10), think about coverage. You want different phrasings of the same intent — some formal, some casual. Include cases where the user doesn't explicitly name the skill or file type but clearly needs it. Throw in some uncommon use cases and cases where this skill competes with another but should win.
|
||||
|
||||
For the **should-not-trigger** queries (8-10), the most valuable ones are the near-misses — queries that share keywords or concepts with the skill but actually need something different. Think adjacent domains, ambiguous phrasing where a naive keyword match would trigger but shouldn't, and cases where the query touches on something the skill does but in a context where another tool is more appropriate.
|
||||
|
||||
The key thing to avoid: don't make should-not-trigger queries obviously irrelevant. "Write a fibonacci function" as a negative test for a PDF skill is too easy — it doesn't test anything. The negative cases should be genuinely tricky.
|
||||
|
||||
### Step 2: Review with user
|
||||
|
||||
Present the eval set to the user for review using the HTML template:
|
||||
|
||||
1. Read the template from `assets/eval_review.html`
|
||||
2. Replace the placeholders:
|
||||
- `__EVAL_DATA_PLACEHOLDER__` → the JSON array of eval items (no quotes around it — it's a JS variable assignment)
|
||||
- `__SKILL_NAME_PLACEHOLDER__` → the skill's name
|
||||
- `__SKILL_DESCRIPTION_PLACEHOLDER__` → the skill's current description
|
||||
3. Write to a temp file (e.g., `/tmp/eval_review_<skill-name>.html`) and open it: `open /tmp/eval_review_<skill-name>.html`
|
||||
4. The user can edit queries, toggle should-trigger, add/remove entries, then click "Export Eval Set"
|
||||
5. The file downloads to `~/Downloads/eval_set.json` — check the Downloads folder for the most recent version in case there are multiple (e.g., `eval_set (1).json`)
|
||||
|
||||
This step matters — bad eval queries lead to bad descriptions.
|
||||
|
||||
### Step 3: Run the optimization loop
|
||||
|
||||
Tell the user: "This will take some time — I'll run the optimization loop in the background and check on it periodically."
|
||||
|
||||
Save the eval set to the workspace, then run in the background:
|
||||
|
||||
```bash
|
||||
python -m scripts.run_loop \
|
||||
--eval-set <path-to-trigger-eval.json> \
|
||||
--skill-path <path-to-skill> \
|
||||
--model <model-id-powering-this-session> \
|
||||
--max-iterations 5 \
|
||||
--verbose
|
||||
```
|
||||
|
||||
Use the model ID from your system prompt (the one powering the current session) so the triggering test matches what the user actually experiences.
|
||||
|
||||
While it runs, periodically tail the output to give the user updates on which iteration it's on and what the scores look like.
|
||||
|
||||
This handles the full optimization loop automatically. It splits the eval set into 60% train and 40% held-out test, evaluates the current description (running each query 3 times to get a reliable trigger rate), then calls Claude to propose improvements based on what failed. It re-evaluates each new description on both train and test, iterating up to 5 times. When it's done, it opens an HTML report in the browser showing the results per iteration and returns JSON with `best_description` — selected by test score rather than train score to avoid overfitting.
|
||||
|
||||
### How skill triggering works
|
||||
|
||||
Understanding the triggering mechanism helps design better eval queries. Skills appear in Claude's `available_skills` list with their name + description, and Claude decides whether to consult a skill based on that description. The important thing to know is that Claude only consults skills for tasks it can't easily handle on its own — simple, one-step queries like "read this PDF" may not trigger a skill even if the description matches perfectly, because Claude can handle them directly with basic tools. Complex, multi-step, or specialized queries reliably trigger skills when the description matches.
|
||||
|
||||
This means your eval queries should be substantive enough that Claude would actually benefit from consulting a skill. Simple queries like "read file X" are poor test cases — they won't trigger skills regardless of description quality.
|
||||
|
||||
### Step 4: Apply the result
|
||||
|
||||
Take `best_description` from the JSON output and update the skill's SKILL.md frontmatter. Show the user before/after and report the scores.
|
||||
|
||||
---
|
||||
|
||||
### Package and Present (only if `present_files` tool is available)
|
||||
|
||||
Check whether you have access to the `present_files` tool. If you don't, skip this step. If you do, package the skill and present the .skill file to the user:
|
||||
|
||||
```bash
|
||||
python -m scripts.package_skill <path/to/skill-folder>
|
||||
```
|
||||
|
||||
After packaging, direct the user to the resulting `.skill` file path so they can install it.
|
||||
|
||||
---
|
||||
|
||||
## Claude.ai-specific instructions
|
||||
|
||||
In Claude.ai, the core workflow is the same (draft → test → review → improve → repeat), but because Claude.ai doesn't have subagents, some mechanics change. Here's what to adapt:
|
||||
|
||||
**Running test cases**: No subagents means no parallel execution. For each test case, read the skill's SKILL.md, then follow its instructions to accomplish the test prompt yourself. Do them one at a time. This is less rigorous than independent subagents (you wrote the skill and you're also running it, so you have full context), but it's a useful sanity check — and the human review step compensates. Skip the baseline runs — just use the skill to complete the task as requested.
|
||||
|
||||
**Reviewing results**: If you can't open a browser (e.g., Claude.ai's VM has no display, or you're on a remote server), skip the browser reviewer entirely. Instead, present results directly in the conversation. For each test case, show the prompt and the output. If the output is a file the user needs to see (like a .docx or .xlsx), save it to the filesystem and tell them where it is so they can download and inspect it. Ask for feedback inline: "How does this look? Anything you'd change?"
|
||||
|
||||
**Benchmarking**: Skip the quantitative benchmarking — it relies on baseline comparisons which aren't meaningful without subagents. Focus on qualitative feedback from the user.
|
||||
|
||||
**The iteration loop**: Same as before — improve the skill, rerun the test cases, ask for feedback — just without the browser reviewer in the middle. You can still organize results into iteration directories on the filesystem if you have one.
|
||||
|
||||
**Description optimization**: This section requires the `claude` CLI tool (specifically `claude -p`) which is only available in Claude Code. Skip it if you're on Claude.ai.
|
||||
|
||||
**Blind comparison**: Requires subagents. Skip it.
|
||||
|
||||
**Packaging**: The `package_skill.py` script works anywhere with Python and a filesystem. On Claude.ai, you can run it and the user can download the resulting `.skill` file.
|
||||
|
||||
**Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. In this case:
|
||||
- **Preserve the original name.** Note the skill's directory name and `name` frontmatter field -- use them unchanged. E.g., if the installed skill is `research-helper`, output `research-helper.skill` (not `research-helper-v2`).
|
||||
- **Copy to a writeable location before editing.** The installed skill path may be read-only. Copy to `/tmp/skill-name/`, edit there, and package from the copy.
|
||||
- **If packaging manually, stage in `/tmp/` first**, then copy to the output directory -- direct writes may fail due to permissions.
|
||||
|
||||
---
|
||||
|
||||
## Cowork-Specific Instructions
|
||||
|
||||
If you're in Cowork, the main things to know are:
|
||||
|
||||
- You have subagents, so the main workflow (spawn test cases in parallel, run baselines, grade, etc.) all works. (However, if you run into severe problems with timeouts, it's OK to run the test prompts in series rather than parallel.)
|
||||
- You don't have a browser or display, so when generating the eval viewer, use `--static <output_path>` to write a standalone HTML file instead of starting a server. Then proffer a link that the user can click to open the HTML in their browser.
|
||||
- For whatever reason, the Cowork setup seems to disincline Claude from generating the eval viewer after running the tests, so just to reiterate: whether you're in Cowork or in Claude Code, after running tests, you should always generate the eval viewer for the human to look at examples before revising the skill yourself and trying to make corrections, using `generate_review.py` (not writing your own boutique html code). Sorry in advance but I'm gonna go all caps here: GENERATE THE EVAL VIEWER *BEFORE* evaluating inputs yourself. You want to get them in front of the human ASAP!
|
||||
- Feedback works differently: since there's no running server, the viewer's "Submit All Reviews" button will download `feedback.json` as a file. You can then read it from there (you may have to request access first).
|
||||
- Packaging works — `package_skill.py` just needs Python and a filesystem.
|
||||
- Description optimization (`run_loop.py` / `run_eval.py`) should work in Cowork just fine since it uses `claude -p` via subprocess, not a browser, but please save it until you've fully finished making the skill and the user agrees it's in good shape.
|
||||
- **Updating an existing skill**: The user might be asking you to update an existing skill, not create a new one. Follow the update guidance in the claude.ai section above.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
The agents/ directory contains instructions for specialized subagents. Read them when you need to spawn the relevant subagent.
|
||||
|
||||
- `agents/grader.md` — How to evaluate assertions against outputs
|
||||
- `agents/comparator.md` — How to do blind A/B comparison between two outputs
|
||||
- `agents/analyzer.md` — How to analyze why one version beat another
|
||||
|
||||
The references/ directory has additional documentation:
|
||||
- `references/schemas.md` — JSON structures for evals.json, grading.json, etc.
|
||||
|
||||
---
|
||||
|
||||
Repeating one more time the core loop here for emphasis:
|
||||
|
||||
- Figure out what the skill is about
|
||||
- Draft or edit the skill
|
||||
- Run claude-with-access-to-the-skill on test prompts
|
||||
- With the user, evaluate the outputs:
|
||||
- Create benchmark.json and run `eval-viewer/generate_review.py` to help the user review them
|
||||
- Run quantitative evals
|
||||
- Repeat until you and the user are satisfied
|
||||
- Package the final skill and return it to the user.
|
||||
|
||||
Please add steps to your TodoList, if you have such a thing, to make sure you don't forget. If you're in Cowork, please specifically put "Create evals JSON and run `eval-viewer/generate_review.py` so human can review test cases" in your TodoList to make sure it happens.
|
||||
|
||||
Good luck!
|
||||
@ -1,274 +0,0 @@
|
||||
# Post-hoc Analyzer Agent
|
||||
|
||||
Analyze blind comparison results to understand WHY the winner won and generate improvement suggestions.
|
||||
|
||||
## Role
|
||||
|
||||
After the blind comparator determines a winner, the Post-hoc Analyzer "unblids" the results by examining the skills and transcripts. The goal is to extract actionable insights: what made the winner better, and how can the loser be improved?
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **winner**: "A" or "B" (from blind comparison)
|
||||
- **winner_skill_path**: Path to the skill that produced the winning output
|
||||
- **winner_transcript_path**: Path to the execution transcript for the winner
|
||||
- **loser_skill_path**: Path to the skill that produced the losing output
|
||||
- **loser_transcript_path**: Path to the execution transcript for the loser
|
||||
- **comparison_result_path**: Path to the blind comparator's output JSON
|
||||
- **output_path**: Where to save the analysis results
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Comparison Result
|
||||
|
||||
1. Read the blind comparator's output at comparison_result_path
|
||||
2. Note the winning side (A or B), the reasoning, and any scores
|
||||
3. Understand what the comparator valued in the winning output
|
||||
|
||||
### Step 2: Read Both Skills
|
||||
|
||||
1. Read the winner skill's SKILL.md and key referenced files
|
||||
2. Read the loser skill's SKILL.md and key referenced files
|
||||
3. Identify structural differences:
|
||||
- Instructions clarity and specificity
|
||||
- Script/tool usage patterns
|
||||
- Example coverage
|
||||
- Edge case handling
|
||||
|
||||
### Step 3: Read Both Transcripts
|
||||
|
||||
1. Read the winner's transcript
|
||||
2. Read the loser's transcript
|
||||
3. Compare execution patterns:
|
||||
- How closely did each follow their skill's instructions?
|
||||
- What tools were used differently?
|
||||
- Where did the loser diverge from optimal behavior?
|
||||
- Did either encounter errors or make recovery attempts?
|
||||
|
||||
### Step 4: Analyze Instruction Following
|
||||
|
||||
For each transcript, evaluate:
|
||||
- Did the agent follow the skill's explicit instructions?
|
||||
- Did the agent use the skill's provided tools/scripts?
|
||||
- Were there missed opportunities to leverage skill content?
|
||||
- Did the agent add unnecessary steps not in the skill?
|
||||
|
||||
Score instruction following 1-10 and note specific issues.
|
||||
|
||||
### Step 5: Identify Winner Strengths
|
||||
|
||||
Determine what made the winner better:
|
||||
- Clearer instructions that led to better behavior?
|
||||
- Better scripts/tools that produced better output?
|
||||
- More comprehensive examples that guided edge cases?
|
||||
- Better error handling guidance?
|
||||
|
||||
Be specific. Quote from skills/transcripts where relevant.
|
||||
|
||||
### Step 6: Identify Loser Weaknesses
|
||||
|
||||
Determine what held the loser back:
|
||||
- Ambiguous instructions that led to suboptimal choices?
|
||||
- Missing tools/scripts that forced workarounds?
|
||||
- Gaps in edge case coverage?
|
||||
- Poor error handling that caused failures?
|
||||
|
||||
### Step 7: Generate Improvement Suggestions
|
||||
|
||||
Based on the analysis, produce actionable suggestions for improving the loser skill:
|
||||
- Specific instruction changes to make
|
||||
- Tools/scripts to add or modify
|
||||
- Examples to include
|
||||
- Edge cases to address
|
||||
|
||||
Prioritize by impact. Focus on changes that would have changed the outcome.
|
||||
|
||||
### Step 8: Write Analysis Results
|
||||
|
||||
Save structured analysis to `{output_path}`.
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors",
|
||||
"Explicit guidance on fallback behavior when OCR fails"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise and made errors",
|
||||
"No guidance on OCR failure, agent gave up instead of trying alternatives"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": [
|
||||
"Minor: skipped optional logging step"
|
||||
]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3",
|
||||
"Missed the 'always validate output' instruction"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps: 1) Extract text, 2) Identify sections, 3) Format per template",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
},
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "tools",
|
||||
"suggestion": "Add validate_output.py script similar to winner skill's validation approach",
|
||||
"expected_impact": "Would catch formatting errors before final output"
|
||||
},
|
||||
{
|
||||
"priority": "medium",
|
||||
"category": "error_handling",
|
||||
"suggestion": "Add fallback instructions: 'If OCR fails, try: 1) different resolution, 2) image preprocessing, 3) manual extraction'",
|
||||
"expected_impact": "Would prevent early failure on difficult documents"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script -> Fixed 2 issues -> Produced output",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods -> No validation -> Output had errors"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be specific**: Quote from skills and transcripts, don't just say "instructions were unclear"
|
||||
- **Be actionable**: Suggestions should be concrete changes, not vague advice
|
||||
- **Focus on skill improvements**: The goal is to improve the losing skill, not critique the agent
|
||||
- **Prioritize by impact**: Which changes would most likely have changed the outcome?
|
||||
- **Consider causation**: Did the skill weakness actually cause the worse output, or is it incidental?
|
||||
- **Stay objective**: Analyze what happened, don't editorialize
|
||||
- **Think about generalization**: Would this improvement help on other evals too?
|
||||
|
||||
## Categories for Suggestions
|
||||
|
||||
Use these categories to organize improvement suggestions:
|
||||
|
||||
| Category | Description |
|
||||
|----------|-------------|
|
||||
| `instructions` | Changes to the skill's prose instructions |
|
||||
| `tools` | Scripts, templates, or utilities to add/modify |
|
||||
| `examples` | Example inputs/outputs to include |
|
||||
| `error_handling` | Guidance for handling failures |
|
||||
| `structure` | Reorganization of skill content |
|
||||
| `references` | External docs or resources to add |
|
||||
|
||||
## Priority Levels
|
||||
|
||||
- **high**: Would likely change the outcome of this comparison
|
||||
- **medium**: Would improve quality but may not change win/loss
|
||||
- **low**: Nice to have, marginal improvement
|
||||
|
||||
---
|
||||
|
||||
# Analyzing Benchmark Results
|
||||
|
||||
When analyzing benchmark results, the analyzer's purpose is to **surface patterns and anomalies** across multiple runs, not suggest skill improvements.
|
||||
|
||||
## Role
|
||||
|
||||
Review all benchmark run results and generate freeform notes that help the user understand skill performance. Focus on patterns that wouldn't be visible from aggregate metrics alone.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **benchmark_data_path**: Path to the in-progress benchmark.json with all run results
|
||||
- **skill_path**: Path to the skill being benchmarked
|
||||
- **output_path**: Where to save the notes (as JSON array of strings)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Benchmark Data
|
||||
|
||||
1. Read the benchmark.json containing all run results
|
||||
2. Note the configurations tested (with_skill, without_skill)
|
||||
3. Understand the run_summary aggregates already calculated
|
||||
|
||||
### Step 2: Analyze Per-Assertion Patterns
|
||||
|
||||
For each expectation across all runs:
|
||||
- Does it **always pass** in both configurations? (may not differentiate skill value)
|
||||
- Does it **always fail** in both configurations? (may be broken or beyond capability)
|
||||
- Does it **always pass with skill but fail without**? (skill clearly adds value here)
|
||||
- Does it **always fail with skill but pass without**? (skill may be hurting)
|
||||
- Is it **highly variable**? (flaky expectation or non-deterministic behavior)
|
||||
|
||||
### Step 3: Analyze Cross-Eval Patterns
|
||||
|
||||
Look for patterns across evals:
|
||||
- Are certain eval types consistently harder/easier?
|
||||
- Do some evals show high variance while others are stable?
|
||||
- Are there surprising results that contradict expectations?
|
||||
|
||||
### Step 4: Analyze Metrics Patterns
|
||||
|
||||
Look at time_seconds, tokens, tool_calls:
|
||||
- Does the skill significantly increase execution time?
|
||||
- Is there high variance in resource usage?
|
||||
- Are there outlier runs that skew the aggregates?
|
||||
|
||||
### Step 5: Generate Notes
|
||||
|
||||
Write freeform observations as a list of strings. Each note should:
|
||||
- State a specific observation
|
||||
- Be grounded in the data (not speculation)
|
||||
- Help the user understand something the aggregate metrics don't show
|
||||
|
||||
Examples:
|
||||
- "Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value"
|
||||
- "Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure that may be flaky"
|
||||
- "Without-skill runs consistently fail on table extraction expectations (0% pass rate)"
|
||||
- "Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
- "Token usage is 80% higher with skill, primarily due to script output parsing"
|
||||
- "All 3 without-skill runs for eval 1 produced empty output"
|
||||
|
||||
### Step 6: Write Notes
|
||||
|
||||
Save notes to `{output_path}` as a JSON array of strings:
|
||||
|
||||
```json
|
||||
[
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - run 2 had an unusual failure",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
```
|
||||
|
||||
## Guidelines
|
||||
|
||||
**DO:**
|
||||
- Report what you observe in the data
|
||||
- Be specific about which evals, expectations, or runs you're referring to
|
||||
- Note patterns that aggregate metrics would hide
|
||||
- Provide context that helps interpret the numbers
|
||||
|
||||
**DO NOT:**
|
||||
- Suggest improvements to the skill (that's for the improvement step, not benchmarking)
|
||||
- Make subjective quality judgments ("the output was good/bad")
|
||||
- Speculate about causes without evidence
|
||||
- Repeat information already in the run_summary aggregates
|
||||
@ -1,202 +0,0 @@
|
||||
# Blind Comparator Agent
|
||||
|
||||
Compare two outputs WITHOUT knowing which skill produced them.
|
||||
|
||||
## Role
|
||||
|
||||
The Blind Comparator judges which output better accomplishes the eval task. You receive two outputs labeled A and B, but you do NOT know which skill produced which. This prevents bias toward a particular skill or approach.
|
||||
|
||||
Your judgment is based purely on output quality and task completion.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **output_a_path**: Path to the first output file or directory
|
||||
- **output_b_path**: Path to the second output file or directory
|
||||
- **eval_prompt**: The original task/prompt that was executed
|
||||
- **expectations**: List of expectations to check (optional - may be empty)
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read Both Outputs
|
||||
|
||||
1. Examine output A (file or directory)
|
||||
2. Examine output B (file or directory)
|
||||
3. Note the type, structure, and content of each
|
||||
4. If outputs are directories, examine all relevant files inside
|
||||
|
||||
### Step 2: Understand the Task
|
||||
|
||||
1. Read the eval_prompt carefully
|
||||
2. Identify what the task requires:
|
||||
- What should be produced?
|
||||
- What qualities matter (accuracy, completeness, format)?
|
||||
- What would distinguish a good output from a poor one?
|
||||
|
||||
### Step 3: Generate Evaluation Rubric
|
||||
|
||||
Based on the task, generate a rubric with two dimensions:
|
||||
|
||||
**Content Rubric** (what the output contains):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Correctness | Major errors | Minor errors | Fully correct |
|
||||
| Completeness | Missing key elements | Mostly complete | All elements present |
|
||||
| Accuracy | Significant inaccuracies | Minor inaccuracies | Accurate throughout |
|
||||
|
||||
**Structure Rubric** (how the output is organized):
|
||||
| Criterion | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
|
||||
|-----------|----------|----------------|---------------|
|
||||
| Organization | Disorganized | Reasonably organized | Clear, logical structure |
|
||||
| Formatting | Inconsistent/broken | Mostly consistent | Professional, polished |
|
||||
| Usability | Difficult to use | Usable with effort | Easy to use |
|
||||
|
||||
Adapt criteria to the specific task. For example:
|
||||
- PDF form → "Field alignment", "Text readability", "Data placement"
|
||||
- Document → "Section structure", "Heading hierarchy", "Paragraph flow"
|
||||
- Data output → "Schema correctness", "Data types", "Completeness"
|
||||
|
||||
### Step 4: Evaluate Each Output Against the Rubric
|
||||
|
||||
For each output (A and B):
|
||||
|
||||
1. **Score each criterion** on the rubric (1-5 scale)
|
||||
2. **Calculate dimension totals**: Content score, Structure score
|
||||
3. **Calculate overall score**: Average of dimension scores, scaled to 1-10
|
||||
|
||||
### Step 5: Check Assertions (if provided)
|
||||
|
||||
If expectations are provided:
|
||||
|
||||
1. Check each expectation against output A
|
||||
2. Check each expectation against output B
|
||||
3. Count pass rates for each output
|
||||
4. Use expectation scores as secondary evidence (not the primary decision factor)
|
||||
|
||||
### Step 6: Determine the Winner
|
||||
|
||||
Compare A and B based on (in priority order):
|
||||
|
||||
1. **Primary**: Overall rubric score (content + structure)
|
||||
2. **Secondary**: Assertion pass rates (if applicable)
|
||||
3. **Tiebreaker**: If truly equal, declare a TIE
|
||||
|
||||
Be decisive - ties should be rare. One output is usually better, even if marginally.
|
||||
|
||||
### Step 7: Write Comparison Results
|
||||
|
||||
Save results to a JSON file at the path specified (or `comparison.json` if not specified).
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": true},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true},
|
||||
{"text": "Output includes date", "passed": false},
|
||||
{"text": "Format is PDF", "passed": true},
|
||||
{"text": "Contains signature", "passed": false},
|
||||
{"text": "Readable text", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If no expectations were provided, omit the `expectation_results` field entirely.
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **winner**: "A", "B", or "TIE"
|
||||
- **reasoning**: Clear explanation of why the winner was chosen (or why it's a tie)
|
||||
- **rubric**: Structured rubric evaluation for each output
|
||||
- **content**: Scores for content criteria (correctness, completeness, accuracy)
|
||||
- **structure**: Scores for structure criteria (organization, formatting, usability)
|
||||
- **content_score**: Average of content criteria (1-5)
|
||||
- **structure_score**: Average of structure criteria (1-5)
|
||||
- **overall_score**: Combined score scaled to 1-10
|
||||
- **output_quality**: Summary quality assessment
|
||||
- **score**: 1-10 rating (should match rubric overall_score)
|
||||
- **strengths**: List of positive aspects
|
||||
- **weaknesses**: List of issues or shortcomings
|
||||
- **expectation_results**: (Only if expectations provided)
|
||||
- **passed**: Number of expectations that passed
|
||||
- **total**: Total number of expectations
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **details**: Individual expectation results
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Stay blind**: DO NOT try to infer which skill produced which output. Judge purely on output quality.
|
||||
- **Be specific**: Cite specific examples when explaining strengths and weaknesses.
|
||||
- **Be decisive**: Choose a winner unless outputs are genuinely equivalent.
|
||||
- **Output quality first**: Assertion scores are secondary to overall task completion.
|
||||
- **Be objective**: Don't favor outputs based on style preferences; focus on correctness and completeness.
|
||||
- **Explain your reasoning**: The reasoning field should make it clear why you chose the winner.
|
||||
- **Handle edge cases**: If both outputs fail, pick the one that fails less badly. If both are excellent, pick the one that's marginally better.
|
||||
@ -1,223 +0,0 @@
|
||||
# Grader Agent
|
||||
|
||||
Evaluate expectations against an execution transcript and outputs.
|
||||
|
||||
## Role
|
||||
|
||||
The Grader reviews a transcript and output files, then determines whether each expectation passes or fails. Provide clear evidence for each judgment.
|
||||
|
||||
You have two jobs: grade the outputs, and critique the evals themselves. A passing grade on a weak assertion is worse than useless — it creates false confidence. When you notice an assertion that's trivially satisfied, or an important outcome that no assertion checks, say so.
|
||||
|
||||
## Inputs
|
||||
|
||||
You receive these parameters in your prompt:
|
||||
|
||||
- **expectations**: List of expectations to evaluate (strings)
|
||||
- **transcript_path**: Path to the execution transcript (markdown file)
|
||||
- **outputs_dir**: Directory containing output files from execution
|
||||
|
||||
## Process
|
||||
|
||||
### Step 1: Read the Transcript
|
||||
|
||||
1. Read the transcript file completely
|
||||
2. Note the eval prompt, execution steps, and final result
|
||||
3. Identify any issues or errors documented
|
||||
|
||||
### Step 2: Examine Output Files
|
||||
|
||||
1. List files in outputs_dir
|
||||
2. Read/examine each file relevant to the expectations. If outputs aren't plain text, use the inspection tools provided in your prompt — don't rely solely on what the transcript says the executor produced.
|
||||
3. Note contents, structure, and quality
|
||||
|
||||
### Step 3: Evaluate Each Assertion
|
||||
|
||||
For each expectation:
|
||||
|
||||
1. **Search for evidence** in the transcript and outputs
|
||||
2. **Determine verdict**:
|
||||
- **PASS**: Clear evidence the expectation is true AND the evidence reflects genuine task completion, not just surface-level compliance
|
||||
- **FAIL**: No evidence, or evidence contradicts the expectation, or the evidence is superficial (e.g., correct filename but empty/wrong content)
|
||||
3. **Cite the evidence**: Quote the specific text or describe what you found
|
||||
|
||||
### Step 4: Extract and Verify Claims
|
||||
|
||||
Beyond the predefined expectations, extract implicit claims from the outputs and verify them:
|
||||
|
||||
1. **Extract claims** from the transcript and outputs:
|
||||
- Factual statements ("The form has 12 fields")
|
||||
- Process claims ("Used pypdf to fill the form")
|
||||
- Quality claims ("All fields were filled correctly")
|
||||
|
||||
2. **Verify each claim**:
|
||||
- **Factual claims**: Can be checked against the outputs or external sources
|
||||
- **Process claims**: Can be verified from the transcript
|
||||
- **Quality claims**: Evaluate whether the claim is justified
|
||||
|
||||
3. **Flag unverifiable claims**: Note claims that cannot be verified with available information
|
||||
|
||||
This catches issues that predefined expectations might miss.
|
||||
|
||||
### Step 5: Read User Notes
|
||||
|
||||
If `{outputs_dir}/user_notes.md` exists:
|
||||
1. Read it and note any uncertainties or issues flagged by the executor
|
||||
2. Include relevant concerns in the grading output
|
||||
3. These may reveal problems even when expectations pass
|
||||
|
||||
### Step 6: Critique the Evals
|
||||
|
||||
After grading, consider whether the evals themselves could be improved. Only surface suggestions when there's a clear gap.
|
||||
|
||||
Good suggestions test meaningful outcomes — assertions that are hard to satisfy without actually doing the work correctly. Think about what makes an assertion *discriminating*: it passes when the skill genuinely succeeds and fails when it doesn't.
|
||||
|
||||
Suggestions worth raising:
|
||||
- An assertion that passed but would also pass for a clearly wrong output (e.g., checking filename existence but not file content)
|
||||
- An important outcome you observed — good or bad — that no assertion covers at all
|
||||
- An assertion that can't actually be verified from the available outputs
|
||||
|
||||
Keep the bar high. The goal is to flag things the eval author would say "good catch" about, not to nitpick every assertion.
|
||||
|
||||
### Step 7: Write Grading Results
|
||||
|
||||
Save results to `{outputs_dir}/../grading.json` (sibling to outputs_dir).
|
||||
|
||||
## Grading Criteria
|
||||
|
||||
**PASS when**:
|
||||
- The transcript or outputs clearly demonstrate the expectation is true
|
||||
- Specific evidence can be cited
|
||||
- The evidence reflects genuine substance, not just surface compliance (e.g., a file exists AND contains correct content, not just the right filename)
|
||||
|
||||
**FAIL when**:
|
||||
- No evidence found for the expectation
|
||||
- Evidence contradicts the expectation
|
||||
- The expectation cannot be verified from available information
|
||||
- The evidence is superficial — the assertion is technically satisfied but the underlying task outcome is wrong or incomplete
|
||||
- The output appears to meet the assertion by coincidence rather than by actually doing the work
|
||||
|
||||
**When uncertain**: The burden of proof to pass is on the expectation.
|
||||
|
||||
### Step 8: Read Executor Metrics and Timing
|
||||
|
||||
1. If `{outputs_dir}/metrics.json` exists, read it and include in grading output
|
||||
2. If `{outputs_dir}/../timing.json` exists, read it and include timing data
|
||||
|
||||
## Output Format
|
||||
|
||||
Write a JSON file with this structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
},
|
||||
{
|
||||
"text": "The assistant used the skill's OCR script",
|
||||
"passed": true,
|
||||
"evidence": "Transcript Step 2 shows: 'Tool: Bash - python ocr_script.py image.png'"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
},
|
||||
{
|
||||
"claim": "All required fields were populated",
|
||||
"type": "quality",
|
||||
"verified": false,
|
||||
"evidence": "Reference section was left blank despite data being available"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass — consider checking it appears as the primary contact with matching phone and email from the input"
|
||||
},
|
||||
{
|
||||
"reason": "No assertion checks whether the extracted phone numbers match the input — I observed incorrect numbers in the output that went uncaught"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness. Consider adding content verification."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Field Descriptions
|
||||
|
||||
- **expectations**: Array of graded expectations
|
||||
- **text**: The original expectation text
|
||||
- **passed**: Boolean - true if expectation passes
|
||||
- **evidence**: Specific quote or description supporting the verdict
|
||||
- **summary**: Aggregate statistics
|
||||
- **passed**: Count of passed expectations
|
||||
- **failed**: Count of failed expectations
|
||||
- **total**: Total expectations evaluated
|
||||
- **pass_rate**: Fraction passed (0.0 to 1.0)
|
||||
- **execution_metrics**: Copied from executor's metrics.json (if available)
|
||||
- **output_chars**: Total character count of output files (proxy for tokens)
|
||||
- **transcript_chars**: Character count of transcript
|
||||
- **timing**: Wall clock timing from timing.json (if available)
|
||||
- **executor_duration_seconds**: Time spent in executor subagent
|
||||
- **total_duration_seconds**: Total elapsed time for the run
|
||||
- **claims**: Extracted and verified claims from the output
|
||||
- **claim**: The statement being verified
|
||||
- **type**: "factual", "process", or "quality"
|
||||
- **verified**: Boolean - whether the claim holds
|
||||
- **evidence**: Supporting or contradicting evidence
|
||||
- **user_notes_summary**: Issues flagged by the executor
|
||||
- **uncertainties**: Things the executor wasn't sure about
|
||||
- **needs_review**: Items requiring human attention
|
||||
- **workarounds**: Places where the skill didn't work as expected
|
||||
- **eval_feedback**: Improvement suggestions for the evals (only when warranted)
|
||||
- **suggestions**: List of concrete suggestions, each with a `reason` and optionally an `assertion` it relates to
|
||||
- **overall**: Brief assessment — can be "No suggestions, evals look solid" if nothing to flag
|
||||
|
||||
## Guidelines
|
||||
|
||||
- **Be objective**: Base verdicts on evidence, not assumptions
|
||||
- **Be specific**: Quote the exact text that supports your verdict
|
||||
- **Be thorough**: Check both transcript and output files
|
||||
- **Be consistent**: Apply the same standard to each expectation
|
||||
- **Explain failures**: Make it clear why evidence was insufficient
|
||||
- **No partial credit**: Each expectation is pass or fail, not partial
|
||||
@ -1,146 +0,0 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Eval Set Review - __SKILL_NAME_PLACEHOLDER__</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
body { font-family: 'Lora', Georgia, serif; background: #faf9f5; padding: 2rem; color: #141413; }
|
||||
h1 { font-family: 'Poppins', sans-serif; margin-bottom: 0.5rem; font-size: 1.5rem; }
|
||||
.description { color: #b0aea5; margin-bottom: 1.5rem; font-style: italic; max-width: 900px; }
|
||||
.controls { margin-bottom: 1rem; display: flex; gap: 0.5rem; }
|
||||
.btn { font-family: 'Poppins', sans-serif; padding: 0.5rem 1rem; border: none; border-radius: 6px; cursor: pointer; font-size: 0.875rem; font-weight: 500; }
|
||||
.btn-add { background: #6a9bcc; color: white; }
|
||||
.btn-add:hover { background: #5889b8; }
|
||||
.btn-export { background: #d97757; color: white; }
|
||||
.btn-export:hover { background: #c4613f; }
|
||||
table { width: 100%; max-width: 1100px; border-collapse: collapse; background: white; border-radius: 6px; overflow: hidden; box-shadow: 0 1px 3px rgba(0,0,0,0.08); }
|
||||
th { font-family: 'Poppins', sans-serif; background: #141413; color: #faf9f5; padding: 0.75rem 1rem; text-align: left; font-size: 0.875rem; }
|
||||
td { padding: 0.75rem 1rem; border-bottom: 1px solid #e8e6dc; vertical-align: top; }
|
||||
tr:nth-child(even) td { background: #faf9f5; }
|
||||
tr:hover td { background: #f3f1ea; }
|
||||
.section-header td { background: #e8e6dc; font-family: 'Poppins', sans-serif; font-weight: 500; font-size: 0.8rem; color: #141413; text-transform: uppercase; letter-spacing: 0.05em; }
|
||||
.query-input { width: 100%; padding: 0.4rem; border: 1px solid #e8e6dc; border-radius: 4px; font-size: 0.875rem; font-family: 'Lora', Georgia, serif; resize: vertical; min-height: 60px; }
|
||||
.query-input:focus { outline: none; border-color: #d97757; box-shadow: 0 0 0 2px rgba(217,119,87,0.15); }
|
||||
.toggle { position: relative; display: inline-block; width: 44px; height: 24px; }
|
||||
.toggle input { opacity: 0; width: 0; height: 0; }
|
||||
.toggle .slider { position: absolute; inset: 0; background: #b0aea5; border-radius: 24px; cursor: pointer; transition: 0.2s; }
|
||||
.toggle .slider::before { content: ""; position: absolute; width: 18px; height: 18px; left: 3px; bottom: 3px; background: white; border-radius: 50%; transition: 0.2s; }
|
||||
.toggle input:checked + .slider { background: #d97757; }
|
||||
.toggle input:checked + .slider::before { transform: translateX(20px); }
|
||||
.btn-delete { background: #c44; color: white; padding: 0.3rem 0.6rem; border: none; border-radius: 4px; cursor: pointer; font-size: 0.75rem; font-family: 'Poppins', sans-serif; }
|
||||
.btn-delete:hover { background: #a33; }
|
||||
.summary { margin-top: 1rem; color: #b0aea5; font-size: 0.875rem; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Eval Set Review: <span id="skill-name">__SKILL_NAME_PLACEHOLDER__</span></h1>
|
||||
<p class="description">Current description: <span id="skill-desc">__SKILL_DESCRIPTION_PLACEHOLDER__</span></p>
|
||||
|
||||
<div class="controls">
|
||||
<button class="btn btn-add" onclick="addRow()">+ Add Query</button>
|
||||
<button class="btn btn-export" onclick="exportEvalSet()">Export Eval Set</button>
|
||||
</div>
|
||||
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th style="width:65%">Query</th>
|
||||
<th style="width:18%">Should Trigger</th>
|
||||
<th style="width:10%">Actions</th>
|
||||
</tr>
|
||||
</thead>
|
||||
<tbody id="eval-body"></tbody>
|
||||
</table>
|
||||
|
||||
<p class="summary" id="summary"></p>
|
||||
|
||||
<script>
|
||||
const EVAL_DATA = __EVAL_DATA_PLACEHOLDER__;
|
||||
|
||||
let evalItems = [...EVAL_DATA];
|
||||
|
||||
function render() {
|
||||
const tbody = document.getElementById('eval-body');
|
||||
tbody.innerHTML = '';
|
||||
|
||||
// Sort: should-trigger first, then should-not-trigger
|
||||
const sorted = evalItems
|
||||
.map((item, origIdx) => ({ ...item, origIdx }))
|
||||
.sort((a, b) => (b.should_trigger ? 1 : 0) - (a.should_trigger ? 1 : 0));
|
||||
|
||||
let lastGroup = null;
|
||||
sorted.forEach(item => {
|
||||
const group = item.should_trigger ? 'trigger' : 'no-trigger';
|
||||
if (group !== lastGroup) {
|
||||
const headerRow = document.createElement('tr');
|
||||
headerRow.className = 'section-header';
|
||||
headerRow.innerHTML = `<td colspan="3">${item.should_trigger ? 'Should Trigger' : 'Should NOT Trigger'}</td>`;
|
||||
tbody.appendChild(headerRow);
|
||||
lastGroup = group;
|
||||
}
|
||||
|
||||
const idx = item.origIdx;
|
||||
const tr = document.createElement('tr');
|
||||
tr.innerHTML = `
|
||||
<td><textarea class="query-input" onchange="updateQuery(${idx}, this.value)">${escapeHtml(item.query)}</textarea></td>
|
||||
<td>
|
||||
<label class="toggle">
|
||||
<input type="checkbox" ${item.should_trigger ? 'checked' : ''} onchange="updateTrigger(${idx}, this.checked)">
|
||||
<span class="slider"></span>
|
||||
</label>
|
||||
<span style="margin-left:8px;font-size:0.8rem;color:#b0aea5">${item.should_trigger ? 'Yes' : 'No'}</span>
|
||||
</td>
|
||||
<td><button class="btn-delete" onclick="deleteRow(${idx})">Delete</button></td>
|
||||
`;
|
||||
tbody.appendChild(tr);
|
||||
});
|
||||
updateSummary();
|
||||
}
|
||||
|
||||
function escapeHtml(text) {
|
||||
const div = document.createElement('div');
|
||||
div.textContent = text;
|
||||
return div.innerHTML;
|
||||
}
|
||||
|
||||
function updateQuery(idx, value) { evalItems[idx].query = value; updateSummary(); }
|
||||
function updateTrigger(idx, value) { evalItems[idx].should_trigger = value; render(); }
|
||||
function deleteRow(idx) { evalItems.splice(idx, 1); render(); }
|
||||
|
||||
function addRow() {
|
||||
evalItems.push({ query: '', should_trigger: true });
|
||||
render();
|
||||
const inputs = document.querySelectorAll('.query-input');
|
||||
inputs[inputs.length - 1].focus();
|
||||
}
|
||||
|
||||
function updateSummary() {
|
||||
const trigger = evalItems.filter(i => i.should_trigger).length;
|
||||
const noTrigger = evalItems.filter(i => !i.should_trigger).length;
|
||||
document.getElementById('summary').textContent =
|
||||
`${evalItems.length} queries total: ${trigger} should trigger, ${noTrigger} should not trigger`;
|
||||
}
|
||||
|
||||
function exportEvalSet() {
|
||||
const valid = evalItems.filter(i => i.query.trim() !== '');
|
||||
const data = valid.map(i => ({ query: i.query.trim(), should_trigger: i.should_trigger }));
|
||||
const blob = new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' });
|
||||
const url = URL.createObjectURL(blob);
|
||||
const a = document.createElement('a');
|
||||
a.href = url;
|
||||
a.download = 'eval_set.json';
|
||||
document.body.appendChild(a);
|
||||
a.click();
|
||||
document.body.removeChild(a);
|
||||
URL.revokeObjectURL(url);
|
||||
}
|
||||
|
||||
render();
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
@ -1,471 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate and serve a review page for eval results.
|
||||
|
||||
Reads the workspace directory, discovers runs (directories with outputs/),
|
||||
embeds all output data into a self-contained HTML page, and serves it via
|
||||
a tiny HTTP server. Feedback auto-saves to feedback.json in the workspace.
|
||||
|
||||
Usage:
|
||||
python generate_review.py <workspace-path> [--port PORT] [--skill-name NAME]
|
||||
python generate_review.py <workspace-path> --previous-feedback /path/to/old/feedback.json
|
||||
|
||||
No dependencies beyond the Python stdlib are required.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import base64
|
||||
import json
|
||||
import mimetypes
|
||||
import os
|
||||
import re
|
||||
import signal
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import webbrowser
|
||||
from functools import partial
|
||||
from http.server import HTTPServer, BaseHTTPRequestHandler
|
||||
from pathlib import Path
|
||||
|
||||
# Files to exclude from output listings
|
||||
METADATA_FILES = {"transcript.md", "user_notes.md", "metrics.json"}
|
||||
|
||||
# Extensions we render as inline text
|
||||
TEXT_EXTENSIONS = {
|
||||
".txt", ".md", ".json", ".csv", ".py", ".js", ".ts", ".tsx", ".jsx",
|
||||
".yaml", ".yml", ".xml", ".html", ".css", ".sh", ".rb", ".go", ".rs",
|
||||
".java", ".c", ".cpp", ".h", ".hpp", ".sql", ".r", ".toml",
|
||||
}
|
||||
|
||||
# Extensions we render as inline images
|
||||
IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".gif", ".svg", ".webp"}
|
||||
|
||||
# MIME type overrides for common types
|
||||
MIME_OVERRIDES = {
|
||||
".svg": "image/svg+xml",
|
||||
".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
|
||||
".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
|
||||
".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
|
||||
}
|
||||
|
||||
|
||||
def get_mime_type(path: Path) -> str:
|
||||
ext = path.suffix.lower()
|
||||
if ext in MIME_OVERRIDES:
|
||||
return MIME_OVERRIDES[ext]
|
||||
mime, _ = mimetypes.guess_type(str(path))
|
||||
return mime or "application/octet-stream"
|
||||
|
||||
|
||||
def find_runs(workspace: Path) -> list[dict]:
|
||||
"""Recursively find directories that contain an outputs/ subdirectory."""
|
||||
runs: list[dict] = []
|
||||
_find_runs_recursive(workspace, workspace, runs)
|
||||
runs.sort(key=lambda r: (r.get("eval_id", float("inf")), r["id"]))
|
||||
return runs
|
||||
|
||||
|
||||
def _find_runs_recursive(root: Path, current: Path, runs: list[dict]) -> None:
|
||||
if not current.is_dir():
|
||||
return
|
||||
|
||||
outputs_dir = current / "outputs"
|
||||
if outputs_dir.is_dir():
|
||||
run = build_run(root, current)
|
||||
if run:
|
||||
runs.append(run)
|
||||
return
|
||||
|
||||
skip = {"node_modules", ".git", "__pycache__", "skill", "inputs"}
|
||||
for child in sorted(current.iterdir()):
|
||||
if child.is_dir() and child.name not in skip:
|
||||
_find_runs_recursive(root, child, runs)
|
||||
|
||||
|
||||
def build_run(root: Path, run_dir: Path) -> dict | None:
|
||||
"""Build a run dict with prompt, outputs, and grading data."""
|
||||
prompt = ""
|
||||
eval_id = None
|
||||
|
||||
# Try eval_metadata.json
|
||||
for candidate in [run_dir / "eval_metadata.json", run_dir.parent / "eval_metadata.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
metadata = json.loads(candidate.read_text())
|
||||
prompt = metadata.get("prompt", "")
|
||||
eval_id = metadata.get("eval_id")
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
# Fall back to transcript.md
|
||||
if not prompt:
|
||||
for candidate in [run_dir / "transcript.md", run_dir / "outputs" / "transcript.md"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
text = candidate.read_text()
|
||||
match = re.search(r"## Eval Prompt\n\n([\s\S]*?)(?=\n##|$)", text)
|
||||
if match:
|
||||
prompt = match.group(1).strip()
|
||||
except OSError:
|
||||
pass
|
||||
if prompt:
|
||||
break
|
||||
|
||||
if not prompt:
|
||||
prompt = "(No prompt found)"
|
||||
|
||||
run_id = str(run_dir.relative_to(root)).replace("/", "-").replace("\\", "-")
|
||||
|
||||
# Collect output files
|
||||
outputs_dir = run_dir / "outputs"
|
||||
output_files: list[dict] = []
|
||||
if outputs_dir.is_dir():
|
||||
for f in sorted(outputs_dir.iterdir()):
|
||||
if f.is_file() and f.name not in METADATA_FILES:
|
||||
output_files.append(embed_file(f))
|
||||
|
||||
# Load grading if present
|
||||
grading = None
|
||||
for candidate in [run_dir / "grading.json", run_dir.parent / "grading.json"]:
|
||||
if candidate.exists():
|
||||
try:
|
||||
grading = json.loads(candidate.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
if grading:
|
||||
break
|
||||
|
||||
return {
|
||||
"id": run_id,
|
||||
"prompt": prompt,
|
||||
"eval_id": eval_id,
|
||||
"outputs": output_files,
|
||||
"grading": grading,
|
||||
}
|
||||
|
||||
|
||||
def embed_file(path: Path) -> dict:
|
||||
"""Read a file and return an embedded representation."""
|
||||
ext = path.suffix.lower()
|
||||
mime = get_mime_type(path)
|
||||
|
||||
if ext in TEXT_EXTENSIONS:
|
||||
try:
|
||||
content = path.read_text(errors="replace")
|
||||
except OSError:
|
||||
content = "(Error reading file)"
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "text",
|
||||
"content": content,
|
||||
}
|
||||
elif ext in IMAGE_EXTENSIONS:
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "image",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".pdf":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "pdf",
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
elif ext == ".xlsx":
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "xlsx",
|
||||
"data_b64": b64,
|
||||
}
|
||||
else:
|
||||
# Binary / unknown — base64 download link
|
||||
try:
|
||||
raw = path.read_bytes()
|
||||
b64 = base64.b64encode(raw).decode("ascii")
|
||||
except OSError:
|
||||
return {"name": path.name, "type": "error", "content": "(Error reading file)"}
|
||||
return {
|
||||
"name": path.name,
|
||||
"type": "binary",
|
||||
"mime": mime,
|
||||
"data_uri": f"data:{mime};base64,{b64}",
|
||||
}
|
||||
|
||||
|
||||
def load_previous_iteration(workspace: Path) -> dict[str, dict]:
|
||||
"""Load previous iteration's feedback and outputs.
|
||||
|
||||
Returns a map of run_id -> {"feedback": str, "outputs": list[dict]}.
|
||||
"""
|
||||
result: dict[str, dict] = {}
|
||||
|
||||
# Load feedback
|
||||
feedback_map: dict[str, str] = {}
|
||||
feedback_path = workspace / "feedback.json"
|
||||
if feedback_path.exists():
|
||||
try:
|
||||
data = json.loads(feedback_path.read_text())
|
||||
feedback_map = {
|
||||
r["run_id"]: r["feedback"]
|
||||
for r in data.get("reviews", [])
|
||||
if r.get("feedback", "").strip()
|
||||
}
|
||||
except (json.JSONDecodeError, OSError, KeyError):
|
||||
pass
|
||||
|
||||
# Load runs (to get outputs)
|
||||
prev_runs = find_runs(workspace)
|
||||
for run in prev_runs:
|
||||
result[run["id"]] = {
|
||||
"feedback": feedback_map.get(run["id"], ""),
|
||||
"outputs": run.get("outputs", []),
|
||||
}
|
||||
|
||||
# Also add feedback for run_ids that had feedback but no matching run
|
||||
for run_id, fb in feedback_map.items():
|
||||
if run_id not in result:
|
||||
result[run_id] = {"feedback": fb, "outputs": []}
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def generate_html(
|
||||
runs: list[dict],
|
||||
skill_name: str,
|
||||
previous: dict[str, dict] | None = None,
|
||||
benchmark: dict | None = None,
|
||||
) -> str:
|
||||
"""Generate the complete standalone HTML page with embedded data."""
|
||||
template_path = Path(__file__).parent / "viewer.html"
|
||||
template = template_path.read_text()
|
||||
|
||||
# Build previous_feedback and previous_outputs maps for the template
|
||||
previous_feedback: dict[str, str] = {}
|
||||
previous_outputs: dict[str, list[dict]] = {}
|
||||
if previous:
|
||||
for run_id, data in previous.items():
|
||||
if data.get("feedback"):
|
||||
previous_feedback[run_id] = data["feedback"]
|
||||
if data.get("outputs"):
|
||||
previous_outputs[run_id] = data["outputs"]
|
||||
|
||||
embedded = {
|
||||
"skill_name": skill_name,
|
||||
"runs": runs,
|
||||
"previous_feedback": previous_feedback,
|
||||
"previous_outputs": previous_outputs,
|
||||
}
|
||||
if benchmark:
|
||||
embedded["benchmark"] = benchmark
|
||||
|
||||
data_json = json.dumps(embedded)
|
||||
|
||||
return template.replace("/*__EMBEDDED_DATA__*/", f"const EMBEDDED_DATA = {data_json};")
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# HTTP server (stdlib only, zero dependencies)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
def _kill_port(port: int) -> None:
|
||||
"""Kill any process listening on the given port."""
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["lsof", "-ti", f":{port}"],
|
||||
capture_output=True, text=True, timeout=5,
|
||||
)
|
||||
for pid_str in result.stdout.strip().split("\n"):
|
||||
if pid_str.strip():
|
||||
try:
|
||||
os.kill(int(pid_str.strip()), signal.SIGTERM)
|
||||
except (ProcessLookupError, ValueError):
|
||||
pass
|
||||
if result.stdout.strip():
|
||||
time.sleep(0.5)
|
||||
except subprocess.TimeoutExpired:
|
||||
pass
|
||||
except FileNotFoundError:
|
||||
print("Note: lsof not found, cannot check if port is in use", file=sys.stderr)
|
||||
|
||||
class ReviewHandler(BaseHTTPRequestHandler):
|
||||
"""Serves the review HTML and handles feedback saves.
|
||||
|
||||
Regenerates the HTML on each page load so that refreshing the browser
|
||||
picks up new eval outputs without restarting the server.
|
||||
"""
|
||||
|
||||
def __init__(
|
||||
self,
|
||||
workspace: Path,
|
||||
skill_name: str,
|
||||
feedback_path: Path,
|
||||
previous: dict[str, dict],
|
||||
benchmark_path: Path | None,
|
||||
*args,
|
||||
**kwargs,
|
||||
):
|
||||
self.workspace = workspace
|
||||
self.skill_name = skill_name
|
||||
self.feedback_path = feedback_path
|
||||
self.previous = previous
|
||||
self.benchmark_path = benchmark_path
|
||||
super().__init__(*args, **kwargs)
|
||||
|
||||
def do_GET(self) -> None:
|
||||
if self.path == "/" or self.path == "/index.html":
|
||||
# Regenerate HTML on each request (re-scans workspace for new outputs)
|
||||
runs = find_runs(self.workspace)
|
||||
benchmark = None
|
||||
if self.benchmark_path and self.benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(self.benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
html = generate_html(runs, self.skill_name, self.previous, benchmark)
|
||||
content = html.encode("utf-8")
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "text/html; charset=utf-8")
|
||||
self.send_header("Content-Length", str(len(content)))
|
||||
self.end_headers()
|
||||
self.wfile.write(content)
|
||||
elif self.path == "/api/feedback":
|
||||
data = b"{}"
|
||||
if self.feedback_path.exists():
|
||||
data = self.feedback_path.read_bytes()
|
||||
self.send_response(200)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(data)))
|
||||
self.end_headers()
|
||||
self.wfile.write(data)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def do_POST(self) -> None:
|
||||
if self.path == "/api/feedback":
|
||||
length = int(self.headers.get("Content-Length", 0))
|
||||
body = self.rfile.read(length)
|
||||
try:
|
||||
data = json.loads(body)
|
||||
if not isinstance(data, dict) or "reviews" not in data:
|
||||
raise ValueError("Expected JSON object with 'reviews' key")
|
||||
self.feedback_path.write_text(json.dumps(data, indent=2) + "\n")
|
||||
resp = b'{"ok":true}'
|
||||
self.send_response(200)
|
||||
except (json.JSONDecodeError, OSError, ValueError) as e:
|
||||
resp = json.dumps({"error": str(e)}).encode()
|
||||
self.send_response(500)
|
||||
self.send_header("Content-Type", "application/json")
|
||||
self.send_header("Content-Length", str(len(resp)))
|
||||
self.end_headers()
|
||||
self.wfile.write(resp)
|
||||
else:
|
||||
self.send_error(404)
|
||||
|
||||
def log_message(self, format: str, *args: object) -> None:
|
||||
# Suppress request logging to keep terminal clean
|
||||
pass
|
||||
|
||||
|
||||
def main() -> None:
|
||||
parser = argparse.ArgumentParser(description="Generate and serve eval review")
|
||||
parser.add_argument("workspace", type=Path, help="Path to workspace directory")
|
||||
parser.add_argument("--port", "-p", type=int, default=3117, help="Server port (default: 3117)")
|
||||
parser.add_argument("--skill-name", "-n", type=str, default=None, help="Skill name for header")
|
||||
parser.add_argument(
|
||||
"--previous-workspace", type=Path, default=None,
|
||||
help="Path to previous iteration's workspace (shows old outputs and feedback as context)",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--benchmark", type=Path, default=None,
|
||||
help="Path to benchmark.json to show in the Benchmark tab",
|
||||
)
|
||||
parser.add_argument(
|
||||
"--static", "-s", type=Path, default=None,
|
||||
help="Write standalone HTML to this path instead of starting a server",
|
||||
)
|
||||
args = parser.parse_args()
|
||||
|
||||
workspace = args.workspace.resolve()
|
||||
if not workspace.is_dir():
|
||||
print(f"Error: {workspace} is not a directory", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
runs = find_runs(workspace)
|
||||
if not runs:
|
||||
print(f"No runs found in {workspace}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
skill_name = args.skill_name or workspace.name.replace("-workspace", "")
|
||||
feedback_path = workspace / "feedback.json"
|
||||
|
||||
previous: dict[str, dict] = {}
|
||||
if args.previous_workspace:
|
||||
previous = load_previous_iteration(args.previous_workspace.resolve())
|
||||
|
||||
benchmark_path = args.benchmark.resolve() if args.benchmark else None
|
||||
benchmark = None
|
||||
if benchmark_path and benchmark_path.exists():
|
||||
try:
|
||||
benchmark = json.loads(benchmark_path.read_text())
|
||||
except (json.JSONDecodeError, OSError):
|
||||
pass
|
||||
|
||||
if args.static:
|
||||
html = generate_html(runs, skill_name, previous, benchmark)
|
||||
args.static.parent.mkdir(parents=True, exist_ok=True)
|
||||
args.static.write_text(html)
|
||||
print(f"\n Static viewer written to: {args.static}\n")
|
||||
sys.exit(0)
|
||||
|
||||
# Kill any existing process on the target port
|
||||
port = args.port
|
||||
_kill_port(port)
|
||||
handler = partial(ReviewHandler, workspace, skill_name, feedback_path, previous, benchmark_path)
|
||||
try:
|
||||
server = HTTPServer(("127.0.0.1", port), handler)
|
||||
except OSError:
|
||||
# Port still in use after kill attempt — find a free one
|
||||
server = HTTPServer(("127.0.0.1", 0), handler)
|
||||
port = server.server_address[1]
|
||||
|
||||
url = f"http://localhost:{port}"
|
||||
print(f"\n Eval Viewer")
|
||||
print(f" ─────────────────────────────────")
|
||||
print(f" URL: {url}")
|
||||
print(f" Workspace: {workspace}")
|
||||
print(f" Feedback: {feedback_path}")
|
||||
if previous:
|
||||
print(f" Previous: {args.previous_workspace} ({len(previous)} runs)")
|
||||
if benchmark_path:
|
||||
print(f" Benchmark: {benchmark_path}")
|
||||
print(f"\n Press Ctrl+C to stop.\n")
|
||||
|
||||
webbrowser.open(url)
|
||||
|
||||
try:
|
||||
server.serve_forever()
|
||||
except KeyboardInterrupt:
|
||||
print("\nStopped.")
|
||||
server.server_close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,430 +0,0 @@
|
||||
# JSON Schemas
|
||||
|
||||
This document defines the JSON schemas used by skill-creator.
|
||||
|
||||
---
|
||||
|
||||
## evals.json
|
||||
|
||||
Defines the evals for a skill. Located at `evals/evals.json` within the skill directory.
|
||||
|
||||
```json
|
||||
{
|
||||
"skill_name": "example-skill",
|
||||
"evals": [
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "User's example prompt",
|
||||
"expected_output": "Description of expected result",
|
||||
"files": ["evals/files/sample1.pdf"],
|
||||
"expectations": [
|
||||
"The output includes X",
|
||||
"The skill used script Y"
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `skill_name`: Name matching the skill's frontmatter
|
||||
- `evals[].id`: Unique integer identifier
|
||||
- `evals[].prompt`: The task to execute
|
||||
- `evals[].expected_output`: Human-readable description of success
|
||||
- `evals[].files`: Optional list of input file paths (relative to skill root)
|
||||
- `evals[].expectations`: List of verifiable statements
|
||||
|
||||
---
|
||||
|
||||
## history.json
|
||||
|
||||
Tracks version progression in Improve mode. Located at workspace root.
|
||||
|
||||
```json
|
||||
{
|
||||
"started_at": "2026-01-15T10:30:00Z",
|
||||
"skill_name": "pdf",
|
||||
"current_best": "v2",
|
||||
"iterations": [
|
||||
{
|
||||
"version": "v0",
|
||||
"parent": null,
|
||||
"expectation_pass_rate": 0.65,
|
||||
"grading_result": "baseline",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v1",
|
||||
"parent": "v0",
|
||||
"expectation_pass_rate": 0.75,
|
||||
"grading_result": "won",
|
||||
"is_current_best": false
|
||||
},
|
||||
{
|
||||
"version": "v2",
|
||||
"parent": "v1",
|
||||
"expectation_pass_rate": 0.85,
|
||||
"grading_result": "won",
|
||||
"is_current_best": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `started_at`: ISO timestamp of when improvement started
|
||||
- `skill_name`: Name of the skill being improved
|
||||
- `current_best`: Version identifier of the best performer
|
||||
- `iterations[].version`: Version identifier (v0, v1, ...)
|
||||
- `iterations[].parent`: Parent version this was derived from
|
||||
- `iterations[].expectation_pass_rate`: Pass rate from grading
|
||||
- `iterations[].grading_result`: "baseline", "won", "lost", or "tie"
|
||||
- `iterations[].is_current_best`: Whether this is the current best version
|
||||
|
||||
---
|
||||
|
||||
## grading.json
|
||||
|
||||
Output from the grader agent. Located at `<run-dir>/grading.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"expectations": [
|
||||
{
|
||||
"text": "The output includes the name 'John Smith'",
|
||||
"passed": true,
|
||||
"evidence": "Found in transcript Step 3: 'Extracted names: John Smith, Sarah Johnson'"
|
||||
},
|
||||
{
|
||||
"text": "The spreadsheet has a SUM formula in cell B10",
|
||||
"passed": false,
|
||||
"evidence": "No spreadsheet was created. The output was a text file."
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"passed": 2,
|
||||
"failed": 1,
|
||||
"total": 3,
|
||||
"pass_rate": 0.67
|
||||
},
|
||||
"execution_metrics": {
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8
|
||||
},
|
||||
"total_tool_calls": 15,
|
||||
"total_steps": 6,
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
},
|
||||
"timing": {
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_duration_seconds": 26.0,
|
||||
"total_duration_seconds": 191.0
|
||||
},
|
||||
"claims": [
|
||||
{
|
||||
"claim": "The form has 12 fillable fields",
|
||||
"type": "factual",
|
||||
"verified": true,
|
||||
"evidence": "Counted 12 fields in field_info.json"
|
||||
}
|
||||
],
|
||||
"user_notes_summary": {
|
||||
"uncertainties": ["Used 2023 data, may be stale"],
|
||||
"needs_review": [],
|
||||
"workarounds": ["Fell back to text overlay for non-fillable fields"]
|
||||
},
|
||||
"eval_feedback": {
|
||||
"suggestions": [
|
||||
{
|
||||
"assertion": "The output includes the name 'John Smith'",
|
||||
"reason": "A hallucinated document that mentions the name would also pass"
|
||||
}
|
||||
],
|
||||
"overall": "Assertions check presence but not correctness."
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `expectations[]`: Graded expectations with evidence
|
||||
- `summary`: Aggregate pass/fail counts
|
||||
- `execution_metrics`: Tool usage and output size (from executor's metrics.json)
|
||||
- `timing`: Wall clock timing (from timing.json)
|
||||
- `claims`: Extracted and verified claims from the output
|
||||
- `user_notes_summary`: Issues flagged by the executor
|
||||
- `eval_feedback`: (optional) Improvement suggestions for the evals, only present when the grader identifies issues worth raising
|
||||
|
||||
---
|
||||
|
||||
## metrics.json
|
||||
|
||||
Output from the executor agent. Located at `<run-dir>/outputs/metrics.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"tool_calls": {
|
||||
"Read": 5,
|
||||
"Write": 2,
|
||||
"Bash": 8,
|
||||
"Edit": 1,
|
||||
"Glob": 2,
|
||||
"Grep": 0
|
||||
},
|
||||
"total_tool_calls": 18,
|
||||
"total_steps": 6,
|
||||
"files_created": ["filled_form.pdf", "field_values.json"],
|
||||
"errors_encountered": 0,
|
||||
"output_chars": 12450,
|
||||
"transcript_chars": 3200
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `tool_calls`: Count per tool type
|
||||
- `total_tool_calls`: Sum of all tool calls
|
||||
- `total_steps`: Number of major execution steps
|
||||
- `files_created`: List of output files created
|
||||
- `errors_encountered`: Number of errors during execution
|
||||
- `output_chars`: Total character count of output files
|
||||
- `transcript_chars`: Character count of transcript
|
||||
|
||||
---
|
||||
|
||||
## timing.json
|
||||
|
||||
Wall clock timing for a run. Located at `<run-dir>/timing.json`.
|
||||
|
||||
**How to capture:** When a subagent task completes, the task notification includes `total_tokens` and `duration_ms`. Save these immediately — they are not persisted anywhere else and cannot be recovered after the fact.
|
||||
|
||||
```json
|
||||
{
|
||||
"total_tokens": 84852,
|
||||
"duration_ms": 23332,
|
||||
"total_duration_seconds": 23.3,
|
||||
"executor_start": "2026-01-15T10:30:00Z",
|
||||
"executor_end": "2026-01-15T10:32:45Z",
|
||||
"executor_duration_seconds": 165.0,
|
||||
"grader_start": "2026-01-15T10:32:46Z",
|
||||
"grader_end": "2026-01-15T10:33:12Z",
|
||||
"grader_duration_seconds": 26.0
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## benchmark.json
|
||||
|
||||
Output from Benchmark mode. Located at `benchmarks/<timestamp>/benchmark.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"metadata": {
|
||||
"skill_name": "pdf",
|
||||
"skill_path": "/path/to/pdf",
|
||||
"executor_model": "claude-sonnet-4-20250514",
|
||||
"analyzer_model": "most-capable-model",
|
||||
"timestamp": "2026-01-15T10:30:00Z",
|
||||
"evals_run": [1, 2, 3],
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
|
||||
"runs": [
|
||||
{
|
||||
"eval_id": 1,
|
||||
"eval_name": "Ocean",
|
||||
"configuration": "with_skill",
|
||||
"run_number": 1,
|
||||
"result": {
|
||||
"pass_rate": 0.85,
|
||||
"passed": 6,
|
||||
"failed": 1,
|
||||
"total": 7,
|
||||
"time_seconds": 42.5,
|
||||
"tokens": 3800,
|
||||
"tool_calls": 18,
|
||||
"errors": 0
|
||||
},
|
||||
"expectations": [
|
||||
{"text": "...", "passed": true, "evidence": "..."}
|
||||
],
|
||||
"notes": [
|
||||
"Used 2023 data, may be stale",
|
||||
"Fell back to text overlay for non-fillable fields"
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
"run_summary": {
|
||||
"with_skill": {
|
||||
"pass_rate": {"mean": 0.85, "stddev": 0.05, "min": 0.80, "max": 0.90},
|
||||
"time_seconds": {"mean": 45.0, "stddev": 12.0, "min": 32.0, "max": 58.0},
|
||||
"tokens": {"mean": 3800, "stddev": 400, "min": 3200, "max": 4100}
|
||||
},
|
||||
"without_skill": {
|
||||
"pass_rate": {"mean": 0.35, "stddev": 0.08, "min": 0.28, "max": 0.45},
|
||||
"time_seconds": {"mean": 32.0, "stddev": 8.0, "min": 24.0, "max": 42.0},
|
||||
"tokens": {"mean": 2100, "stddev": 300, "min": 1800, "max": 2500}
|
||||
},
|
||||
"delta": {
|
||||
"pass_rate": "+0.50",
|
||||
"time_seconds": "+13.0",
|
||||
"tokens": "+1700"
|
||||
}
|
||||
},
|
||||
|
||||
"notes": [
|
||||
"Assertion 'Output is a PDF file' passes 100% in both configurations - may not differentiate skill value",
|
||||
"Eval 3 shows high variance (50% ± 40%) - may be flaky or model-dependent",
|
||||
"Without-skill runs consistently fail on table extraction expectations",
|
||||
"Skill adds 13s average execution time but improves pass rate by 50%"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Fields:**
|
||||
- `metadata`: Information about the benchmark run
|
||||
- `skill_name`: Name of the skill
|
||||
- `timestamp`: When the benchmark was run
|
||||
- `evals_run`: List of eval names or IDs
|
||||
- `runs_per_configuration`: Number of runs per config (e.g. 3)
|
||||
- `runs[]`: Individual run results
|
||||
- `eval_id`: Numeric eval identifier
|
||||
- `eval_name`: Human-readable eval name (used as section header in the viewer)
|
||||
- `configuration`: Must be `"with_skill"` or `"without_skill"` (the viewer uses this exact string for grouping and color coding)
|
||||
- `run_number`: Integer run number (1, 2, 3...)
|
||||
- `result`: Nested object with `pass_rate`, `passed`, `total`, `time_seconds`, `tokens`, `errors`
|
||||
- `run_summary`: Statistical aggregates per configuration
|
||||
- `with_skill` / `without_skill`: Each contains `pass_rate`, `time_seconds`, `tokens` objects with `mean` and `stddev` fields
|
||||
- `delta`: Difference strings like `"+0.50"`, `"+13.0"`, `"+1700"`
|
||||
- `notes`: Freeform observations from the analyzer
|
||||
|
||||
**Important:** The viewer reads these field names exactly. Using `config` instead of `configuration`, or putting `pass_rate` at the top level of a run instead of nested under `result`, will cause the viewer to show empty/zero values. Always reference this schema when generating benchmark.json manually.
|
||||
|
||||
---
|
||||
|
||||
## comparison.json
|
||||
|
||||
Output from blind comparator. Located at `<grading-dir>/comparison-N.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"winner": "A",
|
||||
"reasoning": "Output A provides a complete solution with proper formatting and all required fields. Output B is missing the date field and has formatting inconsistencies.",
|
||||
"rubric": {
|
||||
"A": {
|
||||
"content": {
|
||||
"correctness": 5,
|
||||
"completeness": 5,
|
||||
"accuracy": 4
|
||||
},
|
||||
"structure": {
|
||||
"organization": 4,
|
||||
"formatting": 5,
|
||||
"usability": 4
|
||||
},
|
||||
"content_score": 4.7,
|
||||
"structure_score": 4.3,
|
||||
"overall_score": 9.0
|
||||
},
|
||||
"B": {
|
||||
"content": {
|
||||
"correctness": 3,
|
||||
"completeness": 2,
|
||||
"accuracy": 3
|
||||
},
|
||||
"structure": {
|
||||
"organization": 3,
|
||||
"formatting": 2,
|
||||
"usability": 3
|
||||
},
|
||||
"content_score": 2.7,
|
||||
"structure_score": 2.7,
|
||||
"overall_score": 5.4
|
||||
}
|
||||
},
|
||||
"output_quality": {
|
||||
"A": {
|
||||
"score": 9,
|
||||
"strengths": ["Complete solution", "Well-formatted", "All fields present"],
|
||||
"weaknesses": ["Minor style inconsistency in header"]
|
||||
},
|
||||
"B": {
|
||||
"score": 5,
|
||||
"strengths": ["Readable output", "Correct basic structure"],
|
||||
"weaknesses": ["Missing date field", "Formatting inconsistencies", "Partial data extraction"]
|
||||
}
|
||||
},
|
||||
"expectation_results": {
|
||||
"A": {
|
||||
"passed": 4,
|
||||
"total": 5,
|
||||
"pass_rate": 0.80,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
},
|
||||
"B": {
|
||||
"passed": 3,
|
||||
"total": 5,
|
||||
"pass_rate": 0.60,
|
||||
"details": [
|
||||
{"text": "Output includes name", "passed": true}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## analysis.json
|
||||
|
||||
Output from post-hoc analyzer. Located at `<grading-dir>/analysis.json`.
|
||||
|
||||
```json
|
||||
{
|
||||
"comparison_summary": {
|
||||
"winner": "A",
|
||||
"winner_skill": "path/to/winner/skill",
|
||||
"loser_skill": "path/to/loser/skill",
|
||||
"comparator_reasoning": "Brief summary of why comparator chose winner"
|
||||
},
|
||||
"winner_strengths": [
|
||||
"Clear step-by-step instructions for handling multi-page documents",
|
||||
"Included validation script that caught formatting errors"
|
||||
],
|
||||
"loser_weaknesses": [
|
||||
"Vague instruction 'process the document appropriately' led to inconsistent behavior",
|
||||
"No script for validation, agent had to improvise"
|
||||
],
|
||||
"instruction_following": {
|
||||
"winner": {
|
||||
"score": 9,
|
||||
"issues": ["Minor: skipped optional logging step"]
|
||||
},
|
||||
"loser": {
|
||||
"score": 6,
|
||||
"issues": [
|
||||
"Did not use the skill's formatting template",
|
||||
"Invented own approach instead of following step 3"
|
||||
]
|
||||
}
|
||||
},
|
||||
"improvement_suggestions": [
|
||||
{
|
||||
"priority": "high",
|
||||
"category": "instructions",
|
||||
"suggestion": "Replace 'process the document appropriately' with explicit steps",
|
||||
"expected_impact": "Would eliminate ambiguity that caused inconsistent behavior"
|
||||
}
|
||||
],
|
||||
"transcript_insights": {
|
||||
"winner_execution_pattern": "Read skill -> Followed 5-step process -> Used validation script",
|
||||
"loser_execution_pattern": "Read skill -> Unclear on approach -> Tried 3 different methods"
|
||||
}
|
||||
}
|
||||
```
|
||||
@ -1,401 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Aggregate individual run results into benchmark summary statistics.
|
||||
|
||||
Reads grading.json files from run directories and produces:
|
||||
- run_summary with mean, stddev, min, max for each metric
|
||||
- delta between with_skill and without_skill configurations
|
||||
|
||||
Usage:
|
||||
python aggregate_benchmark.py <benchmark_dir>
|
||||
|
||||
Example:
|
||||
python aggregate_benchmark.py benchmarks/2026-01-15T10-30-00/
|
||||
|
||||
The script supports two directory layouts:
|
||||
|
||||
Workspace layout (from skill-creator iterations):
|
||||
<benchmark_dir>/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ ├── run-1/grading.json
|
||||
│ └── run-2/grading.json
|
||||
└── without_skill/
|
||||
├── run-1/grading.json
|
||||
└── run-2/grading.json
|
||||
|
||||
Legacy layout (with runs/ subdirectory):
|
||||
<benchmark_dir>/
|
||||
└── runs/
|
||||
└── eval-N/
|
||||
├── with_skill/
|
||||
│ └── run-1/grading.json
|
||||
└── without_skill/
|
||||
└── run-1/grading.json
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import math
|
||||
import sys
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def calculate_stats(values: list[float]) -> dict:
|
||||
"""Calculate mean, stddev, min, max for a list of values."""
|
||||
if not values:
|
||||
return {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0}
|
||||
|
||||
n = len(values)
|
||||
mean = sum(values) / n
|
||||
|
||||
if n > 1:
|
||||
variance = sum((x - mean) ** 2 for x in values) / (n - 1)
|
||||
stddev = math.sqrt(variance)
|
||||
else:
|
||||
stddev = 0.0
|
||||
|
||||
return {
|
||||
"mean": round(mean, 4),
|
||||
"stddev": round(stddev, 4),
|
||||
"min": round(min(values), 4),
|
||||
"max": round(max(values), 4)
|
||||
}
|
||||
|
||||
|
||||
def load_run_results(benchmark_dir: Path) -> dict:
|
||||
"""
|
||||
Load all run results from a benchmark directory.
|
||||
|
||||
Returns dict keyed by config name (e.g. "with_skill"/"without_skill",
|
||||
or "new_skill"/"old_skill"), each containing a list of run results.
|
||||
"""
|
||||
# Support both layouts: eval dirs directly under benchmark_dir, or under runs/
|
||||
runs_dir = benchmark_dir / "runs"
|
||||
if runs_dir.exists():
|
||||
search_dir = runs_dir
|
||||
elif list(benchmark_dir.glob("eval-*")):
|
||||
search_dir = benchmark_dir
|
||||
else:
|
||||
print(f"No eval directories found in {benchmark_dir} or {benchmark_dir / 'runs'}")
|
||||
return {}
|
||||
|
||||
results: dict[str, list] = {}
|
||||
|
||||
for eval_idx, eval_dir in enumerate(sorted(search_dir.glob("eval-*"))):
|
||||
metadata_path = eval_dir / "eval_metadata.json"
|
||||
if metadata_path.exists():
|
||||
try:
|
||||
with open(metadata_path) as mf:
|
||||
eval_id = json.load(mf).get("eval_id", eval_idx)
|
||||
except (json.JSONDecodeError, OSError):
|
||||
eval_id = eval_idx
|
||||
else:
|
||||
try:
|
||||
eval_id = int(eval_dir.name.split("-")[1])
|
||||
except ValueError:
|
||||
eval_id = eval_idx
|
||||
|
||||
# Discover config directories dynamically rather than hardcoding names
|
||||
for config_dir in sorted(eval_dir.iterdir()):
|
||||
if not config_dir.is_dir():
|
||||
continue
|
||||
# Skip non-config directories (inputs, outputs, etc.)
|
||||
if not list(config_dir.glob("run-*")):
|
||||
continue
|
||||
config = config_dir.name
|
||||
if config not in results:
|
||||
results[config] = []
|
||||
|
||||
for run_dir in sorted(config_dir.glob("run-*")):
|
||||
run_number = int(run_dir.name.split("-")[1])
|
||||
grading_file = run_dir / "grading.json"
|
||||
|
||||
if not grading_file.exists():
|
||||
print(f"Warning: grading.json not found in {run_dir}")
|
||||
continue
|
||||
|
||||
try:
|
||||
with open(grading_file) as f:
|
||||
grading = json.load(f)
|
||||
except json.JSONDecodeError as e:
|
||||
print(f"Warning: Invalid JSON in {grading_file}: {e}")
|
||||
continue
|
||||
|
||||
# Extract metrics
|
||||
result = {
|
||||
"eval_id": eval_id,
|
||||
"run_number": run_number,
|
||||
"pass_rate": grading.get("summary", {}).get("pass_rate", 0.0),
|
||||
"passed": grading.get("summary", {}).get("passed", 0),
|
||||
"failed": grading.get("summary", {}).get("failed", 0),
|
||||
"total": grading.get("summary", {}).get("total", 0),
|
||||
}
|
||||
|
||||
# Extract timing — check grading.json first, then sibling timing.json
|
||||
timing = grading.get("timing", {})
|
||||
result["time_seconds"] = timing.get("total_duration_seconds", 0.0)
|
||||
timing_file = run_dir / "timing.json"
|
||||
if result["time_seconds"] == 0.0 and timing_file.exists():
|
||||
try:
|
||||
with open(timing_file) as tf:
|
||||
timing_data = json.load(tf)
|
||||
result["time_seconds"] = timing_data.get("total_duration_seconds", 0.0)
|
||||
result["tokens"] = timing_data.get("total_tokens", 0)
|
||||
except json.JSONDecodeError:
|
||||
pass
|
||||
|
||||
# Extract metrics if available
|
||||
metrics = grading.get("execution_metrics", {})
|
||||
result["tool_calls"] = metrics.get("total_tool_calls", 0)
|
||||
if not result.get("tokens"):
|
||||
result["tokens"] = metrics.get("output_chars", 0)
|
||||
result["errors"] = metrics.get("errors_encountered", 0)
|
||||
|
||||
# Extract expectations — viewer requires fields: text, passed, evidence
|
||||
raw_expectations = grading.get("expectations", [])
|
||||
for exp in raw_expectations:
|
||||
if "text" not in exp or "passed" not in exp:
|
||||
print(f"Warning: expectation in {grading_file} missing required fields (text, passed, evidence): {exp}")
|
||||
result["expectations"] = raw_expectations
|
||||
|
||||
# Extract notes from user_notes_summary
|
||||
notes_summary = grading.get("user_notes_summary", {})
|
||||
notes = []
|
||||
notes.extend(notes_summary.get("uncertainties", []))
|
||||
notes.extend(notes_summary.get("needs_review", []))
|
||||
notes.extend(notes_summary.get("workarounds", []))
|
||||
result["notes"] = notes
|
||||
|
||||
results[config].append(result)
|
||||
|
||||
return results
|
||||
|
||||
|
||||
def aggregate_results(results: dict) -> dict:
|
||||
"""
|
||||
Aggregate run results into summary statistics.
|
||||
|
||||
Returns run_summary with stats for each configuration and delta.
|
||||
"""
|
||||
run_summary = {}
|
||||
configs = list(results.keys())
|
||||
|
||||
for config in configs:
|
||||
runs = results.get(config, [])
|
||||
|
||||
if not runs:
|
||||
run_summary[config] = {
|
||||
"pass_rate": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"time_seconds": {"mean": 0.0, "stddev": 0.0, "min": 0.0, "max": 0.0},
|
||||
"tokens": {"mean": 0, "stddev": 0, "min": 0, "max": 0}
|
||||
}
|
||||
continue
|
||||
|
||||
pass_rates = [r["pass_rate"] for r in runs]
|
||||
times = [r["time_seconds"] for r in runs]
|
||||
tokens = [r.get("tokens", 0) for r in runs]
|
||||
|
||||
run_summary[config] = {
|
||||
"pass_rate": calculate_stats(pass_rates),
|
||||
"time_seconds": calculate_stats(times),
|
||||
"tokens": calculate_stats(tokens)
|
||||
}
|
||||
|
||||
# Calculate delta between the first two configs (if two exist)
|
||||
if len(configs) >= 2:
|
||||
primary = run_summary.get(configs[0], {})
|
||||
baseline = run_summary.get(configs[1], {})
|
||||
else:
|
||||
primary = run_summary.get(configs[0], {}) if configs else {}
|
||||
baseline = {}
|
||||
|
||||
delta_pass_rate = primary.get("pass_rate", {}).get("mean", 0) - baseline.get("pass_rate", {}).get("mean", 0)
|
||||
delta_time = primary.get("time_seconds", {}).get("mean", 0) - baseline.get("time_seconds", {}).get("mean", 0)
|
||||
delta_tokens = primary.get("tokens", {}).get("mean", 0) - baseline.get("tokens", {}).get("mean", 0)
|
||||
|
||||
run_summary["delta"] = {
|
||||
"pass_rate": f"{delta_pass_rate:+.2f}",
|
||||
"time_seconds": f"{delta_time:+.1f}",
|
||||
"tokens": f"{delta_tokens:+.0f}"
|
||||
}
|
||||
|
||||
return run_summary
|
||||
|
||||
|
||||
def generate_benchmark(benchmark_dir: Path, skill_name: str = "", skill_path: str = "") -> dict:
|
||||
"""
|
||||
Generate complete benchmark.json from run results.
|
||||
"""
|
||||
results = load_run_results(benchmark_dir)
|
||||
run_summary = aggregate_results(results)
|
||||
|
||||
# Build runs array for benchmark.json
|
||||
runs = []
|
||||
for config in results:
|
||||
for result in results[config]:
|
||||
runs.append({
|
||||
"eval_id": result["eval_id"],
|
||||
"configuration": config,
|
||||
"run_number": result["run_number"],
|
||||
"result": {
|
||||
"pass_rate": result["pass_rate"],
|
||||
"passed": result["passed"],
|
||||
"failed": result["failed"],
|
||||
"total": result["total"],
|
||||
"time_seconds": result["time_seconds"],
|
||||
"tokens": result.get("tokens", 0),
|
||||
"tool_calls": result.get("tool_calls", 0),
|
||||
"errors": result.get("errors", 0)
|
||||
},
|
||||
"expectations": result["expectations"],
|
||||
"notes": result["notes"]
|
||||
})
|
||||
|
||||
# Determine eval IDs from results
|
||||
eval_ids = sorted(set(
|
||||
r["eval_id"]
|
||||
for config in results.values()
|
||||
for r in config
|
||||
))
|
||||
|
||||
benchmark = {
|
||||
"metadata": {
|
||||
"skill_name": skill_name or "<skill-name>",
|
||||
"skill_path": skill_path or "<path/to/skill>",
|
||||
"executor_model": "<model-name>",
|
||||
"analyzer_model": "<model-name>",
|
||||
"timestamp": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
|
||||
"evals_run": eval_ids,
|
||||
"runs_per_configuration": 3
|
||||
},
|
||||
"runs": runs,
|
||||
"run_summary": run_summary,
|
||||
"notes": [] # To be filled by analyzer
|
||||
}
|
||||
|
||||
return benchmark
|
||||
|
||||
|
||||
def generate_markdown(benchmark: dict) -> str:
|
||||
"""Generate human-readable benchmark.md from benchmark data."""
|
||||
metadata = benchmark["metadata"]
|
||||
run_summary = benchmark["run_summary"]
|
||||
|
||||
# Determine config names (excluding "delta")
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
config_a = configs[0] if len(configs) >= 1 else "config_a"
|
||||
config_b = configs[1] if len(configs) >= 2 else "config_b"
|
||||
label_a = config_a.replace("_", " ").title()
|
||||
label_b = config_b.replace("_", " ").title()
|
||||
|
||||
lines = [
|
||||
f"# Skill Benchmark: {metadata['skill_name']}",
|
||||
"",
|
||||
f"**Model**: {metadata['executor_model']}",
|
||||
f"**Date**: {metadata['timestamp']}",
|
||||
f"**Evals**: {', '.join(map(str, metadata['evals_run']))} ({metadata['runs_per_configuration']} runs each per configuration)",
|
||||
"",
|
||||
"## Summary",
|
||||
"",
|
||||
f"| Metric | {label_a} | {label_b} | Delta |",
|
||||
"|--------|------------|---------------|-------|",
|
||||
]
|
||||
|
||||
a_summary = run_summary.get(config_a, {})
|
||||
b_summary = run_summary.get(config_b, {})
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
# Format pass rate
|
||||
a_pr = a_summary.get("pass_rate", {})
|
||||
b_pr = b_summary.get("pass_rate", {})
|
||||
lines.append(f"| Pass Rate | {a_pr.get('mean', 0)*100:.0f}% ± {a_pr.get('stddev', 0)*100:.0f}% | {b_pr.get('mean', 0)*100:.0f}% ± {b_pr.get('stddev', 0)*100:.0f}% | {delta.get('pass_rate', '—')} |")
|
||||
|
||||
# Format time
|
||||
a_time = a_summary.get("time_seconds", {})
|
||||
b_time = b_summary.get("time_seconds", {})
|
||||
lines.append(f"| Time | {a_time.get('mean', 0):.1f}s ± {a_time.get('stddev', 0):.1f}s | {b_time.get('mean', 0):.1f}s ± {b_time.get('stddev', 0):.1f}s | {delta.get('time_seconds', '—')}s |")
|
||||
|
||||
# Format tokens
|
||||
a_tokens = a_summary.get("tokens", {})
|
||||
b_tokens = b_summary.get("tokens", {})
|
||||
lines.append(f"| Tokens | {a_tokens.get('mean', 0):.0f} ± {a_tokens.get('stddev', 0):.0f} | {b_tokens.get('mean', 0):.0f} ± {b_tokens.get('stddev', 0):.0f} | {delta.get('tokens', '—')} |")
|
||||
|
||||
# Notes section
|
||||
if benchmark.get("notes"):
|
||||
lines.extend([
|
||||
"",
|
||||
"## Notes",
|
||||
""
|
||||
])
|
||||
for note in benchmark["notes"]:
|
||||
lines.append(f"- {note}")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Aggregate benchmark run results into summary statistics"
|
||||
)
|
||||
parser.add_argument(
|
||||
"benchmark_dir",
|
||||
type=Path,
|
||||
help="Path to the benchmark directory"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-name",
|
||||
default="",
|
||||
help="Name of the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--skill-path",
|
||||
default="",
|
||||
help="Path to the skill being benchmarked"
|
||||
)
|
||||
parser.add_argument(
|
||||
"--output", "-o",
|
||||
type=Path,
|
||||
help="Output path for benchmark.json (default: <benchmark_dir>/benchmark.json)"
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not args.benchmark_dir.exists():
|
||||
print(f"Directory not found: {args.benchmark_dir}")
|
||||
sys.exit(1)
|
||||
|
||||
# Generate benchmark
|
||||
benchmark = generate_benchmark(args.benchmark_dir, args.skill_name, args.skill_path)
|
||||
|
||||
# Determine output paths
|
||||
output_json = args.output or (args.benchmark_dir / "benchmark.json")
|
||||
output_md = output_json.with_suffix(".md")
|
||||
|
||||
# Write benchmark.json
|
||||
with open(output_json, "w") as f:
|
||||
json.dump(benchmark, f, indent=2)
|
||||
print(f"Generated: {output_json}")
|
||||
|
||||
# Write benchmark.md
|
||||
markdown = generate_markdown(benchmark)
|
||||
with open(output_md, "w") as f:
|
||||
f.write(markdown)
|
||||
print(f"Generated: {output_md}")
|
||||
|
||||
# Print summary
|
||||
run_summary = benchmark["run_summary"]
|
||||
configs = [k for k in run_summary if k != "delta"]
|
||||
delta = run_summary.get("delta", {})
|
||||
|
||||
print(f"\nSummary:")
|
||||
for config in configs:
|
||||
pr = run_summary[config]["pass_rate"]["mean"]
|
||||
label = config.replace("_", " ").title()
|
||||
print(f" {label}: {pr*100:.1f}% pass rate")
|
||||
print(f" Delta: {delta.get('pass_rate', '—')}")
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,326 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Generate an HTML report from run_loop.py output.
|
||||
|
||||
Takes the JSON output from run_loop.py and generates a visual HTML report
|
||||
showing each description attempt with check/x for each test case.
|
||||
Distinguishes between train and test queries.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import html
|
||||
import json
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def generate_html(data: dict, auto_refresh: bool = False, skill_name: str = "") -> str:
|
||||
"""Generate HTML report from loop output data. If auto_refresh is True, adds a meta refresh tag."""
|
||||
history = data.get("history", [])
|
||||
holdout = data.get("holdout", 0)
|
||||
title_prefix = html.escape(skill_name + " \u2014 ") if skill_name else ""
|
||||
|
||||
# Get all unique queries from train and test sets, with should_trigger info
|
||||
train_queries: list[dict] = []
|
||||
test_queries: list[dict] = []
|
||||
if history:
|
||||
for r in history[0].get("train_results", history[0].get("results", [])):
|
||||
train_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
if history[0].get("test_results"):
|
||||
for r in history[0].get("test_results", []):
|
||||
test_queries.append({"query": r["query"], "should_trigger": r.get("should_trigger", True)})
|
||||
|
||||
refresh_tag = ' <meta http-equiv="refresh" content="5">\n' if auto_refresh else ""
|
||||
|
||||
html_parts = ["""<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8">
|
||||
""" + refresh_tag + """ <title>""" + title_prefix + """Skill Description Optimization</title>
|
||||
<link rel="preconnect" href="https://fonts.googleapis.com">
|
||||
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Poppins:wght@500;600&family=Lora:wght@400;500&display=swap" rel="stylesheet">
|
||||
<style>
|
||||
body {
|
||||
font-family: 'Lora', Georgia, serif;
|
||||
max-width: 100%;
|
||||
margin: 0 auto;
|
||||
padding: 20px;
|
||||
background: #faf9f5;
|
||||
color: #141413;
|
||||
}
|
||||
h1 { font-family: 'Poppins', sans-serif; color: #141413; }
|
||||
.explainer {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
color: #b0aea5;
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.6;
|
||||
}
|
||||
.summary {
|
||||
background: white;
|
||||
padding: 15px;
|
||||
border-radius: 6px;
|
||||
margin-bottom: 20px;
|
||||
border: 1px solid #e8e6dc;
|
||||
}
|
||||
.summary p { margin: 5px 0; }
|
||||
.best { color: #788c5d; font-weight: bold; }
|
||||
.table-container {
|
||||
overflow-x: auto;
|
||||
width: 100%;
|
||||
}
|
||||
table {
|
||||
border-collapse: collapse;
|
||||
background: white;
|
||||
border: 1px solid #e8e6dc;
|
||||
border-radius: 6px;
|
||||
font-size: 12px;
|
||||
min-width: 100%;
|
||||
}
|
||||
th, td {
|
||||
padding: 8px;
|
||||
text-align: left;
|
||||
border: 1px solid #e8e6dc;
|
||||
white-space: normal;
|
||||
word-wrap: break-word;
|
||||
}
|
||||
th {
|
||||
font-family: 'Poppins', sans-serif;
|
||||
background: #141413;
|
||||
color: #faf9f5;
|
||||
font-weight: 500;
|
||||
}
|
||||
th.test-col {
|
||||
background: #6a9bcc;
|
||||
}
|
||||
th.query-col { min-width: 200px; }
|
||||
td.description {
|
||||
font-family: monospace;
|
||||
font-size: 11px;
|
||||
word-wrap: break-word;
|
||||
max-width: 400px;
|
||||
}
|
||||
td.result {
|
||||
text-align: center;
|
||||
font-size: 16px;
|
||||
min-width: 40px;
|
||||
}
|
||||
td.test-result {
|
||||
background: #f0f6fc;
|
||||
}
|
||||
.pass { color: #788c5d; }
|
||||
.fail { color: #c44; }
|
||||
.rate {
|
||||
font-size: 9px;
|
||||
color: #b0aea5;
|
||||
display: block;
|
||||
}
|
||||
tr:hover { background: #faf9f5; }
|
||||
.score {
|
||||
display: inline-block;
|
||||
padding: 2px 6px;
|
||||
border-radius: 4px;
|
||||
font-weight: bold;
|
||||
font-size: 11px;
|
||||
}
|
||||
.score-good { background: #eef2e8; color: #788c5d; }
|
||||
.score-ok { background: #fef3c7; color: #d97706; }
|
||||
.score-bad { background: #fceaea; color: #c44; }
|
||||
.train-label { color: #b0aea5; font-size: 10px; }
|
||||
.test-label { color: #6a9bcc; font-size: 10px; font-weight: bold; }
|
||||
.best-row { background: #f5f8f2; }
|
||||
th.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.negative-col { border-bottom: 3px solid #c44; }
|
||||
th.test-col.positive-col { border-bottom: 3px solid #788c5d; }
|
||||
th.test-col.negative-col { border-bottom: 3px solid #c44; }
|
||||
.legend { font-family: 'Poppins', sans-serif; display: flex; gap: 20px; margin-bottom: 10px; font-size: 13px; align-items: center; }
|
||||
.legend-item { display: flex; align-items: center; gap: 6px; }
|
||||
.legend-swatch { width: 16px; height: 16px; border-radius: 3px; display: inline-block; }
|
||||
.swatch-positive { background: #141413; border-bottom: 3px solid #788c5d; }
|
||||
.swatch-negative { background: #141413; border-bottom: 3px solid #c44; }
|
||||
.swatch-test { background: #6a9bcc; }
|
||||
.swatch-train { background: #141413; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>""" + title_prefix + """Skill Description Optimization</h1>
|
||||
<div class="explainer">
|
||||
<strong>Optimizing your skill's description.</strong> This page updates automatically as Claude tests different versions of your skill's description. Each row is an iteration — a new description attempt. The columns show test queries: green checkmarks mean the skill triggered correctly (or correctly didn't trigger), red crosses mean it got it wrong. The "Train" score shows performance on queries used to improve the description; the "Test" score shows performance on held-out queries the optimizer hasn't seen. When it's done, Claude will apply the best-performing description to your skill.
|
||||
</div>
|
||||
"""]
|
||||
|
||||
# Summary section
|
||||
best_test_score = data.get('best_test_score')
|
||||
best_train_score = data.get('best_train_score')
|
||||
html_parts.append(f"""
|
||||
<div class="summary">
|
||||
<p><strong>Original:</strong> {html.escape(data.get('original_description', 'N/A'))}</p>
|
||||
<p class="best"><strong>Best:</strong> {html.escape(data.get('best_description', 'N/A'))}</p>
|
||||
<p><strong>Best Score:</strong> {data.get('best_score', 'N/A')} {'(test)' if best_test_score else '(train)'}</p>
|
||||
<p><strong>Iterations:</strong> {data.get('iterations_run', 0)} | <strong>Train:</strong> {data.get('train_size', '?')} | <strong>Test:</strong> {data.get('test_size', '?')}</p>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Legend
|
||||
html_parts.append("""
|
||||
<div class="legend">
|
||||
<span style="font-weight:600">Query columns:</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-positive"></span> Should trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-negative"></span> Should NOT trigger</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-train"></span> Train</span>
|
||||
<span class="legend-item"><span class="legend-swatch swatch-test"></span> Test</span>
|
||||
</div>
|
||||
""")
|
||||
|
||||
# Table header
|
||||
html_parts.append("""
|
||||
<div class="table-container">
|
||||
<table>
|
||||
<thead>
|
||||
<tr>
|
||||
<th>Iter</th>
|
||||
<th>Train</th>
|
||||
<th>Test</th>
|
||||
<th class="query-col">Description</th>
|
||||
""")
|
||||
|
||||
# Add column headers for train queries
|
||||
for qinfo in train_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="{polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
# Add column headers for test queries (different color)
|
||||
for qinfo in test_queries:
|
||||
polarity = "positive-col" if qinfo["should_trigger"] else "negative-col"
|
||||
html_parts.append(f' <th class="test-col {polarity}">{html.escape(qinfo["query"])}</th>\n')
|
||||
|
||||
html_parts.append(""" </tr>
|
||||
</thead>
|
||||
<tbody>
|
||||
""")
|
||||
|
||||
# Find best iteration for highlighting
|
||||
if test_queries:
|
||||
best_iter = max(history, key=lambda h: h.get("test_passed") or 0).get("iteration")
|
||||
else:
|
||||
best_iter = max(history, key=lambda h: h.get("train_passed", h.get("passed", 0))).get("iteration")
|
||||
|
||||
# Add rows for each iteration
|
||||
for h in history:
|
||||
iteration = h.get("iteration", "?")
|
||||
train_passed = h.get("train_passed", h.get("passed", 0))
|
||||
train_total = h.get("train_total", h.get("total", 0))
|
||||
test_passed = h.get("test_passed")
|
||||
test_total = h.get("test_total")
|
||||
description = h.get("description", "")
|
||||
train_results = h.get("train_results", h.get("results", []))
|
||||
test_results = h.get("test_results", [])
|
||||
|
||||
# Create lookups for results by query
|
||||
train_by_query = {r["query"]: r for r in train_results}
|
||||
test_by_query = {r["query"]: r for r in test_results} if test_results else {}
|
||||
|
||||
# Compute aggregate correct/total runs across all retries
|
||||
def aggregate_runs(results: list[dict]) -> tuple[int, int]:
|
||||
correct = 0
|
||||
total = 0
|
||||
for r in results:
|
||||
runs = r.get("runs", 0)
|
||||
triggers = r.get("triggers", 0)
|
||||
total += runs
|
||||
if r.get("should_trigger", True):
|
||||
correct += triggers
|
||||
else:
|
||||
correct += runs - triggers
|
||||
return correct, total
|
||||
|
||||
train_correct, train_runs = aggregate_runs(train_results)
|
||||
test_correct, test_runs = aggregate_runs(test_results)
|
||||
|
||||
# Determine score classes
|
||||
def score_class(correct: int, total: int) -> str:
|
||||
if total > 0:
|
||||
ratio = correct / total
|
||||
if ratio >= 0.8:
|
||||
return "score-good"
|
||||
elif ratio >= 0.5:
|
||||
return "score-ok"
|
||||
return "score-bad"
|
||||
|
||||
train_class = score_class(train_correct, train_runs)
|
||||
test_class = score_class(test_correct, test_runs)
|
||||
|
||||
row_class = "best-row" if iteration == best_iter else ""
|
||||
|
||||
html_parts.append(f""" <tr class="{row_class}">
|
||||
<td>{iteration}</td>
|
||||
<td><span class="score {train_class}">{train_correct}/{train_runs}</span></td>
|
||||
<td><span class="score {test_class}">{test_correct}/{test_runs}</span></td>
|
||||
<td class="description">{html.escape(description)}</td>
|
||||
""")
|
||||
|
||||
# Add result for each train query
|
||||
for qinfo in train_queries:
|
||||
r = train_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
# Add result for each test query (with different background)
|
||||
for qinfo in test_queries:
|
||||
r = test_by_query.get(qinfo["query"], {})
|
||||
did_pass = r.get("pass", False)
|
||||
triggers = r.get("triggers", 0)
|
||||
runs = r.get("runs", 0)
|
||||
|
||||
icon = "✓" if did_pass else "✗"
|
||||
css_class = "pass" if did_pass else "fail"
|
||||
|
||||
html_parts.append(f' <td class="result test-result {css_class}">{icon}<span class="rate">{triggers}/{runs}</span></td>\n')
|
||||
|
||||
html_parts.append(" </tr>\n")
|
||||
|
||||
html_parts.append(""" </tbody>
|
||||
</table>
|
||||
</div>
|
||||
""")
|
||||
|
||||
html_parts.append("""
|
||||
</body>
|
||||
</html>
|
||||
""")
|
||||
|
||||
return "".join(html_parts)
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Generate HTML report from run_loop output")
|
||||
parser.add_argument("input", help="Path to JSON output from run_loop.py (or - for stdin)")
|
||||
parser.add_argument("-o", "--output", default=None, help="Output HTML file (default: stdout)")
|
||||
parser.add_argument("--skill-name", default="", help="Skill name to include in the report title")
|
||||
args = parser.parse_args()
|
||||
|
||||
if args.input == "-":
|
||||
data = json.load(sys.stdin)
|
||||
else:
|
||||
data = json.loads(Path(args.input).read_text())
|
||||
|
||||
html_output = generate_html(data, skill_name=args.skill_name)
|
||||
|
||||
if args.output:
|
||||
Path(args.output).write_text(html_output)
|
||||
print(f"Report written to {args.output}", file=sys.stderr)
|
||||
else:
|
||||
print(html_output)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,247 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Improve a skill description based on eval results.
|
||||
|
||||
Takes eval results (from run_eval.py) and generates an improved description
|
||||
by calling `claude -p` as a subprocess (same auth pattern as run_eval.py —
|
||||
uses the session's Claude Code auth, no separate ANTHROPIC_API_KEY needed).
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def _call_claude(prompt: str, model: str | None, timeout: int = 300) -> str:
|
||||
"""Run `claude -p` with the prompt on stdin and return the text response.
|
||||
|
||||
Prompt goes over stdin (not argv) because it embeds the full SKILL.md
|
||||
body and can easily exceed comfortable argv length.
|
||||
"""
|
||||
cmd = ["claude", "-p", "--output-format", "text"]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe. Same pattern as run_eval.py.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
result = subprocess.run(
|
||||
cmd,
|
||||
input=prompt,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
env=env,
|
||||
timeout=timeout,
|
||||
)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(
|
||||
f"claude -p exited {result.returncode}\nstderr: {result.stderr}"
|
||||
)
|
||||
return result.stdout
|
||||
|
||||
|
||||
def improve_description(
|
||||
skill_name: str,
|
||||
skill_content: str,
|
||||
current_description: str,
|
||||
eval_results: dict,
|
||||
history: list[dict],
|
||||
model: str,
|
||||
test_results: dict | None = None,
|
||||
log_dir: Path | None = None,
|
||||
iteration: int | None = None,
|
||||
) -> str:
|
||||
"""Call Claude to improve the description based on eval results."""
|
||||
failed_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
false_triggers = [
|
||||
r for r in eval_results["results"]
|
||||
if not r["should_trigger"] and not r["pass"]
|
||||
]
|
||||
|
||||
# Build scores summary
|
||||
train_score = f"{eval_results['summary']['passed']}/{eval_results['summary']['total']}"
|
||||
if test_results:
|
||||
test_score = f"{test_results['summary']['passed']}/{test_results['summary']['total']}"
|
||||
scores_summary = f"Train: {train_score}, Test: {test_score}"
|
||||
else:
|
||||
scores_summary = f"Train: {train_score}"
|
||||
|
||||
prompt = f"""You are optimizing a skill description for a Claude Code skill called "{skill_name}". A "skill" is sort of like a prompt, but with progressive disclosure -- there's a title and description that Claude sees when deciding whether to use the skill, and then if it does use the skill, it reads the .md file which has lots more details and potentially links to other resources in the skill folder like helper files and scripts and additional documentation or examples.
|
||||
|
||||
The description appears in Claude's "available_skills" list. When a user sends a query, Claude decides whether to invoke the skill based solely on the title and on this description. Your goal is to write a description that triggers for relevant queries, and doesn't trigger for irrelevant ones.
|
||||
|
||||
Here's the current description:
|
||||
<current_description>
|
||||
"{current_description}"
|
||||
</current_description>
|
||||
|
||||
Current scores ({scores_summary}):
|
||||
<scores_summary>
|
||||
"""
|
||||
if failed_triggers:
|
||||
prompt += "FAILED TO TRIGGER (should have triggered but didn't):\n"
|
||||
for r in failed_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if false_triggers:
|
||||
prompt += "FALSE TRIGGERS (triggered but shouldn't have):\n"
|
||||
for r in false_triggers:
|
||||
prompt += f' - "{r["query"]}" (triggered {r["triggers"]}/{r["runs"]} times)\n'
|
||||
prompt += "\n"
|
||||
|
||||
if history:
|
||||
prompt += "PREVIOUS ATTEMPTS (do NOT repeat these — try something structurally different):\n\n"
|
||||
for h in history:
|
||||
train_s = f"{h.get('train_passed', h.get('passed', 0))}/{h.get('train_total', h.get('total', 0))}"
|
||||
test_s = f"{h.get('test_passed', '?')}/{h.get('test_total', '?')}" if h.get('test_passed') is not None else None
|
||||
score_str = f"train={train_s}" + (f", test={test_s}" if test_s else "")
|
||||
prompt += f'<attempt {score_str}>\n'
|
||||
prompt += f'Description: "{h["description"]}"\n'
|
||||
if "results" in h:
|
||||
prompt += "Train results:\n"
|
||||
for r in h["results"]:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
prompt += f' [{status}] "{r["query"][:80]}" (triggered {r["triggers"]}/{r["runs"]})\n'
|
||||
if h.get("note"):
|
||||
prompt += f'Note: {h["note"]}\n'
|
||||
prompt += "</attempt>\n\n"
|
||||
|
||||
prompt += f"""</scores_summary>
|
||||
|
||||
Skill content (for context on what the skill does):
|
||||
<skill_content>
|
||||
{skill_content}
|
||||
</skill_content>
|
||||
|
||||
Based on the failures, write a new and improved description that is more likely to trigger correctly. When I say "based on the failures", it's a bit of a tricky line to walk because we don't want to overfit to the specific cases you're seeing. So what I DON'T want you to do is produce an ever-expanding list of specific queries that this skill should or shouldn't trigger for. Instead, try to generalize from the failures to broader categories of user intent and situations where this skill would be useful or not useful. The reason for this is twofold:
|
||||
|
||||
1. Avoid overfitting
|
||||
2. The list might get loooong and it's injected into ALL queries and there might be a lot of skills, so we don't want to blow too much space on any given description.
|
||||
|
||||
Concretely, your description should not be more than about 100-200 words, even if that comes at the cost of accuracy. There is a hard limit of 1024 characters — descriptions over that will be truncated, so stay comfortably under it.
|
||||
|
||||
Here are some tips that we've found to work well in writing these descriptions:
|
||||
- The skill should be phrased in the imperative -- "Use this skill for" rather than "this skill does"
|
||||
- The skill description should focus on the user's intent, what they are trying to achieve, vs. the implementation details of how the skill works.
|
||||
- The description competes with other skills for Claude's attention — make it distinctive and immediately recognizable.
|
||||
- If you're getting lots of failures after repeated attempts, change things up. Try different sentence structures or wordings.
|
||||
|
||||
I'd encourage you to be creative and mix up the style in different iterations since you'll have multiple opportunities to try different approaches and we'll just grab the highest-scoring one at the end.
|
||||
|
||||
Please respond with only the new description text in <new_description> tags, nothing else."""
|
||||
|
||||
text = _call_claude(prompt, model)
|
||||
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", text, re.DOTALL)
|
||||
description = match.group(1).strip().strip('"') if match else text.strip().strip('"')
|
||||
|
||||
transcript: dict = {
|
||||
"iteration": iteration,
|
||||
"prompt": prompt,
|
||||
"response": text,
|
||||
"parsed_description": description,
|
||||
"char_count": len(description),
|
||||
"over_limit": len(description) > 1024,
|
||||
}
|
||||
|
||||
# Safety net: the prompt already states the 1024-char hard limit, but if
|
||||
# the model blew past it anyway, make one fresh single-turn call that
|
||||
# quotes the too-long version and asks for a shorter rewrite. (The old
|
||||
# SDK path did this as a true multi-turn; `claude -p` is one-shot, so we
|
||||
# inline the prior output into the new prompt instead.)
|
||||
if len(description) > 1024:
|
||||
shorten_prompt = (
|
||||
f"{prompt}\n\n"
|
||||
f"---\n\n"
|
||||
f"A previous attempt produced this description, which at "
|
||||
f"{len(description)} characters is over the 1024-character hard limit:\n\n"
|
||||
f'"{description}"\n\n'
|
||||
f"Rewrite it to be under 1024 characters while keeping the most "
|
||||
f"important trigger words and intent coverage. Respond with only "
|
||||
f"the new description in <new_description> tags."
|
||||
)
|
||||
shorten_text = _call_claude(shorten_prompt, model)
|
||||
match = re.search(r"<new_description>(.*?)</new_description>", shorten_text, re.DOTALL)
|
||||
shortened = match.group(1).strip().strip('"') if match else shorten_text.strip().strip('"')
|
||||
|
||||
transcript["rewrite_prompt"] = shorten_prompt
|
||||
transcript["rewrite_response"] = shorten_text
|
||||
transcript["rewrite_description"] = shortened
|
||||
transcript["rewrite_char_count"] = len(shortened)
|
||||
description = shortened
|
||||
|
||||
transcript["final_description"] = description
|
||||
|
||||
if log_dir:
|
||||
log_dir.mkdir(parents=True, exist_ok=True)
|
||||
log_file = log_dir / f"improve_iter_{iteration or 'unknown'}.json"
|
||||
log_file.write_text(json.dumps(transcript, indent=2))
|
||||
|
||||
return description
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Improve a skill description based on eval results")
|
||||
parser.add_argument("--eval-results", required=True, help="Path to eval results JSON (from run_eval.py)")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--history", default=None, help="Path to history JSON (previous attempts)")
|
||||
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print thinking to stderr")
|
||||
args = parser.parse_args()
|
||||
|
||||
skill_path = Path(args.skill_path)
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
eval_results = json.loads(Path(args.eval_results).read_text())
|
||||
history = []
|
||||
if args.history:
|
||||
history = json.loads(Path(args.history).read_text())
|
||||
|
||||
name, _, content = parse_skill_md(skill_path)
|
||||
current_description = eval_results["description"]
|
||||
|
||||
if args.verbose:
|
||||
print(f"Current: {current_description}", file=sys.stderr)
|
||||
print(f"Score: {eval_results['summary']['passed']}/{eval_results['summary']['total']}", file=sys.stderr)
|
||||
|
||||
new_description = improve_description(
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
eval_results=eval_results,
|
||||
history=history,
|
||||
model=args.model,
|
||||
)
|
||||
|
||||
if args.verbose:
|
||||
print(f"Improved: {new_description}", file=sys.stderr)
|
||||
|
||||
# Output as JSON with both the new description and updated history
|
||||
output = {
|
||||
"description": new_description,
|
||||
"history": history + [{
|
||||
"description": current_description,
|
||||
"passed": eval_results["summary"]["passed"],
|
||||
"failed": eval_results["summary"]["failed"],
|
||||
"total": eval_results["summary"]["total"],
|
||||
"results": eval_results["results"],
|
||||
}],
|
||||
}
|
||||
print(json.dumps(output, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,136 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Skill Packager - Creates a distributable .skill file of a skill folder
|
||||
|
||||
Usage:
|
||||
python utils/package_skill.py <path/to/skill-folder> [output-directory]
|
||||
|
||||
Example:
|
||||
python utils/package_skill.py skills/public/my-skill
|
||||
python utils/package_skill.py skills/public/my-skill ./dist
|
||||
"""
|
||||
|
||||
import fnmatch
|
||||
import sys
|
||||
import zipfile
|
||||
from pathlib import Path
|
||||
from scripts.quick_validate import validate_skill
|
||||
|
||||
# Patterns to exclude when packaging skills.
|
||||
EXCLUDE_DIRS = {"__pycache__", "node_modules"}
|
||||
EXCLUDE_GLOBS = {"*.pyc"}
|
||||
EXCLUDE_FILES = {".DS_Store"}
|
||||
# Directories excluded only at the skill root (not when nested deeper).
|
||||
ROOT_EXCLUDE_DIRS = {"evals"}
|
||||
|
||||
|
||||
def should_exclude(rel_path: Path) -> bool:
|
||||
"""Check if a path should be excluded from packaging."""
|
||||
parts = rel_path.parts
|
||||
if any(part in EXCLUDE_DIRS for part in parts):
|
||||
return True
|
||||
# rel_path is relative to skill_path.parent, so parts[0] is the skill
|
||||
# folder name and parts[1] (if present) is the first subdir.
|
||||
if len(parts) > 1 and parts[1] in ROOT_EXCLUDE_DIRS:
|
||||
return True
|
||||
name = rel_path.name
|
||||
if name in EXCLUDE_FILES:
|
||||
return True
|
||||
return any(fnmatch.fnmatch(name, pat) for pat in EXCLUDE_GLOBS)
|
||||
|
||||
|
||||
def package_skill(skill_path, output_dir=None):
|
||||
"""
|
||||
Package a skill folder into a .skill file.
|
||||
|
||||
Args:
|
||||
skill_path: Path to the skill folder
|
||||
output_dir: Optional output directory for the .skill file (defaults to current directory)
|
||||
|
||||
Returns:
|
||||
Path to the created .skill file, or None if error
|
||||
"""
|
||||
skill_path = Path(skill_path).resolve()
|
||||
|
||||
# Validate skill folder exists
|
||||
if not skill_path.exists():
|
||||
print(f"❌ Error: Skill folder not found: {skill_path}")
|
||||
return None
|
||||
|
||||
if not skill_path.is_dir():
|
||||
print(f"❌ Error: Path is not a directory: {skill_path}")
|
||||
return None
|
||||
|
||||
# Validate SKILL.md exists
|
||||
skill_md = skill_path / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
print(f"❌ Error: SKILL.md not found in {skill_path}")
|
||||
return None
|
||||
|
||||
# Run validation before packaging
|
||||
print("🔍 Validating skill...")
|
||||
valid, message = validate_skill(skill_path)
|
||||
if not valid:
|
||||
print(f"❌ Validation failed: {message}")
|
||||
print(" Please fix the validation errors before packaging.")
|
||||
return None
|
||||
print(f"✅ {message}\n")
|
||||
|
||||
# Determine output location
|
||||
skill_name = skill_path.name
|
||||
if output_dir:
|
||||
output_path = Path(output_dir).resolve()
|
||||
output_path.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
output_path = Path.cwd()
|
||||
|
||||
skill_filename = output_path / f"{skill_name}.skill"
|
||||
|
||||
# Create the .skill file (zip format)
|
||||
try:
|
||||
with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
|
||||
# Walk through the skill directory, excluding build artifacts
|
||||
for file_path in skill_path.rglob('*'):
|
||||
if not file_path.is_file():
|
||||
continue
|
||||
arcname = file_path.relative_to(skill_path.parent)
|
||||
if should_exclude(arcname):
|
||||
print(f" Skipped: {arcname}")
|
||||
continue
|
||||
zipf.write(file_path, arcname)
|
||||
print(f" Added: {arcname}")
|
||||
|
||||
print(f"\n✅ Successfully packaged skill to: {skill_filename}")
|
||||
return skill_filename
|
||||
|
||||
except Exception as e:
|
||||
print(f"❌ Error creating .skill file: {e}")
|
||||
return None
|
||||
|
||||
|
||||
def main():
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
|
||||
print("\nExample:")
|
||||
print(" python utils/package_skill.py skills/public/my-skill")
|
||||
print(" python utils/package_skill.py skills/public/my-skill ./dist")
|
||||
sys.exit(1)
|
||||
|
||||
skill_path = sys.argv[1]
|
||||
output_dir = sys.argv[2] if len(sys.argv) > 2 else None
|
||||
|
||||
print(f"📦 Packaging skill: {skill_path}")
|
||||
if output_dir:
|
||||
print(f" Output directory: {output_dir}")
|
||||
print()
|
||||
|
||||
result = package_skill(skill_path, output_dir)
|
||||
|
||||
if result:
|
||||
sys.exit(0)
|
||||
else:
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,103 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Quick validation script for skills - minimal version
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import re
|
||||
import yaml
|
||||
from pathlib import Path
|
||||
|
||||
def validate_skill(skill_path):
|
||||
"""Basic validation of a skill"""
|
||||
skill_path = Path(skill_path)
|
||||
|
||||
# Check SKILL.md exists
|
||||
skill_md = skill_path / 'SKILL.md'
|
||||
if not skill_md.exists():
|
||||
return False, "SKILL.md not found"
|
||||
|
||||
# Read and validate frontmatter
|
||||
content = skill_md.read_text()
|
||||
if not content.startswith('---'):
|
||||
return False, "No YAML frontmatter found"
|
||||
|
||||
# Extract frontmatter
|
||||
match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
|
||||
if not match:
|
||||
return False, "Invalid frontmatter format"
|
||||
|
||||
frontmatter_text = match.group(1)
|
||||
|
||||
# Parse YAML frontmatter
|
||||
try:
|
||||
frontmatter = yaml.safe_load(frontmatter_text)
|
||||
if not isinstance(frontmatter, dict):
|
||||
return False, "Frontmatter must be a YAML dictionary"
|
||||
except yaml.YAMLError as e:
|
||||
return False, f"Invalid YAML in frontmatter: {e}"
|
||||
|
||||
# Define allowed properties
|
||||
ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata', 'compatibility'}
|
||||
|
||||
# Check for unexpected properties (excluding nested keys under metadata)
|
||||
unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
|
||||
if unexpected_keys:
|
||||
return False, (
|
||||
f"Unexpected key(s) in SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
|
||||
f"Allowed properties are: {', '.join(sorted(ALLOWED_PROPERTIES))}"
|
||||
)
|
||||
|
||||
# Check required fields
|
||||
if 'name' not in frontmatter:
|
||||
return False, "Missing 'name' in frontmatter"
|
||||
if 'description' not in frontmatter:
|
||||
return False, "Missing 'description' in frontmatter"
|
||||
|
||||
# Extract name for validation
|
||||
name = frontmatter.get('name', '')
|
||||
if not isinstance(name, str):
|
||||
return False, f"Name must be a string, got {type(name).__name__}"
|
||||
name = name.strip()
|
||||
if name:
|
||||
# Check naming convention (kebab-case: lowercase with hyphens)
|
||||
if not re.match(r'^[a-z0-9-]+$', name):
|
||||
return False, f"Name '{name}' should be kebab-case (lowercase letters, digits, and hyphens only)"
|
||||
if name.startswith('-') or name.endswith('-') or '--' in name:
|
||||
return False, f"Name '{name}' cannot start/end with hyphen or contain consecutive hyphens"
|
||||
# Check name length (max 64 characters per spec)
|
||||
if len(name) > 64:
|
||||
return False, f"Name is too long ({len(name)} characters). Maximum is 64 characters."
|
||||
|
||||
# Extract and validate description
|
||||
description = frontmatter.get('description', '')
|
||||
if not isinstance(description, str):
|
||||
return False, f"Description must be a string, got {type(description).__name__}"
|
||||
description = description.strip()
|
||||
if description:
|
||||
# Check for angle brackets
|
||||
if '<' in description or '>' in description:
|
||||
return False, "Description cannot contain angle brackets (< or >)"
|
||||
# Check description length (max 1024 characters per spec)
|
||||
if len(description) > 1024:
|
||||
return False, f"Description is too long ({len(description)} characters). Maximum is 1024 characters."
|
||||
|
||||
# Validate compatibility field if present (optional)
|
||||
compatibility = frontmatter.get('compatibility', '')
|
||||
if compatibility:
|
||||
if not isinstance(compatibility, str):
|
||||
return False, f"Compatibility must be a string, got {type(compatibility).__name__}"
|
||||
if len(compatibility) > 500:
|
||||
return False, f"Compatibility is too long ({len(compatibility)} characters). Maximum is 500 characters."
|
||||
|
||||
return True, "Skill is valid!"
|
||||
|
||||
if __name__ == "__main__":
|
||||
if len(sys.argv) != 2:
|
||||
print("Usage: python quick_validate.py <skill_directory>")
|
||||
sys.exit(1)
|
||||
|
||||
valid, message = validate_skill(sys.argv[1])
|
||||
print(message)
|
||||
sys.exit(0 if valid else 1)
|
||||
@ -1,310 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run trigger evaluation for a skill description.
|
||||
|
||||
Tests whether a skill's description causes Claude to trigger (read the skill)
|
||||
for a set of queries. Outputs results as JSON.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import select
|
||||
import subprocess
|
||||
import sys
|
||||
import time
|
||||
import uuid
|
||||
from concurrent.futures import ProcessPoolExecutor, as_completed
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def find_project_root() -> Path:
|
||||
"""Find the project root by walking up from cwd looking for .claude/.
|
||||
|
||||
Mimics how Claude Code discovers its project root, so the command file
|
||||
we create ends up where claude -p will look for it.
|
||||
"""
|
||||
current = Path.cwd()
|
||||
for parent in [current, *current.parents]:
|
||||
if (parent / ".claude").is_dir():
|
||||
return parent
|
||||
return current
|
||||
|
||||
|
||||
def run_single_query(
|
||||
query: str,
|
||||
skill_name: str,
|
||||
skill_description: str,
|
||||
timeout: int,
|
||||
project_root: str,
|
||||
model: str | None = None,
|
||||
) -> bool:
|
||||
"""Run a single query and return whether the skill was triggered.
|
||||
|
||||
Creates a command file in .claude/commands/ so it appears in Claude's
|
||||
available_skills list, then runs `claude -p` with the raw query.
|
||||
Uses --include-partial-messages to detect triggering early from
|
||||
stream events (content_block_start) rather than waiting for the
|
||||
full assistant message, which only arrives after tool execution.
|
||||
"""
|
||||
unique_id = uuid.uuid4().hex[:8]
|
||||
clean_name = f"{skill_name}-skill-{unique_id}"
|
||||
project_commands_dir = Path(project_root) / ".claude" / "commands"
|
||||
command_file = project_commands_dir / f"{clean_name}.md"
|
||||
|
||||
try:
|
||||
project_commands_dir.mkdir(parents=True, exist_ok=True)
|
||||
# Use YAML block scalar to avoid breaking on quotes in description
|
||||
indented_desc = "\n ".join(skill_description.split("\n"))
|
||||
command_content = (
|
||||
f"---\n"
|
||||
f"description: |\n"
|
||||
f" {indented_desc}\n"
|
||||
f"---\n\n"
|
||||
f"# {skill_name}\n\n"
|
||||
f"This skill handles: {skill_description}\n"
|
||||
)
|
||||
command_file.write_text(command_content)
|
||||
|
||||
cmd = [
|
||||
"claude",
|
||||
"-p", query,
|
||||
"--output-format", "stream-json",
|
||||
"--verbose",
|
||||
"--include-partial-messages",
|
||||
]
|
||||
if model:
|
||||
cmd.extend(["--model", model])
|
||||
|
||||
# Remove CLAUDECODE env var to allow nesting claude -p inside a
|
||||
# Claude Code session. The guard is for interactive terminal conflicts;
|
||||
# programmatic subprocess usage is safe.
|
||||
env = {k: v for k, v in os.environ.items() if k != "CLAUDECODE"}
|
||||
|
||||
process = subprocess.Popen(
|
||||
cmd,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.DEVNULL,
|
||||
cwd=project_root,
|
||||
env=env,
|
||||
)
|
||||
|
||||
triggered = False
|
||||
start_time = time.time()
|
||||
buffer = ""
|
||||
# Track state for stream event detection
|
||||
pending_tool_name = None
|
||||
accumulated_json = ""
|
||||
|
||||
try:
|
||||
while time.time() - start_time < timeout:
|
||||
if process.poll() is not None:
|
||||
remaining = process.stdout.read()
|
||||
if remaining:
|
||||
buffer += remaining.decode("utf-8", errors="replace")
|
||||
break
|
||||
|
||||
ready, _, _ = select.select([process.stdout], [], [], 1.0)
|
||||
if not ready:
|
||||
continue
|
||||
|
||||
chunk = os.read(process.stdout.fileno(), 8192)
|
||||
if not chunk:
|
||||
break
|
||||
buffer += chunk.decode("utf-8", errors="replace")
|
||||
|
||||
while "\n" in buffer:
|
||||
line, buffer = buffer.split("\n", 1)
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
|
||||
try:
|
||||
event = json.loads(line)
|
||||
except json.JSONDecodeError:
|
||||
continue
|
||||
|
||||
# Early detection via stream events
|
||||
if event.get("type") == "stream_event":
|
||||
se = event.get("event", {})
|
||||
se_type = se.get("type", "")
|
||||
|
||||
if se_type == "content_block_start":
|
||||
cb = se.get("content_block", {})
|
||||
if cb.get("type") == "tool_use":
|
||||
tool_name = cb.get("name", "")
|
||||
if tool_name in ("Skill", "Read"):
|
||||
pending_tool_name = tool_name
|
||||
accumulated_json = ""
|
||||
else:
|
||||
return False
|
||||
|
||||
elif se_type == "content_block_delta" and pending_tool_name:
|
||||
delta = se.get("delta", {})
|
||||
if delta.get("type") == "input_json_delta":
|
||||
accumulated_json += delta.get("partial_json", "")
|
||||
if clean_name in accumulated_json:
|
||||
return True
|
||||
|
||||
elif se_type in ("content_block_stop", "message_stop"):
|
||||
if pending_tool_name:
|
||||
return clean_name in accumulated_json
|
||||
if se_type == "message_stop":
|
||||
return False
|
||||
|
||||
# Fallback: full assistant message
|
||||
elif event.get("type") == "assistant":
|
||||
message = event.get("message", {})
|
||||
for content_item in message.get("content", []):
|
||||
if content_item.get("type") != "tool_use":
|
||||
continue
|
||||
tool_name = content_item.get("name", "")
|
||||
tool_input = content_item.get("input", {})
|
||||
if tool_name == "Skill" and clean_name in tool_input.get("skill", ""):
|
||||
triggered = True
|
||||
elif tool_name == "Read" and clean_name in tool_input.get("file_path", ""):
|
||||
triggered = True
|
||||
return triggered
|
||||
|
||||
elif event.get("type") == "result":
|
||||
return triggered
|
||||
finally:
|
||||
# Clean up process on any exit path (return, exception, timeout)
|
||||
if process.poll() is None:
|
||||
process.kill()
|
||||
process.wait()
|
||||
|
||||
return triggered
|
||||
finally:
|
||||
if command_file.exists():
|
||||
command_file.unlink()
|
||||
|
||||
|
||||
def run_eval(
|
||||
eval_set: list[dict],
|
||||
skill_name: str,
|
||||
description: str,
|
||||
num_workers: int,
|
||||
timeout: int,
|
||||
project_root: Path,
|
||||
runs_per_query: int = 1,
|
||||
trigger_threshold: float = 0.5,
|
||||
model: str | None = None,
|
||||
) -> dict:
|
||||
"""Run the full eval set and return results."""
|
||||
results = []
|
||||
|
||||
with ProcessPoolExecutor(max_workers=num_workers) as executor:
|
||||
future_to_info = {}
|
||||
for item in eval_set:
|
||||
for run_idx in range(runs_per_query):
|
||||
future = executor.submit(
|
||||
run_single_query,
|
||||
item["query"],
|
||||
skill_name,
|
||||
description,
|
||||
timeout,
|
||||
str(project_root),
|
||||
model,
|
||||
)
|
||||
future_to_info[future] = (item, run_idx)
|
||||
|
||||
query_triggers: dict[str, list[bool]] = {}
|
||||
query_items: dict[str, dict] = {}
|
||||
for future in as_completed(future_to_info):
|
||||
item, _ = future_to_info[future]
|
||||
query = item["query"]
|
||||
query_items[query] = item
|
||||
if query not in query_triggers:
|
||||
query_triggers[query] = []
|
||||
try:
|
||||
query_triggers[query].append(future.result())
|
||||
except Exception as e:
|
||||
print(f"Warning: query failed: {e}", file=sys.stderr)
|
||||
query_triggers[query].append(False)
|
||||
|
||||
for query, triggers in query_triggers.items():
|
||||
item = query_items[query]
|
||||
trigger_rate = sum(triggers) / len(triggers)
|
||||
should_trigger = item["should_trigger"]
|
||||
if should_trigger:
|
||||
did_pass = trigger_rate >= trigger_threshold
|
||||
else:
|
||||
did_pass = trigger_rate < trigger_threshold
|
||||
results.append({
|
||||
"query": query,
|
||||
"should_trigger": should_trigger,
|
||||
"trigger_rate": trigger_rate,
|
||||
"triggers": sum(triggers),
|
||||
"runs": len(triggers),
|
||||
"pass": did_pass,
|
||||
})
|
||||
|
||||
passed = sum(1 for r in results if r["pass"])
|
||||
total = len(results)
|
||||
|
||||
return {
|
||||
"skill_name": skill_name,
|
||||
"description": description,
|
||||
"results": results,
|
||||
"summary": {
|
||||
"total": total,
|
||||
"passed": passed,
|
||||
"failed": total - passed,
|
||||
},
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Run trigger evaluation for a skill description")
|
||||
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--description", default=None, help="Override description to test")
|
||||
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||
parser.add_argument("--model", default=None, help="Model to use for claude -p (default: user's configured model)")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||
args = parser.parse_args()
|
||||
|
||||
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||
skill_path = Path(args.skill_path)
|
||||
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
name, original_description, content = parse_skill_md(skill_path)
|
||||
description = args.description or original_description
|
||||
project_root = find_project_root()
|
||||
|
||||
if args.verbose:
|
||||
print(f"Evaluating: {description}", file=sys.stderr)
|
||||
|
||||
output = run_eval(
|
||||
eval_set=eval_set,
|
||||
skill_name=name,
|
||||
description=description,
|
||||
num_workers=args.num_workers,
|
||||
timeout=args.timeout,
|
||||
project_root=project_root,
|
||||
runs_per_query=args.runs_per_query,
|
||||
trigger_threshold=args.trigger_threshold,
|
||||
model=args.model,
|
||||
)
|
||||
|
||||
if args.verbose:
|
||||
summary = output["summary"]
|
||||
print(f"Results: {summary['passed']}/{summary['total']} passed", file=sys.stderr)
|
||||
for r in output["results"]:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:70]}", file=sys.stderr)
|
||||
|
||||
print(json.dumps(output, indent=2))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,328 +0,0 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run the eval + improve loop until all pass or max iterations reached.
|
||||
|
||||
Combines run_eval.py and improve_description.py in a loop, tracking history
|
||||
and returning the best description found. Supports train/test split to prevent
|
||||
overfitting.
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import random
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import webbrowser
|
||||
from pathlib import Path
|
||||
|
||||
from scripts.generate_report import generate_html
|
||||
from scripts.improve_description import improve_description
|
||||
from scripts.run_eval import find_project_root, run_eval
|
||||
from scripts.utils import parse_skill_md
|
||||
|
||||
|
||||
def split_eval_set(eval_set: list[dict], holdout: float, seed: int = 42) -> tuple[list[dict], list[dict]]:
|
||||
"""Split eval set into train and test sets, stratified by should_trigger."""
|
||||
random.seed(seed)
|
||||
|
||||
# Separate by should_trigger
|
||||
trigger = [e for e in eval_set if e["should_trigger"]]
|
||||
no_trigger = [e for e in eval_set if not e["should_trigger"]]
|
||||
|
||||
# Shuffle each group
|
||||
random.shuffle(trigger)
|
||||
random.shuffle(no_trigger)
|
||||
|
||||
# Calculate split points
|
||||
n_trigger_test = max(1, int(len(trigger) * holdout))
|
||||
n_no_trigger_test = max(1, int(len(no_trigger) * holdout))
|
||||
|
||||
# Split
|
||||
test_set = trigger[:n_trigger_test] + no_trigger[:n_no_trigger_test]
|
||||
train_set = trigger[n_trigger_test:] + no_trigger[n_no_trigger_test:]
|
||||
|
||||
return train_set, test_set
|
||||
|
||||
|
||||
def run_loop(
|
||||
eval_set: list[dict],
|
||||
skill_path: Path,
|
||||
description_override: str | None,
|
||||
num_workers: int,
|
||||
timeout: int,
|
||||
max_iterations: int,
|
||||
runs_per_query: int,
|
||||
trigger_threshold: float,
|
||||
holdout: float,
|
||||
model: str,
|
||||
verbose: bool,
|
||||
live_report_path: Path | None = None,
|
||||
log_dir: Path | None = None,
|
||||
) -> dict:
|
||||
"""Run the eval + improvement loop."""
|
||||
project_root = find_project_root()
|
||||
name, original_description, content = parse_skill_md(skill_path)
|
||||
current_description = description_override or original_description
|
||||
|
||||
# Split into train/test if holdout > 0
|
||||
if holdout > 0:
|
||||
train_set, test_set = split_eval_set(eval_set, holdout)
|
||||
if verbose:
|
||||
print(f"Split: {len(train_set)} train, {len(test_set)} test (holdout={holdout})", file=sys.stderr)
|
||||
else:
|
||||
train_set = eval_set
|
||||
test_set = []
|
||||
|
||||
history = []
|
||||
exit_reason = "unknown"
|
||||
|
||||
for iteration in range(1, max_iterations + 1):
|
||||
if verbose:
|
||||
print(f"\n{'='*60}", file=sys.stderr)
|
||||
print(f"Iteration {iteration}/{max_iterations}", file=sys.stderr)
|
||||
print(f"Description: {current_description}", file=sys.stderr)
|
||||
print(f"{'='*60}", file=sys.stderr)
|
||||
|
||||
# Evaluate train + test together in one batch for parallelism
|
||||
all_queries = train_set + test_set
|
||||
t0 = time.time()
|
||||
all_results = run_eval(
|
||||
eval_set=all_queries,
|
||||
skill_name=name,
|
||||
description=current_description,
|
||||
num_workers=num_workers,
|
||||
timeout=timeout,
|
||||
project_root=project_root,
|
||||
runs_per_query=runs_per_query,
|
||||
trigger_threshold=trigger_threshold,
|
||||
model=model,
|
||||
)
|
||||
eval_elapsed = time.time() - t0
|
||||
|
||||
# Split results back into train/test by matching queries
|
||||
train_queries_set = {q["query"] for q in train_set}
|
||||
train_result_list = [r for r in all_results["results"] if r["query"] in train_queries_set]
|
||||
test_result_list = [r for r in all_results["results"] if r["query"] not in train_queries_set]
|
||||
|
||||
train_passed = sum(1 for r in train_result_list if r["pass"])
|
||||
train_total = len(train_result_list)
|
||||
train_summary = {"passed": train_passed, "failed": train_total - train_passed, "total": train_total}
|
||||
train_results = {"results": train_result_list, "summary": train_summary}
|
||||
|
||||
if test_set:
|
||||
test_passed = sum(1 for r in test_result_list if r["pass"])
|
||||
test_total = len(test_result_list)
|
||||
test_summary = {"passed": test_passed, "failed": test_total - test_passed, "total": test_total}
|
||||
test_results = {"results": test_result_list, "summary": test_summary}
|
||||
else:
|
||||
test_results = None
|
||||
test_summary = None
|
||||
|
||||
history.append({
|
||||
"iteration": iteration,
|
||||
"description": current_description,
|
||||
"train_passed": train_summary["passed"],
|
||||
"train_failed": train_summary["failed"],
|
||||
"train_total": train_summary["total"],
|
||||
"train_results": train_results["results"],
|
||||
"test_passed": test_summary["passed"] if test_summary else None,
|
||||
"test_failed": test_summary["failed"] if test_summary else None,
|
||||
"test_total": test_summary["total"] if test_summary else None,
|
||||
"test_results": test_results["results"] if test_results else None,
|
||||
# For backward compat with report generator
|
||||
"passed": train_summary["passed"],
|
||||
"failed": train_summary["failed"],
|
||||
"total": train_summary["total"],
|
||||
"results": train_results["results"],
|
||||
})
|
||||
|
||||
# Write live report if path provided
|
||||
if live_report_path:
|
||||
partial_output = {
|
||||
"original_description": original_description,
|
||||
"best_description": current_description,
|
||||
"best_score": "in progress",
|
||||
"iterations_run": len(history),
|
||||
"holdout": holdout,
|
||||
"train_size": len(train_set),
|
||||
"test_size": len(test_set),
|
||||
"history": history,
|
||||
}
|
||||
live_report_path.write_text(generate_html(partial_output, auto_refresh=True, skill_name=name))
|
||||
|
||||
if verbose:
|
||||
def print_eval_stats(label, results, elapsed):
|
||||
pos = [r for r in results if r["should_trigger"]]
|
||||
neg = [r for r in results if not r["should_trigger"]]
|
||||
tp = sum(r["triggers"] for r in pos)
|
||||
pos_runs = sum(r["runs"] for r in pos)
|
||||
fn = pos_runs - tp
|
||||
fp = sum(r["triggers"] for r in neg)
|
||||
neg_runs = sum(r["runs"] for r in neg)
|
||||
tn = neg_runs - fp
|
||||
total = tp + tn + fp + fn
|
||||
precision = tp / (tp + fp) if (tp + fp) > 0 else 1.0
|
||||
recall = tp / (tp + fn) if (tp + fn) > 0 else 1.0
|
||||
accuracy = (tp + tn) / total if total > 0 else 0.0
|
||||
print(f"{label}: {tp+tn}/{total} correct, precision={precision:.0%} recall={recall:.0%} accuracy={accuracy:.0%} ({elapsed:.1f}s)", file=sys.stderr)
|
||||
for r in results:
|
||||
status = "PASS" if r["pass"] else "FAIL"
|
||||
rate_str = f"{r['triggers']}/{r['runs']}"
|
||||
print(f" [{status}] rate={rate_str} expected={r['should_trigger']}: {r['query'][:60]}", file=sys.stderr)
|
||||
|
||||
print_eval_stats("Train", train_results["results"], eval_elapsed)
|
||||
if test_summary:
|
||||
print_eval_stats("Test ", test_results["results"], 0)
|
||||
|
||||
if train_summary["failed"] == 0:
|
||||
exit_reason = f"all_passed (iteration {iteration})"
|
||||
if verbose:
|
||||
print(f"\nAll train queries passed on iteration {iteration}!", file=sys.stderr)
|
||||
break
|
||||
|
||||
if iteration == max_iterations:
|
||||
exit_reason = f"max_iterations ({max_iterations})"
|
||||
if verbose:
|
||||
print(f"\nMax iterations reached ({max_iterations}).", file=sys.stderr)
|
||||
break
|
||||
|
||||
# Improve the description based on train results
|
||||
if verbose:
|
||||
print(f"\nImproving description...", file=sys.stderr)
|
||||
|
||||
t0 = time.time()
|
||||
# Strip test scores from history so improvement model can't see them
|
||||
blinded_history = [
|
||||
{k: v for k, v in h.items() if not k.startswith("test_")}
|
||||
for h in history
|
||||
]
|
||||
new_description = improve_description(
|
||||
skill_name=name,
|
||||
skill_content=content,
|
||||
current_description=current_description,
|
||||
eval_results=train_results,
|
||||
history=blinded_history,
|
||||
model=model,
|
||||
log_dir=log_dir,
|
||||
iteration=iteration,
|
||||
)
|
||||
improve_elapsed = time.time() - t0
|
||||
|
||||
if verbose:
|
||||
print(f"Proposed ({improve_elapsed:.1f}s): {new_description}", file=sys.stderr)
|
||||
|
||||
current_description = new_description
|
||||
|
||||
# Find the best iteration by TEST score (or train if no test set)
|
||||
if test_set:
|
||||
best = max(history, key=lambda h: h["test_passed"] or 0)
|
||||
best_score = f"{best['test_passed']}/{best['test_total']}"
|
||||
else:
|
||||
best = max(history, key=lambda h: h["train_passed"])
|
||||
best_score = f"{best['train_passed']}/{best['train_total']}"
|
||||
|
||||
if verbose:
|
||||
print(f"\nExit reason: {exit_reason}", file=sys.stderr)
|
||||
print(f"Best score: {best_score} (iteration {best['iteration']})", file=sys.stderr)
|
||||
|
||||
return {
|
||||
"exit_reason": exit_reason,
|
||||
"original_description": original_description,
|
||||
"best_description": best["description"],
|
||||
"best_score": best_score,
|
||||
"best_train_score": f"{best['train_passed']}/{best['train_total']}",
|
||||
"best_test_score": f"{best['test_passed']}/{best['test_total']}" if test_set else None,
|
||||
"final_description": current_description,
|
||||
"iterations_run": len(history),
|
||||
"holdout": holdout,
|
||||
"train_size": len(train_set),
|
||||
"test_size": len(test_set),
|
||||
"history": history,
|
||||
}
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(description="Run eval + improve loop")
|
||||
parser.add_argument("--eval-set", required=True, help="Path to eval set JSON file")
|
||||
parser.add_argument("--skill-path", required=True, help="Path to skill directory")
|
||||
parser.add_argument("--description", default=None, help="Override starting description")
|
||||
parser.add_argument("--num-workers", type=int, default=10, help="Number of parallel workers")
|
||||
parser.add_argument("--timeout", type=int, default=30, help="Timeout per query in seconds")
|
||||
parser.add_argument("--max-iterations", type=int, default=5, help="Max improvement iterations")
|
||||
parser.add_argument("--runs-per-query", type=int, default=3, help="Number of runs per query")
|
||||
parser.add_argument("--trigger-threshold", type=float, default=0.5, help="Trigger rate threshold")
|
||||
parser.add_argument("--holdout", type=float, default=0.4, help="Fraction of eval set to hold out for testing (0 to disable)")
|
||||
parser.add_argument("--model", required=True, help="Model for improvement")
|
||||
parser.add_argument("--verbose", action="store_true", help="Print progress to stderr")
|
||||
parser.add_argument("--report", default="auto", help="Generate HTML report at this path (default: 'auto' for temp file, 'none' to disable)")
|
||||
parser.add_argument("--results-dir", default=None, help="Save all outputs (results.json, report.html, log.txt) to a timestamped subdirectory here")
|
||||
args = parser.parse_args()
|
||||
|
||||
eval_set = json.loads(Path(args.eval_set).read_text())
|
||||
skill_path = Path(args.skill_path)
|
||||
|
||||
if not (skill_path / "SKILL.md").exists():
|
||||
print(f"Error: No SKILL.md found at {skill_path}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
name, _, _ = parse_skill_md(skill_path)
|
||||
|
||||
# Set up live report path
|
||||
if args.report != "none":
|
||||
if args.report == "auto":
|
||||
timestamp = time.strftime("%Y%m%d_%H%M%S")
|
||||
live_report_path = Path(tempfile.gettempdir()) / f"skill_description_report_{skill_path.name}_{timestamp}.html"
|
||||
else:
|
||||
live_report_path = Path(args.report)
|
||||
# Open the report immediately so the user can watch
|
||||
live_report_path.write_text("<html><body><h1>Starting optimization loop...</h1><meta http-equiv='refresh' content='5'></body></html>")
|
||||
webbrowser.open(str(live_report_path))
|
||||
else:
|
||||
live_report_path = None
|
||||
|
||||
# Determine output directory (create before run_loop so logs can be written)
|
||||
if args.results_dir:
|
||||
timestamp = time.strftime("%Y-%m-%d_%H%M%S")
|
||||
results_dir = Path(args.results_dir) / timestamp
|
||||
results_dir.mkdir(parents=True, exist_ok=True)
|
||||
else:
|
||||
results_dir = None
|
||||
|
||||
log_dir = results_dir / "logs" if results_dir else None
|
||||
|
||||
output = run_loop(
|
||||
eval_set=eval_set,
|
||||
skill_path=skill_path,
|
||||
description_override=args.description,
|
||||
num_workers=args.num_workers,
|
||||
timeout=args.timeout,
|
||||
max_iterations=args.max_iterations,
|
||||
runs_per_query=args.runs_per_query,
|
||||
trigger_threshold=args.trigger_threshold,
|
||||
holdout=args.holdout,
|
||||
model=args.model,
|
||||
verbose=args.verbose,
|
||||
live_report_path=live_report_path,
|
||||
log_dir=log_dir,
|
||||
)
|
||||
|
||||
# Save JSON output
|
||||
json_output = json.dumps(output, indent=2)
|
||||
print(json_output)
|
||||
if results_dir:
|
||||
(results_dir / "results.json").write_text(json_output)
|
||||
|
||||
# Write final HTML report (without auto-refresh)
|
||||
if live_report_path:
|
||||
live_report_path.write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||
print(f"\nReport: {live_report_path}", file=sys.stderr)
|
||||
|
||||
if results_dir and live_report_path:
|
||||
(results_dir / "report.html").write_text(generate_html(output, auto_refresh=False, skill_name=name))
|
||||
|
||||
if results_dir:
|
||||
print(f"Results saved to: {results_dir}", file=sys.stderr)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@ -1,47 +0,0 @@
|
||||
"""Shared utilities for skill-creator scripts."""
|
||||
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
|
||||
def parse_skill_md(skill_path: Path) -> tuple[str, str, str]:
|
||||
"""Parse a SKILL.md file, returning (name, description, full_content)."""
|
||||
content = (skill_path / "SKILL.md").read_text()
|
||||
lines = content.split("\n")
|
||||
|
||||
if lines[0].strip() != "---":
|
||||
raise ValueError("SKILL.md missing frontmatter (no opening ---)")
|
||||
|
||||
end_idx = None
|
||||
for i, line in enumerate(lines[1:], start=1):
|
||||
if line.strip() == "---":
|
||||
end_idx = i
|
||||
break
|
||||
|
||||
if end_idx is None:
|
||||
raise ValueError("SKILL.md missing frontmatter (no closing ---)")
|
||||
|
||||
name = ""
|
||||
description = ""
|
||||
frontmatter_lines = lines[1:end_idx]
|
||||
i = 0
|
||||
while i < len(frontmatter_lines):
|
||||
line = frontmatter_lines[i]
|
||||
if line.startswith("name:"):
|
||||
name = line[len("name:"):].strip().strip('"').strip("'")
|
||||
elif line.startswith("description:"):
|
||||
value = line[len("description:"):].strip()
|
||||
# Handle YAML multiline indicators (>, |, >-, |-)
|
||||
if value in (">", "|", ">-", "|-"):
|
||||
continuation_lines: list[str] = []
|
||||
i += 1
|
||||
while i < len(frontmatter_lines) and (frontmatter_lines[i].startswith(" ") or frontmatter_lines[i].startswith("\t")):
|
||||
continuation_lines.append(frontmatter_lines[i].strip())
|
||||
i += 1
|
||||
description = " ".join(continuation_lines)
|
||||
continue
|
||||
else:
|
||||
description = value.strip('"').strip("'")
|
||||
i += 1
|
||||
|
||||
return name, description, content
|
||||
@ -1,285 +0,0 @@
|
||||
---
|
||||
name: zeroclaw
|
||||
description: "Help users operate and interact with their ZeroClaw agent instance — through both the CLI (`zeroclaw` commands) and the REST/WebSocket gateway API. Use this skill whenever the user wants to: send messages to ZeroClaw, manage memory or cron jobs, check system status, configure channels or providers, hit the gateway API, troubleshoot their ZeroClaw setup, build from source, or do anything involving the `zeroclaw` binary or its HTTP endpoints. Trigger this even if the user just says things like 'check my agent status', 'schedule a reminder', 'store this in memory', 'list my cron jobs', 'send a message to my bot', 'set up Telegram', 'build zeroclaw', or 'my bot is broken' — these are all ZeroClaw operations."
|
||||
---
|
||||
|
||||
# ZeroClaw Skill
|
||||
|
||||
You are helping a user operate their ZeroClaw agent instance. ZeroClaw is an autonomous agent runtime with a CLI and an HTTP/WebSocket gateway.
|
||||
|
||||
Your job is to understand what the user wants to accomplish and then **execute it** — run the command, make the API call, report the result. Do not just show commands for the user to copy-paste. Actually run them via the Bash tool and tell the user what happened. The only exception is destructive operations (clearing all memory, estop kill-all) where you should confirm first.
|
||||
|
||||
## Adaptive Expertise
|
||||
|
||||
Pay attention to how the user talks. Someone who says "can you hit the webhook endpoint with a POST" is telling you they know what they're doing — be concise, skip explanations, just execute. Someone who says "how do I make my bot remember things" needs more context about what's happening under the hood.
|
||||
|
||||
Signals of technical comfort: mentions specific endpoints, HTTP methods, JSON fields, talks about tokens/auth, uses CLI flags fluently, references config files directly.
|
||||
|
||||
Signals of less familiarity: asks "what does X do", uses casual language about the bot/agent, describes goals rather than mechanisms ("I want it to check something every morning").
|
||||
|
||||
Default to a middle ground — brief explanation of what you're about to do, then do it. Dial up or down from there based on cues.
|
||||
|
||||
## Discovery — Before You Act
|
||||
|
||||
Before running any ZeroClaw operation, make sure you know where things are:
|
||||
|
||||
1. **Find the binary.** Search in this order:
|
||||
- `which zeroclaw` (PATH)
|
||||
- The current project's build output: `./target/release/zeroclaw` or `./target/debug/zeroclaw` — this is the right choice when the user is working inside the ZeroClaw source tree and may have local changes
|
||||
- Common install locations: `~/.cargo/bin/zeroclaw`, `~/Downloads/zeroclaw-bin/zeroclaw`
|
||||
|
||||
If no binary is found anywhere, offer to build from source (see "Building from Source" below). If the user is a developer working on ZeroClaw itself, they'll likely want the local build — watch for cues like them editing source files, mentioning PRs, or being in the project directory.
|
||||
|
||||
2. **Check if the gateway is running** (only needed for REST/WebSocket operations). A quick `curl -sf http://127.0.0.1:42617/health` tells you. If it's not running and the user wants REST access, let them know and offer to start it (`zeroclaw gateway` or `zeroclaw daemon`).
|
||||
|
||||
3. **Check auth status.** If the gateway requires pairing (`require_pairing = true` is the default), REST calls need a bearer token. Run `zeroclaw status` to see the current state, or check `~/.zeroclaw/config.toml` for a stored token under `[gateway]`.
|
||||
|
||||
Cache these findings for the conversation — don't re-discover every time.
|
||||
|
||||
## Important: REPL Limitation
|
||||
|
||||
`zeroclaw agent` (interactive REPL) requires interactive stdin, which doesn't work through the Bash tool. When the user wants to chat with their agent, use single-message mode instead:
|
||||
|
||||
```bash
|
||||
zeroclaw agent -m "the message"
|
||||
```
|
||||
|
||||
Each `-m` invocation is independent (no conversation history between calls). If the user needs multi-turn conversation, let them know they can run `zeroclaw agent` directly in their terminal, or use the WebSocket endpoint for programmatic streaming.
|
||||
|
||||
## First-Time Setup
|
||||
|
||||
If the user hasn't set up ZeroClaw yet (no `~/.zeroclaw/config.toml` exists), guide them through onboarding:
|
||||
|
||||
```bash
|
||||
zeroclaw onboard # Quick mode — defaults to OpenRouter
|
||||
zeroclaw onboard --provider anthropic # Use Anthropic directly
|
||||
zeroclaw onboard # Guided wizard (default)
|
||||
```
|
||||
|
||||
After onboarding, verify everything works:
|
||||
```bash
|
||||
zeroclaw status
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
If they already have a config but something is broken, `zeroclaw onboard --channels-only` repairs just the channel configuration without overwriting everything else.
|
||||
|
||||
## Building from Source
|
||||
|
||||
If the user wants to build ZeroClaw (or no binary is installed):
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
```
|
||||
|
||||
This produces `target/release/zeroclaw`. For faster iteration during development, `cargo build` (debug mode) is quicker but produces a slower binary at `target/debug/zeroclaw`.
|
||||
|
||||
You can also run directly without a separate build step:
|
||||
```bash
|
||||
cargo run --release -- <subcommand> [args]
|
||||
```
|
||||
|
||||
Before building, `cargo check` gives a quick compile validation without the full build.
|
||||
|
||||
## Choosing CLI vs REST
|
||||
|
||||
Both surfaces can do most things. Rules of thumb:
|
||||
|
||||
- **CLI is simpler** for one-off operations from the terminal. It handles auth internally and formats output nicely. Prefer CLI when the user is working locally.
|
||||
- **REST is needed** when the user is building an integration, scripting from another language, or accessing a remote ZeroClaw instance. Also needed for streaming (WebSocket, SSE).
|
||||
- If unclear, **default to CLI** — it's less setup.
|
||||
|
||||
## Core Operations
|
||||
|
||||
### Sending Messages
|
||||
|
||||
**CLI:** `zeroclaw agent -m "your message here"` — remember, always use `-m` mode, not bare `zeroclaw agent`.
|
||||
|
||||
**REST:**
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:42617/webhook \
|
||||
-H "Authorization: Bearer <token>" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"message": "your message here"}'
|
||||
```
|
||||
Response: `{"response": "...", "model": "..."}`
|
||||
|
||||
**WebSocket** (for streaming): connect to `ws://127.0.0.1:42617/ws/chat?token=<token>`, send `{"type": "message", "content": "..."}`, receive `{"type": "done", "full_response": "..."}`.
|
||||
|
||||
### System Status
|
||||
|
||||
Run `zeroclaw status` to see provider, model, uptime, channels, memory backend. For deeper diagnostics: `zeroclaw doctor`.
|
||||
|
||||
**REST:** `GET /api/status` (same info as JSON), `GET /health` (no auth, quick ok/not-ok).
|
||||
|
||||
### Memory
|
||||
|
||||
The CLI can list, get, and clear memories but **cannot store** them directly. To store a memory:
|
||||
- Via agent: `zeroclaw agent -m "remember that my favorite color is blue"`
|
||||
- Via REST: `POST /api/memory` with `{"key": "...", "content": "...", "category": "core"}`
|
||||
|
||||
**CLI (read/delete):**
|
||||
- `zeroclaw memory list` — list all entries
|
||||
- `zeroclaw memory list --category core --limit 10` — filtered
|
||||
- `zeroclaw memory get "key-name"` — get specific entry
|
||||
- `zeroclaw memory stats` — usage statistics
|
||||
- `zeroclaw memory clear --key "prefix" --yes` — delete entries (confirm with user first)
|
||||
|
||||
**REST (full CRUD):**
|
||||
- `GET /api/memory` — list all (optional: `?query=search+text&category=core`)
|
||||
- `POST /api/memory` — store: `{"key": "...", "content": "...", "category": "core"}`
|
||||
- `DELETE /api/memory/{key}` — delete entry
|
||||
|
||||
Categories: `core`, `daily`, `conversation`, or any custom string.
|
||||
|
||||
### Cron / Scheduling
|
||||
|
||||
**CLI:**
|
||||
- `zeroclaw cron list` — show all jobs
|
||||
- `zeroclaw cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York` — recurring
|
||||
- `zeroclaw cron add-at '2026-03-11T10:00:00Z' 'Remind me'` — one-time at specific time
|
||||
- `zeroclaw cron add-every 3600000 'Check health'` — interval in ms
|
||||
- `zeroclaw cron once 30m 'Follow up'` — delay from now
|
||||
- `zeroclaw cron pause <id>` / `zeroclaw cron resume <id>` / `zeroclaw cron remove <id>`
|
||||
|
||||
**REST:**
|
||||
- `GET /api/cron` — list jobs
|
||||
- `POST /api/cron` — add: `{"name": "...", "schedule": "0 9 * * *", "command": "..."}`
|
||||
- `DELETE /api/cron/{id}` — remove job
|
||||
|
||||
### Tools
|
||||
|
||||
Tools are used automatically by the agent during conversations (shell, file ops, memory, browser, HTTP, web search, git, etc. — 30+ tools gated by security policy).
|
||||
|
||||
To see what's available: `GET /api/tools` (REST) lists all registered tools with descriptions and parameter schemas.
|
||||
|
||||
### Configuration
|
||||
|
||||
Edit `~/.zeroclaw/config.toml` directly, or re-run `zeroclaw onboard` to reconfigure.
|
||||
|
||||
**REST:**
|
||||
- `GET /api/config` — get current config (secrets masked as `***MASKED***`)
|
||||
- `PUT /api/config` — update config (send raw TOML as body, 1MB limit)
|
||||
|
||||
### Providers & Models
|
||||
|
||||
- `zeroclaw providers` — list all supported providers
|
||||
- `zeroclaw models list` — cached model catalog
|
||||
- `zeroclaw models refresh --all` — refresh from providers
|
||||
- `zeroclaw models set anthropic/claude-sonnet-4-6` — set default model
|
||||
|
||||
Override per-message: `zeroclaw agent -p anthropic --model claude-sonnet-4-6 -m "hello"`
|
||||
|
||||
### Real-Time Events (SSE)
|
||||
|
||||
REST only — useful for building dashboards or monitoring:
|
||||
```bash
|
||||
curl -N -H "Authorization: Bearer <token>" http://127.0.0.1:42617/api/events
|
||||
```
|
||||
Streams JSON events: `llm_request`, `tool_call_start`, `tool_call`, `agent_start`, `agent_end`, `error`.
|
||||
|
||||
### Cost Tracking
|
||||
|
||||
`GET /api/cost` — returns session/daily/monthly costs, token counts, per-model breakdown.
|
||||
|
||||
### Emergency Stop
|
||||
|
||||
Confirm with the user before running any estop command — these are disruptive.
|
||||
|
||||
- `zeroclaw estop --level kill-all` — stop everything
|
||||
- `zeroclaw estop --level network-kill` — block all network
|
||||
- `zeroclaw estop --level tool-freeze --tool shell` — freeze specific tool
|
||||
- `zeroclaw estop status` — check current estop state
|
||||
- `zeroclaw estop resume --network` — resume
|
||||
|
||||
### Gateway Lifecycle
|
||||
|
||||
- `zeroclaw gateway` — start HTTP gateway (foreground)
|
||||
- `zeroclaw gateway -p 8080 --host 127.0.0.1` — custom bind
|
||||
- `zeroclaw daemon` — start gateway + channels + scheduler + heartbeat
|
||||
- `zeroclaw service install/start/stop/status/uninstall` — OS service management
|
||||
|
||||
### Channels
|
||||
|
||||
ZeroClaw supports 21 messaging channels. To add one, you need to edit `~/.zeroclaw/config.toml`. For example, to set up Telegram:
|
||||
|
||||
```toml
|
||||
[channels]
|
||||
telegram = true
|
||||
|
||||
[channels_config.telegram]
|
||||
bot_token = "your-bot-token-from-botfather"
|
||||
allowed_users = [123456789]
|
||||
```
|
||||
|
||||
Then restart the daemon. Check channel health with `zeroclaw channels doctor`.
|
||||
|
||||
For the full list of channels and their config fields, read `references/cli-reference.md` (Channels section).
|
||||
|
||||
### Pairing (Authentication Setup)
|
||||
|
||||
When `require_pairing = true` (default), REST clients need a bearer token:
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:42617/pair -H "X-Pairing-Code: <code>"
|
||||
```
|
||||
Response includes `{"token": "..."}` — save this for subsequent requests.
|
||||
|
||||
## Common Workflows
|
||||
|
||||
Here are multi-step sequences you're likely to need:
|
||||
|
||||
**"Is my agent healthy?"**
|
||||
1. Run `zeroclaw status` — check provider, model, channels
|
||||
2. Run `zeroclaw doctor` — check connectivity, diagnose issues
|
||||
3. If gateway needed: `curl -sf http://127.0.0.1:42617/health`
|
||||
|
||||
**"Set up a new channel"**
|
||||
1. Read the current config: `cat ~/.zeroclaw/config.toml`
|
||||
2. Add the channel config (edit the TOML)
|
||||
3. Restart: `zeroclaw service restart` (or restart daemon manually)
|
||||
4. Verify: `zeroclaw channels doctor`
|
||||
|
||||
**"Switch to a different model"**
|
||||
1. Check available: `zeroclaw models list`
|
||||
2. Set it: `zeroclaw models set <provider/model>`
|
||||
3. Verify: `zeroclaw status`
|
||||
4. Test: `zeroclaw agent -m "hello, what model are you?"`
|
||||
|
||||
## Gateway Defaults
|
||||
|
||||
- **Port:** 42617
|
||||
- **Host:** 127.0.0.1
|
||||
- **Auth:** Pairing required (bearer token)
|
||||
- **Rate limits:** 60 webhook requests/min, 10 pairing attempts/min
|
||||
- **Body limit:** 64KB (1MB for config updates)
|
||||
- **Timeout:** 30 seconds
|
||||
- **Idempotency:** Optional `X-Idempotency-Key` header on `/webhook` (300s TTL)
|
||||
- **Config location:** `~/.zeroclaw/config.toml`
|
||||
|
||||
## Reference Files
|
||||
|
||||
For the complete API specification with every endpoint, field, and edge case, read `references/rest-api.md`.
|
||||
|
||||
For the full CLI command tree with all flags and options, read `references/cli-reference.md`.
|
||||
|
||||
Only load these when you need precise details beyond what's in this file — for most operations, the quick references above are sufficient.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"zeroclaw: command not found"** — Binary not in PATH. Check `./target/release/zeroclaw`, `~/.cargo/bin/zeroclaw`, or build from source with `cargo build --release`.
|
||||
|
||||
**"Connection refused" on REST calls** — Gateway isn't running. Start it with `zeroclaw gateway` or `zeroclaw daemon`.
|
||||
|
||||
**"Unauthorized" (401/403)** — Bearer token is missing or invalid. Re-pair via `POST /pair` with the pairing code, or check `~/.zeroclaw/config.toml` for the stored token.
|
||||
|
||||
**"LLM request failed" (500)** — Provider issue. Run `zeroclaw doctor` to check connectivity. Common causes: expired API key, provider outage, rate limiting on the provider side.
|
||||
|
||||
**"Too many requests" (429)** — You're hitting ZeroClaw's rate limit. Back off — the response includes `retry_after` with the number of seconds to wait.
|
||||
|
||||
**Agent not using tools / acting limited** — Check autonomy settings in config.toml under `[autonomy]`. `level = "read_only"` disables most tools. Try `level = "supervised"` or `level = "full"`.
|
||||
|
||||
**Memory not persisting** — Check `[memory]` config. If `backend = "none"`, nothing is stored. Switch to `"sqlite"` or `"markdown"`. Also verify `auto_save = true`.
|
||||
|
||||
**Channel not responding** — Run `zeroclaw channels doctor` for the specific channel. Common issues: expired bot token, wrong allowed_users list, channel not enabled in `[channels]`.
|
||||
|
||||
Report errors to the user with context appropriate to their expertise level. For beginners, explain what went wrong and suggest the fix. For experts, just show the error and the fix.
|
||||
@ -1,23 +0,0 @@
|
||||
{
|
||||
"skill_name": "zeroclaw",
|
||||
"evals": [
|
||||
{
|
||||
"id": 0,
|
||||
"prompt": "how do i make my bot remember my name",
|
||||
"expected_output": "Executes a zeroclaw command to store a memory, explains what happened in beginner-friendly language",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 1,
|
||||
"prompt": "I want to schedule a daily health check on my ZeroClaw instance every morning at 9am ET",
|
||||
"expected_output": "Executes zeroclaw cron add with correct cron expression and timezone flag",
|
||||
"files": []
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"prompt": "Set up a Python script that monitors my ZeroClaw agent's activity via SSE and logs tool calls to a file",
|
||||
"expected_output": "Writes a Python script that connects to /api/events SSE endpoint with auth, filters for tool_call events, and logs to a file",
|
||||
"files": []
|
||||
}
|
||||
]
|
||||
}
|
||||
@ -1,277 +0,0 @@
|
||||
# ZeroClaw CLI Reference
|
||||
|
||||
Complete command reference for the `zeroclaw` binary.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Agent](#agent)
|
||||
2. [Onboarding](#onboarding)
|
||||
3. [Status & Diagnostics](#status--diagnostics)
|
||||
4. [Memory](#memory)
|
||||
5. [Cron](#cron)
|
||||
6. [Providers & Models](#providers--models)
|
||||
7. [Gateway & Daemon](#gateway--daemon)
|
||||
8. [Service Management](#service-management)
|
||||
9. [Channels](#channels)
|
||||
10. [Security & Emergency Stop](#security--emergency-stop)
|
||||
11. [Hardware Peripherals](#hardware-peripherals)
|
||||
12. [Skills](#skills)
|
||||
13. [Shell Completions](#shell-completions)
|
||||
|
||||
---
|
||||
|
||||
## Agent
|
||||
|
||||
Interactive chat or single-message mode.
|
||||
|
||||
```bash
|
||||
zeroclaw agent # Interactive REPL
|
||||
zeroclaw agent -m "Summarize today's logs" # Single message
|
||||
zeroclaw agent -p anthropic --model claude-sonnet-4-6 # Override provider/model
|
||||
zeroclaw agent -t 0.3 # Set temperature
|
||||
zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0 # Attach hardware
|
||||
```
|
||||
|
||||
**Key flags:**
|
||||
- `-m <message>` — single message mode (no REPL)
|
||||
- `-p <provider>` — override provider (openrouter, anthropic, openai, ollama)
|
||||
- `--model <model>` — override model
|
||||
- `-t <float>` — temperature (0.0–2.0)
|
||||
- `--peripheral <name>:<port>` — attach hardware peripheral
|
||||
|
||||
The agent has access to 30+ tools gated by security policy: shell, file_read, file_write, file_edit, glob_search, content_search, memory_store, memory_recall, memory_forget, browser, http_request, web_fetch, web_search, cron, delegate, git, and more. Max tool iterations defaults to 10.
|
||||
|
||||
---
|
||||
|
||||
## Onboarding
|
||||
|
||||
First-time setup or reconfiguration.
|
||||
|
||||
```bash
|
||||
zeroclaw onboard # Quick mode (default: openrouter)
|
||||
zeroclaw onboard --provider anthropic # Quick mode with specific provider
|
||||
zeroclaw onboard # Guided wizard (default)
|
||||
zeroclaw onboard --memory sqlite # Set memory backend
|
||||
zeroclaw onboard --force # Overwrite existing config
|
||||
zeroclaw onboard --channels-only # Repair channels only
|
||||
```
|
||||
|
||||
**Key flags:**
|
||||
- `--provider <name>` — openrouter (default), anthropic, openai, ollama
|
||||
- `--model <model>` — default model
|
||||
- `--memory <backend>` — sqlite, markdown, lucid, none
|
||||
- `--force` — overwrite existing config.toml
|
||||
- `--channels-only` — only repair channel configuration
|
||||
- `--reinit` — start fresh (backs up existing config)
|
||||
|
||||
Creates `~/.zeroclaw/config.toml` with `0600` permissions.
|
||||
|
||||
---
|
||||
|
||||
## Status & Diagnostics
|
||||
|
||||
```bash
|
||||
zeroclaw status # System overview
|
||||
zeroclaw doctor # Run all diagnostic checks
|
||||
zeroclaw doctor models # Probe model connectivity
|
||||
zeroclaw doctor traces # Query execution traces
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory
|
||||
|
||||
```bash
|
||||
zeroclaw memory list # List all entries
|
||||
zeroclaw memory list --category core --limit 10 # Filtered list
|
||||
zeroclaw memory get "some-key" # Get specific entry
|
||||
zeroclaw memory stats # Usage statistics
|
||||
zeroclaw memory clear --key "prefix" --yes # Delete entries (requires --yes)
|
||||
```
|
||||
|
||||
**Key flags:**
|
||||
- `--category <name>` — filter by category (core, daily, conversation, custom)
|
||||
- `--limit <n>` — limit results
|
||||
- `--key <prefix>` — key prefix for clear operations
|
||||
- `--yes` — skip confirmation (required for clear)
|
||||
|
||||
---
|
||||
|
||||
## Cron
|
||||
|
||||
```bash
|
||||
zeroclaw cron list # List all jobs
|
||||
zeroclaw cron add '0 9 * * 1-5' 'Good morning' --tz America/New_York # Recurring (cron expr)
|
||||
zeroclaw cron add-at '2026-03-11T10:00:00Z' 'Remind me about meeting' # One-time at specific time
|
||||
zeroclaw cron add-every 3600000 'Check server health' # Interval in milliseconds
|
||||
zeroclaw cron once 30m 'Follow up on that task' # Delay from now
|
||||
zeroclaw cron pause <id> # Pause job
|
||||
zeroclaw cron resume <id> # Resume job
|
||||
zeroclaw cron remove <id> # Delete job
|
||||
```
|
||||
|
||||
**Subcommands:**
|
||||
- `add <cron-expr> <command>` — standard cron expression (5-field)
|
||||
- `add-at <iso-datetime> <command>` — fire once at exact time
|
||||
- `add-every <ms> <command>` — repeating interval
|
||||
- `once <duration> <command>` — delay from now (e.g., `30m`, `2h`, `1d`)
|
||||
|
||||
---
|
||||
|
||||
## Providers & Models
|
||||
|
||||
```bash
|
||||
zeroclaw providers # List all 40+ supported providers
|
||||
zeroclaw models list # Show cached model catalog
|
||||
zeroclaw models refresh --all # Refresh catalogs from all providers
|
||||
zeroclaw models set anthropic/claude-sonnet-4-6 # Set default model
|
||||
zeroclaw models status # Current model info
|
||||
```
|
||||
|
||||
Model routing in config.toml:
|
||||
```toml
|
||||
[[model_routes]]
|
||||
hint = "reasoning"
|
||||
provider = "openrouter"
|
||||
model = "anthropic/claude-sonnet-4-6"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Gateway & Daemon
|
||||
|
||||
```bash
|
||||
zeroclaw gateway # Start HTTP gateway (foreground)
|
||||
zeroclaw gateway -p 8080 --host 127.0.0.1 # Custom port/host
|
||||
|
||||
zeroclaw daemon # Gateway + channels + scheduler + heartbeat
|
||||
zeroclaw daemon -p 8080 --host 0.0.0.0 # Custom bind
|
||||
```
|
||||
|
||||
**Gateway defaults:**
|
||||
- Port: 42617
|
||||
- Host: 127.0.0.1
|
||||
- Pairing required: true
|
||||
- Public bind allowed: false
|
||||
|
||||
---
|
||||
|
||||
## Service Management
|
||||
|
||||
OS service lifecycle (systemd on Linux, launchd on macOS).
|
||||
|
||||
```bash
|
||||
zeroclaw service install # Install as system service
|
||||
zeroclaw service start # Start the service
|
||||
zeroclaw service status # Check service status
|
||||
zeroclaw service stop # Stop the service
|
||||
zeroclaw service restart # Restart the service
|
||||
zeroclaw service uninstall # Remove the service
|
||||
```
|
||||
|
||||
**Logs:**
|
||||
- macOS: `~/.zeroclaw/logs/daemon.stdout.log`
|
||||
- Linux: `journalctl -u zeroclaw`
|
||||
|
||||
---
|
||||
|
||||
## Channels
|
||||
|
||||
Channels are configured in `config.toml` under `[channels]` and `[channels_config.*]`.
|
||||
|
||||
```bash
|
||||
zeroclaw channels list # List configured channels
|
||||
zeroclaw channels doctor # Check channel health
|
||||
```
|
||||
|
||||
Supported channels (21 total): Telegram, Discord, Slack, WhatsApp (Meta), WATI, Linq (iMessage/RCS/SMS), Email (IMAP/SMTP), IRC, Matrix, Nostr, Signal, Nextcloud Talk, and more.
|
||||
|
||||
Channel config example (Telegram):
|
||||
```toml
|
||||
[channels]
|
||||
telegram = true
|
||||
|
||||
[channels_config.telegram]
|
||||
bot_token = "..."
|
||||
allowed_users = [123456789]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security & Emergency Stop
|
||||
|
||||
```bash
|
||||
zeroclaw estop --level kill-all # Stop everything
|
||||
zeroclaw estop --level network-kill # Block all network access
|
||||
zeroclaw estop --level domain-block --domain "*.example.com" # Block specific domains
|
||||
zeroclaw estop --level tool-freeze --tool shell # Freeze specific tool
|
||||
zeroclaw estop status # Check estop state
|
||||
zeroclaw estop resume --network # Resume (may require OTP)
|
||||
```
|
||||
|
||||
**Estop levels:**
|
||||
- `kill-all` — nuclear option, stops all agent activity
|
||||
- `network-kill` — blocks all outbound network
|
||||
- `domain-block` — blocks specific domain patterns
|
||||
- `tool-freeze` — freezes individual tools
|
||||
|
||||
Autonomy config in config.toml:
|
||||
```toml
|
||||
[autonomy]
|
||||
level = "supervised" # read_only | supervised | full
|
||||
workspace_only = true
|
||||
allowed_commands = ["git", "cargo", "python"]
|
||||
forbidden_paths = ["/etc", "/root", "~/.ssh"]
|
||||
max_actions_per_hour = 20
|
||||
max_cost_per_day_cents = 500
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Hardware Peripherals
|
||||
|
||||
```bash
|
||||
zeroclaw hardware discover # Find USB devices
|
||||
zeroclaw hardware introspect /dev/ttyACM0 # Probe device capabilities
|
||||
zeroclaw peripheral list # List configured peripherals
|
||||
zeroclaw peripheral add nucleo-f401re /dev/ttyACM0 # Add peripheral
|
||||
zeroclaw peripheral flash-nucleo # Flash STM32 firmware
|
||||
zeroclaw peripheral flash --port /dev/cu.usbmodem101 # Flash Arduino firmware
|
||||
```
|
||||
|
||||
**Supported boards:** STM32 Nucleo-F401RE, Arduino Uno R4, Raspberry Pi GPIO, ESP32.
|
||||
|
||||
Attach to agent session: `zeroclaw agent --peripheral nucleo-f401re:/dev/ttyACM0`
|
||||
|
||||
---
|
||||
|
||||
## Skills
|
||||
|
||||
```bash
|
||||
zeroclaw skills list # List installed skills
|
||||
zeroclaw skills install <path-or-url> # Install a skill
|
||||
zeroclaw skills audit # Audit installed skills
|
||||
zeroclaw skills remove <name> # Remove a skill
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shell Completions
|
||||
|
||||
```bash
|
||||
zeroclaw completions zsh # Generate Zsh completions
|
||||
zeroclaw completions bash # Generate Bash completions
|
||||
zeroclaw completions fish # Generate Fish completions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Config File
|
||||
|
||||
Default location: `~/.zeroclaw/config.toml`
|
||||
|
||||
Config resolution order (first match wins):
|
||||
1. `ZEROCLAW_CONFIG_DIR` environment variable
|
||||
2. `ZEROCLAW_WORKSPACE` environment variable
|
||||
3. `~/.zeroclaw/active_workspace.toml` marker file
|
||||
4. `~/.zeroclaw/config.toml` (default)
|
||||
@ -1,505 +0,0 @@
|
||||
# ZeroClaw REST API Reference
|
||||
|
||||
Complete endpoint reference for the ZeroClaw gateway HTTP API.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Authentication](#authentication)
|
||||
2. [Public Endpoints](#public-endpoints)
|
||||
3. [Webhook](#webhook)
|
||||
4. [WebSocket Chat](#websocket-chat)
|
||||
5. [Status & Health](#status--health)
|
||||
6. [Memory](#memory)
|
||||
7. [Cron](#cron)
|
||||
8. [Tools](#tools)
|
||||
9. [Configuration](#configuration)
|
||||
10. [Integrations](#integrations)
|
||||
11. [Cost](#cost)
|
||||
12. [Events (SSE)](#events-sse)
|
||||
13. [Channel Webhooks](#channel-webhooks)
|
||||
14. [Rate Limiting](#rate-limiting)
|
||||
15. [Error Responses](#error-responses)
|
||||
|
||||
---
|
||||
|
||||
## Authentication
|
||||
|
||||
Three authentication mechanisms:
|
||||
|
||||
### Bearer Token (Primary)
|
||||
```
|
||||
Authorization: Bearer <token>
|
||||
```
|
||||
Obtained via `POST /pair`. Required for all `/api/*` endpoints when `require_pairing = true` (default).
|
||||
|
||||
### Webhook Secret
|
||||
```
|
||||
X-Webhook-Secret: <raw_secret>
|
||||
```
|
||||
Optional additional auth for `/webhook`. Server SHA-256 hashes and compares using constant-time comparison.
|
||||
|
||||
### WebSocket Token
|
||||
```
|
||||
ws://host:port/ws/chat?token=<bearer_token>
|
||||
```
|
||||
WebSocket connections pass the token as a query parameter (browsers can't set custom headers on WS handshake).
|
||||
|
||||
---
|
||||
|
||||
## Public Endpoints
|
||||
|
||||
### GET /health
|
||||
No authentication required.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"paired": true,
|
||||
"require_pairing": true,
|
||||
"runtime": {}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /metrics
|
||||
Prometheus text exposition format.
|
||||
|
||||
**Response 200:**
|
||||
```
|
||||
Content-Type: text/plain; version=0.0.4; charset=utf-8
|
||||
```
|
||||
|
||||
### POST /pair
|
||||
Exchange a one-time pairing code for a bearer token.
|
||||
|
||||
**Rate Limit:** Configurable per-minute limit per IP (default: 10/min).
|
||||
|
||||
**Headers:**
|
||||
- `X-Pairing-Code: <code>` (required)
|
||||
|
||||
**Response 200 (success):**
|
||||
```json
|
||||
{
|
||||
"paired": true,
|
||||
"persisted": true,
|
||||
"token": "<bearer_token>",
|
||||
"message": "Save this token — use it as Authorization: Bearer <token>"
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200 (persistence failure):**
|
||||
```json
|
||||
{
|
||||
"paired": true,
|
||||
"persisted": false,
|
||||
"token": "<bearer_token>",
|
||||
"message": "Paired for this process, but failed to persist token to config.toml..."
|
||||
}
|
||||
```
|
||||
|
||||
**Response 403:**
|
||||
```json
|
||||
{"error": "Invalid pairing code"}
|
||||
```
|
||||
|
||||
**Response 429:**
|
||||
```json
|
||||
{"error": "Too many pairing requests. Please retry later.", "retry_after": 60}
|
||||
```
|
||||
|
||||
**Response 429 (lockout):**
|
||||
```json
|
||||
{"error": "Too many failed attempts. Try again in {lockout_secs}s.", "retry_after": 120}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Webhook
|
||||
|
||||
### POST /webhook
|
||||
Send a message to the agent and receive a response.
|
||||
|
||||
**Rate Limit:** Configurable per-minute limit per IP (default: 60/min).
|
||||
|
||||
**Headers:**
|
||||
- `Authorization: Bearer <token>` (if pairing enabled)
|
||||
- `Content-Type: application/json`
|
||||
- `X-Webhook-Secret: <secret>` (optional)
|
||||
- `X-Idempotency-Key: <uuid>` (optional)
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{"message": "your prompt here"}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"response": "<llm_response>", "model": "<model_name>"}
|
||||
```
|
||||
|
||||
**Response 200 (duplicate — idempotency key match):**
|
||||
```json
|
||||
{"status": "duplicate", "idempotent": true, "message": "Request already processed for this idempotency key"}
|
||||
```
|
||||
|
||||
**Response 401:**
|
||||
```json
|
||||
{"error": "Unauthorized — pair first via POST /pair, then send Authorization: Bearer <token>"}
|
||||
```
|
||||
|
||||
**Response 429:**
|
||||
```json
|
||||
{"error": "Too many webhook requests. Please retry later.", "retry_after": 60}
|
||||
```
|
||||
|
||||
**Response 500:**
|
||||
```json
|
||||
{"error": "LLM request failed"}
|
||||
```
|
||||
|
||||
### Idempotency
|
||||
- Header: `X-Idempotency-Key: <uuid>`
|
||||
- TTL: configurable, default 300 seconds
|
||||
- Max tracked keys: configurable, default 10,000
|
||||
- Duplicate requests within TTL return `"status": "duplicate"` instead of re-processing
|
||||
|
||||
---
|
||||
|
||||
## WebSocket Chat
|
||||
|
||||
### GET /ws/chat?token=<bearer_token>
|
||||
Streaming agent chat over WebSocket.
|
||||
|
||||
**Client → Server:**
|
||||
```json
|
||||
{"type": "message", "content": "Hello, what's the weather?"}
|
||||
```
|
||||
|
||||
**Server → Client (complete response):**
|
||||
```json
|
||||
{"type": "done", "full_response": "The weather in San Francisco is sunny..."}
|
||||
```
|
||||
|
||||
**Server → Client (error):**
|
||||
```json
|
||||
{"type": "error", "message": "Error message here"}
|
||||
```
|
||||
|
||||
Ignore unknown message types. Invalid JSON triggers an error response.
|
||||
|
||||
---
|
||||
|
||||
## Status & Health
|
||||
|
||||
### GET /api/status
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"provider": "openrouter",
|
||||
"model": "anthropic/claude-sonnet-4",
|
||||
"temperature": 0.7,
|
||||
"uptime_seconds": 3600,
|
||||
"gateway_port": 42617,
|
||||
"locale": "en",
|
||||
"memory_backend": "sqlite",
|
||||
"paired": true,
|
||||
"channels": {
|
||||
"telegram": false,
|
||||
"discord": true,
|
||||
"slack": false
|
||||
},
|
||||
"health": {}
|
||||
}
|
||||
```
|
||||
|
||||
### GET /api/health
|
||||
Component health snapshot (requires auth).
|
||||
```json
|
||||
{"health": {}}
|
||||
```
|
||||
|
||||
### GET or POST /api/doctor
|
||||
Run system diagnostics.
|
||||
```json
|
||||
{
|
||||
"results": [
|
||||
{"name": "provider_connectivity", "severity": "ok", "message": "OpenRouter API reachable"}
|
||||
],
|
||||
"summary": {"ok": 5, "warnings": 1, "errors": 0}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory
|
||||
|
||||
### GET /api/memory
|
||||
List or search memory entries.
|
||||
|
||||
**Query Parameters:**
|
||||
- `query` (string, optional) — search text; triggers search mode
|
||||
- `category` (string, optional) — filter by category
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"entries": [
|
||||
{
|
||||
"key": "memory_key",
|
||||
"content": "memory content",
|
||||
"category": "core",
|
||||
"timestamp": "2025-01-10T12:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/memory
|
||||
Store a memory entry.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"key": "unique_key",
|
||||
"content": "memory content",
|
||||
"category": "core"
|
||||
}
|
||||
```
|
||||
Category defaults to `"core"` if omitted. Other values: `daily`, `conversation`, or any custom string.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"status": "ok"}
|
||||
```
|
||||
|
||||
### DELETE /api/memory/{key}
|
||||
Delete a memory entry.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"status": "ok", "deleted": true}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cron
|
||||
|
||||
### GET /api/cron
|
||||
List all scheduled jobs.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"jobs": [
|
||||
{
|
||||
"id": "<uuid>",
|
||||
"name": "daily-backup",
|
||||
"command": "backup.sh",
|
||||
"next_run": "2025-01-10T15:00:00Z",
|
||||
"last_run": "2025-01-09T15:00:00Z",
|
||||
"last_status": "success",
|
||||
"enabled": true
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### POST /api/cron
|
||||
Add a new job.
|
||||
|
||||
**Request Body:**
|
||||
```json
|
||||
{
|
||||
"name": "job-name",
|
||||
"schedule": "0 9 * * *",
|
||||
"command": "command to run"
|
||||
}
|
||||
```
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"status": "ok",
|
||||
"job": {"id": "<uuid>", "name": "job-name", "command": "command to run", "enabled": true}
|
||||
}
|
||||
```
|
||||
|
||||
### DELETE /api/cron/{id}
|
||||
Remove a job.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"status": "ok"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Tools
|
||||
|
||||
### GET /api/tools
|
||||
List all registered tools with descriptions and parameter schemas.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"tools": [
|
||||
{"name": "shell", "description": "Execute shell commands", "parameters": {}},
|
||||
{"name": "file_read", "description": "Read file contents", "parameters": {}}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### GET /api/config
|
||||
Get current config. Secrets are masked as `***MASKED***`.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"format": "toml", "content": "<toml_string>"}
|
||||
```
|
||||
|
||||
### PUT /api/config
|
||||
Update config from TOML body. Body limit: 1 MB.
|
||||
|
||||
**Request Body:** Raw TOML text.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{"status": "ok"}
|
||||
```
|
||||
|
||||
**Response 400:**
|
||||
```json
|
||||
{"error": "Invalid TOML: <details>"}
|
||||
```
|
||||
or
|
||||
```json
|
||||
{"error": "Invalid config: <validation_error>"}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integrations
|
||||
|
||||
### GET /api/integrations
|
||||
List all integrations and their status.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"integrations": [
|
||||
{"name": "openrouter", "description": "OpenRouter LLM provider", "category": "providers", "status": "ok"},
|
||||
{"name": "telegram", "description": "Telegram messaging channel", "category": "channels", "status": "configured"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Cost
|
||||
|
||||
### GET /api/cost
|
||||
Cost tracking summary.
|
||||
|
||||
**Response 200:**
|
||||
```json
|
||||
{
|
||||
"cost": {
|
||||
"session_cost_usd": 1.50,
|
||||
"daily_cost_usd": 5.00,
|
||||
"monthly_cost_usd": 150.00,
|
||||
"total_tokens": 50000,
|
||||
"request_count": 25,
|
||||
"by_model": {"anthropic/claude-sonnet-4": 1.50}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Events (SSE)
|
||||
|
||||
### GET /api/events
|
||||
Server-Sent Events stream. Requires bearer token.
|
||||
|
||||
**Content-Type:** `text/event-stream`
|
||||
|
||||
**Event types:**
|
||||
|
||||
| Type | Fields | Description |
|
||||
|------|--------|-------------|
|
||||
| `llm_request` | provider, model, timestamp | LLM call started |
|
||||
| `tool_call_start` | tool, timestamp | Tool execution started |
|
||||
| `tool_call` | tool, duration_ms, success, timestamp | Tool execution completed |
|
||||
| `agent_start` | provider, model, timestamp | Agent loop started |
|
||||
| `agent_end` | provider, model, duration_ms, tokens_used, cost_usd, timestamp | Agent loop completed |
|
||||
| `error` | component, message, timestamp | Error occurred |
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
curl -N -H "Authorization: Bearer <token>" http://127.0.0.1:42617/api/events
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Channel Webhooks
|
||||
|
||||
These are incoming webhook endpoints for specific messaging channels. They're set up automatically when channels are configured.
|
||||
|
||||
### WhatsApp (Meta Cloud API)
|
||||
- `GET /whatsapp` — verification (echoes `hub.challenge`)
|
||||
- `POST /whatsapp` — incoming messages (signature verified via `X-Hub-Signature-256`)
|
||||
|
||||
### WATI (WhatsApp Business)
|
||||
- `GET /wati` — verification (echoes `challenge`)
|
||||
- `POST /wati` — incoming messages
|
||||
|
||||
### Linq (iMessage/RCS/SMS)
|
||||
- `POST /linq` — incoming messages (signature verified via `X-Webhook-Signature` + `X-Webhook-Timestamp`)
|
||||
|
||||
### Nextcloud Talk
|
||||
- `POST /nextcloud-talk` — bot API webhook (signature verified via `X-Nextcloud-Talk-Signature`)
|
||||
|
||||
---
|
||||
|
||||
## Rate Limiting
|
||||
|
||||
Sliding window (60-second window), per client IP.
|
||||
|
||||
| Endpoint | Default Limit |
|
||||
|----------|--------------|
|
||||
| `POST /pair` | 10/min |
|
||||
| `POST /webhook` | 60/min |
|
||||
|
||||
If `trust_forwarded_headers` is enabled, uses `X-Forwarded-For` for client IP.
|
||||
|
||||
Max tracked keys: configurable (default: 10,000).
|
||||
|
||||
---
|
||||
|
||||
## Error Responses
|
||||
|
||||
**Standard format:**
|
||||
```json
|
||||
{"error": "Human-readable error message"}
|
||||
```
|
||||
|
||||
**With retry info:**
|
||||
```json
|
||||
{"error": "...", "retry_after": 60}
|
||||
```
|
||||
|
||||
**Status codes:**
|
||||
| Code | Meaning |
|
||||
|------|---------|
|
||||
| 200 | Success |
|
||||
| 400 | Invalid JSON, missing fields, invalid TOML |
|
||||
| 401 | Invalid/missing bearer token or webhook secret |
|
||||
| 403 | Pairing verification failed |
|
||||
| 404 | Endpoint or channel not configured |
|
||||
| 408 | Request timeout (30s) |
|
||||
| 429 | Rate limited (check `retry_after`) |
|
||||
| 500 | LLM error, database error, internal failure |
|
||||
@ -64,8 +64,3 @@ LICENSE
|
||||
*.profdata
|
||||
coverage
|
||||
lcov.info
|
||||
|
||||
# Application and script directories (not needed for Docker runtime)
|
||||
apps/
|
||||
python/
|
||||
scripts/
|
||||
|
||||
@ -1,44 +1,25 @@
|
||||
# EditorConfig is awesome: https://EditorConfig.org
|
||||
# EditorConfig — https://editorconfig.org
|
||||
# Provides consistent formatting defaults across editors and platforms.
|
||||
|
||||
# top-most EditorConfig file
|
||||
root = true
|
||||
|
||||
# All files
|
||||
[*]
|
||||
indent_style = space
|
||||
indent_size = 2
|
||||
end_of_line = lf
|
||||
charset = utf-8
|
||||
trim_trailing_whitespace = true
|
||||
end_of_line = lf
|
||||
insert_final_newline = true
|
||||
|
||||
# Rust files - match rustfmt.toml
|
||||
[*.rs]
|
||||
trim_trailing_whitespace = true
|
||||
indent_style = space
|
||||
indent_size = 4
|
||||
max_line_length = 100
|
||||
|
||||
# Markdown files
|
||||
[*.md]
|
||||
# Trailing whitespace is significant in Markdown (line breaks).
|
||||
trim_trailing_whitespace = false
|
||||
max_line_length = 80
|
||||
|
||||
# TOML files
|
||||
[*.toml]
|
||||
indent_size = 2
|
||||
|
||||
# YAML files
|
||||
[*.{yml,yaml}]
|
||||
indent_size = 2
|
||||
|
||||
# Python files
|
||||
[*.py]
|
||||
[*.toml]
|
||||
indent_size = 2
|
||||
|
||||
[Dockerfile]
|
||||
indent_size = 4
|
||||
max_line_length = 100
|
||||
|
||||
# Shell scripts
|
||||
[*.{sh,bash}]
|
||||
indent_size = 2
|
||||
|
||||
# JSON files
|
||||
[*.json]
|
||||
indent_size = 2
|
||||
|
||||
@ -59,7 +59,6 @@ PROVIDER=openrouter
|
||||
# ZAI_API_KEY=...
|
||||
# SYNTHETIC_API_KEY=...
|
||||
# OPENCODE_API_KEY=...
|
||||
# OPENCODE_GO_API_KEY=...
|
||||
# VERCEL_API_KEY=...
|
||||
# CLOUDFLARE_API_KEY=...
|
||||
|
||||
@ -118,7 +117,3 @@ PROVIDER=openrouter
|
||||
# Optional: Brave Search (requires API key from https://brave.com/search/api)
|
||||
# WEB_SEARCH_PROVIDER=brave
|
||||
# BRAVE_API_KEY=your-brave-search-api-key
|
||||
#
|
||||
# Optional: SearXNG (self-hosted, requires instance URL)
|
||||
# WEB_SEARCH_PROVIDER=searxng
|
||||
# SEARXNG_INSTANCE_URL=https://searx.example.com
|
||||
|
||||
68
.gitattributes
vendored
68
.gitattributes
vendored
@ -1,61 +1,33 @@
|
||||
# Git attributes for ZeroClaw
|
||||
# https://git-scm.com/docs/gitattributes
|
||||
|
||||
# Auto detect text files and perform LF normalization
|
||||
# Normalize all text files
|
||||
* text=auto
|
||||
|
||||
# Source code
|
||||
*.rs text eol=lf linguist-language=Rust
|
||||
*.toml text eol=lf linguist-language=TOML
|
||||
*.py text eol=lf linguist-language=Python
|
||||
*.js text eol=lf linguist-language=JavaScript
|
||||
*.ts text eol=lf linguist-language=TypeScript
|
||||
*.html text eol=lf linguist-language=HTML
|
||||
*.css text eol=lf linguist-language=CSS
|
||||
*.scss text eol=lf linguist-language=SCSS
|
||||
*.json text eol=lf linguist-language=JSON
|
||||
*.yaml text eol=lf linguist-language=YAML
|
||||
*.yml text eol=lf linguist-language=YAML
|
||||
*.md text eol=lf linguist-language=Markdown
|
||||
*.sh text eol=lf linguist-language=Shell
|
||||
*.bash text eol=lf linguist-language=Shell
|
||||
*.ps1 text eol=crlf linguist-language=PowerShell
|
||||
# Force LF for scripts and build-critical files
|
||||
*.sh text eol=lf
|
||||
Dockerfile* text eol=lf
|
||||
*.rs text eol=lf
|
||||
*.toml text eol=lf
|
||||
*.yml text eol=lf
|
||||
*.yaml text eol=lf
|
||||
|
||||
# Documentation
|
||||
*.txt text eol=lf
|
||||
LICENSE* text eol=lf
|
||||
# CI
|
||||
.github/**/* text eol=lf
|
||||
|
||||
# Configuration files
|
||||
.editorconfig text eol=lf
|
||||
.gitattributes text eol=lf
|
||||
.gitignore text eol=lf
|
||||
.dockerignore text eol=lf
|
||||
|
||||
# Rust-specific
|
||||
Cargo.lock text eol=lf linguist-generated
|
||||
Cargo.toml text eol=lf
|
||||
|
||||
# Declare files that will always have CRLF line endings on checkout
|
||||
*.sln text eol=crlf
|
||||
|
||||
# Denote all files that are truly binary and should not be modified
|
||||
# Images
|
||||
*.png binary
|
||||
*.jpg binary
|
||||
*.jpeg binary
|
||||
*.gif binary
|
||||
*.ico binary
|
||||
*.svg text
|
||||
*.wasm binary
|
||||
*.woff binary
|
||||
*.woff2 binary
|
||||
*.ttf binary
|
||||
*.eot binary
|
||||
*.mp3 binary
|
||||
*.mp4 binary
|
||||
*.webm binary
|
||||
|
||||
# Archives
|
||||
*.zip binary
|
||||
*.tar binary
|
||||
*.tgz binary
|
||||
*.gz binary
|
||||
*.bz2 binary
|
||||
*.7z binary
|
||||
*.db binary
|
||||
|
||||
# Compiled artifacts
|
||||
*.so binary
|
||||
*.dll binary
|
||||
*.exe binary
|
||||
*.a binary
|
||||
|
||||
50
.github/CODEOWNERS
vendored
50
.github/CODEOWNERS
vendored
@ -1,32 +1,32 @@
|
||||
# Default owner for all files
|
||||
* @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
* @chumyin
|
||||
|
||||
# Important functional modules
|
||||
/src/agent/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/providers/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/channels/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/tools/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/gateway/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/runtime/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/memory/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/Cargo.toml @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/Cargo.lock @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/agent/** @theonlyhennygod
|
||||
/src/providers/** @theonlyhennygod
|
||||
/src/channels/** @theonlyhennygod
|
||||
/src/tools/** @theonlyhennygod
|
||||
/src/gateway/** @theonlyhennygod
|
||||
/src/runtime/** @theonlyhennygod
|
||||
/src/memory/** @theonlyhennygod
|
||||
/Cargo.toml @theonlyhennygod
|
||||
/Cargo.lock @theonlyhennygod
|
||||
|
||||
# Security / tests / CI-CD ownership
|
||||
/src/security/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/tests/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/.github/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/.github/workflows/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/.github/codeql/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/.github/dependabot.yml @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/SECURITY.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/docs/actions-source-policy.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/docs/ci-map.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/src/security/** @chumyin
|
||||
/tests/** @chumyin
|
||||
/.github/** @chumyin
|
||||
/.github/workflows/** @chumyin
|
||||
/.github/codeql/** @chumyin
|
||||
/.github/dependabot.yml @chumyin
|
||||
/SECURITY.md @chumyin
|
||||
/docs/actions-source-policy.md @chumyin
|
||||
/docs/ci-map.md @chumyin
|
||||
|
||||
# Docs & governance
|
||||
/docs/** @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/AGENTS.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/CLAUDE.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/CONTRIBUTING.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/docs/pr-workflow.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/docs/reviewer-playbook.md @theonlyhennygod @JordanTheJet @SimianAstronaut7
|
||||
/docs/** @chumyin
|
||||
/AGENTS.md @chumyin
|
||||
/CLAUDE.md @chumyin
|
||||
/CONTRIBUTING.md @chumyin
|
||||
/docs/pr-workflow.md @chumyin
|
||||
/docs/reviewer-playbook.md @chumyin
|
||||
|
||||
24
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
24
.github/ISSUE_TEMPLATE/bug_report.yml
vendored
@ -11,6 +11,15 @@ body:
|
||||
Please provide a minimal reproducible case so maintainers can triage quickly.
|
||||
Do not include personal/sensitive data; redact and anonymize all logs/payloads.
|
||||
|
||||
- type: input
|
||||
id: summary
|
||||
attributes:
|
||||
label: Summary
|
||||
description: One-line description of the problem.
|
||||
placeholder: zeroclaw daemon exits immediately when ...
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: component
|
||||
attributes:
|
||||
@ -63,7 +72,7 @@ body:
|
||||
label: Steps to reproduce
|
||||
description: Please provide exact commands/config.
|
||||
placeholder: |
|
||||
1. zeroclaw onboard
|
||||
1. zeroclaw onboard --interactive
|
||||
2. zeroclaw daemon
|
||||
3. Observe crash in logs
|
||||
render: bash
|
||||
@ -74,13 +83,13 @@ body:
|
||||
id: impact
|
||||
attributes:
|
||||
label: Impact
|
||||
description: Who is affected, how often, and practical consequences (optional but helps triage).
|
||||
description: Who is affected, how often, and practical consequences.
|
||||
placeholder: |
|
||||
Affected users: ...
|
||||
Frequency: always/intermittent
|
||||
Consequence: ...
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: logs
|
||||
@ -103,10 +112,9 @@ body:
|
||||
id: rust
|
||||
attributes:
|
||||
label: Rust version
|
||||
description: Required for runtime/build bugs; optional for docs/config issues.
|
||||
placeholder: rustc 1.xx.x
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: os
|
||||
@ -132,7 +140,9 @@ body:
|
||||
attributes:
|
||||
label: Pre-flight checks
|
||||
options:
|
||||
- label: I reproduced this on the latest master branch or latest release.
|
||||
- label: I reproduced this on the latest main branch or latest release.
|
||||
required: true
|
||||
- label: I redacted secrets, tokens, and personal data from all submitted content.
|
||||
- label: I redacted secrets/tokens from logs.
|
||||
required: true
|
||||
- label: I removed personal identifiers and replaced identity-specific data with neutral placeholders.
|
||||
required: true
|
||||
|
||||
4
.github/ISSUE_TEMPLATE/config.yml
vendored
4
.github/ISSUE_TEMPLATE/config.yml
vendored
@ -4,8 +4,8 @@ contact_links:
|
||||
url: https://github.com/zeroclaw-labs/zeroclaw/security/policy
|
||||
about: Please report security vulnerabilities privately via SECURITY.md policy.
|
||||
- name: Contribution guide
|
||||
url: https://github.com/zeroclaw-labs/zeroclaw/blob/master/CONTRIBUTING.md
|
||||
url: https://github.com/zeroclaw-labs/zeroclaw/blob/main/CONTRIBUTING.md
|
||||
about: Please read contribution and PR requirements before opening an issue.
|
||||
- name: PR workflow & reviewer expectations
|
||||
url: https://github.com/zeroclaw-labs/zeroclaw/blob/master/docs/pr-workflow.md
|
||||
url: https://github.com/zeroclaw-labs/zeroclaw/blob/main/docs/pr-workflow.md
|
||||
about: Read risk-based PR tracks, CI gates, and merge criteria before filing feature requests.
|
||||
|
||||
16
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
16
.github/ISSUE_TEMPLATE/feature_request.yml
vendored
@ -42,10 +42,10 @@ body:
|
||||
id: non_goals
|
||||
attributes:
|
||||
label: Non-goals / out of scope
|
||||
description: Clarify what should not be included in the first iteration (optional but helps scope discussion).
|
||||
description: Clarify what should not be included in the first iteration.
|
||||
placeholder: No UI changes, no cross-provider dynamic adaptation in v1.
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: alternatives
|
||||
@ -60,31 +60,31 @@ body:
|
||||
id: acceptance
|
||||
attributes:
|
||||
label: Acceptance criteria
|
||||
description: What outcomes would make this request complete? (optional — can be defined during triage)
|
||||
description: What outcomes would make this request complete?
|
||||
placeholder: |
|
||||
- Config key is documented and validated
|
||||
- Runtime path uses configured retry budget
|
||||
- Regression tests cover fallback and invalid config
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: architecture
|
||||
attributes:
|
||||
label: Architecture impact
|
||||
description: Which subsystem(s) are affected? (optional — maintainers will assess during triage)
|
||||
description: Which subsystem(s) are affected?
|
||||
placeholder: providers/, channels/, memory/, runtime/, security/, docs/ ...
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: risk
|
||||
attributes:
|
||||
label: Risk and rollback
|
||||
description: Main risk + how to disable/revert quickly (optional — can be defined during planning).
|
||||
description: Main risk + how to disable/revert quickly.
|
||||
placeholder: Risk is ... rollback is ...
|
||||
validations:
|
||||
required: false
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: breaking
|
||||
|
||||
BIN
.github/assets/show-tool-calls-after.png
vendored
BIN
.github/assets/show-tool-calls-after.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 84 KiB |
BIN
.github/assets/show-tool-calls-before.png
vendored
BIN
.github/assets/show-tool-calls-before.png
vendored
Binary file not shown.
|
Before Width: | Height: | Size: 110 KiB |
6
.github/dependabot.yml
vendored
6
.github/dependabot.yml
vendored
@ -5,7 +5,7 @@ updates:
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: daily
|
||||
target-branch: master
|
||||
target-branch: dev
|
||||
open-pull-requests-limit: 3
|
||||
labels:
|
||||
- "dependencies"
|
||||
@ -21,7 +21,7 @@ updates:
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: daily
|
||||
target-branch: master
|
||||
target-branch: dev
|
||||
open-pull-requests-limit: 1
|
||||
labels:
|
||||
- "ci"
|
||||
@ -38,7 +38,7 @@ updates:
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: daily
|
||||
target-branch: master
|
||||
target-branch: dev
|
||||
open-pull-requests-limit: 1
|
||||
labels:
|
||||
- "ci"
|
||||
|
||||
301
.github/labeler.yml
vendored
301
.github/labeler.yml
vendored
@ -36,145 +36,6 @@
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/**"
|
||||
|
||||
"channel:bluesky":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/bluesky.rs"
|
||||
|
||||
"channel:clawdtalk":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/clawdtalk.rs"
|
||||
|
||||
"channel:cli":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/cli.rs"
|
||||
|
||||
"channel:dingtalk":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/dingtalk.rs"
|
||||
|
||||
"channel:discord":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/discord.rs"
|
||||
- "src/channels/discord_history.rs"
|
||||
|
||||
"channel:email":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/email_channel.rs"
|
||||
- "src/channels/gmail_push.rs"
|
||||
|
||||
"channel:imessage":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/imessage.rs"
|
||||
|
||||
"channel:irc":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/irc.rs"
|
||||
|
||||
"channel:lark":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/lark.rs"
|
||||
|
||||
"channel:linq":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/linq.rs"
|
||||
|
||||
"channel:matrix":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/matrix.rs"
|
||||
|
||||
"channel:mattermost":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/mattermost.rs"
|
||||
|
||||
"channel:mochat":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/mochat.rs"
|
||||
|
||||
"channel:mqtt":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/mqtt.rs"
|
||||
|
||||
"channel:nextcloud-talk":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/nextcloud_talk.rs"
|
||||
|
||||
"channel:nostr":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/nostr.rs"
|
||||
|
||||
"channel:notion":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/notion.rs"
|
||||
|
||||
"channel:qq":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/qq.rs"
|
||||
|
||||
"channel:reddit":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/reddit.rs"
|
||||
|
||||
"channel:signal":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/signal.rs"
|
||||
|
||||
"channel:slack":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/slack.rs"
|
||||
|
||||
"channel:telegram":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/telegram.rs"
|
||||
|
||||
"channel:twitter":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/twitter.rs"
|
||||
|
||||
"channel:wati":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/wati.rs"
|
||||
|
||||
"channel:webhook":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/webhook.rs"
|
||||
|
||||
"channel:wecom":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/wecom.rs"
|
||||
|
||||
"channel:whatsapp":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/channels/whatsapp.rs"
|
||||
- "src/channels/whatsapp_storage.rs"
|
||||
- "src/channels/whatsapp_web.rs"
|
||||
|
||||
"gateway":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
@ -240,73 +101,6 @@
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/**"
|
||||
|
||||
"provider:anthropic":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/anthropic.rs"
|
||||
|
||||
"provider:azure-openai":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/azure_openai.rs"
|
||||
|
||||
"provider:bedrock":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/bedrock.rs"
|
||||
|
||||
"provider:claude-code":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/claude_code.rs"
|
||||
|
||||
"provider:compatible":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/compatible.rs"
|
||||
|
||||
"provider:copilot":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/copilot.rs"
|
||||
|
||||
"provider:gemini":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/gemini.rs"
|
||||
- "src/providers/gemini_cli.rs"
|
||||
|
||||
"provider:glm":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/glm.rs"
|
||||
|
||||
"provider:kilocli":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/kilocli.rs"
|
||||
|
||||
"provider:ollama":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/ollama.rs"
|
||||
|
||||
"provider:openai":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/openai.rs"
|
||||
- "src/providers/openai_codex.rs"
|
||||
|
||||
"provider:openrouter":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/openrouter.rs"
|
||||
|
||||
"provider:telnyx":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/providers/telnyx.rs"
|
||||
|
||||
"service":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
@ -327,101 +121,6 @@
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/**"
|
||||
|
||||
"tool:browser":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/browser.rs"
|
||||
- "src/tools/browser_delegate.rs"
|
||||
- "src/tools/browser_open.rs"
|
||||
- "src/tools/text_browser.rs"
|
||||
- "src/tools/screenshot.rs"
|
||||
|
||||
"tool:composio":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/composio.rs"
|
||||
|
||||
"tool:cron":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/cron_add.rs"
|
||||
- "src/tools/cron_list.rs"
|
||||
- "src/tools/cron_remove.rs"
|
||||
- "src/tools/cron_run.rs"
|
||||
- "src/tools/cron_runs.rs"
|
||||
- "src/tools/cron_update.rs"
|
||||
|
||||
"tool:file":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/file_edit.rs"
|
||||
- "src/tools/file_read.rs"
|
||||
- "src/tools/file_write.rs"
|
||||
- "src/tools/glob_search.rs"
|
||||
- "src/tools/content_search.rs"
|
||||
|
||||
"tool:google-workspace":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/google_workspace.rs"
|
||||
|
||||
"tool:mcp":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/mcp_client.rs"
|
||||
- "src/tools/mcp_deferred.rs"
|
||||
- "src/tools/mcp_protocol.rs"
|
||||
- "src/tools/mcp_tool.rs"
|
||||
- "src/tools/mcp_transport.rs"
|
||||
|
||||
"tool:memory":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/memory_forget.rs"
|
||||
- "src/tools/memory_recall.rs"
|
||||
- "src/tools/memory_store.rs"
|
||||
|
||||
"tool:microsoft365":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/microsoft365/**"
|
||||
|
||||
"tool:shell":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/shell.rs"
|
||||
- "src/tools/node_tool.rs"
|
||||
- "src/tools/cli_discovery.rs"
|
||||
|
||||
"tool:sop":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/sop_advance.rs"
|
||||
- "src/tools/sop_approve.rs"
|
||||
- "src/tools/sop_execute.rs"
|
||||
- "src/tools/sop_list.rs"
|
||||
- "src/tools/sop_status.rs"
|
||||
|
||||
"tool:web":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/web_fetch.rs"
|
||||
- "src/tools/web_search_tool.rs"
|
||||
- "src/tools/web_search_provider_routing.rs"
|
||||
- "src/tools/http_request.rs"
|
||||
|
||||
"tool:security":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/security_ops.rs"
|
||||
- "src/tools/verifiable_intent.rs"
|
||||
|
||||
"tool:cloud":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
- "src/tools/cloud_ops.rs"
|
||||
- "src/tools/cloud_patterns.rs"
|
||||
|
||||
"tunnel":
|
||||
- changed-files:
|
||||
- any-glob-to-any-file:
|
||||
|
||||
2
.github/pull_request_template.md
vendored
2
.github/pull_request_template.md
vendored
@ -2,7 +2,7 @@
|
||||
|
||||
Describe this PR in 2-5 bullets:
|
||||
|
||||
- Base branch target (`master` for all contributions):
|
||||
- Base branch target (`dev` for normal contributions; `main` only for `dev` promotion):
|
||||
- Problem:
|
||||
- Why it matters:
|
||||
- What changed:
|
||||
|
||||
9
.github/workflows/README.md
vendored
9
.github/workflows/README.md
vendored
@ -10,8 +10,15 @@ Subdirectories are not valid locations for workflow entry files.
|
||||
Repository convention:
|
||||
|
||||
1. Keep runnable workflow entry files at `.github/workflows/` root.
|
||||
2. Keep cross-tooling/local CI scripts under `dev/` or `scripts/ci/` when used outside Actions.
|
||||
2. Keep cross-tooling/local CI scripts under `scripts/ci/` when they are used outside Actions.
|
||||
|
||||
Workflow behavior documentation in this directory:
|
||||
|
||||
- `.github/workflows/master-branch-flow.md`
|
||||
|
||||
Current workflows:
|
||||
|
||||
- `.github/workflows/ci.yml` — PR checks (test + build)
|
||||
- `.github/workflows/ci-full.yml` — manual full cross-platform build matrix
|
||||
- `.github/workflows/release.yml` — automatic beta release on push to `master`
|
||||
- `.github/workflows/promote-release.yml` — manual stable release
|
||||
|
||||
175
.github/workflows/checks-on-pr.yml
vendored
175
.github/workflows/checks-on-pr.yml
vendored
@ -1,175 +0,0 @@
|
||||
name: Quality Gate
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [master]
|
||||
|
||||
concurrency:
|
||||
group: checks-${{ github.event.pull_request.number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
CARGO_INCREMENTAL: 0
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
components: rustfmt, clippy
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Check formatting
|
||||
run: cargo fmt --all -- --check
|
||||
|
||||
- name: Clippy
|
||||
run: cargo clippy --all-targets -- -D warnings
|
||||
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Install mold linker
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Install cargo-nextest
|
||||
run: curl -LsSf https://get.nexte.st/latest/linux | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin
|
||||
|
||||
- name: Run tests
|
||||
run: cargo nextest run --locked
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
target: x86_64-unknown-linux-gnu
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
if: runner.os != 'Windows'
|
||||
|
||||
- name: Install mold linker
|
||||
if: runner.os == 'Linux'
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
shell: bash
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: cargo build --profile ci --locked --target ${{ matrix.target }}
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
|
||||
security:
|
||||
name: Security Audit
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Install cargo-audit
|
||||
run: cargo install cargo-audit --locked
|
||||
|
||||
- name: Install cargo-deny
|
||||
run: cargo install cargo-deny --locked
|
||||
|
||||
- name: Audit dependencies
|
||||
run: cargo audit
|
||||
|
||||
- name: Check licenses and sources
|
||||
run: cargo deny check licenses sources
|
||||
|
||||
check-32bit:
|
||||
name: "Check (32-bit)"
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: i686-unknown-linux-gnu
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
- name: Install 32-bit libs
|
||||
run: sudo apt-get update && sudo apt-get install -y gcc-multilib
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
- name: Cargo check (32-bit, no default features)
|
||||
run: cargo check --target i686-unknown-linux-gnu --no-default-features
|
||||
|
||||
# Composite status check — branch protection only needs to require this
|
||||
# single job instead of tracking every matrix leg individually.
|
||||
gate:
|
||||
name: CI Required Gate
|
||||
if: always()
|
||||
needs: [lint, test, build, security, check-32bit]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check upstream job results
|
||||
run: |
|
||||
if [[ "${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}" == "true" ]]; then
|
||||
echo "::error::One or more upstream jobs failed or were cancelled"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
security-gate:
|
||||
name: Security Required Gate
|
||||
if: always()
|
||||
needs: [security]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check security job result
|
||||
run: |
|
||||
if [[ "${{ needs.security.result }}" != "success" ]]; then
|
||||
echo "::error::Security audit failed or was cancelled"
|
||||
exit 1
|
||||
fi
|
||||
@ -1,4 +1,4 @@
|
||||
name: Cross-Platform Build
|
||||
name: CI Full Matrix
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
@ -11,28 +11,8 @@ env:
|
||||
CARGO_INCREMENTAL: 0
|
||||
|
||||
jobs:
|
||||
web:
|
||||
name: Build Web Dashboard
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
retention-days: 1
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
needs: [web]
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
@ -44,29 +24,19 @@ jobs:
|
||||
cross_compiler: gcc-aarch64-linux-gnu
|
||||
linker_env: CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
|
||||
linker: aarch64-linux-gnu-gcc
|
||||
- os: ubuntu-latest
|
||||
target: armv7-unknown-linux-gnueabihf
|
||||
cross_compiler: gcc-arm-linux-gnueabihf
|
||||
linker_env: CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER
|
||||
linker: arm-linux-gnueabihf-gcc
|
||||
- os: macos-15-intel
|
||||
target: x86_64-apple-darwin
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
if: runner.os != 'Windows'
|
||||
|
||||
- uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
|
||||
- name: Install cross compiler
|
||||
if: matrix.cross_compiler
|
||||
run: |
|
||||
@ -79,4 +49,4 @@ jobs:
|
||||
if [ -n "${{ matrix.linker_env || '' }}" ] && [ -n "${{ matrix.linker || '' }}" ]; then
|
||||
export "${{ matrix.linker_env }}=${{ matrix.linker }}"
|
||||
fi
|
||||
cargo build --release --locked --features channel-matrix,channel-lark,memory-postgres --target ${{ matrix.target }}
|
||||
cargo build --release --locked --target ${{ matrix.target }}
|
||||
193
.github/workflows/ci-run.yml
vendored
193
.github/workflows/ci-run.yml
vendored
@ -1,193 +0,0 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
pull_request:
|
||||
branches: [master]
|
||||
|
||||
concurrency:
|
||||
group: ci-${{ github.event.pull_request.number || 'push-master' }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
CARGO_INCREMENTAL: 0
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Lint
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
components: rustfmt, clippy
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Check formatting
|
||||
run: cargo fmt --all -- --check
|
||||
|
||||
- name: Clippy
|
||||
run: cargo clippy --all-targets -- -D warnings
|
||||
|
||||
lint-strict-delta:
|
||||
name: Strict Delta Lint
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
components: clippy
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Run strict delta lint gate
|
||||
run: bash scripts/ci/rust_strict_delta_gate.sh
|
||||
env:
|
||||
BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
|
||||
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
needs: [lint]
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Install mold linker
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Install cargo-nextest
|
||||
run: curl -LsSf https://get.nexte.st/latest/linux | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin
|
||||
|
||||
- name: Run tests
|
||||
run: cargo nextest run --locked
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
needs: [lint]
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
target: x86_64-unknown-linux-gnu
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
if: runner.os != 'Windows'
|
||||
|
||||
- name: Install mold linker
|
||||
if: runner.os == 'Linux'
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
shell: bash
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: cargo build --profile ci --locked --target ${{ matrix.target }}
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
|
||||
check-all-features:
|
||||
name: Check (all features)
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 20
|
||||
needs: [lint]
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
|
||||
- name: Install system dependencies
|
||||
run: sudo apt-get update -qq && sudo apt-get install -y libudev-dev
|
||||
|
||||
- name: Ensure web/dist placeholder exists
|
||||
run: mkdir -p web/dist && touch web/dist/.gitkeep
|
||||
|
||||
- name: Check all features
|
||||
run: cargo check --features ci-all --locked
|
||||
|
||||
docs-quality:
|
||||
name: Docs Quality
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- uses: actions/setup-node@1d0ff469b7ec7b3cb9d8673fde0c81c44821de2a # v4
|
||||
with:
|
||||
node-version: 20
|
||||
- uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Run docs quality gate
|
||||
run: bash scripts/ci/docs_quality_gate.sh
|
||||
env:
|
||||
BASE_SHA: ${{ github.event.pull_request.base.sha || github.event.before }}
|
||||
|
||||
# Composite status check — branch protection requires this single job.
|
||||
gate:
|
||||
name: CI Required Gate
|
||||
if: always()
|
||||
needs: [lint, lint-strict-delta, test, build, docs-quality, check-all-features]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check upstream job results
|
||||
env:
|
||||
HAS_FAILURE: ${{ contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') }}
|
||||
run: |
|
||||
if [[ "$HAS_FAILURE" == "true" ]]; then
|
||||
echo "::error::One or more upstream jobs failed or were cancelled"
|
||||
exit 1
|
||||
fi
|
||||
75
.github/workflows/ci.yml
vendored
Normal file
75
.github/workflows/ci.yml
vendored
Normal file
@ -0,0 +1,75 @@
|
||||
name: CI
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [master]
|
||||
|
||||
concurrency:
|
||||
group: ci-${{ github.event.pull_request.number }}
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
CARGO_INCREMENTAL: 0
|
||||
|
||||
jobs:
|
||||
test:
|
||||
name: Test
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
|
||||
- name: Install mold linker
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Install cargo-nextest
|
||||
run: curl -LsSf https://get.nexte.st/latest/linux | tar zxf - -C ${CARGO_HOME:-~/.cargo}/bin
|
||||
|
||||
- name: Run tests
|
||||
run: cargo nextest run --locked
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
target: x86_64-unknown-linux-gnu
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
|
||||
- name: Install mold linker
|
||||
if: runner.os == 'Linux'
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y mold
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: cargo build --release --locked --target ${{ matrix.target }}
|
||||
env:
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_LINKER: clang
|
||||
CARGO_TARGET_X86_64_UNKNOWN_LINUX_GNU_RUSTFLAGS: "-C link-arg=-fuse-ld=mold"
|
||||
83
.github/workflows/main-branch-flow.md
vendored
Normal file
83
.github/workflows/main-branch-flow.md
vendored
Normal file
@ -0,0 +1,83 @@
|
||||
# Master Branch Delivery Flows
|
||||
|
||||
This document explains what runs when code is proposed to `master`, merged, and released.
|
||||
|
||||
Use this with:
|
||||
|
||||
- [`docs/ci-map.md`](../../docs/ci-map.md)
|
||||
- [`docs/pr-workflow.md`](../../docs/pr-workflow.md)
|
||||
- [`docs/release-process.md`](../../docs/release-process.md)
|
||||
|
||||
## Event Summary
|
||||
|
||||
| Event | Workflow |
|
||||
| --- | --- |
|
||||
| PR to `master` | `ci.yml` |
|
||||
| Push to `master` (merge) | `release.yml` (Beta Release) |
|
||||
| Manual dispatch | `ci-full.yml` (CI Full Matrix), `promote-release.yml` (Promote Release) |
|
||||
|
||||
## Step-By-Step
|
||||
|
||||
### 1) PR to `master`
|
||||
|
||||
1. Contributor opens or updates PR against `master`.
|
||||
2. `ci.yml` runs:
|
||||
- `test` — runs `cargo nextest run --locked` with mold linker on Ubuntu.
|
||||
- `build` — builds release binaries for `x86_64-unknown-linux-gnu` and `aarch64-apple-darwin`.
|
||||
3. Both jobs must pass for the PR to be mergeable.
|
||||
4. Maintainer merges PR once checks and review policy are satisfied.
|
||||
|
||||
### 2) Push to `master` (after merge)
|
||||
|
||||
1. Merged commit reaches `master`.
|
||||
2. `release.yml` (Beta Release) runs automatically:
|
||||
- Computes beta version tag: `vX.Y.Z-beta.<run_number>`.
|
||||
- Builds 5-target release matrix (linux x86_64 + aarch64, macOS x86_64 + aarch64, Windows x86_64).
|
||||
- Packages archives with SHA256SUMS.
|
||||
- Creates GitHub pre-release.
|
||||
- Builds and pushes multi-platform Docker image to GHCR (`beta` + version tag).
|
||||
|
||||
### 3) Stable release (manual)
|
||||
|
||||
1. Maintainer runs `promote-release.yml` via workflow dispatch with version input (e.g. `0.2.0`).
|
||||
2. Workflow validates version matches `Cargo.toml` and tag does not already exist.
|
||||
3. Builds same 5-target matrix as beta release.
|
||||
4. Creates GitHub stable release (non-pre-release) with archives + SHA256SUMS.
|
||||
5. Builds and pushes Docker image to GHCR (`latest` + version tag).
|
||||
|
||||
## Mermaid Diagrams
|
||||
|
||||
### PR and Merge Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["PR opened/updated → master"] --> B["ci.yml"]
|
||||
B --> B1["test (cargo nextest)"]
|
||||
B --> B2["build (linux + macOS)"]
|
||||
B1 --> C{"Both pass?"}
|
||||
B2 --> C
|
||||
C -->|No| D["PR stays open"]
|
||||
C -->|Yes| E["Merge PR"]
|
||||
E --> F["push to master"]
|
||||
F --> G["release.yml (Beta Release)"]
|
||||
G --> G1["Build 5 targets"]
|
||||
G1 --> G2["Publish GitHub pre-release"]
|
||||
G1 --> G3["Push Docker image to GHCR"]
|
||||
```
|
||||
|
||||
### Stable Release Flow
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
M["Maintainer runs promote-release.yml"] --> V["Validate version + Cargo.toml"]
|
||||
V --> B["Build 5 targets"]
|
||||
B --> P["Publish GitHub stable release"]
|
||||
B --> D["Push Docker image to GHCR (latest)"]
|
||||
```
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
1. **CI failing on PR:** check `test` and `build` jobs in `.github/workflows/ci.yml`.
|
||||
2. **Beta release failing:** check `.github/workflows/release.yml` job logs.
|
||||
3. **Stable release failing:** check `validate` job in `.github/workflows/promote-release.yml` for version mismatch.
|
||||
4. **Docker push failing:** check GHCR authentication and `docker` job logs in the release workflow.
|
||||
130
.github/workflows/master-branch-flow.md
vendored
130
.github/workflows/master-branch-flow.md
vendored
@ -1,130 +0,0 @@
|
||||
# Master Branch Delivery Flows
|
||||
|
||||
This document explains what runs when code is proposed to `master` and released.
|
||||
|
||||
Use this with:
|
||||
|
||||
- [`docs/ci-map.md`](../../docs/contributing/ci-map.md)
|
||||
- [`docs/pr-workflow.md`](../../docs/contributing/pr-workflow.md)
|
||||
- [`docs/release-process.md`](../../docs/contributing/release-process.md)
|
||||
|
||||
## Branching Model
|
||||
|
||||
ZeroClaw uses a single default branch: `master`. All contributor PRs target `master` directly. There is no `dev` or promotion branch.
|
||||
|
||||
Current maintainers with PR approval authority: `theonlyhennygod`, `JordanTheJet`, and `SimianAstronaut7`.
|
||||
|
||||
## Active Workflows
|
||||
|
||||
| File | Trigger | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `checks-on-pr.yml` | `pull_request` → `master` | Lint + test + build + security audit on every PR |
|
||||
| `cross-platform-build-manual.yml` | `workflow_dispatch` | Full platform build matrix (manual) |
|
||||
| `release-beta-on-push.yml` | `push` → `master` | Beta release on every master commit |
|
||||
| `release-stable-manual.yml` | `workflow_dispatch` | Stable release (manual, version-gated) |
|
||||
|
||||
## Event Summary
|
||||
|
||||
| Event | Workflows triggered |
|
||||
| --- | --- |
|
||||
| PR opened or updated against `master` | `checks-on-pr.yml` |
|
||||
| Push to `master` (including after merge) | `release-beta-on-push.yml` |
|
||||
| Manual dispatch | `cross-platform-build-manual.yml`, `release-stable-manual.yml` |
|
||||
|
||||
## Step-By-Step
|
||||
|
||||
### 1) PR → `master`
|
||||
|
||||
1. Contributor opens or updates a PR against `master`.
|
||||
2. `checks-on-pr.yml` starts:
|
||||
- `lint` job: runs `cargo fmt --check` and `cargo clippy -D warnings`.
|
||||
- `test` job: runs `cargo nextest run --locked` on `ubuntu-latest` with Rust 1.92.0 and mold linker.
|
||||
- `build` job (matrix): compiles release binary on `x86_64-unknown-linux-gnu` and `aarch64-apple-darwin`.
|
||||
- `security` job: runs `cargo audit` and `cargo deny check licenses sources`.
|
||||
- Concurrency group cancels in-progress runs for the same PR on new pushes.
|
||||
3. All jobs must pass before merge.
|
||||
4. Maintainer (`theonlyhennygod`, `JordanTheJet`, or `SimianAstronaut7`) merges PR once checks and review policy are satisfied.
|
||||
5. Merge emits a `push` event on `master` (see section 2).
|
||||
|
||||
### 2) Push to `master` (including after merge)
|
||||
|
||||
1. Commit reaches `master`.
|
||||
2. `release-beta-on-push.yml` (Release Beta) starts:
|
||||
- `version` job: computes beta tag as `v{cargo_version}-beta.{run_number}`.
|
||||
- `build` job (matrix, 4 targets): `x86_64-linux`, `aarch64-linux`, `aarch64-darwin`, `x86_64-windows`.
|
||||
- `publish` job: generates `SHA256SUMS`, creates a GitHub pre-release with all artifacts. Artifact retention: 7 days.
|
||||
- `docker` job: builds multi-platform image (`linux/amd64,linux/arm64`) and pushes to `ghcr.io` with `:beta` and the versioned beta tag.
|
||||
3. This runs on every push to `master` without filtering. Every merged PR produces a beta pre-release.
|
||||
|
||||
### 3) Stable Release (manual)
|
||||
|
||||
1. Maintainer runs `release-stable-manual.yml` via `workflow_dispatch` with a version input (e.g. `0.2.0`).
|
||||
2. `validate` job checks:
|
||||
- Input matches semver `X.Y.Z` format.
|
||||
- `Cargo.toml` version matches input exactly.
|
||||
- Tag `vX.Y.Z` does not already exist on the remote.
|
||||
3. `build` job (matrix, same 4 targets as beta): compiles release binary.
|
||||
4. `publish` job: generates `SHA256SUMS`, creates a stable GitHub Release (not pre-release). Artifact retention: 14 days.
|
||||
5. `docker` job: pushes to `ghcr.io` with `:latest` and `:vX.Y.Z`.
|
||||
|
||||
### 4) Full Platform Build (manual)
|
||||
|
||||
1. Maintainer runs `cross-platform-build-manual.yml` via `workflow_dispatch`.
|
||||
2. `build` job (matrix, 3 targets): `aarch64-linux-gnu`, `x86_64-darwin` (macOS 15 Intel), `x86_64-windows-msvc`.
|
||||
3. Build-only, no tests, no publish. Used to verify cross-compilation on platforms not covered by `checks-on-pr.yml`.
|
||||
|
||||
## Build Targets by Workflow
|
||||
|
||||
| Target | `checks-on-pr.yml` | `cross-platform-build-manual.yml` | `release-beta-on-push.yml` | `release-stable-manual.yml` |
|
||||
| --- | :---: | :---: | :---: | :---: |
|
||||
| `x86_64-unknown-linux-gnu` | ✓ | | ✓ | ✓ |
|
||||
| `aarch64-unknown-linux-gnu` | | ✓ | ✓ | ✓ |
|
||||
| `aarch64-apple-darwin` | ✓ | | ✓ | ✓ |
|
||||
| `x86_64-apple-darwin` | | ✓ | | |
|
||||
| `x86_64-pc-windows-msvc` | ✓ | ✓ | ✓ | ✓ |
|
||||
|
||||
## Mermaid Diagrams
|
||||
|
||||
### PR to Master
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["PR opened or updated → master"] --> B["checks-on-pr.yml"]
|
||||
B --> B0["lint: fmt + clippy"]
|
||||
B --> B1["test: cargo nextest (ubuntu-latest)"]
|
||||
B --> B2["build: x86_64-linux + aarch64-darwin"]
|
||||
B --> B3["security: audit + deny"]
|
||||
B0 & B1 & B2 & B3 --> C{"Checks pass?"}
|
||||
C -->|No| D["PR stays open"]
|
||||
C -->|Yes| E["Maintainer merges"]
|
||||
E --> F["push event on master"]
|
||||
```
|
||||
|
||||
### Beta Release (on every master push)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["Push to master"] --> B["release-beta-on-push.yml"]
|
||||
B --> B1["version: compute v{x.y.z}-beta.{N}"]
|
||||
B1 --> B2["build: 4 targets"]
|
||||
B2 --> B3["publish: GitHub pre-release + SHA256SUMS"]
|
||||
B2 --> B4["docker: push ghcr.io :beta + versioned tag"]
|
||||
```
|
||||
|
||||
### Stable Release (manual)
|
||||
|
||||
```mermaid
|
||||
flowchart TD
|
||||
A["workflow_dispatch: version=X.Y.Z"] --> B["release-stable-manual.yml"]
|
||||
B --> B1["validate: semver + Cargo.toml + tag uniqueness"]
|
||||
B1 --> B2["build: 4 targets"]
|
||||
B2 --> B3["publish: GitHub stable release + SHA256SUMS"]
|
||||
B2 --> B4["docker: push ghcr.io :latest + :vX.Y.Z"]
|
||||
```
|
||||
|
||||
## Quick Troubleshooting
|
||||
|
||||
1. **Quality gate failing on PR**: check `lint` job for formatting/clippy issues; check `test` job for test failures; check `build` job for compile errors; check `security` job for audit/deny failures.
|
||||
2. **Beta release not appearing**: confirm the push landed on `master` (not another branch); check `release-beta-on-push.yml` run status.
|
||||
3. **Stable release failing at validate**: ensure `Cargo.toml` version matches the input version and the tag does not already exist.
|
||||
4. **Full matrix build needed**: run `cross-platform-build-manual.yml` manually from the Actions tab.
|
||||
19
.github/workflows/pr-path-labeler.yml
vendored
19
.github/workflows/pr-path-labeler.yml
vendored
@ -1,19 +0,0 @@
|
||||
name: PR Path Labeler
|
||||
|
||||
on:
|
||||
pull_request_target:
|
||||
types: [opened, synchronize, reopened]
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
pull-requests: write
|
||||
|
||||
jobs:
|
||||
label:
|
||||
name: Apply path labels
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
steps:
|
||||
- uses: actions/labeler@8558fd74291d67161a8a78ce36a881fa63b766a9 # v5
|
||||
with:
|
||||
sync-labels: true
|
||||
186
.github/workflows/promote-release.yml
vendored
Normal file
186
.github/workflows/promote-release.yml
vendored
Normal file
@ -0,0 +1,186 @@
|
||||
name: Promote Release
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Stable version to release (e.g. 0.2.0)"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
concurrency:
|
||||
group: promote-release
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
name: Validate Version
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
tag: ${{ steps.check.outputs.tag }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Validate semver and Cargo.toml match
|
||||
id: check
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
input_version="${{ inputs.version }}"
|
||||
cargo_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
|
||||
if [[ ! "$input_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "::error::Version must be semver (X.Y.Z). Got: ${input_version}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$cargo_version" != "$input_version" ]]; then
|
||||
echo "::error::Cargo.toml version (${cargo_version}) does not match input (${input_version}). Bump Cargo.toml first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
tag="v${input_version}"
|
||||
if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
|
||||
echo "::error::Tag ${tag} already exists."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "tag=${tag}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
needs: [validate]
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
target: x86_64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-latest
|
||||
target: aarch64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-aarch64-linux-gnu
|
||||
linker_env: CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
|
||||
linker: aarch64-linux-gnu-gcc
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: macos-13
|
||||
target: x86_64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
artifact: zeroclaw.exe
|
||||
ext: zip
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
if: runner.os != 'Windows'
|
||||
|
||||
- name: Install cross compiler
|
||||
if: matrix.cross_compiler
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y ${{ matrix.cross_compiler }}
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: |
|
||||
if [ -n "${{ matrix.linker_env || '' }}" ] && [ -n "${{ matrix.linker || '' }}" ]; then
|
||||
export "${{ matrix.linker_env }}=${{ matrix.linker }}"
|
||||
fi
|
||||
cargo build --release --locked --target ${{ matrix.target }}
|
||||
|
||||
- name: Package (Unix)
|
||||
if: runner.os != 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
tar czf ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- name: Package (Windows)
|
||||
if: runner.os == 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
7z a ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: zeroclaw-${{ matrix.target }}
|
||||
path: zeroclaw-${{ matrix.target }}.${{ matrix.ext }}
|
||||
retention-days: 14
|
||||
|
||||
publish:
|
||||
name: Publish Stable Release
|
||||
needs: [validate, build]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
path: artifacts
|
||||
|
||||
- name: Generate checksums
|
||||
run: |
|
||||
cd artifacts
|
||||
find . -type f \( -name '*.tar.gz' -o -name '*.zip' \) -exec sha256sum {} + | sed 's| \./[^/]*/| |' > SHA256SUMS
|
||||
cat SHA256SUMS
|
||||
|
||||
- name: Create GitHub Release
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
tag_name: ${{ needs.validate.outputs.tag }}
|
||||
name: ${{ needs.validate.outputs.tag }}
|
||||
prerelease: false
|
||||
generate_release_notes: true
|
||||
files: |
|
||||
artifacts/**/*
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
docker:
|
||||
name: Push Docker Image
|
||||
needs: [validate, build]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
- uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v6
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.validate.outputs.tag }}
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
|
||||
platforms: linux/amd64,linux/arm64
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
181
.github/workflows/pub-aur.yml
vendored
181
.github/workflows/pub-aur.yml
vendored
@ -1,181 +0,0 @@
|
||||
name: Pub AUR Package
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Generate PKGBUILD only (no push)"
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
secrets:
|
||||
AUR_SSH_KEY:
|
||||
required: false
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Generate PKGBUILD only (no push)"
|
||||
required: false
|
||||
default: true
|
||||
type: boolean
|
||||
|
||||
concurrency:
|
||||
group: aur-publish-${{ github.run_id }}
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
publish-aur:
|
||||
name: Update AUR Package
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
RELEASE_TAG: ${{ inputs.release_tag }}
|
||||
DRY_RUN: ${{ inputs.dry_run }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Validate and compute metadata
|
||||
id: meta
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "::error::release_tag must be vX.Y.Z format."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
version="${RELEASE_TAG#v}"
|
||||
tarball_url="https://github.com/${GITHUB_REPOSITORY}/archive/refs/tags/${RELEASE_TAG}.tar.gz"
|
||||
tarball_sha="$(curl -fsSL "$tarball_url" | sha256sum | awk '{print $1}')"
|
||||
|
||||
if [[ -z "$tarball_sha" ]]; then
|
||||
echo "::error::Could not compute SHA256 for source tarball."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
{
|
||||
echo "version=$version"
|
||||
echo "tarball_url=$tarball_url"
|
||||
echo "tarball_sha=$tarball_sha"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
{
|
||||
echo "### AUR Package Metadata"
|
||||
echo "- version: \`${version}\`"
|
||||
echo "- tarball_url: \`${tarball_url}\`"
|
||||
echo "- tarball_sha: \`${tarball_sha}\`"
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Generate PKGBUILD
|
||||
id: pkgbuild
|
||||
shell: bash
|
||||
env:
|
||||
VERSION: ${{ steps.meta.outputs.version }}
|
||||
TARBALL_SHA: ${{ steps.meta.outputs.tarball_sha }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
pkgbuild_file="$(mktemp)"
|
||||
sed -e "s/^pkgver=.*/pkgver=${VERSION}/" \
|
||||
-e "s/^sha256sums=.*/sha256sums=('${TARBALL_SHA}')/" \
|
||||
dist/aur/PKGBUILD > "$pkgbuild_file"
|
||||
|
||||
echo "pkgbuild_file=$pkgbuild_file" >> "$GITHUB_OUTPUT"
|
||||
|
||||
echo "### Generated PKGBUILD" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo '```bash' >> "$GITHUB_STEP_SUMMARY"
|
||||
cat "$pkgbuild_file" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo '```' >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Generate .SRCINFO
|
||||
id: srcinfo
|
||||
shell: bash
|
||||
env:
|
||||
VERSION: ${{ steps.meta.outputs.version }}
|
||||
TARBALL_SHA: ${{ steps.meta.outputs.tarball_sha }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
srcinfo_file="$(mktemp)"
|
||||
sed -e "s/pkgver = .*/pkgver = ${VERSION}/" \
|
||||
-e "s/sha256sums = .*/sha256sums = ${TARBALL_SHA}/" \
|
||||
-e "s|zeroclaw-[0-9.]*.tar.gz|zeroclaw-${VERSION}.tar.gz|g" \
|
||||
-e "s|/v[0-9.]*\.tar\.gz|/v${VERSION}.tar.gz|g" \
|
||||
dist/aur/.SRCINFO > "$srcinfo_file"
|
||||
|
||||
echo "srcinfo_file=$srcinfo_file" >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Push to AUR
|
||||
if: inputs.dry_run == false
|
||||
shell: bash
|
||||
env:
|
||||
AUR_SSH_KEY: ${{ secrets.AUR_SSH_KEY }}
|
||||
PKGBUILD_FILE: ${{ steps.pkgbuild.outputs.pkgbuild_file }}
|
||||
SRCINFO_FILE: ${{ steps.srcinfo.outputs.srcinfo_file }}
|
||||
VERSION: ${{ steps.meta.outputs.version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [[ -z "${AUR_SSH_KEY}" ]]; then
|
||||
echo "::error::Secret AUR_SSH_KEY is required for non-dry-run."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Set up SSH key — normalize line endings and ensure trailing newline
|
||||
mkdir -p ~/.ssh
|
||||
chmod 700 ~/.ssh
|
||||
printf '%s\n' "$AUR_SSH_KEY" | tr -d '\r' > ~/.ssh/aur
|
||||
chmod 600 ~/.ssh/aur
|
||||
|
||||
cat > ~/.ssh/config <<'SSH_CONFIG'
|
||||
Host aur.archlinux.org
|
||||
IdentityFile ~/.ssh/aur
|
||||
User aur
|
||||
StrictHostKeyChecking accept-new
|
||||
SSH_CONFIG
|
||||
chmod 600 ~/.ssh/config
|
||||
|
||||
# Verify key is valid and print fingerprint for debugging
|
||||
echo "::group::SSH key diagnostics"
|
||||
ssh-keygen -l -f ~/.ssh/aur || { echo "::error::AUR_SSH_KEY is not a valid SSH private key"; exit 1; }
|
||||
echo "::endgroup::"
|
||||
|
||||
# Test SSH connectivity before attempting clone
|
||||
ssh -T -o BatchMode=yes -o ConnectTimeout=10 aur@aur.archlinux.org 2>&1 || true
|
||||
|
||||
tmp_dir="$(mktemp -d)"
|
||||
git clone ssh://aur@aur.archlinux.org/zeroclaw.git "$tmp_dir/aur"
|
||||
|
||||
cp "$PKGBUILD_FILE" "$tmp_dir/aur/PKGBUILD"
|
||||
cp "$SRCINFO_FILE" "$tmp_dir/aur/.SRCINFO"
|
||||
|
||||
cd "$tmp_dir/aur"
|
||||
git config user.name "zeroclaw-bot"
|
||||
git config user.email "bot@zeroclaw.dev"
|
||||
git add PKGBUILD .SRCINFO
|
||||
git commit -m "zeroclaw ${VERSION}"
|
||||
git push origin HEAD
|
||||
|
||||
echo "AUR package updated to ${VERSION}"
|
||||
|
||||
- name: Summary
|
||||
shell: bash
|
||||
run: |
|
||||
if [[ "$DRY_RUN" == "true" ]]; then
|
||||
echo "Dry run complete: PKGBUILD generated, no push performed."
|
||||
else
|
||||
echo "Publish complete: AUR package pushed."
|
||||
fi
|
||||
228
.github/workflows/pub-homebrew-core.yml
vendored
228
.github/workflows/pub-homebrew-core.yml
vendored
@ -1,228 +0,0 @@
|
||||
name: Pub Homebrew Core
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag to publish (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Patch formula only (no push/PR)"
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
secrets:
|
||||
HOMEBREW_UPSTREAM_PR_TOKEN:
|
||||
required: false
|
||||
HOMEBREW_CORE_BOT_TOKEN:
|
||||
required: false
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag to publish (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Patch formula only (no push/PR)"
|
||||
required: false
|
||||
default: true
|
||||
type: boolean
|
||||
|
||||
concurrency:
|
||||
group: homebrew-core-${{ github.run_id }}
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
publish-homebrew-core:
|
||||
name: Publish Homebrew Core PR
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
UPSTREAM_REPO: Homebrew/homebrew-core
|
||||
FORMULA_PATH: Formula/z/zeroclaw.rb
|
||||
RELEASE_TAG: ${{ inputs.release_tag }}
|
||||
DRY_RUN: ${{ inputs.dry_run }}
|
||||
BOT_FORK_REPO: ${{ vars.HOMEBREW_CORE_BOT_FORK_REPO }}
|
||||
BOT_EMAIL: ${{ vars.HOMEBREW_CORE_BOT_EMAIL }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Validate release tag and version alignment
|
||||
id: release_meta
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
semver_pattern='^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$'
|
||||
if [[ ! "$RELEASE_TAG" =~ $semver_pattern ]]; then
|
||||
echo "::error::release_tag must match semver-like format (vX.Y.Z[-suffix])."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if ! git rev-parse "refs/tags/${RELEASE_TAG}" >/dev/null 2>&1; then
|
||||
git fetch --tags origin
|
||||
fi
|
||||
|
||||
tag_version="${RELEASE_TAG#v}"
|
||||
cargo_version="$(git show "${RELEASE_TAG}:Cargo.toml" \
|
||||
| sed -n 's/^version = "\([^"]*\)"/\1/p' | head -n1)"
|
||||
if [[ -z "$cargo_version" ]]; then
|
||||
echo "::error::Unable to read Cargo.toml version from tag ${RELEASE_TAG}."
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$cargo_version" != "$tag_version" ]]; then
|
||||
echo "::error::Tag ${RELEASE_TAG} does not match Cargo.toml version (${cargo_version})."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
tarball_url="https://github.com/${GITHUB_REPOSITORY}/archive/refs/tags/${RELEASE_TAG}.tar.gz"
|
||||
tarball_sha="$(curl -fsSL "$tarball_url" | sha256sum | awk '{print $1}')"
|
||||
|
||||
{
|
||||
echo "tag_version=$tag_version"
|
||||
echo "tarball_url=$tarball_url"
|
||||
echo "tarball_sha=$tarball_sha"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
{
|
||||
echo "### Release Metadata"
|
||||
echo "- release_tag: \`${RELEASE_TAG}\`"
|
||||
echo "- cargo_version: \`${cargo_version}\`"
|
||||
echo "- tarball_sha256: \`${tarball_sha}\`"
|
||||
echo "- dry_run: ${DRY_RUN}"
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Patch Homebrew formula
|
||||
id: patch_formula
|
||||
shell: bash
|
||||
env:
|
||||
HOMEBREW_CORE_BOT_TOKEN: ${{ secrets.HOMEBREW_UPSTREAM_PR_TOKEN || secrets.HOMEBREW_CORE_BOT_TOKEN }}
|
||||
GH_TOKEN: ${{ secrets.HOMEBREW_UPSTREAM_PR_TOKEN || secrets.HOMEBREW_CORE_BOT_TOKEN }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
tmp_repo="$(mktemp -d)"
|
||||
echo "tmp_repo=$tmp_repo" >> "$GITHUB_OUTPUT"
|
||||
|
||||
if [[ "$DRY_RUN" == "true" ]]; then
|
||||
git clone --depth=1 "https://github.com/${UPSTREAM_REPO}.git" "$tmp_repo/homebrew-core"
|
||||
else
|
||||
if [[ -z "${BOT_FORK_REPO}" ]]; then
|
||||
echo "::error::Repository variable HOMEBREW_CORE_BOT_FORK_REPO is required when dry_run=false."
|
||||
exit 1
|
||||
fi
|
||||
if [[ -z "${HOMEBREW_CORE_BOT_TOKEN}" ]]; then
|
||||
echo "::error::Repository secret HOMEBREW_CORE_BOT_TOKEN is required when dry_run=false."
|
||||
exit 1
|
||||
fi
|
||||
if [[ "$BOT_FORK_REPO" != */* ]]; then
|
||||
echo "::error::HOMEBREW_CORE_BOT_FORK_REPO must be in owner/repo format."
|
||||
exit 1
|
||||
fi
|
||||
if ! gh api "repos/${BOT_FORK_REPO}" >/dev/null 2>&1; then
|
||||
echo "::error::HOMEBREW_CORE_BOT_TOKEN cannot access ${BOT_FORK_REPO}."
|
||||
exit 1
|
||||
fi
|
||||
gh repo clone "${BOT_FORK_REPO}" "$tmp_repo/homebrew-core" -- --depth=1
|
||||
fi
|
||||
|
||||
repo_dir="$tmp_repo/homebrew-core"
|
||||
formula_file="$repo_dir/$FORMULA_PATH"
|
||||
if [[ ! -f "$formula_file" ]]; then
|
||||
echo "::error::Formula file not found: $FORMULA_PATH"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$DRY_RUN" == "false" ]]; then
|
||||
if git -C "$repo_dir" remote get-url upstream >/dev/null 2>&1; then
|
||||
git -C "$repo_dir" remote set-url upstream "https://github.com/${UPSTREAM_REPO}.git"
|
||||
else
|
||||
git -C "$repo_dir" remote add upstream "https://github.com/${UPSTREAM_REPO}.git"
|
||||
fi
|
||||
if git -C "$repo_dir" ls-remote --exit-code --heads upstream main >/dev/null 2>&1; then
|
||||
upstream_ref="main"
|
||||
else
|
||||
upstream_ref="master"
|
||||
fi
|
||||
git -C "$repo_dir" fetch --depth=1 upstream "$upstream_ref"
|
||||
branch_name="zeroclaw-${RELEASE_TAG}-${GITHUB_RUN_ID}"
|
||||
git -C "$repo_dir" checkout -B "$branch_name" "upstream/$upstream_ref"
|
||||
echo "branch_name=$branch_name" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
tarball_url="$(grep 'tarball_url=' "$GITHUB_OUTPUT" | head -1 | cut -d= -f2-)"
|
||||
tarball_sha="$(grep 'tarball_sha=' "$GITHUB_OUTPUT" | head -1 | cut -d= -f2-)"
|
||||
|
||||
perl -0pi -e "s|^ url \".*\"| url \"${tarball_url}\"|m" "$formula_file"
|
||||
perl -0pi -e "s|^ sha256 \".*\"| sha256 \"${tarball_sha}\"|m" "$formula_file"
|
||||
perl -0pi -e "s|^ license \".*\"| license \"Apache-2.0 OR MIT\"|m" "$formula_file"
|
||||
|
||||
# Ensure Node.js build dependency is declared so that build.rs can
|
||||
# run `npm ci && npm run build` to produce the web frontend assets.
|
||||
if ! grep -q 'depends_on "node" => :build' "$formula_file"; then
|
||||
perl -0pi -e 's|( depends_on "rust" => :build\n)|\1 depends_on "node" => :build\n|m' "$formula_file"
|
||||
fi
|
||||
|
||||
git -C "$repo_dir" diff -- "$FORMULA_PATH" > "$tmp_repo/formula.diff"
|
||||
if [[ ! -s "$tmp_repo/formula.diff" ]]; then
|
||||
echo "::error::No formula changes generated. Nothing to publish."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
{
|
||||
echo "### Formula Diff"
|
||||
echo '```diff'
|
||||
cat "$tmp_repo/formula.diff"
|
||||
echo '```'
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Push branch and open Homebrew PR
|
||||
if: inputs.dry_run == false
|
||||
shell: bash
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.HOMEBREW_UPSTREAM_PR_TOKEN || secrets.HOMEBREW_CORE_BOT_TOKEN }}
|
||||
TMP_REPO: ${{ steps.patch_formula.outputs.tmp_repo }}
|
||||
BRANCH_NAME: ${{ steps.patch_formula.outputs.branch_name }}
|
||||
TAG_VERSION: ${{ steps.release_meta.outputs.tag_version }}
|
||||
TARBALL_URL: ${{ steps.release_meta.outputs.tarball_url }}
|
||||
TARBALL_SHA: ${{ steps.release_meta.outputs.tarball_sha }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
repo_dir="${TMP_REPO}/homebrew-core"
|
||||
fork_owner="${BOT_FORK_REPO%%/*}"
|
||||
bot_email="${BOT_EMAIL:-${fork_owner}@users.noreply.github.com}"
|
||||
|
||||
git -C "$repo_dir" config user.name "$fork_owner"
|
||||
git -C "$repo_dir" config user.email "$bot_email"
|
||||
git -C "$repo_dir" add "$FORMULA_PATH"
|
||||
git -C "$repo_dir" commit -m "zeroclaw ${TAG_VERSION}"
|
||||
gh auth setup-git
|
||||
git -C "$repo_dir" push --set-upstream origin "$BRANCH_NAME"
|
||||
|
||||
pr_body="Automated formula bump from ZeroClaw release workflow.
|
||||
|
||||
- Release tag: ${RELEASE_TAG}
|
||||
- Source tarball: ${TARBALL_URL}
|
||||
- Source sha256: ${TARBALL_SHA}"
|
||||
|
||||
gh pr create \
|
||||
--repo "$UPSTREAM_REPO" \
|
||||
--base main \
|
||||
--head "${fork_owner}:${BRANCH_NAME}" \
|
||||
--title "zeroclaw ${TAG_VERSION}" \
|
||||
--body "$pr_body"
|
||||
|
||||
- name: Summary
|
||||
shell: bash
|
||||
run: |
|
||||
if [[ "$DRY_RUN" == "true" ]]; then
|
||||
echo "Dry run complete: formula diff generated, no push/PR performed."
|
||||
else
|
||||
echo "Publish complete: branch pushed and PR opened from bot fork."
|
||||
fi
|
||||
165
.github/workflows/pub-scoop.yml
vendored
165
.github/workflows/pub-scoop.yml
vendored
@ -1,165 +0,0 @@
|
||||
name: Pub Scoop Manifest
|
||||
|
||||
on:
|
||||
workflow_call:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Generate manifest only (no push)"
|
||||
required: false
|
||||
default: false
|
||||
type: boolean
|
||||
secrets:
|
||||
SCOOP_BUCKET_TOKEN:
|
||||
required: false
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Existing release tag (vX.Y.Z)"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Generate manifest only (no push)"
|
||||
required: false
|
||||
default: true
|
||||
type: boolean
|
||||
|
||||
concurrency:
|
||||
group: scoop-publish-${{ github.run_id }}
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
jobs:
|
||||
publish-scoop:
|
||||
name: Update Scoop Manifest
|
||||
runs-on: ubuntu-latest
|
||||
env:
|
||||
RELEASE_TAG: ${{ inputs.release_tag }}
|
||||
DRY_RUN: ${{ inputs.dry_run }}
|
||||
SCOOP_BUCKET_REPO: ${{ vars.SCOOP_BUCKET_REPO }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Validate and compute metadata
|
||||
id: meta
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "::error::release_tag must be vX.Y.Z format."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
version="${RELEASE_TAG#v}"
|
||||
zip_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/${RELEASE_TAG}/zeroclaw-x86_64-pc-windows-msvc.zip"
|
||||
sums_url="https://github.com/${GITHUB_REPOSITORY}/releases/download/${RELEASE_TAG}/SHA256SUMS"
|
||||
|
||||
sha256="$(curl -fsSL "$sums_url" | grep 'zeroclaw-x86_64-pc-windows-msvc.zip' | awk '{print $1}')"
|
||||
|
||||
if [[ -z "$sha256" ]]; then
|
||||
echo "::error::Could not find Windows binary hash in SHA256SUMS for ${RELEASE_TAG}."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
{
|
||||
echo "version=$version"
|
||||
echo "zip_url=$zip_url"
|
||||
echo "sha256=$sha256"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
{
|
||||
echo "### Scoop Manifest Metadata"
|
||||
echo "- version: \`${version}\`"
|
||||
echo "- zip_url: \`${zip_url}\`"
|
||||
echo "- sha256: \`${sha256}\`"
|
||||
} >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Generate manifest
|
||||
id: manifest
|
||||
shell: bash
|
||||
env:
|
||||
VERSION: ${{ steps.meta.outputs.version }}
|
||||
ZIP_URL: ${{ steps.meta.outputs.zip_url }}
|
||||
SHA256: ${{ steps.meta.outputs.sha256 }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
manifest_file="$(mktemp)"
|
||||
cat > "$manifest_file" <<MANIFEST
|
||||
{
|
||||
"version": "${VERSION}",
|
||||
"description": "Zero overhead. Zero compromise. 100% Rust. The fastest, smallest AI assistant.",
|
||||
"homepage": "https://github.com/zeroclaw-labs/zeroclaw",
|
||||
"license": "MIT|Apache-2.0",
|
||||
"architecture": {
|
||||
"64bit": {
|
||||
"url": "${ZIP_URL}",
|
||||
"hash": "${SHA256}",
|
||||
"bin": "zeroclaw.exe"
|
||||
}
|
||||
},
|
||||
"checkver": {
|
||||
"github": "https://github.com/zeroclaw-labs/zeroclaw"
|
||||
},
|
||||
"autoupdate": {
|
||||
"architecture": {
|
||||
"64bit": {
|
||||
"url": "https://github.com/zeroclaw-labs/zeroclaw/releases/download/v\$version/zeroclaw-x86_64-pc-windows-msvc.zip"
|
||||
}
|
||||
},
|
||||
"hash": {
|
||||
"url": "https://github.com/zeroclaw-labs/zeroclaw/releases/download/v\$version/SHA256SUMS",
|
||||
"regex": "([a-f0-9]{64})\\\\s+zeroclaw-x86_64-pc-windows-msvc\\\\.zip"
|
||||
}
|
||||
}
|
||||
}
|
||||
MANIFEST
|
||||
|
||||
jq '.' "$manifest_file" > "${manifest_file}.formatted"
|
||||
mv "${manifest_file}.formatted" "$manifest_file"
|
||||
|
||||
echo "manifest_file=$manifest_file" >> "$GITHUB_OUTPUT"
|
||||
|
||||
echo "### Generated Manifest" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo '```json' >> "$GITHUB_STEP_SUMMARY"
|
||||
cat "$manifest_file" >> "$GITHUB_STEP_SUMMARY"
|
||||
echo '```' >> "$GITHUB_STEP_SUMMARY"
|
||||
|
||||
- name: Push to Scoop bucket
|
||||
if: inputs.dry_run == false
|
||||
shell: bash
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.SCOOP_BUCKET_TOKEN }}
|
||||
MANIFEST_FILE: ${{ steps.manifest.outputs.manifest_file }}
|
||||
VERSION: ${{ steps.meta.outputs.version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [[ -z "${SCOOP_BUCKET_REPO}" ]]; then
|
||||
echo "::error::Repository variable SCOOP_BUCKET_REPO is required (e.g. zeroclaw-labs/scoop-zeroclaw)."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
tmp_dir="$(mktemp -d)"
|
||||
gh repo clone "${SCOOP_BUCKET_REPO}" "$tmp_dir/bucket" -- --depth=1
|
||||
|
||||
mkdir -p "$tmp_dir/bucket/bucket"
|
||||
cp "$MANIFEST_FILE" "$tmp_dir/bucket/bucket/zeroclaw.json"
|
||||
|
||||
cd "$tmp_dir/bucket"
|
||||
git config user.name "zeroclaw-bot"
|
||||
git config user.email "bot@zeroclaw.dev"
|
||||
git add bucket/zeroclaw.json
|
||||
git commit -m "zeroclaw ${VERSION}"
|
||||
gh auth setup-git
|
||||
git push origin HEAD
|
||||
|
||||
echo "Scoop manifest updated to ${VERSION}"
|
||||
160
.github/workflows/publish-crates-auto.yml
vendored
160
.github/workflows/publish-crates-auto.yml
vendored
@ -1,160 +0,0 @@
|
||||
name: Auto-sync crates.io
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
paths:
|
||||
- "Cargo.toml"
|
||||
|
||||
concurrency:
|
||||
group: publish-crates-auto
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
|
||||
jobs:
|
||||
detect-version-change:
|
||||
name: Detect Version Bump
|
||||
if: github.repository == 'zeroclaw-labs/zeroclaw'
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
changed: ${{ steps.check.outputs.changed }}
|
||||
version: ${{ steps.check.outputs.version }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 2
|
||||
|
||||
- name: Check if version changed
|
||||
id: check
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
current=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
previous=$(git show HEAD~1:Cargo.toml 2>/dev/null | sed -n 's/^version = "\([^"]*\)"/\1/p' | head -1 || echo "")
|
||||
|
||||
echo "Current version: ${current}"
|
||||
echo "Previous version: ${previous}"
|
||||
|
||||
# Skip if stable release workflow will handle this version
|
||||
# (indicated by an existing or imminent stable tag)
|
||||
if git ls-remote --exit-code --tags origin "refs/tags/v${current}" >/dev/null 2>&1; then
|
||||
echo "Stable tag v${current} exists — stable release workflow handles crates.io"
|
||||
echo "changed=false" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
if [[ "$current" != "$previous" && -n "$current" ]]; then
|
||||
echo "changed=true" >> "$GITHUB_OUTPUT"
|
||||
echo "version=${current}" >> "$GITHUB_OUTPUT"
|
||||
echo "Version bumped from ${previous} to ${current} — will publish"
|
||||
else
|
||||
echo "changed=false" >> "$GITHUB_OUTPUT"
|
||||
echo "Version unchanged (${current}) — skipping publish"
|
||||
fi
|
||||
|
||||
check-registry:
|
||||
name: Check if Already Published
|
||||
needs: [detect-version-change]
|
||||
if: needs.detect-version-change.outputs.changed == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
should_publish: ${{ steps.check.outputs.should_publish }}
|
||||
steps:
|
||||
- name: Check crates.io for existing version
|
||||
id: check
|
||||
shell: bash
|
||||
env:
|
||||
VERSION: ${{ needs.detect-version-change.outputs.version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
status=$(curl -s -o /dev/null -w "%{http_code}" \
|
||||
"https://crates.io/api/v1/crates/zeroclawlabs/${VERSION}")
|
||||
|
||||
if [[ "$status" == "200" ]]; then
|
||||
echo "Version ${VERSION} already exists on crates.io — skipping"
|
||||
echo "should_publish=false" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "Version ${VERSION} not yet published — proceeding"
|
||||
echo "should_publish=true" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
publish:
|
||||
name: Publish to crates.io
|
||||
needs: [detect-version-change, check-registry]
|
||||
if: needs.check-registry.outputs.should_publish == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
|
||||
- name: Clean web build artifacts
|
||||
run: rm -rf web/node_modules web/src web/package.json web/package-lock.json web/tsconfig*.json web/vite.config.ts web/index.html
|
||||
|
||||
- name: Publish aardvark-sys to crates.io
|
||||
shell: bash
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
run: |
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify -p aardvark-sys 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::aardvark-sys already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
|
||||
- name: Wait for aardvark-sys to index
|
||||
run: sleep 15
|
||||
|
||||
- name: Publish to crates.io
|
||||
shell: bash
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
VERSION: ${{ needs.detect-version-change.outputs.version }}
|
||||
run: |
|
||||
# Publish to crates.io; treat "already exists" as success
|
||||
# (manual publish or stable workflow may have already published)
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::zeroclawlabs@${VERSION} already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
|
||||
- name: Verify published
|
||||
shell: bash
|
||||
env:
|
||||
VERSION: ${{ needs.detect-version-change.outputs.version }}
|
||||
run: |
|
||||
echo "Waiting for crates.io to index..."
|
||||
sleep 15
|
||||
status=$(curl -s -o /dev/null -w "%{http_code}" \
|
||||
"https://crates.io/api/v1/crates/zeroclawlabs/${VERSION}")
|
||||
if [[ "$status" == "200" ]]; then
|
||||
echo "zeroclawlabs v${VERSION} is live on crates.io"
|
||||
echo "Install: cargo install zeroclawlabs"
|
||||
else
|
||||
echo "::warning::Version may still be indexing — check https://crates.io/crates/zeroclawlabs"
|
||||
fi
|
||||
108
.github/workflows/publish-crates.yml
vendored
108
.github/workflows/publish-crates.yml
vendored
@ -1,108 +0,0 @@
|
||||
name: Publish to crates.io
|
||||
|
||||
on:
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Version to publish (e.g. 0.2.0) — must match Cargo.toml"
|
||||
required: true
|
||||
type: string
|
||||
dry_run:
|
||||
description: "Dry run (validate without publishing)"
|
||||
required: false
|
||||
type: boolean
|
||||
default: false
|
||||
|
||||
concurrency:
|
||||
group: publish-crates
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
name: Validate
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Check version matches Cargo.toml
|
||||
shell: bash
|
||||
env:
|
||||
INPUT_VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
if [[ "$cargo_version" != "$INPUT_VERSION" ]]; then
|
||||
echo "::error::Cargo.toml version (${cargo_version}) does not match input (${INPUT_VERSION})"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
publish:
|
||||
name: Publish to crates.io
|
||||
needs: [validate]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
|
||||
- name: Clean web build artifacts
|
||||
run: rm -rf web/node_modules web/src web/package.json web/package-lock.json web/tsconfig*.json web/vite.config.ts web/index.html
|
||||
|
||||
- name: Publish aardvark-sys to crates.io
|
||||
if: "!inputs.dry_run"
|
||||
shell: bash
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
run: |
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify -p aardvark-sys 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::aardvark-sys already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
|
||||
- name: Wait for aardvark-sys to index
|
||||
if: "!inputs.dry_run"
|
||||
run: sleep 15
|
||||
|
||||
- name: Publish (dry run)
|
||||
if: inputs.dry_run
|
||||
run: cargo publish --dry-run --locked --allow-dirty --no-verify
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
|
||||
- name: Publish to crates.io
|
||||
if: "!inputs.dry_run"
|
||||
shell: bash
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
# Publish to crates.io; treat "already exists" as success
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::zeroclawlabs@${VERSION} already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
458
.github/workflows/release-beta-on-push.yml
vendored
458
.github/workflows/release-beta-on-push.yml
vendored
@ -1,458 +0,0 @@
|
||||
name: Release Beta
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
|
||||
concurrency:
|
||||
group: release-beta
|
||||
cancel-in-progress: true
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
RELEASE_CARGO_FEATURES: channel-matrix,channel-lark,memory-postgres
|
||||
|
||||
jobs:
|
||||
version:
|
||||
name: Resolve Version
|
||||
if: github.repository == 'zeroclaw-labs/zeroclaw'
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
version: ${{ steps.ver.outputs.version }}
|
||||
tag: ${{ steps.ver.outputs.tag }}
|
||||
skip: ${{ steps.ver.outputs.skip }}
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 2
|
||||
- name: Compute beta version
|
||||
id: ver
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
base_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
|
||||
# Skip beta if this is a version bump commit (stable release handles it)
|
||||
commit_msg=$(git log -1 --pretty=format:"%s")
|
||||
if [[ "$commit_msg" =~ ^chore:\ bump\ version ]]; then
|
||||
echo "Version bump commit detected — skipping beta release"
|
||||
echo "skip=true" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Skip beta if a stable tag already exists for this version
|
||||
if git ls-remote --exit-code --tags origin "refs/tags/v${base_version}" >/dev/null 2>&1; then
|
||||
echo "Stable tag v${base_version} exists — skipping beta release"
|
||||
echo "skip=true" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
beta_tag="v${base_version}-beta.${GITHUB_RUN_NUMBER}"
|
||||
echo "version=${base_version}" >> "$GITHUB_OUTPUT"
|
||||
echo "tag=${beta_tag}" >> "$GITHUB_OUTPUT"
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
echo "Beta release: ${beta_tag}"
|
||||
|
||||
release-notes:
|
||||
name: Generate Release Notes
|
||||
needs: [version]
|
||||
if: github.repository == 'zeroclaw-labs/zeroclaw' && needs.version.outputs.skip != 'true'
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
notes: ${{ steps.notes.outputs.body }}
|
||||
features: ${{ steps.notes.outputs.features }}
|
||||
contributors: ${{ steps.notes.outputs.contributors }}
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Build release notes
|
||||
id: notes
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
# Use a wider range — find the previous stable tag to capture all
|
||||
# contributors across the full release cycle, not just one beta bump
|
||||
PREV_TAG=$(git tag --sort=-creatordate \
|
||||
| grep -vE '\-beta\.' \
|
||||
| head -1 || echo "")
|
||||
if [ -z "$PREV_TAG" ]; then
|
||||
RANGE="HEAD"
|
||||
else
|
||||
RANGE="${PREV_TAG}..HEAD"
|
||||
fi
|
||||
|
||||
# Extract features only (feat commits) — skip bug fixes for clean notes
|
||||
FEATURES=$(git log "$RANGE" --pretty=format:"%s" --no-merges \
|
||||
| grep -iE '^feat(\(|:)' \
|
||||
| sed 's/^feat(\([^)]*\)): /\1: /' \
|
||||
| sed 's/^feat: //' \
|
||||
| sed 's/ (#[0-9]*)$//' \
|
||||
| sort -uf \
|
||||
| while IFS= read -r line; do echo "- ${line}"; done || true)
|
||||
|
||||
if [ -z "$FEATURES" ]; then
|
||||
FEATURES="- Incremental improvements and polish"
|
||||
fi
|
||||
|
||||
# Collect ALL unique contributors: git authors + Co-Authored-By
|
||||
GIT_AUTHORS=$(git log "$RANGE" --pretty=format:"%an" --no-merges | sort -uf || true)
|
||||
CO_AUTHORS=$(git log "$RANGE" --pretty=format:"%b" --no-merges \
|
||||
| grep -ioE 'Co-Authored-By: *[^<]+' \
|
||||
| sed 's/Co-Authored-By: *//i' \
|
||||
| sed 's/ *$//' \
|
||||
| sort -uf || true)
|
||||
|
||||
# Merge, deduplicate, and filter out bots
|
||||
ALL_CONTRIBUTORS=$(printf "%s\n%s" "$GIT_AUTHORS" "$CO_AUTHORS" \
|
||||
| sort -uf \
|
||||
| grep -v '^$' \
|
||||
| grep -viE '\[bot\]$|^dependabot|^github-actions|^copilot|^ZeroClaw Bot|^ZeroClaw Runner|^ZeroClaw Agent|^blacksmith' \
|
||||
| while IFS= read -r name; do echo "- ${name}"; done || true)
|
||||
|
||||
# Build release body
|
||||
BODY=$(cat <<NOTES_EOF
|
||||
## What's New
|
||||
|
||||
${FEATURES}
|
||||
|
||||
## Contributors
|
||||
|
||||
${ALL_CONTRIBUTORS}
|
||||
|
||||
---
|
||||
*Full changelog: ${PREV_TAG}...HEAD*
|
||||
NOTES_EOF
|
||||
)
|
||||
|
||||
# Output multiline values
|
||||
{
|
||||
echo "body<<BODY_EOF"
|
||||
echo "$BODY"
|
||||
echo "BODY_EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
{
|
||||
echo "features<<FEAT_EOF"
|
||||
echo "$FEATURES"
|
||||
echo "FEAT_EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
{
|
||||
echo "contributors<<CONTRIB_EOF"
|
||||
echo "$ALL_CONTRIBUTORS"
|
||||
echo "CONTRIB_EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
web:
|
||||
name: Build Web Dashboard
|
||||
needs: [version]
|
||||
if: github.repository == 'zeroclaw-labs/zeroclaw' && needs.version.outputs.skip != 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
retention-days: 1
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
needs: [version, web]
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
# Use ubuntu-22.04 for Linux builds to link against glibc 2.35,
|
||||
# ensuring compatibility with Ubuntu 22.04+ (#3573).
|
||||
- os: ubuntu-22.04
|
||||
target: x86_64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-22.04
|
||||
target: aarch64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-aarch64-linux-gnu
|
||||
linker_env: CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
|
||||
linker: aarch64-linux-gnu-gcc
|
||||
- os: ubuntu-22.04
|
||||
target: armv7-unknown-linux-gnueabihf
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-arm-linux-gnueabihf
|
||||
linker_env: CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER
|
||||
linker: arm-linux-gnueabihf-gcc
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-latest
|
||||
target: aarch64-linux-android
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
ndk: true
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
artifact: zeroclaw.exe
|
||||
ext: zip
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
if: runner.os != 'Windows'
|
||||
with:
|
||||
prefix-key: ${{ matrix.os }}-${{ matrix.target }}
|
||||
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
|
||||
- name: Install cross compiler
|
||||
if: matrix.cross_compiler
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y ${{ matrix.cross_compiler }}
|
||||
|
||||
- name: Setup Android NDK
|
||||
if: matrix.ndk
|
||||
run: echo "$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin" >> "$GITHUB_PATH"
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: |
|
||||
if [ -n "${{ matrix.linker_env || '' }}" ] && [ -n "${{ matrix.linker || '' }}" ]; then
|
||||
export "${{ matrix.linker_env }}=${{ matrix.linker }}"
|
||||
fi
|
||||
cargo build --release --locked --features "${{ env.RELEASE_CARGO_FEATURES }}" --target ${{ matrix.target }}
|
||||
|
||||
- name: Package (Unix)
|
||||
if: runner.os != 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
tar czf ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- name: Package (Windows)
|
||||
if: runner.os == 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
7z a ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
||||
with:
|
||||
name: zeroclaw-${{ matrix.target }}
|
||||
path: zeroclaw-${{ matrix.target }}.${{ matrix.ext }}
|
||||
retention-days: 7
|
||||
|
||||
build-desktop:
|
||||
name: Build Desktop App (macOS Universal)
|
||||
needs: [version]
|
||||
if: needs.version.outputs.skip != 'true'
|
||||
runs-on: macos-14
|
||||
timeout-minutes: 40
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: aarch64-apple-darwin,x86_64-apple-darwin
|
||||
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
with:
|
||||
prefix-key: macos-tauri
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
|
||||
- name: Install Tauri CLI
|
||||
run: cargo install tauri-cli --locked
|
||||
|
||||
- name: Sync Tauri version with Cargo.toml
|
||||
shell: bash
|
||||
run: |
|
||||
VERSION=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
cd apps/tauri
|
||||
if command -v jq >/dev/null 2>&1; then
|
||||
jq --arg v "$VERSION" '.version = $v' tauri.conf.json > tmp.json && mv tmp.json tauri.conf.json
|
||||
else
|
||||
sed -i '' "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" tauri.conf.json
|
||||
fi
|
||||
echo "Tauri version set to: $VERSION"
|
||||
|
||||
- name: Build Tauri app (universal binary)
|
||||
working-directory: apps/tauri
|
||||
run: cargo tauri build --target universal-apple-darwin
|
||||
|
||||
- name: Prepare desktop release assets
|
||||
run: |
|
||||
mkdir -p desktop-assets
|
||||
find target -name '*.dmg' -exec cp {} desktop-assets/ZeroClaw.dmg \; 2>/dev/null || true
|
||||
find target -name '*.app.tar.gz' -exec cp {} desktop-assets/ZeroClaw-macos.app.tar.gz \; 2>/dev/null || true
|
||||
find target -name '*.app.tar.gz.sig' -exec cp {} desktop-assets/ZeroClaw-macos.app.tar.gz.sig \; 2>/dev/null || true
|
||||
echo "--- Desktop assets ---"
|
||||
ls -lh desktop-assets/
|
||||
|
||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
||||
with:
|
||||
name: desktop-macos
|
||||
path: desktop-assets/*
|
||||
retention-days: 7
|
||||
|
||||
publish:
|
||||
name: Publish Beta Release
|
||||
needs: [version, release-notes, build, build-desktop]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
pattern: zeroclaw-*
|
||||
path: artifacts
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: desktop-macos
|
||||
path: artifacts/desktop-macos
|
||||
|
||||
- name: Generate checksums
|
||||
run: |
|
||||
cd artifacts
|
||||
find . -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.dmg' \) -exec sha256sum {} + | sed 's| \./[^/]*/| |' > SHA256SUMS
|
||||
cat SHA256SUMS
|
||||
|
||||
- name: Collect release assets
|
||||
run: |
|
||||
mkdir -p release-assets
|
||||
find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.dmg' -o -name 'SHA256SUMS' \) -exec cp {} release-assets/ \;
|
||||
cp install.sh release-assets/
|
||||
echo "--- Assets ---"
|
||||
ls -lh release-assets/
|
||||
|
||||
- name: Write release notes
|
||||
env:
|
||||
NOTES: ${{ needs.release-notes.outputs.notes }}
|
||||
run: printf '%s\n' "$NOTES" > release-notes.md
|
||||
|
||||
- name: Create GitHub Release
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
|
||||
TAG: ${{ needs.version.outputs.tag }}
|
||||
run: |
|
||||
gh release create "$TAG" release-assets/* \
|
||||
--repo "${{ github.repository }}" \
|
||||
--title "$TAG" \
|
||||
--notes-file release-notes.md \
|
||||
--prerelease
|
||||
|
||||
redeploy-website:
|
||||
name: Trigger Website Redeploy
|
||||
needs: [publish]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Trigger website redeploy
|
||||
env:
|
||||
PAT: ${{ secrets.WEBSITE_REPO_PAT }}
|
||||
run: |
|
||||
curl -fsSL -X POST \
|
||||
-H "Authorization: token $PAT" \
|
||||
-H "Accept: application/vnd.github+json" \
|
||||
https://api.github.com/repos/zeroclaw-labs/zeroclaw-website/dispatches \
|
||||
-d '{"event_type":"new-release","client_payload":{"install_script_url":"https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh"}}'
|
||||
|
||||
docker:
|
||||
name: Push Docker Image
|
||||
needs: [version, build]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: zeroclaw-x86_64-unknown-linux-gnu
|
||||
path: artifacts/
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: zeroclaw-aarch64-unknown-linux-gnu
|
||||
path: artifacts/
|
||||
|
||||
- name: Prepare Docker context with pre-built binaries
|
||||
run: |
|
||||
mkdir -p docker-ctx/bin/amd64 docker-ctx/bin/arm64
|
||||
tar xzf artifacts/zeroclaw-x86_64-unknown-linux-gnu.tar.gz -C docker-ctx/bin/amd64
|
||||
tar xzf artifacts/zeroclaw-aarch64-unknown-linux-gnu.tar.gz -C docker-ctx/bin/arm64
|
||||
|
||||
mkdir -p docker-ctx/zeroclaw-data/.zeroclaw docker-ctx/zeroclaw-data/workspace
|
||||
printf '%s\n' \
|
||||
'workspace_dir = "/zeroclaw-data/workspace"' \
|
||||
'config_path = "/zeroclaw-data/.zeroclaw/config.toml"' \
|
||||
'api_key = ""' \
|
||||
'default_provider = "openrouter"' \
|
||||
'default_model = "anthropic/claude-sonnet-4-20250514"' \
|
||||
'default_temperature = 0.7' \
|
||||
'' \
|
||||
'[gateway]' \
|
||||
'port = 42617' \
|
||||
'host = "[::]"' \
|
||||
'allow_public_bind = true' \
|
||||
> docker-ctx/zeroclaw-data/.zeroclaw/config.toml
|
||||
|
||||
cp Dockerfile.ci docker-ctx/Dockerfile
|
||||
cp Dockerfile.debian.ci docker-ctx/Dockerfile.debian
|
||||
|
||||
- uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
|
||||
|
||||
- uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
|
||||
with:
|
||||
context: docker-ctx
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.version.outputs.tag }}
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:beta
|
||||
platforms: linux/amd64,linux/arm64
|
||||
|
||||
- name: Build and push Debian compatibility image
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
|
||||
with:
|
||||
context: docker-ctx
|
||||
file: docker-ctx/Dockerfile.debian
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.version.outputs.tag }}-debian
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:beta-debian
|
||||
platforms: linux/amd64,linux/arm64
|
||||
|
||||
# Tweet removed — only stable releases should tweet (see tweet-release.yml).
|
||||
570
.github/workflows/release-stable-manual.yml
vendored
570
.github/workflows/release-stable-manual.yml
vendored
@ -1,570 +0,0 @@
|
||||
name: Release Stable
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v[0-9]+.[0-9]+.[0-9]+" # stable tags only (no -beta suffix)
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
version:
|
||||
description: "Stable version to release (e.g. 0.2.0)"
|
||||
required: true
|
||||
type: string
|
||||
|
||||
concurrency:
|
||||
group: promote-release
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
RELEASE_CARGO_FEATURES: channel-matrix,channel-lark,memory-postgres
|
||||
|
||||
jobs:
|
||||
validate:
|
||||
name: Validate Version
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
tag: ${{ steps.check.outputs.tag }}
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- name: Validate semver and Cargo.toml match
|
||||
id: check
|
||||
shell: bash
|
||||
env:
|
||||
INPUT_VERSION: ${{ inputs.version || '' }}
|
||||
REF_NAME: ${{ github.ref_name }}
|
||||
EVENT_NAME: ${{ github.event_name }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
cargo_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
|
||||
# Resolve version from tag push or manual input
|
||||
if [[ "$EVENT_NAME" == "push" ]]; then
|
||||
# Tag push: extract version from tag name (v0.5.9 -> 0.5.9)
|
||||
input_version="${REF_NAME#v}"
|
||||
else
|
||||
input_version="$INPUT_VERSION"
|
||||
fi
|
||||
|
||||
if [[ ! "$input_version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
|
||||
echo "::error::Version must be semver (X.Y.Z). Got: ${input_version}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
if [[ "$cargo_version" != "$input_version" ]]; then
|
||||
echo "::error::Cargo.toml version (${cargo_version}) does not match input (${input_version}). Bump Cargo.toml first."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
tag="v${input_version}"
|
||||
|
||||
# Only check tag existence for manual dispatch (tag push means it already exists)
|
||||
if [[ "$EVENT_NAME" != "push" ]]; then
|
||||
if git ls-remote --exit-code --tags origin "refs/tags/${tag}" >/dev/null 2>&1; then
|
||||
echo "::error::Tag ${tag} already exists."
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "tag=${tag}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
web:
|
||||
name: Build Web Dashboard
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
retention-days: 1
|
||||
|
||||
release-notes:
|
||||
name: Generate Release Notes
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
notes: ${{ steps.notes.outputs.body }}
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Build release notes
|
||||
id: notes
|
||||
shell: bash
|
||||
env:
|
||||
INPUT_VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
# Find the previous stable tag (exclude beta tags)
|
||||
PREV_TAG=$(git tag --sort=-creatordate | grep -vE '\-beta\.' | grep -v "^v${INPUT_VERSION}$" | head -1 || echo "")
|
||||
if [ -z "$PREV_TAG" ]; then
|
||||
RANGE="HEAD"
|
||||
else
|
||||
RANGE="${PREV_TAG}..HEAD"
|
||||
fi
|
||||
|
||||
# Extract features only — skip bug fixes for clean release notes
|
||||
FEATURES=$(git log "$RANGE" --pretty=format:"%s" --no-merges \
|
||||
| grep -iE '^feat(\(|:)' \
|
||||
| sed 's/^feat(\([^)]*\)): /\1: /' \
|
||||
| sed 's/^feat: //' \
|
||||
| sed 's/ (#[0-9]*)$//' \
|
||||
| sort -uf \
|
||||
| while IFS= read -r line; do echo "- ${line}"; done || true)
|
||||
|
||||
if [ -z "$FEATURES" ]; then
|
||||
FEATURES="- Incremental improvements and polish"
|
||||
fi
|
||||
|
||||
# Collect ALL unique contributors: git authors + Co-Authored-By
|
||||
GIT_AUTHORS=$(git log "$RANGE" --pretty=format:"%an" --no-merges | sort -uf || true)
|
||||
CO_AUTHORS=$(git log "$RANGE" --pretty=format:"%b" --no-merges \
|
||||
| grep -ioE 'Co-Authored-By: *[^<]+' \
|
||||
| sed 's/Co-Authored-By: *//i' \
|
||||
| sed 's/ *$//' \
|
||||
| sort -uf || true)
|
||||
|
||||
# Merge, deduplicate, and filter out bots
|
||||
ALL_CONTRIBUTORS=$(printf "%s\n%s" "$GIT_AUTHORS" "$CO_AUTHORS" \
|
||||
| sort -uf \
|
||||
| grep -v '^$' \
|
||||
| grep -viE '\[bot\]$|^dependabot|^github-actions|^copilot|^ZeroClaw Bot|^ZeroClaw Runner|^ZeroClaw Agent|^blacksmith' \
|
||||
| while IFS= read -r name; do echo "- ${name}"; done || true)
|
||||
|
||||
BODY=$(cat <<NOTES_EOF
|
||||
## What's New
|
||||
|
||||
${FEATURES}
|
||||
|
||||
## Contributors
|
||||
|
||||
${ALL_CONTRIBUTORS}
|
||||
|
||||
---
|
||||
*Full changelog: ${PREV_TAG}...v${INPUT_VERSION}*
|
||||
NOTES_EOF
|
||||
)
|
||||
|
||||
{
|
||||
echo "body<<BODY_EOF"
|
||||
echo "$BODY"
|
||||
echo "BODY_EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
needs: [validate, web]
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
# Use ubuntu-22.04 for Linux builds to link against glibc 2.35,
|
||||
# ensuring compatibility with Ubuntu 22.04+ (#3573).
|
||||
- os: ubuntu-22.04
|
||||
target: x86_64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-22.04
|
||||
target: aarch64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-aarch64-linux-gnu
|
||||
linker_env: CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
|
||||
linker: aarch64-linux-gnu-gcc
|
||||
- os: ubuntu-22.04
|
||||
target: armv7-unknown-linux-gnueabihf
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-arm-linux-gnueabihf
|
||||
linker_env: CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER
|
||||
linker: arm-linux-gnueabihf-gcc
|
||||
skip_prometheus: true
|
||||
- os: ubuntu-22.04
|
||||
target: arm-unknown-linux-gnueabihf
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-arm-linux-gnueabihf
|
||||
linker_env: CARGO_TARGET_ARM_UNKNOWN_LINUX_GNUEABIHF_LINKER
|
||||
linker: arm-linux-gnueabihf-gcc
|
||||
skip_prometheus: true
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-latest
|
||||
target: aarch64-linux-android
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
ndk: true
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
artifact: zeroclaw.exe
|
||||
ext: zip
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
if: runner.os != 'Windows'
|
||||
with:
|
||||
prefix-key: ${{ matrix.os }}-${{ matrix.target }}
|
||||
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
name: web-dist
|
||||
path: web/dist/
|
||||
|
||||
- name: Install cross compiler
|
||||
if: matrix.cross_compiler
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y ${{ matrix.cross_compiler }}
|
||||
|
||||
- name: Setup Android NDK
|
||||
if: matrix.ndk
|
||||
run: echo "$ANDROID_NDK/toolchains/llvm/prebuilt/linux-x86_64/bin" >> "$GITHUB_PATH"
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: |
|
||||
if [ -n "${{ matrix.linker_env || '' }}" ] && [ -n "${{ matrix.linker || '' }}" ]; then
|
||||
export "${{ matrix.linker_env }}=${{ matrix.linker }}"
|
||||
fi
|
||||
if [ "${{ matrix.skip_prometheus || 'false' }}" = "true" ]; then
|
||||
cargo build --release --locked --no-default-features --features "${{ env.RELEASE_CARGO_FEATURES }},channel-nostr,skill-creation" --target ${{ matrix.target }}
|
||||
else
|
||||
cargo build --release --locked --features "${{ env.RELEASE_CARGO_FEATURES }}" --target ${{ matrix.target }}
|
||||
fi
|
||||
|
||||
- name: Package (Unix)
|
||||
if: runner.os != 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
tar czf ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- name: Package (Windows)
|
||||
if: runner.os == 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
7z a ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
||||
with:
|
||||
name: zeroclaw-${{ matrix.target }}
|
||||
path: zeroclaw-${{ matrix.target }}.${{ matrix.ext }}
|
||||
retention-days: 14
|
||||
|
||||
build-desktop:
|
||||
name: Build Desktop App (macOS Universal)
|
||||
needs: [validate]
|
||||
runs-on: macos-14
|
||||
timeout-minutes: 40
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: aarch64-apple-darwin,x86_64-apple-darwin
|
||||
|
||||
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v2
|
||||
with:
|
||||
prefix-key: macos-tauri
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
|
||||
- name: Install Tauri CLI
|
||||
run: cargo install tauri-cli --locked
|
||||
|
||||
- name: Sync Tauri version with Cargo.toml
|
||||
shell: bash
|
||||
run: |
|
||||
VERSION=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
cd apps/tauri
|
||||
if command -v jq >/dev/null 2>&1; then
|
||||
jq --arg v "$VERSION" '.version = $v' tauri.conf.json > tmp.json && mv tmp.json tauri.conf.json
|
||||
else
|
||||
sed -i '' "s/\"version\": \"[^\"]*\"/\"version\": \"$VERSION\"/" tauri.conf.json
|
||||
fi
|
||||
echo "Tauri version set to: $VERSION"
|
||||
|
||||
- name: Build Tauri app (universal binary)
|
||||
working-directory: apps/tauri
|
||||
run: cargo tauri build --target universal-apple-darwin
|
||||
|
||||
- name: Prepare desktop release assets
|
||||
run: |
|
||||
mkdir -p desktop-assets
|
||||
find target -name '*.dmg' -exec cp {} desktop-assets/ZeroClaw.dmg \; 2>/dev/null || true
|
||||
find target -name '*.app.tar.gz' -exec cp {} desktop-assets/ZeroClaw-macos.app.tar.gz \; 2>/dev/null || true
|
||||
find target -name '*.app.tar.gz.sig' -exec cp {} desktop-assets/ZeroClaw-macos.app.tar.gz.sig \; 2>/dev/null || true
|
||||
echo "--- Desktop assets ---"
|
||||
ls -lh desktop-assets/
|
||||
|
||||
- uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
|
||||
with:
|
||||
name: desktop-macos
|
||||
path: desktop-assets/*
|
||||
retention-days: 14
|
||||
|
||||
publish:
|
||||
name: Publish Stable Release
|
||||
needs: [validate, release-notes, build, build-desktop]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
pattern: zeroclaw-*
|
||||
path: artifacts
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: desktop-macos
|
||||
path: artifacts/desktop-macos
|
||||
|
||||
- name: Generate checksums
|
||||
run: |
|
||||
cd artifacts
|
||||
find . -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.dmg' \) -exec sha256sum {} + | sed 's| \./[^/]*/| |' > SHA256SUMS
|
||||
cat SHA256SUMS
|
||||
|
||||
- name: Collect release assets
|
||||
run: |
|
||||
mkdir -p release-assets
|
||||
find artifacts -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.dmg' -o -name 'SHA256SUMS' \) -exec cp {} release-assets/ \;
|
||||
cp install.sh release-assets/
|
||||
echo "--- Assets ---"
|
||||
ls -lh release-assets/
|
||||
|
||||
- name: Write release notes
|
||||
env:
|
||||
NOTES: ${{ needs.release-notes.outputs.notes }}
|
||||
run: printf '%s\n' "$NOTES" > release-notes.md
|
||||
|
||||
- name: Create tag if manual dispatch
|
||||
if: github.event_name == 'workflow_dispatch'
|
||||
env:
|
||||
TAG: ${{ needs.validate.outputs.tag }}
|
||||
run: |
|
||||
git tag -a "$TAG" -m "zeroclaw $TAG"
|
||||
git push origin "$TAG"
|
||||
|
||||
- name: Create GitHub Release
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.RELEASE_TOKEN }}
|
||||
TAG: ${{ needs.validate.outputs.tag }}
|
||||
run: |
|
||||
gh release create "$TAG" release-assets/* \
|
||||
--repo "${{ github.repository }}" \
|
||||
--title "$TAG" \
|
||||
--notes-file release-notes.md \
|
||||
--latest
|
||||
|
||||
crates-io:
|
||||
name: Publish to crates.io
|
||||
needs: [validate, publish]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
|
||||
- uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: 22
|
||||
cache: npm
|
||||
cache-dependency-path: web/package-lock.json
|
||||
|
||||
- name: Build web dashboard
|
||||
run: cd web && npm ci && npm run build
|
||||
|
||||
- name: Clean web build artifacts
|
||||
run: rm -rf web/node_modules web/src web/package.json web/package-lock.json web/tsconfig*.json web/vite.config.ts web/index.html
|
||||
|
||||
- name: Publish aardvark-sys to crates.io
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
run: |
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify -p aardvark-sys 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::aardvark-sys already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
|
||||
- name: Wait for aardvark-sys to index
|
||||
run: sleep 15
|
||||
|
||||
- name: Publish to crates.io
|
||||
env:
|
||||
CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
|
||||
VERSION: ${{ inputs.version }}
|
||||
run: |
|
||||
# Publish to crates.io; treat "already exists" as success
|
||||
# (auto-publish workflow may have already published this version)
|
||||
CRATE_NAME=$(sed -n 's/^name = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
OUTPUT=$(cargo publish --locked --allow-dirty --no-verify 2>&1) && exit 0
|
||||
echo "$OUTPUT"
|
||||
if echo "$OUTPUT" | grep -q 'already exists'; then
|
||||
echo "::notice::${CRATE_NAME}@${VERSION} already on crates.io — skipping"
|
||||
exit 0
|
||||
fi
|
||||
exit 1
|
||||
|
||||
redeploy-website:
|
||||
name: Trigger Website Redeploy
|
||||
needs: [publish]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Trigger website redeploy
|
||||
env:
|
||||
PAT: ${{ secrets.WEBSITE_REPO_PAT }}
|
||||
run: |
|
||||
curl -fsSL -X POST \
|
||||
-H "Authorization: token $PAT" \
|
||||
-H "Accept: application/vnd.github+json" \
|
||||
https://api.github.com/repos/zeroclaw-labs/zeroclaw-website/dispatches \
|
||||
-d '{"event_type":"new-release","client_payload":{"install_script_url":"https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh"}}'
|
||||
|
||||
docker:
|
||||
name: Push Docker Image
|
||||
needs: [validate, build]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: zeroclaw-x86_64-unknown-linux-gnu
|
||||
path: artifacts/
|
||||
|
||||
- uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
|
||||
with:
|
||||
name: zeroclaw-aarch64-unknown-linux-gnu
|
||||
path: artifacts/
|
||||
|
||||
- name: Prepare Docker context with pre-built binaries
|
||||
run: |
|
||||
mkdir -p docker-ctx/bin/amd64 docker-ctx/bin/arm64
|
||||
tar xzf artifacts/zeroclaw-x86_64-unknown-linux-gnu.tar.gz -C docker-ctx/bin/amd64
|
||||
tar xzf artifacts/zeroclaw-aarch64-unknown-linux-gnu.tar.gz -C docker-ctx/bin/arm64
|
||||
|
||||
mkdir -p docker-ctx/zeroclaw-data/.zeroclaw docker-ctx/zeroclaw-data/workspace
|
||||
printf '%s\n' \
|
||||
'workspace_dir = "/zeroclaw-data/workspace"' \
|
||||
'config_path = "/zeroclaw-data/.zeroclaw/config.toml"' \
|
||||
'api_key = ""' \
|
||||
'default_provider = "openrouter"' \
|
||||
'default_model = "anthropic/claude-sonnet-4-20250514"' \
|
||||
'default_temperature = 0.7' \
|
||||
'' \
|
||||
'[gateway]' \
|
||||
'port = 42617' \
|
||||
'host = "[::]"' \
|
||||
'allow_public_bind = true' \
|
||||
> docker-ctx/zeroclaw-data/.zeroclaw/config.toml
|
||||
|
||||
cp Dockerfile.ci docker-ctx/Dockerfile
|
||||
cp Dockerfile.debian.ci docker-ctx/Dockerfile.debian
|
||||
|
||||
- uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
|
||||
|
||||
- uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
|
||||
with:
|
||||
context: docker-ctx
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.validate.outputs.tag }}
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:latest
|
||||
platforms: linux/amd64,linux/arm64
|
||||
|
||||
- name: Build and push Debian compatibility image
|
||||
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
|
||||
with:
|
||||
context: docker-ctx
|
||||
file: docker-ctx/Dockerfile.debian
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.validate.outputs.tag }}-debian
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:debian
|
||||
platforms: linux/amd64,linux/arm64
|
||||
|
||||
# ── Post-publish: package manager auto-sync ─────────────────────────
|
||||
scoop:
|
||||
name: Update Scoop Manifest
|
||||
needs: [validate, publish]
|
||||
if: ${{ !cancelled() && needs.publish.result == 'success' }}
|
||||
uses: ./.github/workflows/pub-scoop.yml
|
||||
with:
|
||||
release_tag: ${{ needs.validate.outputs.tag }}
|
||||
dry_run: false
|
||||
secrets: inherit
|
||||
|
||||
aur:
|
||||
name: Update AUR Package
|
||||
needs: [validate, publish]
|
||||
if: ${{ !cancelled() && needs.publish.result == 'success' }}
|
||||
uses: ./.github/workflows/pub-aur.yml
|
||||
with:
|
||||
release_tag: ${{ needs.validate.outputs.tag }}
|
||||
dry_run: false
|
||||
secrets: inherit
|
||||
|
||||
homebrew:
|
||||
name: Update Homebrew Core
|
||||
needs: [validate, publish]
|
||||
if: ${{ !cancelled() && needs.publish.result == 'success' }}
|
||||
uses: ./.github/workflows/pub-homebrew-core.yml
|
||||
with:
|
||||
release_tag: ${{ needs.validate.outputs.tag }}
|
||||
dry_run: false
|
||||
secrets: inherit
|
||||
|
||||
# ── Post-publish: tweet after release + website are live ──────────────
|
||||
# Docker push can be slow; don't let it block the tweet.
|
||||
tweet:
|
||||
name: Tweet Release
|
||||
needs: [validate, publish, redeploy-website]
|
||||
if: ${{ !cancelled() && needs.publish.result == 'success' }}
|
||||
uses: ./.github/workflows/tweet-release.yml
|
||||
with:
|
||||
release_tag: ${{ needs.validate.outputs.tag }}
|
||||
release_url: https://github.com/zeroclaw-labs/zeroclaw/releases/tag/${{ needs.validate.outputs.tag }}
|
||||
secrets: inherit
|
||||
168
.github/workflows/release.yml
vendored
Normal file
168
.github/workflows/release.yml
vendored
Normal file
@ -0,0 +1,168 @@
|
||||
name: Beta Release
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [master]
|
||||
|
||||
concurrency:
|
||||
group: release
|
||||
cancel-in-progress: false
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
packages: write
|
||||
|
||||
env:
|
||||
CARGO_TERM_COLOR: always
|
||||
REGISTRY: ghcr.io
|
||||
IMAGE_NAME: ${{ github.repository }}
|
||||
|
||||
jobs:
|
||||
version:
|
||||
name: Resolve Version
|
||||
runs-on: ubuntu-latest
|
||||
outputs:
|
||||
version: ${{ steps.ver.outputs.version }}
|
||||
tag: ${{ steps.ver.outputs.tag }}
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- name: Compute beta version
|
||||
id: ver
|
||||
shell: bash
|
||||
run: |
|
||||
set -euo pipefail
|
||||
base_version=$(sed -n 's/^version = "\([^"]*\)"/\1/p' Cargo.toml | head -1)
|
||||
beta_tag="v${base_version}-beta.${GITHUB_RUN_NUMBER}"
|
||||
echo "version=${base_version}" >> "$GITHUB_OUTPUT"
|
||||
echo "tag=${beta_tag}" >> "$GITHUB_OUTPUT"
|
||||
echo "Beta release: ${beta_tag}"
|
||||
|
||||
build:
|
||||
name: Build ${{ matrix.target }}
|
||||
needs: [version]
|
||||
runs-on: ${{ matrix.os }}
|
||||
timeout-minutes: 40
|
||||
strategy:
|
||||
fail-fast: false
|
||||
matrix:
|
||||
include:
|
||||
- os: ubuntu-latest
|
||||
target: x86_64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: ubuntu-latest
|
||||
target: aarch64-unknown-linux-gnu
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
cross_compiler: gcc-aarch64-linux-gnu
|
||||
linker_env: CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER
|
||||
linker: aarch64-linux-gnu-gcc
|
||||
- os: macos-14
|
||||
target: aarch64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: macos-13
|
||||
target: x86_64-apple-darwin
|
||||
artifact: zeroclaw
|
||||
ext: tar.gz
|
||||
- os: windows-latest
|
||||
target: x86_64-pc-windows-msvc
|
||||
artifact: zeroclaw.exe
|
||||
ext: zip
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
- uses: dtolnay/rust-toolchain@stable
|
||||
with:
|
||||
toolchain: 1.92.0
|
||||
targets: ${{ matrix.target }}
|
||||
- uses: Swatinem/rust-cache@v2
|
||||
if: runner.os != 'Windows'
|
||||
|
||||
- name: Install cross compiler
|
||||
if: matrix.cross_compiler
|
||||
run: |
|
||||
sudo apt-get update -qq
|
||||
sudo apt-get install -y ${{ matrix.cross_compiler }}
|
||||
|
||||
- name: Build release
|
||||
shell: bash
|
||||
run: |
|
||||
if [ -n "${{ matrix.linker_env || '' }}" ] && [ -n "${{ matrix.linker || '' }}" ]; then
|
||||
export "${{ matrix.linker_env }}=${{ matrix.linker }}"
|
||||
fi
|
||||
cargo build --release --locked --target ${{ matrix.target }}
|
||||
|
||||
- name: Package (Unix)
|
||||
if: runner.os != 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
tar czf ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- name: Package (Windows)
|
||||
if: runner.os == 'Windows'
|
||||
run: |
|
||||
cd target/${{ matrix.target }}/release
|
||||
7z a ../../../zeroclaw-${{ matrix.target }}.${{ matrix.ext }} ${{ matrix.artifact }}
|
||||
|
||||
- uses: actions/upload-artifact@v4
|
||||
with:
|
||||
name: zeroclaw-${{ matrix.target }}
|
||||
path: zeroclaw-${{ matrix.target }}.${{ matrix.ext }}
|
||||
retention-days: 7
|
||||
|
||||
publish:
|
||||
name: Publish Beta Release
|
||||
needs: [version, build]
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: actions/download-artifact@v4
|
||||
with:
|
||||
path: artifacts
|
||||
|
||||
- name: Generate checksums
|
||||
run: |
|
||||
cd artifacts
|
||||
find . -type f \( -name '*.tar.gz' -o -name '*.zip' \) -exec sha256sum {} + | sed 's| \./[^/]*/| |' > SHA256SUMS
|
||||
cat SHA256SUMS
|
||||
|
||||
- name: Create GitHub Release
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
tag_name: ${{ needs.version.outputs.tag }}
|
||||
name: ${{ needs.version.outputs.tag }}
|
||||
prerelease: true
|
||||
generate_release_notes: true
|
||||
files: |
|
||||
artifacts/**/*
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
docker:
|
||||
name: Push Docker Image
|
||||
needs: [version, build]
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- uses: docker/setup-buildx-action@v3
|
||||
|
||||
- uses: docker/login-action@v3
|
||||
with:
|
||||
registry: ${{ env.REGISTRY }}
|
||||
username: ${{ github.actor }}
|
||||
password: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
- name: Build and push
|
||||
uses: docker/build-push-action@v6
|
||||
with:
|
||||
context: .
|
||||
push: true
|
||||
tags: |
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ needs.version.outputs.tag }}
|
||||
${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:beta
|
||||
platforms: linux/amd64,linux/arm64
|
||||
cache-from: type=gha
|
||||
cache-to: type=gha,mode=max
|
||||
308
.github/workflows/tweet-release.yml
vendored
308
.github/workflows/tweet-release.yml
vendored
@ -1,308 +0,0 @@
|
||||
name: Tweet Release
|
||||
|
||||
on:
|
||||
# Called by release workflows AFTER all publish steps (docker, crates, website) complete.
|
||||
workflow_call:
|
||||
inputs:
|
||||
release_tag:
|
||||
description: "Stable release tag (e.g. v0.3.0)"
|
||||
required: true
|
||||
type: string
|
||||
release_url:
|
||||
description: "GitHub Release URL"
|
||||
required: true
|
||||
type: string
|
||||
secrets:
|
||||
TWITTER_CONSUMER_API_KEY:
|
||||
required: false
|
||||
TWITTER_CONSUMER_API_SECRET_KEY:
|
||||
required: false
|
||||
TWITTER_ACCESS_TOKEN:
|
||||
required: false
|
||||
TWITTER_ACCESS_TOKEN_SECRET:
|
||||
required: false
|
||||
workflow_dispatch:
|
||||
inputs:
|
||||
tweet_text:
|
||||
description: "Custom tweet text (include emojis, keep it punchy)"
|
||||
required: true
|
||||
type: string
|
||||
image_url:
|
||||
description: "Optional image URL to attach (png/jpg)"
|
||||
required: false
|
||||
type: string
|
||||
|
||||
jobs:
|
||||
tweet:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Check for new features
|
||||
id: check
|
||||
shell: bash
|
||||
env:
|
||||
RELEASE_TAG: ${{ inputs.release_tag || '' }}
|
||||
MANUAL_TEXT: ${{ inputs.tweet_text || '' }}
|
||||
run: |
|
||||
# Manual dispatch always proceeds
|
||||
if [ -n "$MANUAL_TEXT" ]; then
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Stable releases (no -beta suffix) always tweet — they represent
|
||||
# the full release cycle, so skipping them loses visibility.
|
||||
if [[ ! "$RELEASE_TAG" =~ -beta\. ]]; then
|
||||
echo "Stable release ${RELEASE_TAG} — always tweet"
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Find the previous STABLE release tag (exclude betas) to check for new features
|
||||
PREV_TAG=$(git tag --sort=-creatordate \
|
||||
| grep -v "^${RELEASE_TAG}$" \
|
||||
| grep -vE '\-beta\.' \
|
||||
| head -1 || echo "")
|
||||
|
||||
if [ -z "$PREV_TAG" ]; then
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
# Count new feat() OR fix() commits since the previous release
|
||||
NEW_CHANGES=$(git log "${PREV_TAG}..${RELEASE_TAG}" --pretty=format:"%s" --no-merges \
|
||||
| grep -ciE '^(feat|fix)(\(|:)' || echo "0")
|
||||
|
||||
if [ "$NEW_CHANGES" -eq 0 ]; then
|
||||
echo "No new features or fixes since ${PREV_TAG} — skipping tweet"
|
||||
echo "skip=true" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "${NEW_CHANGES} new change(s) since ${PREV_TAG} — tweeting"
|
||||
echo "skip=false" >> "$GITHUB_OUTPUT"
|
||||
fi
|
||||
|
||||
- name: Build tweet text
|
||||
id: tweet
|
||||
if: steps.check.outputs.skip != 'true'
|
||||
shell: bash
|
||||
env:
|
||||
RELEASE_TAG: ${{ inputs.release_tag || '' }}
|
||||
RELEASE_URL: ${{ inputs.release_url || '' }}
|
||||
MANUAL_TEXT: ${{ inputs.tweet_text || '' }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
if [ -n "$MANUAL_TEXT" ]; then
|
||||
TWEET="$MANUAL_TEXT"
|
||||
else
|
||||
# Diff against the last STABLE release (exclude betas) to capture
|
||||
# ALL features accumulated across the full beta cycle
|
||||
PREV_STABLE=$(git tag --sort=-creatordate \
|
||||
| grep -v "^${RELEASE_TAG}$" \
|
||||
| grep -vE '\-beta\.' \
|
||||
| head -1 || echo "")
|
||||
|
||||
RANGE="${PREV_STABLE:+${PREV_STABLE}..}${RELEASE_TAG}"
|
||||
|
||||
# Extract ALL features since the last stable release
|
||||
FEATURES=$(git log "$RANGE" --pretty=format:"%s" --no-merges \
|
||||
| grep -iE '^feat(\(|:)' \
|
||||
| sed 's/^feat(\([^)]*\)): /\1: /' \
|
||||
| sed 's/^feat: //' \
|
||||
| sed 's/ (#[0-9]*)$//' \
|
||||
| sort -uf || true)
|
||||
|
||||
FEAT_COUNT=$(echo "$FEATURES" | grep -c . || echo "0")
|
||||
|
||||
# Format top features with rocket emoji (limit to 6 for tweet space)
|
||||
FEAT_LIST=$(echo "$FEATURES" \
|
||||
| head -6 \
|
||||
| while IFS= read -r line; do echo "🚀 ${line}"; done || true)
|
||||
|
||||
if [ -z "$FEAT_LIST" ]; then
|
||||
FEAT_LIST="🚀 Incremental improvements and polish"
|
||||
fi
|
||||
|
||||
# Build tweet — feature-focused style
|
||||
TWEET=$(printf "🦀 ZeroClaw %s\n\n%s\n\nZero overhead. Zero compromise. 100%% Rust.\n\n#zeroclaw #rust #ai #opensource" \
|
||||
"$RELEASE_TAG" "$FEAT_LIST")
|
||||
fi
|
||||
|
||||
# X/Twitter counts any URL as 23 chars (t.co shortening).
|
||||
# Extract the URL (if present), truncate the BODY to fit, then
|
||||
# re-append the URL so it is never chopped.
|
||||
URL=""
|
||||
BODY="$TWEET"
|
||||
|
||||
# Pull URL out of existing tweet text or use RELEASE_URL
|
||||
FOUND_URL=$(echo "$TWEET" | grep -oE 'https?://[^ ]+' | tail -1 || true)
|
||||
if [ -n "$FOUND_URL" ]; then
|
||||
URL="$FOUND_URL"
|
||||
BODY=$(echo "$TWEET" | sed "s|${URL}||" | sed -e 's/[[:space:]]*$//')
|
||||
elif [ -n "$RELEASE_URL" ]; then
|
||||
URL="$RELEASE_URL"
|
||||
fi
|
||||
|
||||
if [ -n "$URL" ]; then
|
||||
# URL counts as 23 chars on X + 2 chars for \n\n separator = 25
|
||||
MAX_BODY=$((280 - 25))
|
||||
if [ ${#BODY} -gt $MAX_BODY ]; then
|
||||
BODY="${BODY:0:$((MAX_BODY - 3))}..."
|
||||
fi
|
||||
TWEET=$(printf "%s\n\n%s" "$BODY" "$URL")
|
||||
else
|
||||
if [ ${#TWEET} -gt 280 ]; then
|
||||
TWEET="${TWEET:0:277}..."
|
||||
fi
|
||||
fi
|
||||
|
||||
echo "--- Tweet preview ---"
|
||||
echo "$TWEET"
|
||||
echo "--- ${#TWEET} chars ---"
|
||||
|
||||
{
|
||||
echo "text<<TWEET_EOF"
|
||||
echo "$TWEET"
|
||||
echo "TWEET_EOF"
|
||||
} >> "$GITHUB_OUTPUT"
|
||||
|
||||
- name: Check for duplicate tweet
|
||||
id: dedup
|
||||
if: steps.check.outputs.skip != 'true'
|
||||
shell: bash
|
||||
env:
|
||||
TWEET_TEXT: ${{ steps.tweet.outputs.text }}
|
||||
run: |
|
||||
# Hash the tweet content (ignore whitespace differences)
|
||||
TWEET_HASH=$(echo "$TWEET_TEXT" | tr -s '[:space:]' | sha256sum | cut -d' ' -f1)
|
||||
echo "hash=${TWEET_HASH}" >> "$GITHUB_OUTPUT"
|
||||
|
||||
# Check if we already have a cache hit for this exact tweet
|
||||
MARKER_FILE="/tmp/tweet-dedup-${TWEET_HASH}"
|
||||
echo "$TWEET_HASH" > "$MARKER_FILE"
|
||||
|
||||
- uses: actions/cache@v4
|
||||
if: steps.check.outputs.skip != 'true'
|
||||
id: tweet-cache
|
||||
with:
|
||||
path: /tmp/tweet-dedup-${{ steps.dedup.outputs.hash }}
|
||||
key: tweet-${{ steps.dedup.outputs.hash }}
|
||||
|
||||
- name: Skip duplicate tweet
|
||||
if: steps.check.outputs.skip != 'true' && steps.tweet-cache.outputs.cache-hit == 'true'
|
||||
run: |
|
||||
echo "::warning::Duplicate tweet detected (hash=${{ steps.dedup.outputs.hash }}) — skipping"
|
||||
echo "This exact tweet was already posted in a previous run."
|
||||
|
||||
- name: Post to X
|
||||
if: steps.check.outputs.skip != 'true' && steps.tweet-cache.outputs.cache-hit != 'true'
|
||||
shell: bash
|
||||
env:
|
||||
TWITTER_CONSUMER_KEY: ${{ secrets.TWITTER_CONSUMER_API_KEY }}
|
||||
TWITTER_CONSUMER_SECRET: ${{ secrets.TWITTER_CONSUMER_API_SECRET_KEY }}
|
||||
TWITTER_ACCESS_TOKEN: ${{ secrets.TWITTER_ACCESS_TOKEN }}
|
||||
TWITTER_ACCESS_TOKEN_SECRET: ${{ secrets.TWITTER_ACCESS_TOKEN_SECRET }}
|
||||
TWEET_TEXT: ${{ steps.tweet.outputs.text }}
|
||||
IMAGE_URL: ${{ inputs.image_url || '' }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
|
||||
# Skip if Twitter secrets are not configured
|
||||
if [ -z "$TWITTER_CONSUMER_KEY" ] || [ -z "$TWITTER_ACCESS_TOKEN" ]; then
|
||||
echo "::warning::Twitter secrets not configured — skipping tweet"
|
||||
exit 0
|
||||
fi
|
||||
|
||||
pip install requests requests-oauthlib --quiet
|
||||
|
||||
python3 - <<'PYEOF'
|
||||
import os, sys, time
|
||||
from requests_oauthlib import OAuth1Session
|
||||
|
||||
consumer_key = os.environ["TWITTER_CONSUMER_KEY"]
|
||||
consumer_secret = os.environ["TWITTER_CONSUMER_SECRET"]
|
||||
access_token = os.environ["TWITTER_ACCESS_TOKEN"]
|
||||
access_token_secret = os.environ["TWITTER_ACCESS_TOKEN_SECRET"]
|
||||
tweet_text = os.environ["TWEET_TEXT"]
|
||||
image_url = os.environ.get("IMAGE_URL", "")
|
||||
|
||||
oauth = OAuth1Session(
|
||||
consumer_key,
|
||||
client_secret=consumer_secret,
|
||||
resource_owner_key=access_token,
|
||||
resource_owner_secret=access_token_secret,
|
||||
)
|
||||
|
||||
media_id = None
|
||||
|
||||
# Upload image if provided
|
||||
if image_url:
|
||||
import requests
|
||||
print(f"Downloading image: {image_url}")
|
||||
img_resp = requests.get(image_url, timeout=30)
|
||||
img_resp.raise_for_status()
|
||||
|
||||
content_type = img_resp.headers.get("content-type", "image/png")
|
||||
init_resp = oauth.post(
|
||||
"https://upload.twitter.com/1.1/media/upload.json",
|
||||
data={
|
||||
"command": "INIT",
|
||||
"total_bytes": len(img_resp.content),
|
||||
"media_type": content_type,
|
||||
},
|
||||
)
|
||||
if init_resp.status_code != 202:
|
||||
print(f"Media INIT failed: {init_resp.status_code} {init_resp.text}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
media_id = init_resp.json()["media_id_string"]
|
||||
|
||||
append_resp = oauth.post(
|
||||
"https://upload.twitter.com/1.1/media/upload.json",
|
||||
data={"command": "APPEND", "media_id": media_id, "segment_index": 0},
|
||||
files={"media_data": img_resp.content},
|
||||
)
|
||||
if append_resp.status_code not in (200, 204):
|
||||
print(f"Media APPEND failed: {append_resp.status_code} {append_resp.text}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
fin_resp = oauth.post(
|
||||
"https://upload.twitter.com/1.1/media/upload.json",
|
||||
data={"command": "FINALIZE", "media_id": media_id},
|
||||
)
|
||||
if fin_resp.status_code not in (200, 201):
|
||||
print(f"Media FINALIZE failed: {fin_resp.status_code} {fin_resp.text}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
state = fin_resp.json().get("processing_info", {}).get("state")
|
||||
while state == "pending" or state == "in_progress":
|
||||
wait = fin_resp.json().get("processing_info", {}).get("check_after_secs", 2)
|
||||
time.sleep(wait)
|
||||
status_resp = oauth.get(
|
||||
"https://upload.twitter.com/1.1/media/upload.json",
|
||||
params={"command": "STATUS", "media_id": media_id},
|
||||
)
|
||||
state = status_resp.json().get("processing_info", {}).get("state")
|
||||
fin_resp = status_resp
|
||||
|
||||
print(f"Image uploaded: media_id={media_id}")
|
||||
|
||||
# Post tweet
|
||||
payload = {"text": tweet_text}
|
||||
if media_id:
|
||||
payload["media"] = {"media_ids": [media_id]}
|
||||
|
||||
resp = oauth.post("https://api.x.com/2/tweets", json=payload)
|
||||
|
||||
if resp.status_code == 201:
|
||||
data = resp.json()
|
||||
tweet_id = data["data"]["id"]
|
||||
print(f"Tweet posted: https://x.com/zeroclawlabs/status/{tweet_id}")
|
||||
else:
|
||||
print(f"Failed to post tweet: {resp.status_code}", file=sys.stderr)
|
||||
print(resp.text, file=sys.stderr)
|
||||
sys.exit(1)
|
||||
PYEOF
|
||||
20
.gitignore
vendored
20
.gitignore
vendored
@ -1,8 +1,5 @@
|
||||
/target
|
||||
/target-*/
|
||||
firmware/*/target
|
||||
web/dist/*
|
||||
!web/dist/.gitkeep
|
||||
*.db
|
||||
*.db-journal
|
||||
.DS_Store
|
||||
@ -32,20 +29,3 @@ venv/
|
||||
*.pem
|
||||
credentials.json
|
||||
.worktrees/
|
||||
.zeroclaw/*
|
||||
|
||||
# Skill eval workspaces (test outputs, transcripts, grading)
|
||||
.claude/skills/*-workspace/
|
||||
|
||||
# Local state backups
|
||||
.local-state-backups/
|
||||
*.local-state-backup/
|
||||
|
||||
# Coverage artifacts
|
||||
lcov.info
|
||||
|
||||
# IDE's stuff
|
||||
.idea
|
||||
|
||||
# Wrangler cache
|
||||
.wrangler/
|
||||
14
.vscode/extensions.json
vendored
14
.vscode/extensions.json
vendored
@ -1,14 +0,0 @@
|
||||
{
|
||||
"recommendations": [
|
||||
"rust-lang.rust-analyzer",
|
||||
"vadimcn.vscode-lldb",
|
||||
"serayuzgur.crates",
|
||||
"bungcip.better-toml",
|
||||
"usernamehw.errorlens",
|
||||
"eamodio.gitlens",
|
||||
"tamasfe.even-better-toml",
|
||||
"dbaeumer.vscode-eslint",
|
||||
"oderwat.indent-rainbow",
|
||||
"ryanluker.vscode-coverage-gutters"
|
||||
]
|
||||
}
|
||||
73
.vscode/launch.json
vendored
73
.vscode/launch.json
vendored
@ -1,73 +0,0 @@
|
||||
{
|
||||
"version": "0.2.0",
|
||||
"inputs": [
|
||||
{
|
||||
"id": "testName",
|
||||
"description": "Exact test name to debug (e.g. tests::my_test)",
|
||||
"type": "promptString",
|
||||
"default": ""
|
||||
}
|
||||
],
|
||||
"configurations": [
|
||||
// ── Runtime ───────────────────────────────────────────
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Agent",
|
||||
"program": "${workspaceFolder}/target/debug/zeroclaw",
|
||||
"args": ["agent"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"preLaunchTask": "Build: Debug"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Gateway",
|
||||
"program": "${workspaceFolder}/target/debug/zeroclaw",
|
||||
"args": ["gateway"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"preLaunchTask": "Build: Debug"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Daemon",
|
||||
"program": "${workspaceFolder}/target/debug/zeroclaw",
|
||||
"args": ["daemon"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"preLaunchTask": "Build: Debug"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Status",
|
||||
"program": "${workspaceFolder}/target/debug/zeroclaw",
|
||||
"args": ["status"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"preLaunchTask": "Build: Debug"
|
||||
},
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Onboard",
|
||||
"program": "${workspaceFolder}/target/debug/zeroclaw",
|
||||
"args": ["onboard"],
|
||||
"cwd": "${workspaceFolder}",
|
||||
"preLaunchTask": "Build: Debug"
|
||||
},
|
||||
// ── Test ──────────────────────────────────────────────
|
||||
{
|
||||
"type": "lldb",
|
||||
"request": "launch",
|
||||
"name": "Debug: Test (by name)",
|
||||
"cargo": {
|
||||
"args": ["test", "--no-run", "--lib", "--"],
|
||||
"filter": {
|
||||
"kind": "lib"
|
||||
}
|
||||
},
|
||||
"args": ["--exact", "${input:testName}", "--nocapture"],
|
||||
"cwd": "${workspaceFolder}"
|
||||
}
|
||||
]
|
||||
}
|
||||
22
.vscode/settings.json
vendored
22
.vscode/settings.json
vendored
@ -1,22 +0,0 @@
|
||||
{
|
||||
"git.autofetch": true,
|
||||
"git.autofetchPeriod": 90,
|
||||
"search.exclude": {
|
||||
"**/target": true
|
||||
},
|
||||
"files.watcherExclude": {
|
||||
"**/target/**": true
|
||||
},
|
||||
"[rust]": {
|
||||
"editor.defaultFormatter": "rust-lang.rust-analyzer"
|
||||
},
|
||||
"editor.formatOnSave": true,
|
||||
"editor.formatOnPaste": true,
|
||||
"files.autoSave": "afterDelay",
|
||||
"files.autoSaveDelay": 1000,
|
||||
"rust-analyzer.check.command": "clippy",
|
||||
"rust-analyzer.check.extraArgs": ["--all-targets", "--", "-D", "warnings"],
|
||||
"window.title": "${activeRepositoryBranchName}",
|
||||
"coverage-gutters.coverageFileNames": ["lcov.info"],
|
||||
"git.postCommitCommand": "push"
|
||||
}
|
||||
133
.vscode/tasks.json
vendored
133
.vscode/tasks.json
vendored
@ -1,133 +0,0 @@
|
||||
{
|
||||
"version": "2.0.0",
|
||||
"inputs": [
|
||||
{
|
||||
"id": "testFilter",
|
||||
"description": "Test name or filter pattern",
|
||||
"type": "promptString",
|
||||
"default": ""
|
||||
}
|
||||
],
|
||||
"tasks": [
|
||||
// ── Build ──────────────────────────────────────────────
|
||||
{
|
||||
"label": "Build: Debug",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["build"],
|
||||
"group": {
|
||||
"kind": "build",
|
||||
"isDefault": true
|
||||
},
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
{
|
||||
"label": "Build: Release",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["build", "--release"],
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
{
|
||||
"label": "Build: Check (fast)",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["check", "--all-targets"],
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
// ── Lint ───────────────────────────────────────────────
|
||||
{
|
||||
"label": "Lint: Clippy",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["clippy", "--all-targets", "--", "-D", "warnings"],
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
{
|
||||
"label": "Lint: Format Check",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["fmt", "--all", "--", "--check"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Lint: Format Fix",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["fmt", "--all"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
// ── Test ──────────────────────────────────────────────
|
||||
{
|
||||
"label": "Test: All",
|
||||
"type": "shell",
|
||||
"command": "cargo nextest --version >/dev/null 2>&1 || cargo install cargo-nextest && cargo nextest run",
|
||||
"group": {
|
||||
"kind": "test",
|
||||
"isDefault": true
|
||||
},
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
{
|
||||
"label": "Test: Filtered",
|
||||
"type": "shell",
|
||||
"command": "cargo nextest --version >/dev/null 2>&1 || cargo install cargo-nextest && cargo nextest run -E 'test(${input:testFilter})'",
|
||||
"problemMatcher": ["$rustc"]
|
||||
},
|
||||
{
|
||||
"label": "Test: Coverage Report",
|
||||
"type": "shell",
|
||||
"command": "cargo llvm-cov --version >/dev/null 2>&1 || cargo install cargo-llvm-cov && cargo llvm-cov --lcov --output-path lcov.info",
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Test: Benchmarks",
|
||||
"type": "shell",
|
||||
"command": "cargo",
|
||||
"args": ["bench"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
// ── Security ──────────────────────────────────────────
|
||||
{
|
||||
"label": "Security: Audit",
|
||||
"type": "shell",
|
||||
"command": "cargo audit --version >/dev/null 2>&1 || cargo install cargo-audit && cargo audit",
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "Security: Deny (licenses + sources)",
|
||||
"type": "shell",
|
||||
"command": "cargo deny --version >/dev/null 2>&1 || cargo install cargo-deny && cargo deny check licenses sources",
|
||||
"problemMatcher": []
|
||||
},
|
||||
// ── CI (Docker) ───────────────────────────────────────
|
||||
{
|
||||
"label": "CI: All (Docker)",
|
||||
"type": "shell",
|
||||
"command": "./dev/ci.sh",
|
||||
"args": ["all"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "CI: Lint (Docker)",
|
||||
"type": "shell",
|
||||
"command": "./dev/ci.sh",
|
||||
"args": ["lint"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "CI: Test (Docker)",
|
||||
"type": "shell",
|
||||
"command": "./dev/ci.sh",
|
||||
"args": ["test"],
|
||||
"problemMatcher": []
|
||||
},
|
||||
{
|
||||
"label": "CI: Security (Docker)",
|
||||
"type": "shell",
|
||||
"command": "./dev/ci.sh",
|
||||
"args": ["security"],
|
||||
"problemMatcher": []
|
||||
}
|
||||
]
|
||||
}
|
||||
478
AGENTS.md
478
AGENTS.md
@ -1,28 +1,20 @@
|
||||
# AGENTS.md — ZeroClaw
|
||||
# AGENTS.md — ZeroClaw Agent Engineering Protocol
|
||||
|
||||
Cross-tool agent instructions for any AI coding assistant working on this repository.
|
||||
This file defines the default working protocol for coding agents in this repository.
|
||||
Scope: entire repository.
|
||||
|
||||
## Commands
|
||||
## 1) Project Snapshot (Read First)
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo test
|
||||
```
|
||||
ZeroClaw is a Rust-first autonomous agent runtime optimized for:
|
||||
|
||||
Full pre-PR validation (recommended):
|
||||
- high performance
|
||||
- high efficiency
|
||||
- high stability
|
||||
- high extensibility
|
||||
- high sustainability
|
||||
- high security
|
||||
|
||||
```bash
|
||||
./dev/ci.sh all
|
||||
```
|
||||
|
||||
Docs-only changes: run markdown lint and link-integrity checks. If touching bootstrap scripts: `bash -n install.sh`.
|
||||
|
||||
## Project Snapshot
|
||||
|
||||
ZeroClaw is a Rust-first autonomous agent runtime optimized for performance, efficiency, stability, extensibility, sustainability, and security.
|
||||
|
||||
Core architecture is trait-driven and modular. Extend by implementing traits and registering in factory modules.
|
||||
Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules.
|
||||
|
||||
Key extension points:
|
||||
|
||||
@ -34,7 +26,111 @@ Key extension points:
|
||||
- `src/runtime/traits.rs` (`RuntimeAdapter`)
|
||||
- `src/peripherals/traits.rs` (`Peripheral`) — hardware boards (STM32, RPi GPIO)
|
||||
|
||||
## Repository Map
|
||||
## 2) Deep Architecture Observations (Why This Protocol Exists)
|
||||
|
||||
These codebase realities should drive every design decision:
|
||||
|
||||
1. **Trait + factory architecture is the stability backbone**
|
||||
- Extension points are intentionally explicit and swappable.
|
||||
- Most features should be added via trait implementation + factory registration, not cross-cutting rewrites.
|
||||
2. **Security-critical surfaces are first-class and internet-adjacent**
|
||||
- `src/gateway/`, `src/security/`, `src/tools/`, `src/runtime/` carry high blast radius.
|
||||
- Defaults already lean secure-by-default (pairing, bind safety, limits, secret handling); keep it that way.
|
||||
3. **Performance and binary size are product goals, not nice-to-have**
|
||||
- `Cargo.toml` release profile and dependency choices optimize for size and determinism.
|
||||
- Convenience dependencies and broad abstractions can silently regress these goals.
|
||||
4. **Config and runtime contracts are user-facing API**
|
||||
- `src/config/schema.rs` and CLI commands are effectively public interfaces.
|
||||
- Backward compatibility and explicit migration matter.
|
||||
5. **The project now runs in high-concurrency collaboration mode**
|
||||
- CI + docs governance + label routing are part of the product delivery system.
|
||||
- PR throughput is a design constraint; not just a maintainer inconvenience.
|
||||
|
||||
## 3) Engineering Principles (Normative)
|
||||
|
||||
These principles are mandatory by default. They are not slogans; they are implementation constraints.
|
||||
|
||||
### 3.1 KISS (Keep It Simple, Stupid)
|
||||
|
||||
**Why here:** Runtime + security behavior must stay auditable under pressure.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer straightforward control flow over clever meta-programming.
|
||||
- Prefer explicit match branches and typed structs over hidden dynamic behavior.
|
||||
- Keep error paths obvious and localized.
|
||||
|
||||
### 3.2 YAGNI (You Aren't Gonna Need It)
|
||||
|
||||
**Why here:** Premature features increase attack surface and maintenance burden.
|
||||
|
||||
Required:
|
||||
|
||||
- Do not add new config keys, trait methods, feature flags, or workflow branches without a concrete accepted use case.
|
||||
- Do not introduce speculative “future-proof” abstractions without at least one current caller.
|
||||
- Keep unsupported paths explicit (error out) rather than adding partial fake support.
|
||||
|
||||
### 3.3 DRY + Rule of Three
|
||||
|
||||
**Why here:** Naive DRY can create brittle shared abstractions across providers/channels/tools.
|
||||
|
||||
Required:
|
||||
|
||||
- Duplicate small, local logic when it preserves clarity.
|
||||
- Extract shared utilities only after repeated, stable patterns (rule-of-three).
|
||||
- When extracting, preserve module boundaries and avoid hidden coupling.
|
||||
|
||||
### 3.4 SRP + ISP (Single Responsibility + Interface Segregation)
|
||||
|
||||
**Why here:** Trait-driven architecture already encodes subsystem boundaries.
|
||||
|
||||
Required:
|
||||
|
||||
- Keep each module focused on one concern.
|
||||
- Extend behavior by implementing existing narrow traits whenever possible.
|
||||
- Avoid fat interfaces and “god modules” that mix policy + transport + storage.
|
||||
|
||||
### 3.5 Fail Fast + Explicit Errors
|
||||
|
||||
**Why here:** Silent fallback in agent runtimes can create unsafe or costly behavior.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer explicit `bail!`/errors for unsupported or unsafe states.
|
||||
- Never silently broaden permissions/capabilities.
|
||||
- Document fallback behavior when fallback is intentional and safe.
|
||||
|
||||
### 3.6 Secure by Default + Least Privilege
|
||||
|
||||
**Why here:** Gateway/tools/runtime can execute actions with real-world side effects.
|
||||
|
||||
Required:
|
||||
|
||||
- Deny-by-default for access and exposure boundaries.
|
||||
- Never log secrets, raw tokens, or sensitive payloads.
|
||||
- Keep network/filesystem/shell scope as narrow as possible unless explicitly justified.
|
||||
|
||||
### 3.7 Determinism + Reproducibility
|
||||
|
||||
**Why here:** Reliable CI and low-latency triage depend on deterministic behavior.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer reproducible commands and locked dependency behavior in CI-sensitive paths.
|
||||
- Keep tests deterministic (no flaky timing/network dependence without guardrails).
|
||||
- Ensure local validation commands map to CI expectations.
|
||||
|
||||
### 3.8 Reversibility + Rollback-First Thinking
|
||||
|
||||
**Why here:** Fast recovery is mandatory under high PR volume.
|
||||
|
||||
Required:
|
||||
|
||||
- Keep changes easy to revert (small scope, clear blast radius).
|
||||
- For risky changes, define rollback path before merge.
|
||||
- Avoid mixed mega-patches that block safe rollback.
|
||||
|
||||
## 4) Repository Map (High-Level)
|
||||
|
||||
- `src/main.rs` — CLI entrypoint and command routing
|
||||
- `src/lib.rs` — module exports and shared command enums
|
||||
@ -46,12 +142,59 @@ Key extension points:
|
||||
- `src/providers/` — model providers and resilient wrapper
|
||||
- `src/channels/` — Telegram/Discord/Slack/etc channels
|
||||
- `src/tools/` — tool execution surface (shell, file, memory, browser)
|
||||
- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO)
|
||||
- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md`
|
||||
- `src/runtime/` — runtime adapters (currently native)
|
||||
- `docs/` — topic-based documentation (setup-guides, reference, ops, security, hardware, contributing, maintainers)
|
||||
- `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
|
||||
- `.github/` — CI, templates, automation workflows
|
||||
|
||||
## Risk Tiers
|
||||
## 4.1 Documentation System Contract (Required)
|
||||
|
||||
Treat documentation as a first-class product surface, not a post-merge artifact.
|
||||
|
||||
Canonical entry points:
|
||||
|
||||
- root READMEs: `README.md`, `README.zh-CN.md`, `README.ja.md`, `README.ru.md`, `README.fr.md`, `README.vi.md`
|
||||
- docs hubs: `docs/README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `docs/README.ru.md`, `docs/README.fr.md`, `docs/i18n/vi/README.md`
|
||||
- unified TOC: `docs/SUMMARY.md`
|
||||
|
||||
Supported locales (current contract):
|
||||
|
||||
- `en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`
|
||||
|
||||
Collection indexes (category navigation):
|
||||
|
||||
- `docs/getting-started/README.md`
|
||||
- `docs/reference/README.md`
|
||||
- `docs/operations/README.md`
|
||||
- `docs/security/README.md`
|
||||
- `docs/hardware/README.md`
|
||||
- `docs/contributing/README.md`
|
||||
- `docs/project/README.md`
|
||||
|
||||
Runtime-contract references (must track behavior changes):
|
||||
|
||||
- `docs/commands-reference.md`
|
||||
- `docs/providers-reference.md`
|
||||
- `docs/channels-reference.md`
|
||||
- `docs/config-reference.md`
|
||||
- `docs/operations-runbook.md`
|
||||
- `docs/troubleshooting.md`
|
||||
- `docs/one-click-bootstrap.md`
|
||||
|
||||
Required docs governance rules:
|
||||
|
||||
- Keep README/hub top navigation and quick routes intuitive and non-duplicative.
|
||||
- Keep entry-point parity across all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`) when changing navigation architecture.
|
||||
- If a change touches docs IA, runtime-contract references, or user-facing wording in shared docs, perform i18n follow-through for currently supported locales in the same PR:
|
||||
- Update locale navigation links (`README*`, `docs/README*`, `docs/SUMMARY.md`).
|
||||
- Update localized runtime-contract docs where equivalents exist (at minimum `commands-reference`, `config-reference`, `troubleshooting` for `fr` and `vi`).
|
||||
- For Vietnamese, treat `docs/i18n/vi/**` as canonical. Keep `docs/*.<locale>.md` compatibility shims aligned if present.
|
||||
- Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
|
||||
- Keep project snapshots date-stamped and immutable once superseded by a newer date.
|
||||
|
||||
## 5) Risk Tiers by Path (Review Depth Contract)
|
||||
|
||||
Use these tiers when deciding validation depth and review rigor.
|
||||
|
||||
- **Low risk**: docs/chore/tests-only changes
|
||||
- **Medium risk**: most `src/**` behavior changes without boundary/security impact
|
||||
@ -59,34 +202,283 @@ Key extension points:
|
||||
|
||||
When uncertain, classify as higher risk.
|
||||
|
||||
## Workflow
|
||||
## 6) Agent Workflow (Required)
|
||||
|
||||
1. **Read before write** — inspect existing module, factory wiring, and adjacent tests before editing.
|
||||
2. **One concern per PR** — avoid mixed feature+refactor+infra patches.
|
||||
3. **Implement minimal patch** — no speculative abstractions, no config keys without a concrete use case.
|
||||
4. **Validate by risk tier** — docs-only: lightweight checks. Code changes: full relevant checks.
|
||||
5. **Document impact** — update PR notes for behavior, risk, side effects, and rollback.
|
||||
6. **Queue hygiene** — stacked PR: declare `Depends on #...`. Replacing old PR: declare `Supersedes #...`.
|
||||
1. **Read before write**
|
||||
- Inspect existing module, factory wiring, and adjacent tests before editing.
|
||||
2. **Define scope boundary**
|
||||
- One concern per PR; avoid mixed feature+refactor+infra patches.
|
||||
3. **Implement minimal patch**
|
||||
- Apply KISS/YAGNI/DRY rule-of-three explicitly.
|
||||
4. **Validate by risk tier**
|
||||
- Docs-only: lightweight checks.
|
||||
- Code/risky changes: full relevant checks and focused scenarios.
|
||||
5. **Document impact**
|
||||
- Update docs/PR notes for behavior, risk, side effects, and rollback.
|
||||
- If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
|
||||
- If docs entry points changed, keep all supported locale README/docs-hub navigation aligned (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`).
|
||||
6. **Respect queue hygiene**
|
||||
- If stacked PR: declare `Depends on #...`.
|
||||
- If replacing old PR: declare `Supersedes #...`.
|
||||
|
||||
Branch/commit/PR rules:
|
||||
- Work from a non-`master` branch. Open a PR to `master`; do not push directly.
|
||||
- Use conventional commit titles. Prefer small PRs (`size: XS/S/M`).
|
||||
- Follow `.github/pull_request_template.md` fully.
|
||||
- Never commit secrets, personal data, or real identity information (see `@docs/contributing/pr-discipline.md`).
|
||||
### 6.1 Branch / Commit / PR Flow (Required)
|
||||
|
||||
## Anti-Patterns
|
||||
All contributors (human or agent) must follow the same collaboration flow:
|
||||
|
||||
- Create and work from a non-`main` branch.
|
||||
- Commit changes to that branch with clear, scoped commit messages.
|
||||
- Open a PR to `dev`; do not push directly to `dev` or `main`.
|
||||
- `main` is reserved for release promotion PRs from `dev`.
|
||||
- Wait for required checks and review outcomes before merging.
|
||||
- Merge via PR controls (squash/rebase/merge as repository policy allows).
|
||||
- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
|
||||
|
||||
### 6.2 Worktree Workflow (Required for Multi-Track Agent Work)
|
||||
|
||||
Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
|
||||
|
||||
- Use one worktree per active branch/PR stream to avoid cross-task contamination.
|
||||
- Keep each worktree on a single branch; do not mix unrelated edits in one worktree.
|
||||
- Run validation commands inside the corresponding worktree before commit/PR.
|
||||
- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
|
||||
- PR checkpoint rules from section 6.1 still apply to worktree-based development.
|
||||
|
||||
### 6.3 Code Naming Contract (Required)
|
||||
|
||||
Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
|
||||
|
||||
- Use Rust standard casing consistently: modules/files `snake_case`, types/traits/enums `PascalCase`, functions/variables `snake_case`, constants/statics `SCREAMING_SNAKE_CASE`.
|
||||
- Name types and modules by domain role, not implementation detail (for example `DiscordChannel`, `SecurityPolicy`, `MemoryStore` over vague names like `Manager`/`Helper`).
|
||||
- Keep trait implementer naming explicit and predictable: `<ProviderName>Provider`, `<ChannelName>Channel`, `<ToolName>Tool`, `<BackendName>Memory`.
|
||||
- Keep factory registration keys stable, lowercase, and user-facing (for example `"openai"`, `"discord"`, `"shell"`), and avoid alias sprawl without migration need.
|
||||
- Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped.
|
||||
- If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`).
|
||||
|
||||
### 6.4 Architecture Boundary Contract (Required)
|
||||
|
||||
Use these rules to keep the trait/factory architecture stable under growth.
|
||||
|
||||
- Extend capabilities by adding trait implementations + factory wiring first; avoid cross-module rewrites for isolated features.
|
||||
- Keep dependency direction inward to contracts: concrete integrations depend on trait/config/util layers, not on other concrete integrations.
|
||||
- Avoid creating cross-subsystem coupling (for example provider code importing channel internals, tool code mutating gateway policy directly).
|
||||
- Keep module responsibilities single-purpose: orchestration in `agent/`, transport in `channels/`, model I/O in `providers/`, policy in `security/`, execution in `tools/`.
|
||||
- Introduce new shared abstractions only after repeated use (rule-of-three), with at least one real caller in current scope.
|
||||
- For config/schema changes, treat keys as public contract: document defaults, compatibility impact, and migration/rollback path.
|
||||
|
||||
## 7) Change Playbooks
|
||||
|
||||
### 7.1 Adding a Provider
|
||||
|
||||
- Implement `Provider` in `src/providers/`.
|
||||
- Register in `src/providers/mod.rs` factory.
|
||||
- Add focused tests for factory wiring and error paths.
|
||||
- Avoid provider-specific behavior leaks into shared orchestration code.
|
||||
|
||||
### 7.2 Adding a Channel
|
||||
|
||||
- Implement `Channel` in `src/channels/`.
|
||||
- Keep `send`, `listen`, `health_check`, typing semantics consistent.
|
||||
- Cover auth/allowlist/health behavior with tests.
|
||||
|
||||
### 7.3 Adding a Tool
|
||||
|
||||
- Implement `Tool` in `src/tools/` with strict parameter schema.
|
||||
- Validate and sanitize all inputs.
|
||||
- Return structured `ToolResult`; avoid panics in runtime path.
|
||||
|
||||
### 7.4 Adding a Peripheral
|
||||
|
||||
- Implement `Peripheral` in `src/peripherals/`.
|
||||
- Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.).
|
||||
- Register board type in config schema if needed.
|
||||
- See `docs/hardware-peripherals-design.md` for protocol and firmware notes.
|
||||
|
||||
### 7.5 Security / Runtime / Gateway Changes
|
||||
|
||||
- Include threat/risk notes and rollback strategy.
|
||||
- Add/update tests or validation evidence for failure modes and boundaries.
|
||||
- Keep observability useful but non-sensitive.
|
||||
- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
|
||||
|
||||
### 7.6 Docs System / README / IA Changes
|
||||
|
||||
- Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
|
||||
- Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
|
||||
- When runtime surfaces change, update related references (`commands/providers/channels/config/runbook/troubleshooting`).
|
||||
- Keep multilingual entry-point parity for all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`) when nav or key wording changes.
|
||||
- When shared docs wording changes, sync corresponding localized docs for supported locales in the same PR (or explicitly document deferral and follow-up PR).
|
||||
- For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.
|
||||
|
||||
|
||||
## 8) Validation Matrix
|
||||
|
||||
Default local checks for code changes:
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo test
|
||||
```
|
||||
|
||||
Preferred local pre-PR validation path (recommended, not required):
|
||||
|
||||
```bash
|
||||
./dev/ci.sh all
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Local Docker-based CI is strongly recommended when Docker is available.
|
||||
- Contributors are not blocked from opening a PR if local Docker CI is unavailable; in that case run the most relevant native checks and document what was run.
|
||||
|
||||
Additional expectations by change type:
|
||||
|
||||
- **Docs/template-only**:
|
||||
- run markdown lint and link-integrity checks
|
||||
- if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
|
||||
- if touching bootstrap docs/scripts, run `bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh`
|
||||
- **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available.
|
||||
- **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation.
|
||||
|
||||
If full checks are impractical, run the most relevant subset and document what was skipped and why.
|
||||
|
||||
## 9) Collaboration and PR Discipline
|
||||
|
||||
- Follow `.github/pull_request_template.md` fully (including side effects / blast radius).
|
||||
- Keep PR descriptions concrete: problem, change, non-goals, risk, rollback.
|
||||
- Use conventional commit titles.
|
||||
- Prefer small PRs (`size: XS/S/M`) when possible.
|
||||
- Agent-assisted PRs are welcome, **but contributors remain accountable for understanding what their code will do**.
|
||||
|
||||
### 9.1 Privacy/Sensitive Data and Neutral Wording (Required)
|
||||
|
||||
Treat privacy and neutrality as merge gates, not best-effort guidelines.
|
||||
|
||||
- Never commit personal or sensitive data in code, docs, tests, fixtures, snapshots, logs, examples, or commit messages.
|
||||
- Prohibited data includes (non-exhaustive): real names, personal emails, phone numbers, addresses, access tokens, API keys, credentials, IDs, and private URLs.
|
||||
- Use neutral project-scoped placeholders (for example: `user_a`, `test_user`, `project_bot`, `example.com`) instead of real identity data.
|
||||
- Test names/messages/fixtures must be impersonal and system-focused; avoid first-person or identity-specific language.
|
||||
- If identity-like context is unavoidable, use ZeroClaw-scoped roles/labels only (for example: `ZeroClawAgent`, `ZeroClawOperator`, `zeroclaw_user`) and avoid real-world personas.
|
||||
- Recommended identity-safe naming palette (use when identity-like context is required):
|
||||
- actor labels: `ZeroClawAgent`, `ZeroClawOperator`, `ZeroClawMaintainer`, `zeroclaw_user`
|
||||
- service/runtime labels: `zeroclaw_bot`, `zeroclaw_service`, `zeroclaw_runtime`, `zeroclaw_node`
|
||||
- environment labels: `zeroclaw_project`, `zeroclaw_workspace`, `zeroclaw_channel`
|
||||
- If reproducing external incidents, redact and anonymize all payloads before committing.
|
||||
- Before push, review `git diff --cached` specifically for accidental sensitive strings and identity leakage.
|
||||
|
||||
### 9.2 Superseded-PR Attribution (Required)
|
||||
|
||||
When a PR supersedes another contributor's PR and carries forward substantive code or design decisions, preserve authorship explicitly.
|
||||
|
||||
- In the integrating commit message, add one `Co-authored-by: Name <email>` trailer per superseded contributor whose work is materially incorporated.
|
||||
- Use a GitHub-recognized email (`<login@users.noreply.github.com>` or the contributor's verified commit email) so attribution is rendered correctly.
|
||||
- Keep trailers on their own lines after a blank line at commit-message end; never encode them as escaped `\\n` text.
|
||||
- In the PR body, list superseded PR links and briefly state what was incorporated from each.
|
||||
- If no actual code/design was incorporated (only inspiration), do not use `Co-authored-by`; give credit in PR notes instead.
|
||||
|
||||
### 9.3 Superseded-PR PR Template (Recommended)
|
||||
|
||||
When superseding multiple PRs, use a consistent title/body structure to reduce reviewer ambiguity.
|
||||
|
||||
- Recommended title format: `feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]`
|
||||
- If this is docs/chore/meta only, keep the same supersede suffix and use the appropriate conventional-commit type.
|
||||
- In the PR body, include the following template (fill placeholders, remove non-applicable lines):
|
||||
|
||||
```md
|
||||
## Supersedes
|
||||
- #<pr_a> by @<author_a>
|
||||
- #<pr_b> by @<author_b>
|
||||
- #<pr_n> by @<author_n>
|
||||
|
||||
## Integrated Scope
|
||||
- From #<pr_a>: <what was materially incorporated>
|
||||
- From #<pr_b>: <what was materially incorporated>
|
||||
- From #<pr_n>: <what was materially incorporated>
|
||||
|
||||
## Attribution
|
||||
- Co-authored-by trailers added for materially incorporated contributors: Yes/No
|
||||
- If No, explain why (for example: no direct code/design carry-over)
|
||||
|
||||
## Non-goals
|
||||
- <explicitly list what was not carried over>
|
||||
|
||||
## Risk and Rollback
|
||||
- Risk: <summary>
|
||||
- Rollback: <revert commit/PR strategy>
|
||||
```
|
||||
|
||||
### 9.4 Superseded-PR Commit Template (Recommended)
|
||||
|
||||
When a commit unifies or supersedes prior PR work, use a deterministic commit message layout so attribution is machine-parsed and reviewer-friendly.
|
||||
|
||||
- Keep one blank line between message sections, and exactly one blank line before trailer lines.
|
||||
- Keep each trailer on its own line; do not wrap, indent, or encode as escaped `\n` text.
|
||||
- Add one `Co-authored-by` trailer per materially incorporated contributor, using GitHub-recognized email.
|
||||
- If no direct code/design is carried over, omit `Co-authored-by` and explain attribution in the PR body instead.
|
||||
|
||||
```text
|
||||
feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]
|
||||
|
||||
<one-paragraph summary of integrated outcome>
|
||||
|
||||
Supersedes:
|
||||
- #<pr_a> by @<author_a>
|
||||
- #<pr_b> by @<author_b>
|
||||
- #<pr_n> by @<author_n>
|
||||
|
||||
Integrated scope:
|
||||
- <subsystem_or_feature_a>: from #<pr_x>
|
||||
- <subsystem_or_feature_b>: from #<pr_y>
|
||||
|
||||
Co-authored-by: <Name A> <login_a@users.noreply.github.com>
|
||||
Co-authored-by: <Name B> <login_b@users.noreply.github.com>
|
||||
```
|
||||
|
||||
Reference docs:
|
||||
|
||||
- `CONTRIBUTING.md`
|
||||
- `docs/README.md`
|
||||
- `docs/SUMMARY.md`
|
||||
- `docs/docs-inventory.md`
|
||||
- `docs/commands-reference.md`
|
||||
- `docs/providers-reference.md`
|
||||
- `docs/channels-reference.md`
|
||||
- `docs/config-reference.md`
|
||||
- `docs/operations-runbook.md`
|
||||
- `docs/troubleshooting.md`
|
||||
- `docs/one-click-bootstrap.md`
|
||||
- `docs/pr-workflow.md`
|
||||
- `docs/reviewer-playbook.md`
|
||||
- `docs/ci-map.md`
|
||||
- `docs/actions-source-policy.md`
|
||||
|
||||
## 10) Anti-Patterns (Do Not)
|
||||
|
||||
- Do not add heavy dependencies for minor convenience.
|
||||
- Do not silently weaken security policy or access constraints.
|
||||
- Do not add speculative config/feature flags "just in case".
|
||||
- Do not add speculative config/feature flags “just in case”.
|
||||
- Do not mix massive formatting-only changes with functional changes.
|
||||
- Do not modify unrelated modules "while here".
|
||||
- Do not modify unrelated modules “while here”.
|
||||
- Do not bypass failing checks without explicit explanation.
|
||||
- Do not hide behavior-changing side effects in refactor commits.
|
||||
- Do not include personal identity or sensitive information in test data, examples, docs, or commits.
|
||||
|
||||
## Linked References
|
||||
## 11) Handoff Template (Agent -> Agent / Maintainer)
|
||||
|
||||
- `@docs/contributing/change-playbooks.md` — adding providers, channels, tools, peripherals; security/gateway changes; architecture boundaries
|
||||
- `@docs/contributing/pr-discipline.md` — privacy rules, superseded-PR attribution/templates, handoff template
|
||||
- `@docs/contributing/docs-contract.md` — docs system contract, i18n rules, locale parity
|
||||
When handing off work, include:
|
||||
|
||||
1. What changed
|
||||
2. What did not change
|
||||
3. Validation run and results
|
||||
4. Remaining risks / unknowns
|
||||
5. Next recommended action
|
||||
|
||||
## 12) Vibe Coding Guardrails
|
||||
|
||||
When working in fast iterative mode:
|
||||
|
||||
- Keep each iteration reversible (small commits, clear rollback).
|
||||
- Validate assumptions with code search before implementing.
|
||||
- Prefer deterministic behavior over clever shortcuts.
|
||||
- Do not “ship and hope” on security-sensitive paths.
|
||||
- If uncertain, leave a concrete TODO with verification context, not a hidden guess.
|
||||
|
||||
66
CHANGELOG.md
66
CHANGELOG.md
@ -1 +1,67 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to ZeroClaw will be documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Security
|
||||
- **Legacy XOR cipher migration**: The `enc:` prefix (XOR cipher) is now deprecated.
|
||||
Secrets using this format will be automatically migrated to `enc2:` (ChaCha20-Poly1305 AEAD)
|
||||
when decrypted via `decrypt_and_migrate()`. A `tracing::warn!` is emitted when legacy
|
||||
values are encountered. The XOR cipher will be removed in a future release.
|
||||
|
||||
### Added
|
||||
- `SecretStore::decrypt_and_migrate()` — Decrypts secrets and returns a migrated `enc2:`
|
||||
value if the input used the legacy `enc:` format
|
||||
- `SecretStore::needs_migration()` — Check if a value uses the legacy `enc:` format
|
||||
- `SecretStore::is_secure_encrypted()` — Check if a value uses the secure `enc2:` format
|
||||
- **Telegram mention_only mode** — New config option `mention_only` for Telegram channel.
|
||||
When enabled, bot only responds to messages that @-mention the bot in group chats.
|
||||
Direct messages always work regardless of this setting. Default: `false`.
|
||||
|
||||
### Deprecated
|
||||
- `enc:` prefix for encrypted secrets — Use `enc2:` (ChaCha20-Poly1305) instead.
|
||||
Legacy values are still decrypted for backward compatibility but should be migrated.
|
||||
|
||||
### Fixed
|
||||
- **Gemini thinking model support** — Responses from thinking models (e.g. `gemini-3-pro-preview`)
|
||||
are now handled correctly. The provider skips internal reasoning parts (`thought: true`) and
|
||||
signature parts (`thoughtSignature`), extracting only the final answer text. Falls back to
|
||||
thinking content when no non-thinking response is available.
|
||||
- Updated default gateway port to `42617`.
|
||||
- Removed all user-facing references to port `3000`.
|
||||
- **Onboarding channel menu dispatch** now uses an enum-backed selector instead of hard-coded
|
||||
numeric match arms, preventing duplicated pattern arms and related `unreachable pattern`
|
||||
compiler warnings in `src/onboard/wizard.rs`.
|
||||
- **OpenAI native tool spec parsing** now uses owned serializable/deserializable structs,
|
||||
fixing a compile-time type mismatch when validating tool schemas before API calls.
|
||||
|
||||
## [0.1.0] - 2026-02-13
|
||||
|
||||
### Added
|
||||
- **Core Architecture**: Trait-based pluggable system for Provider, Channel, Observer, RuntimeAdapter, Tool
|
||||
- **Provider**: OpenRouter implementation (access Claude, GPT-4, Llama, Gemini via single API)
|
||||
- **Channels**: CLI channel with interactive and single-message modes
|
||||
- **Observability**: NoopObserver (zero overhead), LogObserver (tracing), MultiObserver (fan-out)
|
||||
- **Security**: Workspace sandboxing, command allowlisting, path traversal blocking, autonomy levels (ReadOnly/Supervised/Full), rate limiting
|
||||
- **Tools**: Shell (sandboxed), FileRead (path-checked), FileWrite (path-checked)
|
||||
- **Memory (Brain)**: SQLite persistent backend (searchable, survives restarts), Markdown backend (plain files, human-readable)
|
||||
- **Heartbeat Engine**: Periodic task execution from HEARTBEAT.md
|
||||
- **Runtime**: Native adapter for Mac/Linux/Raspberry Pi
|
||||
- **Config**: TOML-based configuration with sensible defaults
|
||||
- **Onboarding**: Interactive CLI wizard with workspace scaffolding
|
||||
- **CLI Commands**: agent, gateway, status, cron, channel, tools, onboard
|
||||
- **CI/CD**: GitHub Actions with cross-platform builds (Linux, macOS Intel/ARM, Windows)
|
||||
- **Tests**: 159 inline tests covering all modules and edge cases
|
||||
- **Binary**: 3.1MB optimized release build (includes bundled SQLite)
|
||||
|
||||
### Security
|
||||
- Path traversal attack prevention
|
||||
- Command injection blocking
|
||||
- Workspace escape prevention
|
||||
- Forbidden system path protection (`/etc`, `/root`, `~/.ssh`)
|
||||
|
||||
[0.1.0]: https://github.com/theonlyhennygod/zeroclaw/releases/tag/v0.1.0
|
||||
|
||||
@ -84,7 +84,7 @@ You represent that:
|
||||
## 6. No Trademark Rights
|
||||
|
||||
This CLA does not grant you any rights to use the ZeroClaw name,
|
||||
trademarks, service marks, or logos. See [trademark.md](../maintainers/trademark.md) for trademark policy.
|
||||
trademarks, service marks, or logos. See TRADEMARK.md for trademark policy.
|
||||
|
||||
---
|
||||
|
||||
485
CLAUDE.md
485
CLAUDE.md
@ -1,16 +1,483 @@
|
||||
# CLAUDE.md — ZeroClaw (Claude Code)
|
||||
# CLAUDE.md — ZeroClaw Agent Engineering Protocol
|
||||
|
||||
> **Shared instructions live in [`AGENTS.md`](./AGENTS.md).**
|
||||
> This file contains only Claude Code-specific directives.
|
||||
This file defines the default working protocol for Claude agents in this repository.
|
||||
Scope: entire repository.
|
||||
|
||||
## Claude Code Settings
|
||||
## 1) Project Snapshot (Read First)
|
||||
|
||||
Claude Code should read and follow all instructions in `AGENTS.md` at the repository root for project conventions, commands, risk tiers, workflow rules, and anti-patterns.
|
||||
ZeroClaw is a Rust-first autonomous agent runtime optimized for:
|
||||
|
||||
## Hooks
|
||||
- high performance
|
||||
- high efficiency
|
||||
- high stability
|
||||
- high extensibility
|
||||
- high sustainability
|
||||
- high security
|
||||
|
||||
_No custom hooks defined yet._
|
||||
Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules.
|
||||
|
||||
## Slash Commands
|
||||
Key extension points:
|
||||
|
||||
_No custom slash commands defined yet._
|
||||
- `src/providers/traits.rs` (`Provider`)
|
||||
- `src/channels/traits.rs` (`Channel`)
|
||||
- `src/tools/traits.rs` (`Tool`)
|
||||
- `src/memory/traits.rs` (`Memory`)
|
||||
- `src/observability/traits.rs` (`Observer`)
|
||||
- `src/runtime/traits.rs` (`RuntimeAdapter`)
|
||||
- `src/peripherals/traits.rs` (`Peripheral`) — hardware boards (STM32, RPi GPIO)
|
||||
|
||||
## 2) Deep Architecture Observations (Why This Protocol Exists)
|
||||
|
||||
These codebase realities should drive every design decision:
|
||||
|
||||
1. **Trait + factory architecture is the stability backbone**
|
||||
- Extension points are intentionally explicit and swappable.
|
||||
- Most features should be added via trait implementation + factory registration, not cross-cutting rewrites.
|
||||
2. **Security-critical surfaces are first-class and internet-adjacent**
|
||||
- `src/gateway/`, `src/security/`, `src/tools/`, `src/runtime/` carry high blast radius.
|
||||
- Defaults already lean secure-by-default (pairing, bind safety, limits, secret handling); keep it that way.
|
||||
3. **Performance and binary size are product goals, not nice-to-have**
|
||||
- `Cargo.toml` release profile and dependency choices optimize for size and determinism.
|
||||
- Convenience dependencies and broad abstractions can silently regress these goals.
|
||||
4. **Config and runtime contracts are user-facing API**
|
||||
- `src/config/schema.rs` and CLI commands are effectively public interfaces.
|
||||
- Backward compatibility and explicit migration matter.
|
||||
5. **The project now runs in high-concurrency collaboration mode**
|
||||
- CI + docs governance + label routing are part of the product delivery system.
|
||||
- PR throughput is a design constraint; not just a maintainer inconvenience.
|
||||
|
||||
## 3) Engineering Principles (Normative)
|
||||
|
||||
These principles are mandatory by default. They are not slogans; they are implementation constraints.
|
||||
|
||||
### 3.1 KISS (Keep It Simple, Stupid)
|
||||
|
||||
**Why here:** Runtime + security behavior must stay auditable under pressure.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer straightforward control flow over clever meta-programming.
|
||||
- Prefer explicit match branches and typed structs over hidden dynamic behavior.
|
||||
- Keep error paths obvious and localized.
|
||||
|
||||
### 3.2 YAGNI (You Aren't Gonna Need It)
|
||||
|
||||
**Why here:** Premature features increase attack surface and maintenance burden.
|
||||
|
||||
Required:
|
||||
|
||||
- Do not add new config keys, trait methods, feature flags, or workflow branches without a concrete accepted use case.
|
||||
- Do not introduce speculative “future-proof” abstractions without at least one current caller.
|
||||
- Keep unsupported paths explicit (error out) rather than adding partial fake support.
|
||||
|
||||
### 3.3 DRY + Rule of Three
|
||||
|
||||
**Why here:** Naive DRY can create brittle shared abstractions across providers/channels/tools.
|
||||
|
||||
Required:
|
||||
|
||||
- Duplicate small, local logic when it preserves clarity.
|
||||
- Extract shared utilities only after repeated, stable patterns (rule-of-three).
|
||||
- When extracting, preserve module boundaries and avoid hidden coupling.
|
||||
|
||||
### 3.4 SRP + ISP (Single Responsibility + Interface Segregation)
|
||||
|
||||
**Why here:** Trait-driven architecture already encodes subsystem boundaries.
|
||||
|
||||
Required:
|
||||
|
||||
- Keep each module focused on one concern.
|
||||
- Extend behavior by implementing existing narrow traits whenever possible.
|
||||
- Avoid fat interfaces and “god modules” that mix policy + transport + storage.
|
||||
|
||||
### 3.5 Fail Fast + Explicit Errors
|
||||
|
||||
**Why here:** Silent fallback in agent runtimes can create unsafe or costly behavior.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer explicit `bail!`/errors for unsupported or unsafe states.
|
||||
- Never silently broaden permissions/capabilities.
|
||||
- Document fallback behavior when fallback is intentional and safe.
|
||||
|
||||
### 3.6 Secure by Default + Least Privilege
|
||||
|
||||
**Why here:** Gateway/tools/runtime can execute actions with real-world side effects.
|
||||
|
||||
Required:
|
||||
|
||||
- Deny-by-default for access and exposure boundaries.
|
||||
- Never log secrets, raw tokens, or sensitive payloads.
|
||||
- Keep network/filesystem/shell scope as narrow as possible unless explicitly justified.
|
||||
|
||||
### 3.7 Determinism + Reproducibility
|
||||
|
||||
**Why here:** Reliable CI and low-latency triage depend on deterministic behavior.
|
||||
|
||||
Required:
|
||||
|
||||
- Prefer reproducible commands and locked dependency behavior in CI-sensitive paths.
|
||||
- Keep tests deterministic (no flaky timing/network dependence without guardrails).
|
||||
- Ensure local validation commands map to CI expectations.
|
||||
|
||||
### 3.8 Reversibility + Rollback-First Thinking
|
||||
|
||||
**Why here:** Fast recovery is mandatory under high PR volume.
|
||||
|
||||
Required:
|
||||
|
||||
- Keep changes easy to revert (small scope, clear blast radius).
|
||||
- For risky changes, define rollback path before merge.
|
||||
- Avoid mixed mega-patches that block safe rollback.
|
||||
|
||||
## 4) Repository Map (High-Level)
|
||||
|
||||
- `src/main.rs` — CLI entrypoint and command routing
|
||||
- `src/lib.rs` — module exports and shared command enums
|
||||
- `src/config/` — schema + config loading/merging
|
||||
- `src/agent/` — orchestration loop
|
||||
- `src/gateway/` — webhook/gateway server
|
||||
- `src/security/` — policy, pairing, secret store
|
||||
- `src/memory/` — markdown/sqlite memory backends + embeddings/vector merge
|
||||
- `src/providers/` — model providers and resilient wrapper
|
||||
- `src/channels/` — Telegram/Discord/Slack/etc channels
|
||||
- `src/tools/` — tool execution surface (shell, file, memory, browser)
|
||||
- `src/peripherals/` — hardware peripherals (STM32, RPi GPIO); see `docs/hardware-peripherals-design.md`
|
||||
- `src/runtime/` — runtime adapters (currently native)
|
||||
- `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
|
||||
- `.github/` — CI, templates, automation workflows
|
||||
|
||||
## 4.1 Documentation System Contract (Required)
|
||||
|
||||
Treat documentation as a first-class product surface, not a post-merge artifact.
|
||||
|
||||
Canonical entry points:
|
||||
|
||||
- root READMEs: `README.md`, `README.zh-CN.md`, `README.ja.md`, `README.ru.md`, `README.fr.md`, `README.vi.md`
|
||||
- docs hubs: `docs/README.md`, `docs/README.zh-CN.md`, `docs/README.ja.md`, `docs/README.ru.md`, `docs/README.fr.md`, `docs/i18n/vi/README.md`
|
||||
- unified TOC: `docs/SUMMARY.md`
|
||||
|
||||
Supported locales (current contract):
|
||||
|
||||
- `en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`
|
||||
|
||||
Collection indexes (category navigation):
|
||||
|
||||
- `docs/getting-started/README.md`
|
||||
- `docs/reference/README.md`
|
||||
- `docs/operations/README.md`
|
||||
- `docs/security/README.md`
|
||||
- `docs/hardware/README.md`
|
||||
- `docs/contributing/README.md`
|
||||
- `docs/project/README.md`
|
||||
|
||||
Runtime-contract references (must track behavior changes):
|
||||
|
||||
- `docs/commands-reference.md`
|
||||
- `docs/providers-reference.md`
|
||||
- `docs/channels-reference.md`
|
||||
- `docs/config-reference.md`
|
||||
- `docs/operations-runbook.md`
|
||||
- `docs/troubleshooting.md`
|
||||
- `docs/one-click-bootstrap.md`
|
||||
|
||||
Required docs governance rules:
|
||||
|
||||
- Keep README/hub top navigation and quick routes intuitive and non-duplicative.
|
||||
- Keep entry-point parity across all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`) when changing navigation architecture.
|
||||
- If a change touches docs IA, runtime-contract references, or user-facing wording in shared docs, perform i18n follow-through for currently supported locales in the same PR:
|
||||
- Update locale navigation links (`README*`, `docs/README*`, `docs/SUMMARY.md`).
|
||||
- Update localized runtime-contract docs where equivalents exist (at minimum `commands-reference`, `config-reference`, `troubleshooting` for `fr` and `vi`).
|
||||
- For Vietnamese, treat `docs/i18n/vi/**` as canonical. Keep `docs/*.<locale>.md` compatibility shims aligned if present.
|
||||
- Keep proposal/roadmap docs explicitly labeled; avoid mixing proposal text into runtime-contract docs.
|
||||
- Keep project snapshots date-stamped and immutable once superseded by a newer date.
|
||||
|
||||
## 5) Risk Tiers by Path (Review Depth Contract)
|
||||
|
||||
Use these tiers when deciding validation depth and review rigor.
|
||||
|
||||
- **Low risk**: docs/chore/tests-only changes
|
||||
- **Medium risk**: most `src/**` behavior changes without boundary/security impact
|
||||
- **High risk**: `src/security/**`, `src/runtime/**`, `src/gateway/**`, `src/tools/**`, `.github/workflows/**`, access-control boundaries
|
||||
|
||||
When uncertain, classify as higher risk.
|
||||
|
||||
## 6) Agent Workflow (Required)
|
||||
|
||||
1. **Read before write**
|
||||
- Inspect existing module, factory wiring, and adjacent tests before editing.
|
||||
2. **Define scope boundary**
|
||||
- One concern per PR; avoid mixed feature+refactor+infra patches.
|
||||
3. **Implement minimal patch**
|
||||
- Apply KISS/YAGNI/DRY rule-of-three explicitly.
|
||||
4. **Validate by risk tier**
|
||||
- Docs-only: lightweight checks.
|
||||
- Code/risky changes: full relevant checks and focused scenarios.
|
||||
5. **Document impact**
|
||||
- Update docs/PR notes for behavior, risk, side effects, and rollback.
|
||||
- If CLI/config/provider/channel behavior changed, update corresponding runtime-contract references.
|
||||
- If docs entry points changed, keep all supported locale README/docs-hub navigation aligned (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`).
|
||||
6. **Respect queue hygiene**
|
||||
- If stacked PR: declare `Depends on #...`.
|
||||
- If replacing old PR: declare `Supersedes #...`.
|
||||
|
||||
### 6.1 Branch / Commit / PR Flow (Required)
|
||||
|
||||
All contributors (human or agent) must follow the same collaboration flow:
|
||||
|
||||
- Create and work from a non-`main` branch.
|
||||
- Commit changes to that branch with clear, scoped commit messages.
|
||||
- Open a PR to `main`; do not push directly to `main`.
|
||||
- Wait for required checks and review outcomes before merging.
|
||||
- Merge via PR controls (squash/rebase/merge as repository policy allows).
|
||||
- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
|
||||
|
||||
### 6.2 Worktree Workflow (Required for Multi-Track Agent Work)
|
||||
|
||||
Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
|
||||
|
||||
- Use one worktree per active branch/PR stream to avoid cross-task contamination.
|
||||
- Keep each worktree on a single branch; do not mix unrelated edits in one worktree.
|
||||
- Run validation commands inside the corresponding worktree before commit/PR.
|
||||
- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
|
||||
- PR checkpoint rules from section 6.1 still apply to worktree-based development.
|
||||
|
||||
### 6.3 Code Naming Contract (Required)
|
||||
|
||||
Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
|
||||
|
||||
- Use Rust standard casing consistently: modules/files `snake_case`, types/traits/enums `PascalCase`, functions/variables `snake_case`, constants/statics `SCREAMING_SNAKE_CASE`.
|
||||
- Name types and modules by domain role, not implementation detail (for example `DiscordChannel`, `SecurityPolicy`, `MemoryStore` over vague names like `Manager`/`Helper`).
|
||||
- Keep trait implementer naming explicit and predictable: `<ProviderName>Provider`, `<ChannelName>Channel`, `<ToolName>Tool`, `<BackendName>Memory`.
|
||||
- Keep factory registration keys stable, lowercase, and user-facing (for example `"openai"`, `"discord"`, `"shell"`), and avoid alias sprawl without migration need.
|
||||
- Name tests by behavior/outcome (`<subject>_<expected_behavior>`) and keep fixture identifiers neutral/project-scoped.
|
||||
- If identity-like naming is required in tests/examples, use ZeroClaw-native labels only (`ZeroClawAgent`, `zeroclaw_user`, `zeroclaw_node`).
|
||||
|
||||
### 6.4 Architecture Boundary Contract (Required)
|
||||
|
||||
Use these rules to keep the trait/factory architecture stable under growth.
|
||||
|
||||
- Extend capabilities by adding trait implementations + factory wiring first; avoid cross-module rewrites for isolated features.
|
||||
- Keep dependency direction inward to contracts: concrete integrations depend on trait/config/util layers, not on other concrete integrations.
|
||||
- Avoid creating cross-subsystem coupling (for example provider code importing channel internals, tool code mutating gateway policy directly).
|
||||
- Keep module responsibilities single-purpose: orchestration in `agent/`, transport in `channels/`, model I/O in `providers/`, policy in `security/`, execution in `tools/`.
|
||||
- Introduce new shared abstractions only after repeated use (rule-of-three), with at least one real caller in current scope.
|
||||
- For config/schema changes, treat keys as public contract: document defaults, compatibility impact, and migration/rollback path.
|
||||
|
||||
## 7) Change Playbooks
|
||||
|
||||
### 7.1 Adding a Provider
|
||||
|
||||
- Implement `Provider` in `src/providers/`.
|
||||
- Register in `src/providers/mod.rs` factory.
|
||||
- Add focused tests for factory wiring and error paths.
|
||||
- Avoid provider-specific behavior leaks into shared orchestration code.
|
||||
|
||||
### 7.2 Adding a Channel
|
||||
|
||||
- Implement `Channel` in `src/channels/`.
|
||||
- Keep `send`, `listen`, `health_check`, typing semantics consistent.
|
||||
- Cover auth/allowlist/health behavior with tests.
|
||||
|
||||
### 7.3 Adding a Tool
|
||||
|
||||
- Implement `Tool` in `src/tools/` with strict parameter schema.
|
||||
- Validate and sanitize all inputs.
|
||||
- Return structured `ToolResult`; avoid panics in runtime path.
|
||||
|
||||
### 7.4 Adding a Peripheral
|
||||
|
||||
- Implement `Peripheral` in `src/peripherals/`.
|
||||
- Peripherals expose `tools()` — each tool delegates to the hardware (GPIO, sensors, etc.).
|
||||
- Register board type in config schema if needed.
|
||||
- See `docs/hardware-peripherals-design.md` for protocol and firmware notes.
|
||||
|
||||
### 7.5 Security / Runtime / Gateway Changes
|
||||
|
||||
- Include threat/risk notes and rollback strategy.
|
||||
- Add/update tests or validation evidence for failure modes and boundaries.
|
||||
- Keep observability useful but non-sensitive.
|
||||
- For `.github/workflows/**` changes, include Actions allowlist impact in PR notes and update `docs/actions-source-policy.md` when sources change.
|
||||
|
||||
### 7.6 Docs System / README / IA Changes
|
||||
|
||||
- Treat docs navigation as product UX: preserve clear pathing from README -> docs hub -> SUMMARY -> category index.
|
||||
- Keep top-level nav concise; avoid duplicative links across adjacent nav blocks.
|
||||
- When runtime surfaces change, update related references (`commands/providers/channels/config/runbook/troubleshooting`).
|
||||
- Keep multilingual entry-point parity for all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`) when nav or key wording changes.
|
||||
- When shared docs wording changes, sync corresponding localized docs for supported locales in the same PR (or explicitly document deferral and follow-up PR).
|
||||
- For docs snapshots, add new date-stamped files for new sprints rather than rewriting historical context.
|
||||
|
||||
|
||||
## 8) Validation Matrix
|
||||
|
||||
Default local checks for code changes:
|
||||
|
||||
```bash
|
||||
cargo fmt --all -- --check
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
cargo test
|
||||
```
|
||||
|
||||
Preferred local pre-PR validation path (recommended, not required):
|
||||
|
||||
```bash
|
||||
./dev/ci.sh all
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Local Docker-based CI is strongly recommended when Docker is available.
|
||||
- Contributors are not blocked from opening a PR if local Docker CI is unavailable; in that case run the most relevant native checks and document what was run.
|
||||
|
||||
Additional expectations by change type:
|
||||
|
||||
- **Docs/template-only**:
|
||||
- run markdown lint and link-integrity checks
|
||||
- if touching README/docs-hub/SUMMARY/collection indexes, verify EN/ZH/JA/RU navigation parity
|
||||
- if touching bootstrap docs/scripts, run `bash -n bootstrap.sh scripts/bootstrap.sh scripts/install.sh`
|
||||
- **Workflow changes**: validate YAML syntax; run workflow lint/sanity checks when available.
|
||||
- **Security/runtime/gateway/tools**: include at least one boundary/failure-mode validation.
|
||||
|
||||
If full checks are impractical, run the most relevant subset and document what was skipped and why.
|
||||
|
||||
## 9) Collaboration and PR Discipline
|
||||
|
||||
- Follow `.github/pull_request_template.md` fully (including side effects / blast radius).
|
||||
- Keep PR descriptions concrete: problem, change, non-goals, risk, rollback.
|
||||
- Use conventional commit titles.
|
||||
- Prefer small PRs (`size: XS/S/M`) when possible.
|
||||
- Agent-assisted PRs are welcome, **but contributors remain accountable for understanding what their code will do**.
|
||||
|
||||
### 9.1 Privacy/Sensitive Data and Neutral Wording (Required)
|
||||
|
||||
Treat privacy and neutrality as merge gates, not best-effort guidelines.
|
||||
|
||||
- Never commit personal or sensitive data in code, docs, tests, fixtures, snapshots, logs, examples, or commit messages.
|
||||
- Prohibited data includes (non-exhaustive): real names, personal emails, phone numbers, addresses, access tokens, API keys, credentials, IDs, and private URLs.
|
||||
- Use neutral project-scoped placeholders (for example: `user_a`, `test_user`, `project_bot`, `example.com`) instead of real identity data.
|
||||
- Test names/messages/fixtures must be impersonal and system-focused; avoid first-person or identity-specific language.
|
||||
- If identity-like context is unavoidable, use ZeroClaw-scoped roles/labels only (for example: `ZeroClawAgent`, `ZeroClawOperator`, `zeroclaw_user`) and avoid real-world personas.
|
||||
- Recommended identity-safe naming palette (use when identity-like context is required):
|
||||
- actor labels: `ZeroClawAgent`, `ZeroClawOperator`, `ZeroClawMaintainer`, `zeroclaw_user`
|
||||
- service/runtime labels: `zeroclaw_bot`, `zeroclaw_service`, `zeroclaw_runtime`, `zeroclaw_node`
|
||||
- environment labels: `zeroclaw_project`, `zeroclaw_workspace`, `zeroclaw_channel`
|
||||
- If reproducing external incidents, redact and anonymize all payloads before committing.
|
||||
- Before push, review `git diff --cached` specifically for accidental sensitive strings and identity leakage.
|
||||
|
||||
### 9.2 Superseded-PR Attribution (Required)
|
||||
|
||||
When a PR supersedes another contributor's PR and carries forward substantive code or design decisions, preserve authorship explicitly.
|
||||
|
||||
- In the integrating commit message, add one `Co-authored-by: Name <email>` trailer per superseded contributor whose work is materially incorporated.
|
||||
- Use a GitHub-recognized email (`<login@users.noreply.github.com>` or the contributor's verified commit email) so attribution is rendered correctly.
|
||||
- Keep trailers on their own lines after a blank line at commit-message end; never encode them as escaped `\\n` text.
|
||||
- In the PR body, list superseded PR links and briefly state what was incorporated from each.
|
||||
- If no actual code/design was incorporated (only inspiration), do not use `Co-authored-by`; give credit in PR notes instead.
|
||||
|
||||
### 9.3 Superseded-PR PR Template (Recommended)
|
||||
|
||||
When superseding multiple PRs, use a consistent title/body structure to reduce reviewer ambiguity.
|
||||
|
||||
- Recommended title format: `feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]`
|
||||
- If this is docs/chore/meta only, keep the same supersede suffix and use the appropriate conventional-commit type.
|
||||
- In the PR body, include the following template (fill placeholders, remove non-applicable lines):
|
||||
|
||||
```md
|
||||
## Supersedes
|
||||
- #<pr_a> by @<author_a>
|
||||
- #<pr_b> by @<author_b>
|
||||
- #<pr_n> by @<author_n>
|
||||
|
||||
## Integrated Scope
|
||||
- From #<pr_a>: <what was materially incorporated>
|
||||
- From #<pr_b>: <what was materially incorporated>
|
||||
- From #<pr_n>: <what was materially incorporated>
|
||||
|
||||
## Attribution
|
||||
- Co-authored-by trailers added for materially incorporated contributors: Yes/No
|
||||
- If No, explain why (for example: no direct code/design carry-over)
|
||||
|
||||
## Non-goals
|
||||
- <explicitly list what was not carried over>
|
||||
|
||||
## Risk and Rollback
|
||||
- Risk: <summary>
|
||||
- Rollback: <revert commit/PR strategy>
|
||||
```
|
||||
|
||||
### 9.4 Superseded-PR Commit Template (Recommended)
|
||||
|
||||
When a commit unifies or supersedes prior PR work, use a deterministic commit message layout so attribution is machine-parsed and reviewer-friendly.
|
||||
|
||||
- Keep one blank line between message sections, and exactly one blank line before trailer lines.
|
||||
- Keep each trailer on its own line; do not wrap, indent, or encode as escaped `\n` text.
|
||||
- Add one `Co-authored-by` trailer per materially incorporated contributor, using GitHub-recognized email.
|
||||
- If no direct code/design is carried over, omit `Co-authored-by` and explain attribution in the PR body instead.
|
||||
|
||||
```text
|
||||
feat(<scope>): unify and supersede #<pr_a>, #<pr_b> [and #<pr_n>]
|
||||
|
||||
<one-paragraph summary of integrated outcome>
|
||||
|
||||
Supersedes:
|
||||
- #<pr_a> by @<author_a>
|
||||
- #<pr_b> by @<author_b>
|
||||
- #<pr_n> by @<author_n>
|
||||
|
||||
Integrated scope:
|
||||
- <subsystem_or_feature_a>: from #<pr_x>
|
||||
- <subsystem_or_feature_b>: from #<pr_y>
|
||||
|
||||
Co-authored-by: <Name A> <login_a@users.noreply.github.com>
|
||||
Co-authored-by: <Name B> <login_b@users.noreply.github.com>
|
||||
```
|
||||
|
||||
Reference docs:
|
||||
|
||||
- `CONTRIBUTING.md`
|
||||
- `docs/README.md`
|
||||
- `docs/SUMMARY.md`
|
||||
- `docs/docs-inventory.md`
|
||||
- `docs/commands-reference.md`
|
||||
- `docs/providers-reference.md`
|
||||
- `docs/channels-reference.md`
|
||||
- `docs/config-reference.md`
|
||||
- `docs/operations-runbook.md`
|
||||
- `docs/troubleshooting.md`
|
||||
- `docs/one-click-bootstrap.md`
|
||||
- `docs/pr-workflow.md`
|
||||
- `docs/reviewer-playbook.md`
|
||||
- `docs/ci-map.md`
|
||||
- `docs/actions-source-policy.md`
|
||||
|
||||
## 10) Anti-Patterns (Do Not)
|
||||
|
||||
- Do not add heavy dependencies for minor convenience.
|
||||
- Do not silently weaken security policy or access constraints.
|
||||
- Do not add speculative config/feature flags “just in case”.
|
||||
- Do not mix massive formatting-only changes with functional changes.
|
||||
- Do not modify unrelated modules “while here”.
|
||||
- Do not bypass failing checks without explicit explanation.
|
||||
- Do not hide behavior-changing side effects in refactor commits.
|
||||
- Do not include personal identity or sensitive information in test data, examples, docs, or commits.
|
||||
|
||||
## 11) Handoff Template (Agent -> Agent / Maintainer)
|
||||
|
||||
When handing off work, include:
|
||||
|
||||
1. What changed
|
||||
2. What did not change
|
||||
3. Validation run and results
|
||||
4. Remaining risks / unknowns
|
||||
5. Next recommended action
|
||||
|
||||
## 12) Vibe Coding Guardrails
|
||||
|
||||
When working in fast iterative mode:
|
||||
|
||||
- Keep each iteration reversible (small commits, clear rollback).
|
||||
- Validate assumptions with code search before implementing.
|
||||
- Prefer deterministic behavior over clever shortcuts.
|
||||
- Do not “ship and hope” on security-sensitive paths.
|
||||
- If uncertain, leave a concrete TODO with verification context, not a hidden guess.
|
||||
|
||||
@ -60,7 +60,7 @@ representative at an online or offline event.
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be
|
||||
reported to the community leaders responsible for enforcement at
|
||||
https://x.com/argenistherose.
|
||||
https://x.com/willsarg617.
|
||||
All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
All community leaders are obligated to respect the privacy and security of the
|
||||
|
||||
@ -2,42 +2,6 @@
|
||||
|
||||
Thanks for your interest in contributing to ZeroClaw! This guide will help you get started.
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ Branch Migration Notice (March 2026)
|
||||
|
||||
**`master` is the ONLY default branch. The `main` branch no longer exists.**
|
||||
|
||||
If you have an existing fork or local clone that tracks `main`, you **must** update it:
|
||||
|
||||
```bash
|
||||
# Update your local clone to track master
|
||||
git checkout master
|
||||
git branch -D main 2>/dev/null # delete local main if it exists
|
||||
git remote set-head origin master
|
||||
git fetch origin --prune # remove stale remote refs
|
||||
|
||||
# If your fork still has a main branch, delete it
|
||||
git push origin --delete main 2>/dev/null
|
||||
```
|
||||
|
||||
All PRs must target **`master`**. PRs targeting `main` will be rejected.
|
||||
|
||||
**Background:** ZeroClaw previously used `main` in some documentation and scripts, which caused 404 errors, broken CI refs, and contributor confusion (see [#2929](https://github.com/zeroclaw-labs/zeroclaw/issues/2929), [#3061](https://github.com/zeroclaw-labs/zeroclaw/issues/3061), [#3194](https://github.com/zeroclaw-labs/zeroclaw/pull/3194)). As of March 2026, all references have been corrected, stale branches cleaned up, and the `main` branch permanently deleted.
|
||||
|
||||
---
|
||||
|
||||
## Branching Model
|
||||
|
||||
> **`master`** is the single source-of-truth branch.
|
||||
>
|
||||
> **How contributors should work:**
|
||||
> 1. Fork the repository
|
||||
> 2. Create a `feat/*` or `fix/*` branch from `master`
|
||||
> 3. Open a PR targeting `master`
|
||||
>
|
||||
> Do **not** create or push to a `main` branch. There is no `main` branch — it will not work.
|
||||
|
||||
## First-Time Contributors
|
||||
|
||||
Welcome — contributions of all sizes are valued. If this is your first contribution, here is how to get started:
|
||||
@ -51,9 +15,9 @@ Welcome — contributions of all sizes are valued. If this is your first contrib
|
||||
|
||||
3. **Follow the fork → branch → change → test → PR workflow:**
|
||||
- Fork the repository and clone your fork
|
||||
- Create a feature branch (`git checkout -b feat/my-change` or `git checkout -b fix/my-change`)
|
||||
- Create a feature branch (`git checkout -b fix/my-change`)
|
||||
- Make your changes and run `cargo fmt && cargo clippy && cargo test`
|
||||
- Open a PR against `master` using the PR template
|
||||
- Open a PR against `dev` using the PR template
|
||||
|
||||
4. **Start with Track A.** ZeroClaw uses three [collaboration tracks](#collaboration-tracks-risk-based) (A/B/C) based on risk. First-time contributors should target **Track A** (docs, tests, chore) — these require lighter review and are the fastest path to a merged PR.
|
||||
|
||||
@ -230,7 +194,7 @@ To keep review throughput high without lowering quality, every PR should map to
|
||||
|
||||
| Track | Typical scope | Required review depth |
|
||||
|---|---|---|
|
||||
| **Track A (Low risk)** | docs/tests/chore, isolated refactors, no security/runtime/CI impact | 1 maintainer review + green `CI Required Gate` |
|
||||
| **Track A (Low risk)** | docs/tests/chore, isolated refactors, no security/runtime/CI impact | 1 maintainer review + green CI checks (`test` + `build`) |
|
||||
| **Track B (Medium risk)** | providers/channels/memory/tools behavior changes | 1 subsystem-aware review + explicit validation evidence |
|
||||
| **Track C (High risk)** | `src/security/**`, `src/runtime/**`, `src/gateway/**`, `.github/workflows/**`, access-control boundaries | 2-pass review (fast triage + deep risk review), rollback plan required |
|
||||
|
||||
@ -246,20 +210,20 @@ To keep docs useful under high PR volume, we use these rules:
|
||||
- **Side-effect visibility**: document blast radius, failure modes, and rollback before merge.
|
||||
- **Automation assists, humans decide**: bots triage and label, but merge accountability stays human.
|
||||
- **Index-first discoverability**: `docs/README.md` is the first entry point for operational documentation.
|
||||
- **Template-first authoring**: start new operational docs from `docs/contributing/doc-template.md`.
|
||||
- **Template-first authoring**: start new operational docs from `docs/doc-template.md`.
|
||||
|
||||
### Documentation System Map
|
||||
|
||||
| Doc | Primary purpose | When to update |
|
||||
|---|---|---|
|
||||
| `docs/README.md` | canonical docs index and taxonomy | add/remove docs or change documentation ownership/navigation |
|
||||
| `docs/contributing/doc-template.md` | standard skeleton for new operational documentation | when required sections or documentation quality bar changes |
|
||||
| `docs/doc-template.md` | standard skeleton for new operational documentation | when required sections or documentation quality bar changes |
|
||||
| `CONTRIBUTING.md` | contributor contract and readiness baseline | contributor expectations or policy changes |
|
||||
| `docs/contributing/pr-workflow.md` | governance logic and merge contract | workflow/risk/merge gate changes |
|
||||
| `docs/contributing/reviewer-playbook.md` | reviewer operating checklist | review depth or triage behavior changes |
|
||||
| `docs/contributing/ci-map.md` | CI ownership and triage entry points | workflow trigger/job ownership changes |
|
||||
| `docs/ops/network-deployment.md` | runtime deployment and network operating guide | gateway/channel/tunnel/network runtime behavior changes |
|
||||
| `docs/ops/proxy-agent-playbook.md` | agent-operable proxy runbook and rollback recipes | proxy scope/selector/tooling behavior changes |
|
||||
| `docs/pr-workflow.md` | governance logic and merge contract | workflow/risk/merge gate changes |
|
||||
| `docs/reviewer-playbook.md` | reviewer operating checklist | review depth or triage behavior changes |
|
||||
| `docs/ci-map.md` | CI ownership and triage entry points | workflow trigger/job ownership changes |
|
||||
| `docs/network-deployment.md` | runtime deployment and network operating guide | gateway/channel/tunnel/network runtime behavior changes |
|
||||
| `docs/proxy-agent-playbook.md` | agent-operable proxy runbook and rollback recipes | proxy scope/selector/tooling behavior changes |
|
||||
|
||||
## PR Definition of Ready (DoR)
|
||||
|
||||
@ -273,14 +237,14 @@ Before requesting review, ensure all of the following are true:
|
||||
- Tests/fixtures/examples use neutral project-scoped wording (no identity-specific or first-person phrasing).
|
||||
- If identity-like wording is required, use ZeroClaw-centric labels only (for example: `ZeroClawAgent`, `ZeroClawOperator`, `zeroclaw_user`).
|
||||
- If docs were changed, update `docs/README.md` navigation and reciprocal links with related docs.
|
||||
- If a new operational doc was added, start from `docs/contributing/doc-template.md` and keep risk/rollback/troubleshooting sections where applicable.
|
||||
- If a new operational doc was added, start from `docs/doc-template.md` and keep risk/rollback/troubleshooting sections where applicable.
|
||||
- Linked issue (or rationale for no issue) is included.
|
||||
|
||||
## PR Definition of Done (DoD)
|
||||
|
||||
A PR is merge-ready when:
|
||||
|
||||
- `CI Required Gate` is green.
|
||||
- CI checks are green (`test` + `build` from `ci.yml`).
|
||||
- Required reviewers approved (including CODEOWNERS paths).
|
||||
- Risk level matches changed paths (`risk: low/medium/high`).
|
||||
- User-visible behavior, migration, and rollback notes are complete.
|
||||
@ -301,9 +265,9 @@ When PR traffic is high (especially with AI-assisted contributions), these rules
|
||||
- **Identity normalization**: when identity traits are unavoidable, use ZeroClaw/project-native roles instead of personal or real-world identities.
|
||||
- **Supersede hygiene**: if your PR replaces an older open PR, add `Supersedes #...` and request maintainers close the outdated one.
|
||||
|
||||
Full maintainer workflow: [`docs/contributing/pr-workflow.md`](docs/contributing/pr-workflow.md).
|
||||
CI workflow ownership and triage map: [`docs/contributing/ci-map.md`](docs/contributing/ci-map.md).
|
||||
Reviewer operating checklist: [`docs/contributing/reviewer-playbook.md`](docs/contributing/reviewer-playbook.md).
|
||||
Full maintainer workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md).
|
||||
CI workflow ownership and triage map: [`docs/ci-map.md`](docs/ci-map.md).
|
||||
Reviewer operating checklist: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md).
|
||||
|
||||
## Agent Collaboration Guidance
|
||||
|
||||
@ -568,12 +532,10 @@ Recommended scope keys in commit titles:
|
||||
|
||||
## Maintainer Merge Policy
|
||||
|
||||
- Require passing `CI Required Gate` before merge.
|
||||
- Require docs quality checks when docs are touched.
|
||||
- Require passing CI checks (`test` + `build`) before merge.
|
||||
- Require review approval for non-trivial changes.
|
||||
- Require CODEOWNERS review for protected paths.
|
||||
- Use risk labels to determine review depth, scope labels (`core`, `provider`, `channel`, `security`, etc.) to route ownership, and module labels (`<module>:<component>`, e.g. `channel:telegram`, `provider:kimi`, `tool:shell`) to route subsystem expertise.
|
||||
- Contributor tier labels are auto-applied on PRs and issues by merged PR count: `experienced contributor` (>=10), `principal contributor` (>=20), `distinguished contributor` (>=50). Treat them as read-only automation labels; manual edits are auto-corrected.
|
||||
- Use risk labels to determine review depth and scope labels to route ownership.
|
||||
- Prefer squash merge with conventional commit title.
|
||||
- Revert fast on regressions; re-land with tests.
|
||||
|
||||
|
||||
5327
Cargo.lock
generated
5327
Cargo.lock
generated
File diff suppressed because it is too large
Load Diff
117
Cargo.toml
117
Cargo.toml
@ -1,10 +1,10 @@
|
||||
[workspace]
|
||||
members = [".", "crates/robot-kit", "crates/aardvark-sys", "apps/tauri"]
|
||||
members = [".", "crates/robot-kit"]
|
||||
resolver = "2"
|
||||
|
||||
[package]
|
||||
name = "zeroclawlabs"
|
||||
version = "0.6.1"
|
||||
name = "zeroclaw"
|
||||
version = "0.1.7"
|
||||
edition = "2021"
|
||||
authors = ["theonlyhennygod"]
|
||||
license = "MIT OR Apache-2.0"
|
||||
@ -14,24 +14,6 @@ readme = "README.md"
|
||||
keywords = ["ai", "agent", "cli", "assistant", "chatbot"]
|
||||
categories = ["command-line-utilities", "api-bindings"]
|
||||
rust-version = "1.87"
|
||||
include = [
|
||||
"/src/**/*",
|
||||
"/build.rs",
|
||||
"/Cargo.toml",
|
||||
"/Cargo.lock",
|
||||
"/LICENSE*",
|
||||
"/README.md",
|
||||
"/web/dist/**/*",
|
||||
"/tool_descriptions/**/*",
|
||||
]
|
||||
|
||||
[[bin]]
|
||||
name = "zeroclaw"
|
||||
path = "src/main.rs"
|
||||
|
||||
[lib]
|
||||
name = "zeroclaw"
|
||||
path = "src/lib.rs"
|
||||
|
||||
[dependencies]
|
||||
# CLI - minimal and fast
|
||||
@ -39,7 +21,7 @@ clap = { version = "4.5", features = ["derive"] }
|
||||
clap_complete = "4.5"
|
||||
|
||||
# Async runtime - feature-optimized for size
|
||||
tokio = { version = "1.50", default-features = false, features = ["rt-multi-thread", "macros", "time", "net", "io-util", "sync", "process", "io-std", "fs", "signal"] }
|
||||
tokio = { version = "1.42", default-features = false, features = ["rt-multi-thread", "macros", "time", "net", "io-util", "sync", "process", "io-std", "fs", "signal"] }
|
||||
tokio-util = { version = "0.7", default-features = false }
|
||||
tokio-stream = { version = "0.1.18", default-features = false, features = ["fs", "sync"] }
|
||||
|
||||
@ -53,7 +35,6 @@ matrix-sdk = { version = "0.16", optional = true, default-features = false, feat
|
||||
serde = { version = "1.0", default-features = false, features = ["derive"] }
|
||||
serde_json = { version = "1.0", default-features = false, features = ["std"] }
|
||||
serde_ignored = "0.1"
|
||||
serde_yaml = "0.9"
|
||||
|
||||
# Config
|
||||
directories = "6.0"
|
||||
@ -67,8 +48,8 @@ schemars = "1.2"
|
||||
tracing = { version = "0.1", default-features = false }
|
||||
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "ansi", "env-filter"] }
|
||||
|
||||
# Observability - Prometheus metrics (optional; requires AtomicU64, unavailable on 32-bit)
|
||||
prometheus = { version = "0.14", default-features = false, optional = true }
|
||||
# Observability - Prometheus metrics
|
||||
prometheus = { version = "0.14", default-features = false }
|
||||
|
||||
# Base64 encoding (screenshots, image data)
|
||||
base64 = "0.22"
|
||||
@ -81,26 +62,14 @@ urlencoding = "2.1"
|
||||
nanohtml2text = "0.2"
|
||||
|
||||
# Optional Rust-native browser automation backend
|
||||
fantoccini = { version = "0.22.1", optional = true, default-features = false, features = ["rustls-tls"] }
|
||||
|
||||
# Progress bars (update pipeline)
|
||||
indicatif = "0.18"
|
||||
|
||||
# Temp files (update pipeline rollback)
|
||||
tempfile = "3.26"
|
||||
|
||||
# Zip extraction for ClawhHub / OpenClaw registry installers
|
||||
zip = { version = "8.1", default-features = false, features = ["deflate"] }
|
||||
fantoccini = { version = "0.22.0", optional = true, default-features = false, features = ["rustls-tls"] }
|
||||
|
||||
# Error handling
|
||||
anyhow = "1.0"
|
||||
thiserror = "2.0"
|
||||
|
||||
# Aardvark I2C/SPI/GPIO USB adapter (Total Phase) — stub when SDK absent
|
||||
aardvark-sys = { path = "crates/aardvark-sys", version = "0.1.0" }
|
||||
|
||||
# UUID generation
|
||||
uuid = { version = "1.22", default-features = false, features = ["v4", "std"] }
|
||||
uuid = { version = "1.11", default-features = false, features = ["v4", "std"] }
|
||||
|
||||
# Authenticated encryption (AEAD) for secret store
|
||||
chacha20poly1305 = "0.10"
|
||||
@ -113,9 +82,6 @@ hex = "0.4"
|
||||
# CSPRNG for secure token generation
|
||||
rand = "0.10"
|
||||
|
||||
# Portable atomic fallbacks for targets without native 64-bit atomics
|
||||
portable-atomic = "1"
|
||||
|
||||
# serde-big-array for wa-rs storage (large array serialization)
|
||||
serde-big-array = { version = "0.5", optional = true }
|
||||
|
||||
@ -149,10 +115,9 @@ glob = "0.3"
|
||||
which = "8.0"
|
||||
|
||||
# WebSocket client channels (Discord/Lark/DingTalk/Nostr)
|
||||
tokio-tungstenite = { version = "0.29", features = ["rustls-tls-webpki-roots"] }
|
||||
tokio-socks = "0.5"
|
||||
tokio-tungstenite = { version = "0.28", features = ["rustls-tls-webpki-roots"] }
|
||||
futures-util = { version = "0.3", default-features = false, features = ["sink"] }
|
||||
nostr-sdk = { version = "0.44", default-features = false, features = ["nip04", "nip59"], optional = true }
|
||||
nostr-sdk = { version = "0.44", default-features = false, features = ["nip04", "nip59"] }
|
||||
regex = "1.10"
|
||||
hostname = "0.4.2"
|
||||
rustls = "0.23"
|
||||
@ -197,12 +162,6 @@ probe-rs = { version = "0.31", optional = true }
|
||||
# PDF extraction for datasheet RAG (optional, enable with --features rag-pdf)
|
||||
pdf-extract = { version = "0.10", optional = true }
|
||||
|
||||
# WASM plugin runtime (extism)
|
||||
extism = { version = "1.20", optional = true }
|
||||
|
||||
# Cross-platform audio capture for voice wake word detection (optional, enable with --features voice-wake)
|
||||
cpal = { version = "0.15", optional = true }
|
||||
|
||||
# Terminal QR rendering for WhatsApp Web pairing flow.
|
||||
qrcode = { version = "0.14", optional = true }
|
||||
|
||||
@ -225,14 +184,11 @@ landlock = { version = "0.4", optional = true }
|
||||
libc = "0.2"
|
||||
|
||||
[features]
|
||||
default = ["observability-prometheus", "channel-nostr", "channel-lark", "skill-creation"]
|
||||
channel-nostr = ["dep:nostr-sdk"]
|
||||
default = []
|
||||
hardware = ["nusb", "tokio-serial"]
|
||||
channel-matrix = ["dep:matrix-sdk"]
|
||||
channel-lark = ["dep:prost"]
|
||||
channel-feishu = ["channel-lark"] # Alias for Feishu users (Lark and Feishu are the same platform)
|
||||
memory-postgres = ["dep:postgres"]
|
||||
observability-prometheus = ["dep:prometheus"]
|
||||
observability-otel = ["dep:opentelemetry", "dep:opentelemetry_sdk", "dep:opentelemetry-otlp"]
|
||||
peripheral-rpi = ["rppal"]
|
||||
# Browser backend feature alias used by cfg(feature = "browser-native")
|
||||
@ -244,40 +200,12 @@ sandbox-landlock = ["dep:landlock"]
|
||||
sandbox-bubblewrap = []
|
||||
# Backward-compatible alias for older invocations
|
||||
landlock = ["sandbox-landlock"]
|
||||
# Prometheus metrics observer (requires 64-bit atomics; disable on 32-bit targets)
|
||||
metrics = ["observability-prometheus"]
|
||||
# probe = probe-rs for Nucleo memory read (adds ~50 deps; optional)
|
||||
probe = ["dep:probe-rs"]
|
||||
# rag-pdf = PDF ingestion for datasheet RAG
|
||||
rag-pdf = ["dep:pdf-extract"]
|
||||
# skill-creation = Autonomous skill creation from successful multi-step tasks
|
||||
skill-creation = []
|
||||
# whatsapp-web = Native WhatsApp Web client with custom rusqlite storage backend
|
||||
whatsapp-web = ["dep:wa-rs", "dep:wa-rs-core", "dep:wa-rs-binary", "dep:wa-rs-proto", "dep:wa-rs-ureq-http", "dep:wa-rs-tokio-transport", "dep:serde-big-array", "dep:prost", "dep:qrcode"]
|
||||
# voice-wake = Voice wake word detection via microphone (cpal)
|
||||
voice-wake = ["dep:cpal"]
|
||||
# WASM plugin system (extism-based)
|
||||
plugins-wasm = ["dep:extism"]
|
||||
# Meta-feature for CI: all features except those requiring system C libraries
|
||||
# not available on standard CI runners (e.g., voice-wake needs libasound2-dev).
|
||||
ci-all = [
|
||||
"channel-nostr",
|
||||
"hardware",
|
||||
"channel-matrix",
|
||||
"channel-lark",
|
||||
"memory-postgres",
|
||||
"observability-prometheus",
|
||||
"observability-otel",
|
||||
"peripheral-rpi",
|
||||
"browser-native",
|
||||
"sandbox-landlock",
|
||||
"sandbox-bubblewrap",
|
||||
"probe",
|
||||
"rag-pdf",
|
||||
"skill-creation",
|
||||
"whatsapp-web",
|
||||
"plugins-wasm",
|
||||
]
|
||||
|
||||
[profile.release]
|
||||
opt-level = "z" # Optimize for size
|
||||
@ -292,11 +220,6 @@ inherits = "release"
|
||||
codegen-units = 8 # Parallel codegen for faster builds on powerful machines (16GB+ RAM recommended)
|
||||
# Use: cargo build --profile release-fast
|
||||
|
||||
[profile.ci]
|
||||
inherits = "release"
|
||||
lto = "thin" # Much faster than fat LTO; still catches release-mode issues
|
||||
codegen-units = 16 # Full parallelism for CI runners
|
||||
|
||||
[profile.dist]
|
||||
inherits = "release"
|
||||
opt-level = "z"
|
||||
@ -306,27 +229,11 @@ strip = true
|
||||
panic = "abort"
|
||||
|
||||
[dev-dependencies]
|
||||
tempfile = "3.26"
|
||||
tempfile = "3.14"
|
||||
criterion = { version = "0.8", features = ["async_tokio"] }
|
||||
wiremock = "0.6"
|
||||
scopeguard = "1.2"
|
||||
|
||||
[[test]]
|
||||
name = "component"
|
||||
path = "tests/test_component.rs"
|
||||
|
||||
[[test]]
|
||||
name = "integration"
|
||||
path = "tests/test_integration.rs"
|
||||
|
||||
[[test]]
|
||||
name = "system"
|
||||
path = "tests/test_system.rs"
|
||||
|
||||
[[test]]
|
||||
name = "live"
|
||||
path = "tests/test_live.rs"
|
||||
|
||||
[[bench]]
|
||||
name = "agent_benchmarks"
|
||||
harness = false
|
||||
|
||||
107
Dockerfile
107
Dockerfile
@ -1,18 +1,9 @@
|
||||
# syntax=docker/dockerfile:1.7
|
||||
|
||||
# ── Stage 0: Frontend build ─────────────────────────────────────
|
||||
FROM node:22-alpine AS web-builder
|
||||
WORKDIR /web
|
||||
COPY web/package.json web/package-lock.json* ./
|
||||
RUN npm ci --ignore-scripts 2>/dev/null || npm install --ignore-scripts
|
||||
COPY web/ .
|
||||
RUN npm run build
|
||||
|
||||
# ── Stage 1: Build ────────────────────────────────────────────
|
||||
FROM rust:1.94-slim@sha256:da9dab7a6b8dd428e71718402e97207bb3e54167d37b5708616050b1e8f60ed6 AS builder
|
||||
FROM rust:1.93-slim@sha256:9663b80a1621253d30b146454f903de48f0af925c967be48c84745537cd35d8b AS builder
|
||||
|
||||
WORKDIR /app
|
||||
ARG ZEROCLAW_CARGO_FEATURES="memory-postgres,channel-lark"
|
||||
|
||||
# Install build dependencies
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
@ -23,68 +14,64 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
|
||||
# 1. Copy manifests to cache dependencies
|
||||
COPY Cargo.toml Cargo.lock ./
|
||||
# Include every workspace member: Cargo.lock is generated for the full workspace.
|
||||
# Previously we used sed to drop `crates/robot-kit`, which made the manifest disagree
|
||||
# with the lockfile and caused `cargo --locked` to fail (Cargo refused to rewrite the lock).
|
||||
COPY crates/robot-kit/ crates/robot-kit/
|
||||
COPY crates/aardvark-sys/ crates/aardvark-sys/
|
||||
COPY crates/robot-kit/Cargo.toml crates/robot-kit/Cargo.toml
|
||||
# Create dummy targets declared in Cargo.toml so manifest parsing succeeds.
|
||||
RUN mkdir -p src benches \
|
||||
RUN mkdir -p src benches crates/robot-kit/src \
|
||||
&& echo "fn main() {}" > src/main.rs \
|
||||
&& echo "" > src/lib.rs \
|
||||
&& echo "fn main() {}" > benches/agent_benchmarks.rs
|
||||
&& echo "fn main() {}" > benches/agent_benchmarks.rs \
|
||||
&& echo "pub fn placeholder() {}" > crates/robot-kit/src/lib.rs
|
||||
RUN --mount=type=cache,id=zeroclaw-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-cargo-git,target=/usr/local/cargo/git,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-target,target=/app/target,sharing=locked \
|
||||
if [ -n "$ZEROCLAW_CARGO_FEATURES" ]; then \
|
||||
cargo build --release --locked --features "$ZEROCLAW_CARGO_FEATURES"; \
|
||||
else \
|
||||
cargo build --release --locked; \
|
||||
fi
|
||||
RUN rm -rf src benches
|
||||
cargo build --release --locked
|
||||
RUN rm -rf src benches crates/robot-kit/src
|
||||
|
||||
# 2. Copy only build-relevant source paths (avoid cache-busting on docs/tests/scripts)
|
||||
COPY src/ src/
|
||||
COPY benches/ benches/
|
||||
COPY --from=web-builder /web/dist web/dist
|
||||
COPY *.rs .
|
||||
RUN touch src/main.rs
|
||||
COPY crates/ crates/
|
||||
COPY firmware/ firmware/
|
||||
COPY web/ web/
|
||||
# Keep release builds resilient when frontend dist assets are not prebuilt in Git.
|
||||
RUN mkdir -p web/dist && \
|
||||
if [ ! -f web/dist/index.html ]; then \
|
||||
printf '%s\n' \
|
||||
'<!doctype html>' \
|
||||
'<html lang="en">' \
|
||||
' <head>' \
|
||||
' <meta charset="utf-8" />' \
|
||||
' <meta name="viewport" content="width=device-width,initial-scale=1" />' \
|
||||
' <title>ZeroClaw Dashboard</title>' \
|
||||
' </head>' \
|
||||
' <body>' \
|
||||
' <h1>ZeroClaw Dashboard Unavailable</h1>' \
|
||||
' <p>Frontend assets are not bundled in this build. Build the web UI to populate <code>web/dist</code>.</p>' \
|
||||
' </body>' \
|
||||
'</html>' > web/dist/index.html; \
|
||||
fi
|
||||
RUN --mount=type=cache,id=zeroclaw-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-cargo-git,target=/usr/local/cargo/git,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-target,target=/app/target,sharing=locked \
|
||||
rm -rf target/release/.fingerprint/zeroclawlabs-* \
|
||||
target/release/deps/zeroclawlabs-* \
|
||||
target/release/incremental/zeroclawlabs-* && \
|
||||
if [ -n "$ZEROCLAW_CARGO_FEATURES" ]; then \
|
||||
cargo build --release --locked --features "$ZEROCLAW_CARGO_FEATURES"; \
|
||||
else \
|
||||
cargo build --release --locked; \
|
||||
fi && \
|
||||
cargo build --release --locked && \
|
||||
cp target/release/zeroclaw /app/zeroclaw && \
|
||||
strip /app/zeroclaw
|
||||
RUN size=$(stat -c%s /app/zeroclaw) && \
|
||||
if [ "$size" -lt 1000000 ]; then echo "ERROR: binary too small (${size} bytes), likely dummy build artifact" && exit 1; fi
|
||||
|
||||
# Prepare runtime directory structure and default config inline (no extra stage)
|
||||
RUN mkdir -p /zeroclaw-data/.zeroclaw /zeroclaw-data/workspace && \
|
||||
printf '%s\n' \
|
||||
'workspace_dir = "/zeroclaw-data/workspace"' \
|
||||
'config_path = "/zeroclaw-data/.zeroclaw/config.toml"' \
|
||||
'api_key = ""' \
|
||||
'default_provider = "openrouter"' \
|
||||
'default_model = "anthropic/claude-sonnet-4-20250514"' \
|
||||
'default_temperature = 0.7' \
|
||||
'' \
|
||||
'[gateway]' \
|
||||
'port = 42617' \
|
||||
'host = "[::]"' \
|
||||
'allow_public_bind = true' \
|
||||
'' \
|
||||
'[autonomy]' \
|
||||
'level = "supervised"' \
|
||||
'auto_approve = ["file_read", "file_write", "file_edit", "memory_recall", "memory_store", "web_search_tool", "web_fetch", "calculator", "glob_search", "content_search", "image_info", "weather", "git_operations"]' \
|
||||
> /zeroclaw-data/.zeroclaw/config.toml && \
|
||||
cat > /zeroclaw-data/.zeroclaw/config.toml <<EOF && \
|
||||
chown -R 65534:65534 /zeroclaw-data
|
||||
workspace_dir = "/zeroclaw-data/workspace"
|
||||
config_path = "/zeroclaw-data/.zeroclaw/config.toml"
|
||||
api_key = ""
|
||||
default_provider = "openrouter"
|
||||
default_model = "anthropic/claude-sonnet-4-20250514"
|
||||
default_temperature = 0.7
|
||||
|
||||
[gateway]
|
||||
port = 42617
|
||||
host = "[::]"
|
||||
allow_public_bind = true
|
||||
EOF
|
||||
|
||||
# ── Stage 2: Development Runtime (Debian) ────────────────────
|
||||
FROM debian:trixie-slim@sha256:f6e2cfac5cf956ea044b4bd75e6397b4372ad88fe00908045e9a0d21712ae3ba AS dev
|
||||
@ -103,8 +90,6 @@ COPY dev/config.template.toml /zeroclaw-data/.zeroclaw/config.toml
|
||||
RUN chown 65534:65534 /zeroclaw-data/.zeroclaw/config.toml
|
||||
|
||||
# Environment setup
|
||||
# Ensure UTF-8 locale so CJK / multibyte input is handled correctly
|
||||
ENV LANG=C.UTF-8
|
||||
# Use consistent workspace path
|
||||
ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
|
||||
ENV HOME=/zeroclaw-data
|
||||
@ -119,10 +104,8 @@ ENV ZEROCLAW_GATEWAY_PORT=42617
|
||||
WORKDIR /zeroclaw-data
|
||||
USER 65534:65534
|
||||
EXPOSE 42617
|
||||
HEALTHCHECK --interval=60s --timeout=10s --retries=3 --start-period=10s \
|
||||
CMD ["zeroclaw", "status", "--format=exit-code"]
|
||||
ENTRYPOINT ["zeroclaw"]
|
||||
CMD ["daemon"]
|
||||
CMD ["gateway"]
|
||||
|
||||
# ── Stage 3: Production Runtime (Distroless) ─────────────────
|
||||
FROM gcr.io/distroless/cc-debian13:nonroot@sha256:84fcd3c223b144b0cb6edc5ecc75641819842a9679a3a58fd6294bec47532bf7 AS release
|
||||
@ -131,8 +114,6 @@ COPY --from=builder /app/zeroclaw /usr/local/bin/zeroclaw
|
||||
COPY --from=builder /zeroclaw-data /zeroclaw-data
|
||||
|
||||
# Environment setup
|
||||
# Ensure UTF-8 locale so CJK / multibyte input is handled correctly
|
||||
ENV LANG=C.UTF-8
|
||||
ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
|
||||
ENV HOME=/zeroclaw-data
|
||||
# Default provider and model are set in config.toml, not here,
|
||||
@ -145,7 +126,5 @@ ENV ZEROCLAW_GATEWAY_PORT=42617
|
||||
WORKDIR /zeroclaw-data
|
||||
USER 65534:65534
|
||||
EXPOSE 42617
|
||||
HEALTHCHECK --interval=60s --timeout=10s --retries=3 --start-period=10s \
|
||||
CMD ["zeroclaw", "status", "--format=exit-code"]
|
||||
ENTRYPOINT ["zeroclaw"]
|
||||
CMD ["daemon"]
|
||||
CMD ["gateway"]
|
||||
|
||||
@ -1,25 +0,0 @@
|
||||
# Dockerfile.ci — CI/release image using pre-built binaries.
|
||||
# Used by release workflows to skip the ~60 min Rust compilation.
|
||||
# The main Dockerfile is still used for local dev builds.
|
||||
|
||||
# ── Runtime (Distroless) ─────────────────────────────────────
|
||||
FROM gcr.io/distroless/cc-debian13:nonroot@sha256:84fcd3c223b144b0cb6edc5ecc75641819842a9679a3a58fd6294bec47532bf7
|
||||
|
||||
ARG TARGETARCH
|
||||
|
||||
# Copy the pre-built binary for this platform (amd64 or arm64)
|
||||
COPY bin/${TARGETARCH}/zeroclaw /usr/local/bin/zeroclaw
|
||||
|
||||
# Runtime directory structure and default config
|
||||
COPY --chown=65534:65534 zeroclaw-data/ /zeroclaw-data/
|
||||
|
||||
ENV LANG=C.UTF-8
|
||||
ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
|
||||
ENV HOME=/zeroclaw-data
|
||||
ENV ZEROCLAW_GATEWAY_PORT=42617
|
||||
|
||||
WORKDIR /zeroclaw-data
|
||||
USER 65534:65534
|
||||
EXPOSE 42617
|
||||
ENTRYPOINT ["zeroclaw"]
|
||||
CMD ["gateway"]
|
||||
@ -1,130 +0,0 @@
|
||||
# syntax=docker/dockerfile:1.7
|
||||
|
||||
# ── Stage 0: Frontend build ─────────────────────────────────────
|
||||
FROM node:22-alpine AS web-builder
|
||||
WORKDIR /web
|
||||
COPY web/package.json web/package-lock.json* ./
|
||||
RUN npm ci --ignore-scripts 2>/dev/null || npm install --ignore-scripts
|
||||
COPY web/ .
|
||||
RUN npm run build
|
||||
|
||||
# Dockerfile.debian — Shell-equipped variant of the ZeroClaw container.
|
||||
#
|
||||
# The default Dockerfile produces a distroless "release" image with no shell,
|
||||
# which is ideal for minimal attack surface but prevents the agent from using
|
||||
# shell-based tools (pwd, ls, git, curl, etc.).
|
||||
#
|
||||
# This variant uses debian:bookworm-slim as the runtime base and ships
|
||||
# essential CLI tools so the agent can operate as a full coding assistant.
|
||||
#
|
||||
# Build:
|
||||
# docker build -f Dockerfile.debian -t zeroclaw:debian .
|
||||
#
|
||||
# Or with docker compose:
|
||||
# docker compose -f docker-compose.yml -f docker-compose.debian.yml up
|
||||
|
||||
# ── Stage 1: Build (match runtime glibc baseline) ───────────
|
||||
FROM rust:1.94-bookworm AS builder
|
||||
|
||||
WORKDIR /app
|
||||
ARG ZEROCLAW_CARGO_FEATURES="memory-postgres,channel-lark"
|
||||
|
||||
# Install build dependencies
|
||||
RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
|
||||
--mount=type=cache,target=/var/lib/apt,sharing=locked \
|
||||
apt-get update && apt-get install -y \
|
||||
pkg-config \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# 1. Copy manifests to cache dependencies
|
||||
COPY Cargo.toml Cargo.lock ./
|
||||
# Include every workspace member: Cargo.lock is generated for the full workspace.
|
||||
# Previously we used sed to drop `crates/robot-kit`, which made the manifest disagree
|
||||
# with the lockfile and caused `cargo --locked` to fail (Cargo refused to rewrite the lock).
|
||||
COPY crates/robot-kit/ crates/robot-kit/
|
||||
# Create dummy targets declared in Cargo.toml so manifest parsing succeeds.
|
||||
RUN mkdir -p src benches \
|
||||
&& echo "fn main() {}" > src/main.rs \
|
||||
&& echo "" > src/lib.rs \
|
||||
&& echo "fn main() {}" > benches/agent_benchmarks.rs
|
||||
RUN --mount=type=cache,id=zeroclaw-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-cargo-git,target=/usr/local/cargo/git,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-target,target=/app/target,sharing=locked \
|
||||
if [ -n "$ZEROCLAW_CARGO_FEATURES" ]; then \
|
||||
cargo build --release --locked --features "$ZEROCLAW_CARGO_FEATURES"; \
|
||||
else \
|
||||
cargo build --release --locked; \
|
||||
fi
|
||||
RUN rm -rf src benches
|
||||
|
||||
# 2. Copy only build-relevant source paths (avoid cache-busting on docs/tests/scripts)
|
||||
COPY src/ src/
|
||||
COPY benches/ benches/
|
||||
COPY --from=web-builder /web/dist web/dist
|
||||
RUN touch src/main.rs
|
||||
RUN --mount=type=cache,id=zeroclaw-cargo-registry,target=/usr/local/cargo/registry,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-cargo-git,target=/usr/local/cargo/git,sharing=locked \
|
||||
--mount=type=cache,id=zeroclaw-target,target=/app/target,sharing=locked \
|
||||
if [ -n "$ZEROCLAW_CARGO_FEATURES" ]; then \
|
||||
cargo build --release --locked --features "$ZEROCLAW_CARGO_FEATURES"; \
|
||||
else \
|
||||
cargo build --release --locked; \
|
||||
fi && \
|
||||
cp target/release/zeroclaw /app/zeroclaw && \
|
||||
strip /app/zeroclaw
|
||||
RUN size=$(stat -c%s /app/zeroclaw) && \
|
||||
if [ "$size" -lt 1000000 ]; then echo "ERROR: binary too small (${size} bytes), likely dummy build artifact" && exit 1; fi
|
||||
|
||||
# Prepare runtime directory structure and default config inline (no extra stage)
|
||||
RUN mkdir -p /zeroclaw-data/.zeroclaw /zeroclaw-data/workspace && \
|
||||
printf '%s\n' \
|
||||
'workspace_dir = "/zeroclaw-data/workspace"' \
|
||||
'config_path = "/zeroclaw-data/.zeroclaw/config.toml"' \
|
||||
'api_key = ""' \
|
||||
'default_provider = "openrouter"' \
|
||||
'default_model = "anthropic/claude-sonnet-4-20250514"' \
|
||||
'default_temperature = 0.7' \
|
||||
'' \
|
||||
'[gateway]' \
|
||||
'port = 42617' \
|
||||
'host = "[::]"' \
|
||||
'allow_public_bind = true' \
|
||||
'' \
|
||||
'[autonomy]' \
|
||||
'level = "supervised"' \
|
||||
'auto_approve = ["file_read", "file_write", "file_edit", "memory_recall", "memory_store", "web_search_tool", "web_fetch", "calculator", "glob_search", "content_search", "image_info", "weather", "git_operations"]' \
|
||||
> /zeroclaw-data/.zeroclaw/config.toml && \
|
||||
chown -R 65534:65534 /zeroclaw-data
|
||||
|
||||
# ── Stage 2: Runtime (Debian with shell) ─────────────────────
|
||||
FROM debian:bookworm-slim AS runtime
|
||||
|
||||
# Install essential tools for agent shell operations
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
bash \
|
||||
ca-certificates \
|
||||
curl \
|
||||
git \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
COPY --from=builder /app/zeroclaw /usr/local/bin/zeroclaw
|
||||
COPY --from=builder /zeroclaw-data /zeroclaw-data
|
||||
|
||||
# Environment setup
|
||||
# Ensure UTF-8 locale so CJK / multibyte input is handled correctly
|
||||
ENV LANG=C.UTF-8
|
||||
ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
|
||||
ENV HOME=/zeroclaw-data
|
||||
# Default provider and model are set in config.toml, not here,
|
||||
# so config file edits are not silently overridden
|
||||
ENV ZEROCLAW_GATEWAY_PORT=42617
|
||||
|
||||
# API_KEY must be provided at runtime!
|
||||
|
||||
WORKDIR /zeroclaw-data
|
||||
USER 65534:65534
|
||||
EXPOSE 42617
|
||||
HEALTHCHECK --interval=60s --timeout=10s --retries=3 --start-period=10s \
|
||||
CMD ["zeroclaw", "status", "--format=exit-code"]
|
||||
ENTRYPOINT ["zeroclaw"]
|
||||
CMD ["daemon"]
|
||||
@ -1,34 +0,0 @@
|
||||
# Dockerfile.debian.ci — CI/release Debian image using pre-built binaries.
|
||||
# Mirrors Dockerfile.ci but uses debian:bookworm-slim with shell tools
|
||||
# so the agent can use shell-based tools (pwd, ls, git, curl, etc.).
|
||||
# Used by release workflows to skip ~60 min QEMU cross-compilation.
|
||||
|
||||
# ── Runtime (Debian with shell) ────────────────────────────────
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
ARG TARGETARCH
|
||||
|
||||
# Install essential tools for agent shell operations
|
||||
RUN apt-get update && apt-get install -y --no-install-recommends \
|
||||
bash \
|
||||
ca-certificates \
|
||||
curl \
|
||||
git \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
# Copy the pre-built binary for this platform (amd64 or arm64)
|
||||
COPY bin/${TARGETARCH}/zeroclaw /usr/local/bin/zeroclaw
|
||||
|
||||
# Runtime directory structure and default config
|
||||
COPY --chown=65534:65534 zeroclaw-data/ /zeroclaw-data/
|
||||
|
||||
ENV LANG=C.UTF-8
|
||||
ENV ZEROCLAW_WORKSPACE=/zeroclaw-data/workspace
|
||||
ENV HOME=/zeroclaw-data
|
||||
ENV ZEROCLAW_GATEWAY_PORT=42617
|
||||
|
||||
WORKDIR /zeroclaw-data
|
||||
USER 65534:65534
|
||||
EXPOSE 42617
|
||||
ENTRYPOINT ["zeroclaw"]
|
||||
CMD ["gateway"]
|
||||
78
Justfile
78
Justfile
@ -1,78 +0,0 @@
|
||||
# Justfile - Convenient command runner for ZeroClaw development
|
||||
# https://github.com/casey/just
|
||||
|
||||
# Default recipe to display help
|
||||
_default:
|
||||
@just --list
|
||||
|
||||
# Format all code
|
||||
fmt:
|
||||
cargo fmt --all
|
||||
|
||||
# Check formatting without making changes
|
||||
fmt-check:
|
||||
cargo fmt --all -- --check
|
||||
|
||||
# Run clippy lints
|
||||
lint:
|
||||
cargo clippy --all-targets -- -D warnings
|
||||
|
||||
# Run all tests
|
||||
test:
|
||||
cargo test --locked
|
||||
|
||||
# Run only unit tests (faster)
|
||||
test-lib:
|
||||
cargo test --lib
|
||||
|
||||
# Run the full CI quality gate locally
|
||||
ci: fmt-check lint test
|
||||
@echo "✅ All CI checks passed!"
|
||||
|
||||
# Build in release mode
|
||||
build:
|
||||
cargo build --release --locked
|
||||
|
||||
# Build in debug mode
|
||||
build-debug:
|
||||
cargo build
|
||||
|
||||
# Clean build artifacts
|
||||
clean:
|
||||
cargo clean
|
||||
|
||||
# Run zeroclaw with example config (for development)
|
||||
dev *ARGS:
|
||||
cargo run -- {{ARGS}}
|
||||
|
||||
# Check code without building
|
||||
check:
|
||||
cargo check --all-targets
|
||||
|
||||
# Run cargo doc and open in browser
|
||||
doc:
|
||||
cargo doc --no-deps --open
|
||||
|
||||
# Update dependencies
|
||||
update:
|
||||
cargo update
|
||||
|
||||
# Run cargo audit to check for security vulnerabilities
|
||||
audit:
|
||||
cargo audit
|
||||
|
||||
# Run cargo deny checks
|
||||
deny:
|
||||
cargo deny check
|
||||
|
||||
# Format TOML files (requires taplo)
|
||||
fmt-toml:
|
||||
taplo format
|
||||
|
||||
# Check TOML formatting (requires taplo)
|
||||
fmt-toml-check:
|
||||
taplo format --check
|
||||
|
||||
# Run all formatting tools
|
||||
fmt-all: fmt fmt-toml
|
||||
@echo "✅ All formatting complete!"
|
||||
17
NOTICE
17
NOTICE
@ -17,7 +17,7 @@ License
|
||||
|
||||
This software is available under a dual-license model:
|
||||
|
||||
1. MIT License — see LICENSE-MIT
|
||||
1. MIT License — see LICENSE
|
||||
2. Apache License 2.0 — see LICENSE-APACHE
|
||||
|
||||
You may use either license. Contributors grant rights under both.
|
||||
@ -41,18 +41,3 @@ This project uses third-party libraries and components,
|
||||
each licensed under their respective terms.
|
||||
|
||||
See Cargo.lock for a complete dependency list.
|
||||
|
||||
Verifiable Intent Specification
|
||||
================================
|
||||
|
||||
The src/verifiable_intent/ module is a Rust-native reimplementation based on
|
||||
the Verifiable Intent open specification and reference implementation:
|
||||
|
||||
Project: Verifiable Intent (VI)
|
||||
Author: agent-intent
|
||||
Source: https://github.com/agent-intent/verifiable-intent
|
||||
License: Apache License, Version 2.0
|
||||
|
||||
This implementation follows the VI specification design (SD-JWT layered
|
||||
credentials, constraint model, three-layer chain). No source code was copied
|
||||
from the reference implementation.
|
||||
|
||||
755
README.ar.md
755
README.ar.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — مساعد الذكاء الاصطناعي الشخصي</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>صفر حمل زائد. صفر تنازلات. 100% Rust. 100% مستقل.</strong><br>
|
||||
⚡️ <strong>يعمل على أجهزة بقيمة 10 دولارات بأقل من 5 ميجابايت رام: هذا أقل بنسبة 99% من الذاكرة مقارنة بـ OpenClaw و98% أرخص من Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
تم بناؤه بواسطة طلاب وأعضاء من مجتمعات Harvard وMIT وSundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>اللغات:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw هو مساعد ذكاء اصطناعي شخصي تشغّله على أجهزتك الخاصة. يجيبك على القنوات التي تستخدمها بالفعل (WhatsApp، Telegram، Slack، Discord، Signal، iMessage، Matrix، IRC، Email، Bluesky، Nostr، Mattermost، Nextcloud Talk، DingTalk، Lark، QQ، Reddit، LinkedIn، Twitter، MQTT، WeChat Work، والمزيد). يحتوي على لوحة تحكم ويب للتحكم في الوقت الفعلي ويمكنه الاتصال بالأجهزة الطرفية (ESP32، STM32، Arduino، Raspberry Pi). البوابة هي مجرد مستوى التحكم — المنتج هو المساعد.
|
||||
|
||||
إذا كنت تريد مساعدًا شخصيًا لمستخدم واحد يشعر بأنه محلي وسريع ويعمل دائمًا، فهذا هو.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">الموقع الإلكتروني</a> ·
|
||||
<a href="docs/README.md">التوثيق</a> ·
|
||||
<a href="docs/architecture.md">البنية المعمارية</a> ·
|
||||
<a href="#البداية-السريعة">البدء</a> ·
|
||||
<a href="#الانتقال-من-openclaw">الانتقال من OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">استكشاف الأخطاء</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **الإعداد المفضل:** شغّل `zeroclaw onboard` في طرفيتك. ZeroClaw Onboard يرشدك خطوة بخطوة لإعداد البوابة ومساحة العمل والقنوات والمزود. إنه مسار الإعداد الموصى به ويعمل على macOS وLinux وWindows (عبر WSL2). تثبيت جديد؟ ابدأ هنا: [البدء](#البداية-السريعة)
|
||||
|
||||
### مصادقة الاشتراك (OAuth)
|
||||
|
||||
- **OpenAI Codex** (اشتراك ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (مفتاح API أو رمز مصادقة)
|
||||
|
||||
ملاحظة حول النماذج: بينما يتم دعم العديد من المزودين/النماذج، للحصول على أفضل تجربة استخدم أقوى نموذج من أحدث جيل متاح لديك. انظر [الإعداد](#البداية-السريعة).
|
||||
|
||||
إعدادات النماذج + CLI: [مرجع المزودين](docs/reference/api/providers-reference.md)
|
||||
تدوير ملف المصادقة (OAuth مقابل مفاتيح API) + الانتقال التلقائي: [الانتقال التلقائي للنماذج](docs/reference/api/providers-reference.md)
|
||||
|
||||
## التثبيت (موصى به)
|
||||
|
||||
بيئة التشغيل: سلسلة أدوات Rust المستقرة. ملف ثنائي واحد، بدون تبعيات وقت التشغيل.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### التثبيت بنقرة واحدة
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` يعمل تلقائيًا بعد التثبيت لتكوين مساحة العمل والمزود.
|
||||
|
||||
## البداية السريعة (TL;DR)
|
||||
|
||||
دليل المبتدئين الكامل (المصادقة، الاقتران، القنوات): [البدء](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Install + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start the gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Talk to the assistant
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonomous runtime (gateway + channels + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
zeroclaw status
|
||||
|
||||
# Run diagnostics
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
هل تقوم بالترقية؟ شغّل `zeroclaw doctor` بعد التحديث.
|
||||
|
||||
### من المصدر (التطوير)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **البديل للتطوير (بدون تثبيت عام):** ابدأ الأوامر بـ `cargo run --release --` (مثال: `cargo run --release -- status`).
|
||||
|
||||
## الانتقال من OpenClaw
|
||||
|
||||
يمكن لـ ZeroClaw استيراد مساحة عمل OpenClaw والذاكرة والتكوين الخاص بك:
|
||||
|
||||
```bash
|
||||
# Preview what will be migrated (safe, read-only)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Run the migration
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
يقوم هذا بترحيل إدخالات الذاكرة وملفات مساحة العمل والتكوين من `~/.openclaw/` إلى `~/.zeroclaw/`. يتم تحويل التكوين من JSON إلى TOML تلقائيًا.
|
||||
|
||||
## إعدادات الأمان الافتراضية (الوصول عبر الرسائل المباشرة)
|
||||
|
||||
يتصل ZeroClaw بأسطح المراسلة الحقيقية. تعامل مع الرسائل المباشرة الواردة كمدخلات غير موثوقة.
|
||||
|
||||
دليل الأمان الكامل: [SECURITY.md](SECURITY.md)
|
||||
|
||||
السلوك الافتراضي على جميع القنوات:
|
||||
|
||||
- **اقتران الرسائل المباشرة** (افتراضي): يتلقى المرسلون غير المعروفين رمز اقتران قصير ولا يعالج البوت رسالتهم.
|
||||
- الموافقة باستخدام: `zeroclaw pairing approve <channel> <code>` (ثم يُضاف المرسل إلى قائمة السماح المحلية).
|
||||
- تتطلب الرسائل المباشرة العامة الواردة اشتراكًا صريحًا في `config.toml`.
|
||||
- شغّل `zeroclaw doctor` لكشف سياسات الرسائل المباشرة الخطرة أو المُعدة خطأ.
|
||||
|
||||
**مستويات الاستقلالية:**
|
||||
|
||||
| المستوى | السلوك |
|
||||
|---------|--------|
|
||||
| `ReadOnly` | يمكن للوكيل المراقبة ولكن لا يمكنه التصرف |
|
||||
| `Supervised` (افتراضي) | يتصرف الوكيل مع الموافقة على العمليات متوسطة/عالية المخاطر |
|
||||
| `Full` | يتصرف الوكيل بشكل مستقل ضمن حدود السياسة |
|
||||
|
||||
**طبقات العزل:** عزل مساحة العمل، حظر اجتياز المسار، قوائم السماح للأوامر، المسارات المحظورة (`/etc`، `/root`، `~/.ssh`)، تحديد المعدل (أقصى إجراءات/ساعة، حدود التكلفة/يوم).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 الإعلانات
|
||||
|
||||
استخدم هذه اللوحة للإشعارات المهمة (التغييرات الجذرية، إرشادات الأمان، نوافذ الصيانة، وعوائق الإصدار).
|
||||
|
||||
| التاريخ (UTC) | المستوى | الإشعار | الإجراء |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _حرج_ | نحن **غير مرتبطين** بـ `openagen/zeroclaw` أو `zeroclaw.org` أو `zeroclaw.net`. نطاقا `zeroclaw.org` و`zeroclaw.net` يشيران حاليًا إلى نسخة `openagen/zeroclaw` المتفرعة، وهذا النطاق/المستودع ينتحل صفة موقعنا/مشروعنا الرسمي. | لا تثق بالمعلومات أو الملفات الثنائية أو جمع التبرعات أو الإعلانات من تلك المصادر. استخدم فقط [هذا المستودع](https://github.com/zeroclaw-labs/zeroclaw) وحساباتنا الاجتماعية الموثقة. |
|
||||
| 2026-02-21 | _مهم_ | موقعنا الرسمي متاح الآن: [zeroclawlabs.ai](https://zeroclawlabs.ai). شكرًا لصبركم أثناء تحضيرنا للإطلاق. ما زلنا نرى محاولات انتحال، لذا **لا** تنضم إلى أي نشاط استثمار أو جمع تبرعات يدعي اسم ZeroClaw ما لم يتم نشره عبر قنواتنا الرسمية. | استخدم [هذا المستودع](https://github.com/zeroclaw-labs/zeroclaw) كمصدر الحقيقة الوحيد. تابع [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21) و[Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) و[Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) للتحديثات الرسمية. |
|
||||
| 2026-02-19 | _مهم_ | قامت Anthropic بتحديث شروط المصادقة واستخدام بيانات الاعتماد في 2026-02-19. رموز Claude Code OAuth (Free، Pro، Max) مخصصة حصريًا لـ Claude Code وClaude.ai؛ استخدام رموز OAuth من Claude Free/Pro/Max في أي منتج أو أداة أو خدمة أخرى (بما في ذلك Agent SDK) غير مسموح به وقد ينتهك شروط خدمة المستهلك. | يرجى تجنب تكاملات Claude Code OAuth مؤقتًا لمنع الخسارة المحتملة. البند الأصلي: [المصادقة واستخدام بيانات الاعتماد](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## أبرز الميزات
|
||||
|
||||
- **بيئة تشغيل خفيفة افتراضيًا** — تعمل مسارات CLI والحالة الشائعة في غلاف ذاكرة بضعة ميجابايت على إصدارات الإنتاج.
|
||||
- **نشر فعال التكلفة** — مصمم للوحات بقيمة 10 دولارات والخوادم السحابية الصغيرة، بدون تبعيات وقت تشغيل ثقيلة.
|
||||
- **بدء تشغيل بارد سريع** — بيئة تشغيل Rust بملف ثنائي واحد تجعل بدء تشغيل الأوامر والخدمة شبه فوري.
|
||||
- **بنية قابلة للنقل** — ملف ثنائي واحد عبر ARM وx86 وRISC-V مع مزودين/قنوات/أدوات قابلة للتبديل.
|
||||
- **بوابة محلية أولاً** — مستوى تحكم واحد للجلسات والقنوات والأدوات والمهام المجدولة وإجراءات التشغيل القياسية والأحداث.
|
||||
- **صندوق وارد متعدد القنوات** — WhatsApp، Telegram، Slack، Discord، Signal، iMessage، Matrix، IRC، Email، Bluesky، Nostr، Mattermost، Nextcloud Talk، DingTalk، Lark، QQ، Reddit، LinkedIn، Twitter، MQTT، WeChat Work، WebSocket، والمزيد.
|
||||
- **تنسيق متعدد الوكلاء (Hands)** — أسراب وكلاء مستقلة تعمل وفق جدول زمني وتصبح أذكى مع مرور الوقت.
|
||||
- **إجراءات التشغيل القياسية (SOPs)** — أتمتة سير العمل المدفوعة بالأحداث مع MQTT والخطافات والمهام المجدولة ومشغلات الأجهزة الطرفية.
|
||||
- **لوحة تحكم ويب** — واجهة مستخدم React 19 + Vite مع دردشة في الوقت الفعلي ومتصفح ذاكرة ومحرر تكوين ومدير مهام مجدولة وفاحص أدوات.
|
||||
- **أجهزة طرفية** — ESP32، STM32 Nucleo، Arduino، Raspberry Pi GPIO عبر سمة `Peripheral`.
|
||||
- **أدوات من الدرجة الأولى** — shell، قراءة/كتابة/تحرير الملفات، git، جلب/بحث الويب، MCP، Jira، Notion، Google Workspace، و70+ أخرى.
|
||||
- **خطافات دورة الحياة** — اعتراض وتعديل استدعاءات LLM وتنفيذ الأدوات والرسائل في كل مرحلة.
|
||||
- **منصة المهارات** — مهارات مدمجة ومجتمعية ومساحة عمل مع تدقيق أمني.
|
||||
- **دعم الأنفاق** — Cloudflare، Tailscale، ngrok، OpenVPN، وأنفاق مخصصة للوصول عن بُعد.
|
||||
|
||||
### لماذا تختار الفرق ZeroClaw
|
||||
|
||||
- **خفيف افتراضيًا:** ملف Rust ثنائي صغير، بدء تشغيل سريع، بصمة ذاكرة منخفضة.
|
||||
- **آمن بالتصميم:** اقتران، عزل صارم، قوائم سماح صريحة، نطاق مساحة العمل.
|
||||
- **قابل للتبديل بالكامل:** الأنظمة الأساسية هي سمات (مزودون، قنوات، أدوات، ذاكرة، أنفاق).
|
||||
- **بدون تقييد:** دعم مزود متوافق مع OpenAI + نقاط نهاية مخصصة قابلة للتوصيل.
|
||||
|
||||
## لقطة المقارنة المرجعية (ZeroClaw مقابل OpenClaw، قابلة للتكرار)
|
||||
|
||||
مقارنة محلية سريعة (macOS arm64، فبراير 2026) مُعايرة لأجهزة الحافة بتردد 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **اللغة** | TypeScript | Python | Go | **Rust** |
|
||||
| **الرام** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **البدء (نواة 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **حجم الملف الثنائي** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **التكلفة** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **أي جهاز 10$** |
|
||||
|
||||
> ملاحظات: نتائج ZeroClaw تم قياسها على إصدارات الإنتاج باستخدام `/usr/bin/time -l`. يتطلب OpenClaw بيئة تشغيل Node.js (عادةً ~390 ميجابايت حمل ذاكرة إضافي)، بينما يتطلب NanoBot بيئة تشغيل Python. PicoClaw وZeroClaw ملفات ثنائية ثابتة. أرقام الرام أعلاه هي ذاكرة وقت التشغيل؛ متطلبات التجميع في وقت البناء أعلى.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### القياس المحلي القابل للتكرار
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## كل ما بنيناه حتى الآن
|
||||
|
||||
### المنصة الأساسية
|
||||
|
||||
- بوابة HTTP/WS/SSE كمستوى تحكم مع الجلسات والحضور والتكوين والمهام المجدولة والخطافات ولوحة تحكم الويب والاقتران.
|
||||
- واجهة CLI: `gateway`، `agent`، `onboard`، `doctor`، `status`، `service`، `migrate`، `auth`، `cron`، `channel`، `skills`.
|
||||
- حلقة تنسيق الوكيل مع إرسال الأدوات وبناء الموجهات وتصنيف الرسائل وتحميل الذاكرة.
|
||||
- نموذج الجلسات مع تطبيق سياسة الأمان ومستويات الاستقلالية وبوابة الموافقة.
|
||||
- غلاف مزود مرن مع الانتقال التلقائي وإعادة المحاولة وتوجيه النماذج عبر 20+ واجهة LLM خلفية.
|
||||
|
||||
### القنوات
|
||||
|
||||
القنوات: WhatsApp (أصلي)، Telegram، Slack، Discord، Signal، iMessage، Matrix، IRC، Email، Bluesky، DingTalk، Lark، Mattermost، Nextcloud Talk، Nostr، QQ، Reddit، LinkedIn، Twitter، MQTT، WeChat Work، WATI، Mochat، Linq، Notion، WebSocket، ClawdTalk.
|
||||
|
||||
مُحددة بالميزات: Matrix (`channel-matrix`)، Lark (`channel-lark`)، Nostr (`channel-nostr`).
|
||||
|
||||
### لوحة تحكم الويب
|
||||
|
||||
لوحة تحكم ويب React 19 + Vite 6 + Tailwind CSS 4 تُقدم مباشرة من البوابة:
|
||||
|
||||
- **لوحة التحكم** — نظرة عامة على النظام، حالة الصحة، وقت التشغيل، تتبع التكاليف
|
||||
- **دردشة الوكيل** — دردشة تفاعلية مع الوكيل
|
||||
- **الذاكرة** — تصفح وإدارة إدخالات الذاكرة
|
||||
- **التكوين** — عرض وتحرير التكوين
|
||||
- **المهام المجدولة** — إدارة المهام المجدولة
|
||||
- **الأدوات** — تصفح الأدوات المتاحة
|
||||
- **السجلات** — عرض سجلات نشاط الوكيل
|
||||
- **التكلفة** — استخدام الرموز وتتبع التكاليف
|
||||
- **التشخيص** — تشخيصات صحة النظام
|
||||
- **التكاملات** — حالة التكامل والإعداد
|
||||
- **الاقتران** — إدارة اقتران الأجهزة
|
||||
|
||||
### أهداف البرامج الثابتة
|
||||
|
||||
| الهدف | المنصة | الغرض |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | وكيل طرفي لاسلكي |
|
||||
| ESP32-UI | ESP32 + Display | وكيل بواجهة مرئية |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | طرفي صناعي |
|
||||
| Arduino | Arduino | جسر مستشعر/مشغل أساسي |
|
||||
| Uno Q Bridge | Arduino Uno | جسر تسلسلي إلى الوكيل |
|
||||
|
||||
### الأدوات + الأتمتة
|
||||
|
||||
- **الأساسية:** shell، قراءة/كتابة/تحرير الملفات، عمليات git، بحث glob، بحث المحتوى
|
||||
- **الويب:** التحكم بالمتصفح، جلب الويب، بحث الويب، لقطة شاشة، معلومات الصور، قراءة PDF
|
||||
- **التكاملات:** Jira، Notion، Google Workspace، Microsoft 365، LinkedIn، Composio، Pushover
|
||||
- **MCP:** غلاف أداة Model Context Protocol + مجموعات أدوات مؤجلة
|
||||
- **الجدولة:** إضافة/إزالة/تحديث/تشغيل cron، أداة الجدولة
|
||||
- **الذاكرة:** استرجاع، تخزين، نسيان، معرفة، استخبارات المشروع
|
||||
- **متقدم:** تفويض (وكيل إلى وكيل)، سرب، تبديل/توجيه النموذج، عمليات الأمان، العمليات السحابية
|
||||
- **الأجهزة:** معلومات اللوحة، خريطة الذاكرة، قراءة الذاكرة (محددة بالميزات)
|
||||
|
||||
### وقت التشغيل + الأمان
|
||||
|
||||
- **مستويات الاستقلالية:** ReadOnly، Supervised (افتراضي)، Full.
|
||||
- **العزل:** عزل مساحة العمل، حظر اجتياز المسار، قوائم السماح للأوامر، المسارات المحظورة، Landlock (Linux)، Bubblewrap.
|
||||
- **تحديد المعدل:** أقصى إجراءات في الساعة، أقصى تكلفة في اليوم (قابل للتكوين).
|
||||
- **بوابة الموافقة:** موافقة تفاعلية للعمليات متوسطة/عالية المخاطر.
|
||||
- **إيقاف طارئ:** قدرة الإغلاق الطارئ.
|
||||
- **129+ اختبار أمني** في CI الآلي.
|
||||
|
||||
### العمليات + التغليف
|
||||
|
||||
- لوحة تحكم ويب تُقدم مباشرة من البوابة.
|
||||
- دعم الأنفاق: Cloudflare، Tailscale، ngrok، OpenVPN، أمر مخصص.
|
||||
- محول وقت تشغيل Docker للتنفيذ في حاويات.
|
||||
- CI/CD: تجريبي (تلقائي عند الدفع) → مستقر (إرسال يدوي) → Docker، crates.io، Scoop، AUR، Homebrew، تغريدة.
|
||||
- ملفات ثنائية مُعدة مسبقًا لـ Linux (x86_64، aarch64، armv7)، macOS (x86_64، aarch64)، Windows (x86_64).
|
||||
|
||||
|
||||
## التكوين
|
||||
|
||||
الحد الأدنى `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
مرجع التكوين الكامل: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### تكوين القنوات
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### تكوين الأنفاق
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
التفاصيل: [مرجع القنوات](docs/reference/api/channels-reference.md) · [مرجع التكوين](docs/reference/api/config-reference.md)
|
||||
|
||||
### دعم وقت التشغيل (الحالي)
|
||||
|
||||
- **`native`** (افتراضي) — تنفيذ مباشر للعمليات، أسرع مسار، مثالي للبيئات الموثوقة.
|
||||
- **`docker`** — عزل كامل بالحاويات، سياسات أمان مفروضة، يتطلب Docker.
|
||||
|
||||
اضبط `runtime.kind = "docker"` للعزل الصارم أو عزل الشبكة.
|
||||
|
||||
## مصادقة الاشتراك (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
يدعم ZeroClaw ملفات تعريف مصادقة أصلية للاشتراك (متعددة الحسابات، مشفرة عند الراحة).
|
||||
|
||||
- ملف التخزين: `~/.zeroclaw/auth-profiles.json`
|
||||
- مفتاح التشفير: `~/.zeroclaw/.secret_key`
|
||||
- تنسيق معرف الملف: `<provider>:<profile_name>` (مثال: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## مساحة عمل الوكيل + المهارات
|
||||
|
||||
جذر مساحة العمل: `~/.zeroclaw/workspace/` (قابل للتكوين عبر التكوين).
|
||||
|
||||
ملفات الموجه المحقونة:
|
||||
- `IDENTITY.md` — شخصية الوكيل ودوره
|
||||
- `USER.md` — سياق المستخدم وتفضيلاته
|
||||
- `MEMORY.md` — حقائق ودروس طويلة المدى
|
||||
- `AGENTS.md` — اتفاقيات الجلسة وقواعد التهيئة
|
||||
- `SOUL.md` — الهوية الأساسية ومبادئ التشغيل
|
||||
|
||||
المهارات: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` أو `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## أوامر CLI
|
||||
|
||||
```bash
|
||||
# Workspace management
|
||||
zeroclaw onboard # Guided setup wizard
|
||||
zeroclaw status # Show daemon/agent status
|
||||
zeroclaw doctor # Run system diagnostics
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonomous runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactive chat mode
|
||||
zeroclaw agent -m "message" # Single message mode
|
||||
|
||||
# Service management
|
||||
zeroclaw service install # Install as OS service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Channels
|
||||
zeroclaw channel list # List configured channels
|
||||
zeroclaw channel doctor # Check channel health
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + scheduling
|
||||
zeroclaw cron list # List scheduled jobs
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memory
|
||||
zeroclaw memory list # List memory entries
|
||||
zeroclaw memory get <key> # Retrieve a memory
|
||||
zeroclaw memory stats # Memory statistics
|
||||
|
||||
# Auth profiles
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware peripherals
|
||||
zeroclaw hardware discover # Scan for connected devices
|
||||
zeroclaw peripheral list # List connected peripherals
|
||||
zeroclaw peripheral flash # Flash firmware to device
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell completions
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
مرجع الأوامر الكامل: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## المتطلبات الأساسية
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### مطلوب
|
||||
|
||||
1. **Visual Studio Build Tools** (يوفر رابط MSVC وWindows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
أثناء التثبيت (أو عبر Visual Studio Installer)، حدد حزمة عمل **"Desktop development with C++"**.
|
||||
|
||||
2. **سلسلة أدوات Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
بعد التثبيت، افتح طرفية جديدة وشغّل `rustup default stable` لضمان أن سلسلة الأدوات المستقرة نشطة.
|
||||
|
||||
3. **تحقق** من أن كليهما يعملان:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### اختياري
|
||||
|
||||
- **Docker Desktop** — مطلوب فقط إذا كنت تستخدم [وقت تشغيل Docker المعزول](#دعم-وقت-التشغيل-الحالي) (`runtime.kind = "docker"`). ثبّت عبر `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### مطلوب
|
||||
|
||||
1. **أساسيات البناء:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** ثبّت Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **سلسلة أدوات Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
انظر [rustup.rs](https://rustup.rs) للتفاصيل.
|
||||
|
||||
3. **تحقق** من أن كليهما يعملان:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### مثبّت بسطر واحد
|
||||
|
||||
أو تخطى الخطوات أعلاه وثبّت كل شيء (تبعيات النظام، Rust، ZeroClaw) بأمر واحد:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### متطلبات موارد التجميع
|
||||
|
||||
البناء من المصدر يحتاج موارد أكثر من تشغيل الملف الثنائي الناتج:
|
||||
|
||||
| المورد | الحد الأدنى | الموصى به |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **الرام + swap** | 2 GB | 4 GB+ |
|
||||
| **مساحة القرص الحرة** | 6 GB | 10 GB+ |
|
||||
|
||||
إذا كان جهازك أقل من الحد الأدنى، استخدم الملفات الثنائية المُعدة مسبقًا:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
لطلب تثبيت ثنائي فقط بدون بديل مصدري:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### اختياري
|
||||
|
||||
- **Docker** — مطلوب فقط إذا كنت تستخدم [وقت تشغيل Docker المعزول](#دعم-وقت-التشغيل-الحالي) (`runtime.kind = "docker"`). ثبّت عبر مدير الحزم أو [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **ملاحظة:** الأمر الافتراضي `cargo build --release` يستخدم `codegen-units=1` لتقليل ضغط التجميع الذروة. للبناء الأسرع على أجهزة قوية، استخدم `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### ملفات ثنائية مُعدة مسبقًا
|
||||
|
||||
يتم نشر أصول الإصدار لـ:
|
||||
|
||||
- Linux: `x86_64`، `aarch64`، `armv7`
|
||||
- macOS: `x86_64`، `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
حمّل أحدث الأصول من:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## التوثيق
|
||||
|
||||
استخدم هذه عندما تتجاوز مرحلة الإعداد وتريد المرجع الأعمق.
|
||||
|
||||
- ابدأ بـ [فهرس التوثيق](docs/README.md) للتنقل و"ما هو أين."
|
||||
- اقرأ [نظرة عامة على البنية المعمارية](docs/architecture.md) لنموذج النظام الكامل.
|
||||
- استخدم [مرجع التكوين](docs/reference/api/config-reference.md) عندما تحتاج كل مفتاح ومثال.
|
||||
- شغّل البوابة حسب الكتاب مع [دليل العمليات](docs/ops/operations-runbook.md).
|
||||
- اتبع [ZeroClaw Onboard](#البداية-السريعة) للإعداد الموجه.
|
||||
- صحح الأعطال الشائعة مع [دليل استكشاف الأخطاء](docs/ops/troubleshooting.md).
|
||||
- راجع [إرشادات الأمان](docs/security/README.md) قبل كشف أي شيء.
|
||||
|
||||
### مراجع التوثيق
|
||||
|
||||
- مركز التوثيق: [docs/README.md](docs/README.md)
|
||||
- جدول محتويات التوثيق الموحد: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- مرجع الأوامر: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- مرجع التكوين: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- مرجع المزودين: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- مرجع القنوات: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- دليل العمليات: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- استكشاف الأخطاء: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### وثائق التعاون
|
||||
|
||||
- دليل المساهمة: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- سياسة سير عمل PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- دليل سير عمل CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- دليل المراجع: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- سياسة الإفصاح الأمني: [SECURITY.md](SECURITY.md)
|
||||
- قالب التوثيق: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### النشر + العمليات
|
||||
|
||||
- دليل نشر الشبكة: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- دليل وكيل البروكسي: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- أدلة الأجهزة: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
تم بناء ZeroClaw للسلطعون الناعم 🦀، مساعد ذكاء اصطناعي سريع وفعال. بناه Argenis De La Rosa والمجتمع.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ادعم ZeroClaw
|
||||
|
||||
إذا ساعدك ZeroClaw في عملك وتريد دعم التطوير المستمر، يمكنك التبرع هنا:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 شكر خاص
|
||||
|
||||
شكر من القلب للمجتمعات والمؤسسات التي تلهم وتغذي هذا العمل مفتوح المصدر:
|
||||
|
||||
- **Harvard University** — لتعزيز الفضول الفكري ودفع حدود ما هو ممكن.
|
||||
- **MIT** — لتبني المعرفة المفتوحة والمصدر المفتوح والإيمان بأن التكنولوجيا يجب أن تكون متاحة للجميع.
|
||||
- **Sundai Club** — للمجتمع والطاقة والسعي الدؤوب لبناء أشياء مهمة.
|
||||
- **العالم وما وراءه** 🌍✨ — لكل مساهم وحالم وبانٍ هناك يجعل المصدر المفتوح قوة للخير. هذا من أجلكم.
|
||||
|
||||
نحن نبني علنًا لأن أفضل الأفكار تأتي من كل مكان. إذا كنت تقرأ هذا، فأنت جزء منه. مرحبًا. 🦀❤️
|
||||
|
||||
## المساهمة
|
||||
|
||||
جديد على ZeroClaw؟ ابحث عن المشكلات المصنفة [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — انظر [دليل المساهمة](CONTRIBUTING.md#first-time-contributors) لمعرفة كيفية البدء. مرحبًا بمساهمات AI/vibe-coded! 🤖
|
||||
|
||||
انظر [CONTRIBUTING.md](CONTRIBUTING.md) و[CLA.md](docs/contributing/cla.md). نفّذ سمة، قدّم PR:
|
||||
|
||||
- دليل سير عمل CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- `Provider` جديد → `src/providers/`
|
||||
- `Channel` جديد → `src/channels/`
|
||||
- `Observer` جديد → `src/observability/`
|
||||
- `Tool` جديد → `src/tools/`
|
||||
- `Memory` جديد → `src/memory/`
|
||||
- `Tunnel` جديد → `src/tunnel/`
|
||||
- `Peripheral` جديد → `src/peripherals/`
|
||||
- `Skill` جديد → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ المستودع الرسمي وتحذير الانتحال
|
||||
|
||||
**هذا هو مستودع ZeroClaw الرسمي الوحيد:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
أي مستودع أو منظمة أو نطاق أو حزمة أخرى تدعي أنها "ZeroClaw" أو تشير إلى انتمائها لـ ZeroClaw Labs هي **غير مصرح بها وغير مرتبطة بهذا المشروع**. سيتم سرد النسخ المتفرعة غير المصرح بها المعروفة في [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
إذا واجهت انتحالًا أو إساءة استخدام للعلامة التجارية، يرجى [فتح مشكلة](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## الترخيص
|
||||
|
||||
ZeroClaw مرخص بترخيص مزدوج لأقصى انفتاح وحماية للمساهمين:
|
||||
|
||||
| الترخيص | حالة الاستخدام |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | مفتوح المصدر، بحثي، أكاديمي، استخدام شخصي |
|
||||
| [Apache 2.0](LICENSE-APACHE) | حماية براءات الاختراع، مؤسسي، نشر تجاري |
|
||||
|
||||
يمكنك اختيار أي ترخيص. **يمنح المساهمون الحقوق تلقائيًا بموجب كليهما** — انظر [CLA.md](docs/contributing/cla.md) لاتفاقية المساهم الكاملة.
|
||||
|
||||
### العلامة التجارية
|
||||
|
||||
اسم وشعار **ZeroClaw** هما علامتان تجاريتان لـ ZeroClaw Labs. لا يمنح هذا الترخيص إذنًا لاستخدامهما للإشارة إلى التأييد أو الانتماء. انظر [TRADEMARK.md](docs/maintainers/trademark.md) للاستخدامات المسموحة والمحظورة.
|
||||
|
||||
### حماية المساهمين
|
||||
|
||||
- أنت **تحتفظ بحقوق الملكية الفكرية** لمساهماتك
|
||||
- **منح براءة الاختراع** (Apache 2.0) يحميك من مطالبات براءات الاختراع من مساهمين آخرين
|
||||
- مساهماتك **منسوبة بشكل دائم** في تاريخ الالتزامات و[NOTICE](NOTICE)
|
||||
- لا يتم نقل حقوق العلامة التجارية بالمساهمة
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — صفر حمل زائد. صفر تنازلات. انشر في أي مكان. بدّل أي شيء. 🦀
|
||||
|
||||
## المساهمون
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
يتم إنشاء هذه القائمة من رسم المساهمين في GitHub وتُحدّث تلقائيًا.
|
||||
|
||||
## تاريخ النجوم
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.bn.md
755
README.bn.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — ব্যক্তিগত AI সহকারী</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>শূন্য ওভারহেড। শূন্য আপস। 100% Rust। 100% অজ্ঞেয়বাদী।</strong><br>
|
||||
⚡️ <strong>$10 হার্ডওয়্যারে <5MB RAM দিয়ে চলে: এটি OpenClaw থেকে 99% কম মেমোরি এবং Mac mini থেকে 98% সস্তা!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Harvard, MIT, এবং Sundai.Club সম্প্রদায়ের ছাত্র ও সদস্যদের দ্বারা নির্মিত।
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>ভাষাসমূহ:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw একটি ব্যক্তিগত AI সহকারী যা আপনি আপনার নিজের ডিভাইসে চালান। এটি আপনাকে সেই চ্যানেলগুলোতে উত্তর দেয় যা আপনি ইতিমধ্যে ব্যবহার করেন (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, এবং আরও)। এতে রিয়েল-টাইম নিয়ন্ত্রণের জন্য একটি ওয়েব ড্যাশবোর্ড আছে এবং এটি হার্ডওয়্যার পেরিফেরালের (ESP32, STM32, Arduino, Raspberry Pi) সাথে সংযোগ করতে পারে। Gateway শুধুমাত্র কন্ট্রোল প্লেন — পণ্যটি হল সহকারী।
|
||||
|
||||
আপনি যদি একটি ব্যক্তিগত, একক-ব্যবহারকারী সহকারী চান যা স্থানীয়, দ্রুত এবং সর্বদা চালু মনে হয়, এটাই সেটি।
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">ওয়েবসাইট</a> ·
|
||||
<a href="docs/README.md">ডকুমেন্টেশন</a> ·
|
||||
<a href="docs/architecture.md">আর্কিটেকচার</a> ·
|
||||
<a href="#দ্রুত-শুরু">শুরু করুন</a> ·
|
||||
<a href="#openclaw-থেকে-মাইগ্রেশন">OpenClaw থেকে মাইগ্রেশন</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">সমস্যা সমাধান</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **পছন্দের সেটআপ:** আপনার টার্মিনালে `zeroclaw onboard` চালান। ZeroClaw Onboard আপনাকে gateway, workspace, channels, এবং provider সেট আপ করতে ধাপে ধাপে গাইড করে। এটি প্রস্তাবিত সেটআপ পথ এবং macOS, Linux, এবং Windows (WSL2 এর মাধ্যমে) এ কাজ করে। নতুন ইনস্টল? এখানে শুরু করুন: [শুরু করুন](#দ্রুত-শুরু)
|
||||
|
||||
### সাবস্ক্রিপশন অথ (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT সাবস্ক্রিপশন)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API key বা auth token)
|
||||
|
||||
মডেল নোট: যদিও অনেক প্রদানকারী/মডেল সমর্থিত, সেরা অভিজ্ঞতার জন্য আপনার কাছে উপলব্ধ সবচেয়ে শক্তিশালী সর্বশেষ প্রজন্মের মডেল ব্যবহার করুন। দেখুন [অনবোর্ডিং](#দ্রুত-শুরু)।
|
||||
|
||||
মডেল কনফিগ + CLI: [প্রদানকারী রেফারেন্স](docs/reference/api/providers-reference.md)
|
||||
অথ প্রোফাইল রোটেশন (OAuth বনাম API keys) + ফেইলওভার: [মডেল ফেইলওভার](docs/reference/api/providers-reference.md)
|
||||
|
||||
## ইনস্টল (প্রস্তাবিত)
|
||||
|
||||
রানটাইম: Rust স্থিতিশীল টুলচেইন। একক বাইনারি, কোনো রানটাইম নির্ভরতা নেই।
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### এক-ক্লিক বুটস্ট্র্যাপ
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` ইনস্টলের পরে স্বয়ংক্রিয়ভাবে চলে আপনার workspace এবং provider কনফিগার করতে।
|
||||
|
||||
## দ্রুত শুরু (TL;DR)
|
||||
|
||||
সম্পূর্ণ শিক্ষানবিশ গাইড (অথ, পেয়ারিং, চ্যানেল): [শুরু করুন](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Install + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start the gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Talk to the assistant
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonomous runtime (gateway + channels + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
zeroclaw status
|
||||
|
||||
# Run diagnostics
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
আপগ্রেড করছেন? আপডেটের পরে `zeroclaw doctor` চালান।
|
||||
|
||||
### সোর্স থেকে (ডেভেলপমেন্ট)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **ডেভ ফলব্যাক (কোনো গ্লোবাল ইনস্টল নেই):** কমান্ডের আগে `cargo run --release --` যোগ করুন (উদাহরণ: `cargo run --release -- status`)।
|
||||
|
||||
## OpenClaw থেকে মাইগ্রেশন
|
||||
|
||||
ZeroClaw আপনার OpenClaw workspace, মেমোরি, এবং কনফিগারেশন আমদানি করতে পারে:
|
||||
|
||||
```bash
|
||||
# Preview what will be migrated (safe, read-only)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Run the migration
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
এটি আপনার মেমোরি এন্ট্রি, workspace ফাইল, এবং কনফিগারেশন `~/.openclaw/` থেকে `~/.zeroclaw/` তে মাইগ্রেট করে। কনফিগ স্বয়ংক্রিয়ভাবে JSON থেকে TOML এ রূপান্তরিত হয়।
|
||||
|
||||
## নিরাপত্তা ডিফল্ট (DM অ্যাক্সেস)
|
||||
|
||||
ZeroClaw প্রকৃত মেসেজিং সারফেসের সাথে সংযোগ করে। ইনবাউন্ড DM গুলোকে অবিশ্বস্ত ইনপুট হিসেবে বিবেচনা করুন।
|
||||
|
||||
সম্পূর্ণ নিরাপত্তা গাইড: [SECURITY.md](SECURITY.md)
|
||||
|
||||
সকল চ্যানেলে ডিফল্ট আচরণ:
|
||||
|
||||
- **DM পেয়ারিং** (ডিফল্ট): অজানা প্রেরকরা একটি সংক্ষিপ্ত পেয়ারিং কোড পায় এবং বট তাদের বার্তা প্রক্রিয়া করে না।
|
||||
- এর মাধ্যমে অনুমোদন করুন: `zeroclaw pairing approve <channel> <code>` (তারপর প্রেরক স্থানীয় অনুমতি তালিকায় যুক্ত হয়)।
|
||||
- পাবলিক ইনবাউন্ড DM এর জন্য `config.toml` এ স্পষ্ট অপ্ট-ইন প্রয়োজন।
|
||||
- ঝুঁকিপূর্ণ বা ভুল কনফিগার করা DM নীতি প্রকাশ করতে `zeroclaw doctor` চালান।
|
||||
|
||||
**স্বায়ত্তশাসন স্তর:**
|
||||
|
||||
| স্তর | আচরণ |
|
||||
|-------|----------|
|
||||
| `ReadOnly` | এজেন্ট পর্যবেক্ষণ করতে পারে কিন্তু কাজ করতে পারে না |
|
||||
| `Supervised` (ডিফল্ট) | এজেন্ট মাঝারি/উচ্চ ঝুঁকি অপারেশনের জন্য অনুমোদন সহ কাজ করে |
|
||||
| `Full` | এজেন্ট নীতি সীমার মধ্যে স্বায়ত্তশাসিতভাবে কাজ করে |
|
||||
|
||||
**স্যান্ডবক্সিং স্তর:** workspace আইসোলেশন, পাথ ট্রাভার্সাল ব্লকিং, কমান্ড অনুমতি তালিকা, নিষিদ্ধ পাথ (`/etc`, `/root`, `~/.ssh`), রেট লিমিটিং (সর্বোচ্চ কার্য/ঘণ্টা, খরচ/দিন সীমা)।
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 ঘোষণা
|
||||
|
||||
গুরুত্বপূর্ণ নোটিশের (ব্রেকিং পরিবর্তন, নিরাপত্তা পরামর্শ, রক্ষণাবেক্ষণ উইন্ডো, এবং রিলিজ ব্লকার) জন্য এই বোর্ড ব্যবহার করুন।
|
||||
|
||||
| তারিখ (UTC) | স্তর | নোটিশ | পদক্ষেপ |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _জটিল_ | আমরা `openagen/zeroclaw`, `zeroclaw.org` বা `zeroclaw.net` এর সাথে **সম্পর্কিত নই**। `zeroclaw.org` এবং `zeroclaw.net` ডোমেইনগুলো বর্তমানে `openagen/zeroclaw` ফর্কের দিকে নির্দেশ করে, এবং সেই ডোমেইন/রিপোজিটরি আমাদের অফিসিয়াল ওয়েবসাইট/প্রকল্পের ছদ্মবেশ ধারণ করছে। | সেই উৎসগুলো থেকে তথ্য, বাইনারি, তহবিল সংগ্রহ, বা ঘোষণায় বিশ্বাস করবেন না। শুধুমাত্র [এই রিপোজিটরি](https://github.com/zeroclaw-labs/zeroclaw) এবং আমাদের যাচাইকৃত সোশ্যাল অ্যাকাউন্ট ব্যবহার করুন। |
|
||||
| 2026-02-21 | _গুরুত্বপূর্ণ_ | আমাদের অফিসিয়াল ওয়েবসাইট এখন লাইভ: [zeroclawlabs.ai](https://zeroclawlabs.ai)। লঞ্চ প্রস্তুত করার সময় আপনার ধৈর্যের জন্য ধন্যবাদ। আমরা এখনও ছদ্মবেশ প্রচেষ্টা দেখছি, তাই কোনো বিনিয়োগ বা তহবিল সংগ্রহ কার্যকলাপে **যোগ দেবেন না** যা ZeroClaw নাম দাবি করে যদি না এটি আমাদের অফিসিয়াল চ্যানেলের মাধ্যমে প্রকাশিত হয়। | [এই রিপোজিটরি](https://github.com/zeroclaw-labs/zeroclaw) কে সত্যের একক উৎস হিসেবে ব্যবহার করুন। অফিসিয়াল আপডেটের জন্য [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs), এবং [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) অনুসরণ করুন। |
|
||||
| 2026-02-19 | _গুরুত্বপূর্ণ_ | Anthropic 2026-02-19 তে Authentication and Credential Use শর্তাবলী আপডেট করেছে। Claude Code OAuth টোকেন (Free, Pro, Max) একচেটিয়াভাবে Claude Code এবং Claude.ai এর জন্য; Claude Free/Pro/Max থেকে OAuth টোকেন অন্য কোনো পণ্য, টুল, বা সেবায় (Agent SDK সহ) ব্যবহার অনুমোদিত নয় এবং Consumer Terms of Service লঙ্ঘন করতে পারে। | সম্ভাব্য ক্ষতি রোধ করতে অনুগ্রহ করে Claude Code OAuth ইন্টিগ্রেশন সাময়িকভাবে এড়িয়ে চলুন। মূল ধারা: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)। |
|
||||
|
||||
## প্রধান বৈশিষ্ট্য
|
||||
|
||||
- **ডিফল্টভাবে হালকা রানটাইম** — সাধারণ CLI এবং স্ট্যাটাস ওয়ার্কফ্লো রিলিজ বিল্ডে কয়েক-মেগাবাইট মেমোরি এনভেলপে চলে।
|
||||
- **খরচ-সাশ্রয়ী ডিপ্লয়মেন্ট** — $10 বোর্ড এবং ছোট ক্লাউড ইনস্ট্যান্সের জন্য ডিজাইন করা, কোনো ভারী রানটাইম নির্ভরতা নেই।
|
||||
- **দ্রুত কোল্ড স্টার্ট** — একক-বাইনারি Rust রানটাইম কমান্ড এবং ডেমন স্টার্টআপ প্রায় তাৎক্ষণিক রাখে।
|
||||
- **পোর্টেবল আর্কিটেকচার** — ARM, x86, এবং RISC-V জুড়ে একটি বাইনারি যার সাথে বিনিময়যোগ্য প্রদানকারী/চ্যানেল/টুল।
|
||||
- **লোকাল-ফার্স্ট Gateway** — সেশন, চ্যানেল, টুল, cron, SOPs, এবং ইভেন্টের জন্য একক কন্ট্রোল প্লেন।
|
||||
- **মাল্টি-চ্যানেল ইনবক্স** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket, এবং আরও।
|
||||
- **মাল্টি-এজেন্ট অর্কেস্ট্রেশন (Hands)** — স্বায়ত্তশাসিত এজেন্ট সোয়ার্ম যা সময়সূচী অনুযায়ী চলে এবং সময়ের সাথে আরও স্মার্ট হয়।
|
||||
- **স্ট্যান্ডার্ড অপারেটিং প্রসিডিউর (SOPs)** — MQTT, webhook, cron, এবং পেরিফেরাল ট্রিগার সহ ইভেন্ট-চালিত ওয়ার্কফ্লো অটোমেশন।
|
||||
- **ওয়েব ড্যাশবোর্ড** — React 19 + Vite ওয়েব UI যাতে রিয়েল-টাইম চ্যাট, মেমোরি ব্রাউজার, কনফিগ এডিটর, cron ম্যানেজার, এবং টুল ইন্সপেক্টর আছে।
|
||||
- **হার্ডওয়্যার পেরিফেরাল** — `Peripheral` trait এর মাধ্যমে ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO।
|
||||
- **প্রথম-শ্রেণীর টুল** — shell, ফাইল I/O, browser, git, ওয়েব fetch/search, MCP, Jira, Notion, Google Workspace, এবং 70+ আরও।
|
||||
- **লাইফসাইকেল হুক** — প্রতিটি পর্যায়ে LLM কল, টুল এক্সিকিউশন, এবং বার্তা ইন্টারসেপ্ট ও পরিবর্তন করুন।
|
||||
- **স্কিল প্ল্যাটফর্ম** — নিরাপত্তা অডিটিং সহ বান্ডেল, সম্প্রদায়, এবং workspace স্কিল।
|
||||
- **টানেল সাপোর্ট** — রিমোট অ্যাক্সেসের জন্য Cloudflare, Tailscale, ngrok, OpenVPN, এবং কাস্টম টানেল।
|
||||
|
||||
### দলগুলো কেন ZeroClaw বেছে নেয়
|
||||
|
||||
- **ডিফল্টভাবে হালকা:** ছোট Rust বাইনারি, দ্রুত স্টার্টআপ, কম মেমোরি ফুটপ্রিন্ট।
|
||||
- **ডিজাইনে নিরাপদ:** পেয়ারিং, কঠোর স্যান্ডবক্সিং, স্পষ্ট অনুমতি তালিকা, workspace স্কোপিং।
|
||||
- **সম্পূর্ণ বিনিময়যোগ্য:** মূল সিস্টেমগুলো traits (providers, channels, tools, memory, tunnels)।
|
||||
- **কোনো লক-ইন নেই:** OpenAI-সামঞ্জস্যপূর্ণ প্রদানকারী সমর্থন + প্লাগেবল কাস্টম এন্ডপয়েন্ট।
|
||||
|
||||
## বেঞ্চমার্ক স্ন্যাপশট (ZeroClaw বনাম OpenClaw, পুনরুৎপাদনযোগ্য)
|
||||
|
||||
স্থানীয় মেশিন দ্রুত বেঞ্চমার্ক (macOS arm64, ফেব্রুয়ারি 2026) 0.8GHz এজ হার্ডওয়্যারের জন্য স্বাভাবিকীকৃত।
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **ভাষা** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **স্টার্টআপ (0.8GHz কোর)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **বাইনারি আকার** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **খরচ** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **যেকোনো হার্ডওয়্যার $10** |
|
||||
|
||||
> নোট: ZeroClaw ফলাফল `/usr/bin/time -l` ব্যবহার করে রিলিজ বিল্ডে পরিমাপ করা হয়েছে। OpenClaw এর Node.js রানটাইম প্রয়োজন (সাধারণত ~390MB অতিরিক্ত মেমোরি ওভারহেড), যেখানে NanoBot এর Python রানটাইম প্রয়োজন। PicoClaw এবং ZeroClaw স্ট্যাটিক বাইনারি। উপরের RAM পরিসংখ্যান রানটাইম মেমোরি; বিল্ড-টাইম কম্পাইলেশন প্রয়োজনীয়তা বেশি।
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### পুনরুৎপাদনযোগ্য স্থানীয় পরিমাপ
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## এখন পর্যন্ত আমরা যা তৈরি করেছি
|
||||
|
||||
### কোর প্ল্যাটফর্ম
|
||||
|
||||
- Gateway HTTP/WS/SSE কন্ট্রোল প্লেন যাতে সেশন, উপস্থিতি, কনফিগ, cron, webhooks, ওয়েব ড্যাশবোর্ড, এবং পেয়ারিং আছে।
|
||||
- CLI সারফেস: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`।
|
||||
- এজেন্ট অর্কেস্ট্রেশন লুপ যাতে টুল ডিসপ্যাচ, প্রম্পট নির্মাণ, বার্তা শ্রেণীবিভাগ, এবং মেমোরি লোডিং আছে।
|
||||
- নিরাপত্তা নীতি প্রয়োগ, স্বায়ত্তশাসন স্তর, এবং অনুমোদন গেটিং সহ সেশন মডেল।
|
||||
- 20+ LLM ব্যাকএন্ড জুড়ে ফেইলওভার, রিট্রাই, এবং মডেল রাউটিং সহ রেজিলিয়েন্ট প্রদানকারী র্যাপার।
|
||||
|
||||
### চ্যানেল
|
||||
|
||||
চ্যানেল: WhatsApp (নেটিভ), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk।
|
||||
|
||||
ফিচার-গেটেড: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`)।
|
||||
|
||||
### ওয়েব ড্যাশবোর্ড
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 ওয়েব ড্যাশবোর্ড সরাসরি Gateway থেকে পরিবেশিত:
|
||||
|
||||
- **ড্যাশবোর্ড** — সিস্টেম ওভারভিউ, স্বাস্থ্য অবস্থা, আপটাইম, খরচ ট্র্যাকিং
|
||||
- **এজেন্ট চ্যাট** — এজেন্টের সাথে ইন্টারেক্টিভ চ্যাট
|
||||
- **মেমোরি** — মেমোরি এন্ট্রি ব্রাউজ ও পরিচালনা
|
||||
- **কনফিগ** — কনফিগারেশন দেখুন ও সম্পাদনা করুন
|
||||
- **Cron** — নির্ধারিত কাজ পরিচালনা
|
||||
- **টুলস** — উপলব্ধ টুল ব্রাউজ করুন
|
||||
- **লগস** — এজেন্ট কার্যকলাপ লগ দেখুন
|
||||
- **খরচ** — টোকেন ব্যবহার এবং খরচ ট্র্যাকিং
|
||||
- **ডক্টর** — সিস্টেম স্বাস্থ্য ডায়াগনস্টিকস
|
||||
- **ইন্টিগ্রেশন** — ইন্টিগ্রেশন অবস্থা এবং সেটআপ
|
||||
- **পেয়ারিং** — ডিভাইস পেয়ারিং পরিচালনা
|
||||
|
||||
### ফার্মওয়্যার টার্গেট
|
||||
|
||||
| টার্গেট | প্ল্যাটফর্ম | উদ্দেশ্য |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | ওয়্যারলেস পেরিফেরাল এজেন্ট |
|
||||
| ESP32-UI | ESP32 + Display | ভিজ্যুয়াল ইন্টারফেস সহ এজেন্ট |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | ইন্ডাস্ট্রিয়াল পেরিফেরাল |
|
||||
| Arduino | Arduino | বেসিক সেন্সর/অ্যাকচুয়েটর ব্রিজ |
|
||||
| Uno Q Bridge | Arduino Uno | এজেন্টের জন্য সিরিয়াল ব্রিজ |
|
||||
|
||||
### টুল + অটোমেশন
|
||||
|
||||
- **কোর:** shell, ফাইল read/write/edit, git অপারেশন, glob search, content search
|
||||
- **ওয়েব:** ব্রাউজার নিয়ন্ত্রণ, web fetch, web search, screenshot, image info, PDF read
|
||||
- **ইন্টিগ্রেশন:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol টুল র্যাপার + ডিফার্ড টুল সেট
|
||||
- **শিডিউলিং:** cron add/remove/update/run, schedule tool
|
||||
- **মেমোরি:** recall, store, forget, knowledge, project intel
|
||||
- **উন্নত:** delegate (এজেন্ট-টু-এজেন্ট), swarm, model switch/routing, security ops, cloud ops
|
||||
- **হার্ডওয়্যার:** board info, memory map, memory read (ফিচার-গেটেড)
|
||||
|
||||
### রানটাইম + নিরাপত্তা
|
||||
|
||||
- **স্বায়ত্তশাসন স্তর:** ReadOnly, Supervised (ডিফল্ট), Full।
|
||||
- **স্যান্ডবক্সিং:** workspace আইসোলেশন, পাথ ট্রাভার্সাল ব্লকিং, কমান্ড অনুমতি তালিকা, নিষিদ্ধ পাথ, Landlock (Linux), Bubblewrap।
|
||||
- **রেট লিমিটিং:** প্রতি ঘণ্টায় সর্বোচ্চ কার্য, প্রতি দিনে সর্বোচ্চ খরচ (কনফিগারযোগ্য)।
|
||||
- **অনুমোদন গেটিং:** মাঝারি/উচ্চ ঝুঁকি অপারেশনের জন্য ইন্টারেক্টিভ অনুমোদন।
|
||||
- **ই-স্টপ:** জরুরি শাটডাউন ক্ষমতা।
|
||||
- **129+ নিরাপত্তা পরীক্ষা** স্বয়ংক্রিয় CI তে।
|
||||
|
||||
### অপস + প্যাকেজিং
|
||||
|
||||
- ওয়েব ড্যাশবোর্ড সরাসরি Gateway থেকে পরিবেশিত।
|
||||
- টানেল সাপোর্ট: Cloudflare, Tailscale, ngrok, OpenVPN, কাস্টম কমান্ড।
|
||||
- কন্টেইনারাইজড এক্সিকিউশনের জন্য Docker রানটাইম অ্যাডাপ্টার।
|
||||
- CI/CD: বেটা (পুশে অটো) → স্টেবল (ম্যানুয়াল ডিসপ্যাচ) → Docker, crates.io, Scoop, AUR, Homebrew, টুইট।
|
||||
- Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64) এর জন্য প্রি-বিল্ট বাইনারি।
|
||||
|
||||
|
||||
## কনফিগারেশন
|
||||
|
||||
ন্যূনতম `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
সম্পূর্ণ কনফিগারেশন রেফারেন্স: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)।
|
||||
|
||||
### চ্যানেল কনফিগারেশন
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### টানেল কনফিগারেশন
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
বিস্তারিত: [চ্যানেল রেফারেন্স](docs/reference/api/channels-reference.md) · [কনফিগ রেফারেন্স](docs/reference/api/config-reference.md)
|
||||
|
||||
### রানটাইম সাপোর্ট (বর্তমান)
|
||||
|
||||
- **`native`** (ডিফল্ট) — সরাসরি প্রসেস এক্সিকিউশন, দ্রুততম পথ, বিশ্বস্ত পরিবেশের জন্য আদর্শ।
|
||||
- **`docker`** — সম্পূর্ণ কন্টেইনার আইসোলেশন, প্রয়োগকৃত নিরাপত্তা নীতি, Docker প্রয়োজন।
|
||||
|
||||
কঠোর স্যান্ডবক্সিং বা নেটওয়ার্ক আইসোলেশনের জন্য `runtime.kind = "docker"` সেট করুন।
|
||||
|
||||
## সাবস্ক্রিপশন অথ (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw সাবস্ক্রিপশন-নেটিভ অথ প্রোফাইল সমর্থন করে (মাল্টি-অ্যাকাউন্ট, বিশ্রামে এনক্রিপ্টেড)।
|
||||
|
||||
- স্টোর ফাইল: `~/.zeroclaw/auth-profiles.json`
|
||||
- এনক্রিপশন কী: `~/.zeroclaw/.secret_key`
|
||||
- প্রোফাইল id ফরম্যাট: `<provider>:<profile_name>` (উদাহরণ: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## এজেন্ট workspace + স্কিল
|
||||
|
||||
Workspace রুট: `~/.zeroclaw/workspace/` (কনফিগের মাধ্যমে কনফিগারযোগ্য)।
|
||||
|
||||
ইনজেক্ট করা প্রম্পট ফাইল:
|
||||
- `IDENTITY.md` — এজেন্টের ব্যক্তিত্ব এবং ভূমিকা
|
||||
- `USER.md` — ব্যবহারকারীর প্রসঙ্গ এবং পছন্দ
|
||||
- `MEMORY.md` — দীর্ঘমেয়াদী তথ্য এবং শিক্ষা
|
||||
- `AGENTS.md` — সেশন কনভেনশন এবং ইনিশিয়ালাইজেশন নিয়ম
|
||||
- `SOUL.md` — মূল পরিচয় এবং পরিচালন নীতি
|
||||
|
||||
স্কিল: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` বা `SKILL.toml`।
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI কমান্ড
|
||||
|
||||
```bash
|
||||
# Workspace management
|
||||
zeroclaw onboard # Guided setup wizard
|
||||
zeroclaw status # Show daemon/agent status
|
||||
zeroclaw doctor # Run system diagnostics
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonomous runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactive chat mode
|
||||
zeroclaw agent -m "message" # Single message mode
|
||||
|
||||
# Service management
|
||||
zeroclaw service install # Install as OS service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Channels
|
||||
zeroclaw channel list # List configured channels
|
||||
zeroclaw channel doctor # Check channel health
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + scheduling
|
||||
zeroclaw cron list # List scheduled jobs
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memory
|
||||
zeroclaw memory list # List memory entries
|
||||
zeroclaw memory get <key> # Retrieve a memory
|
||||
zeroclaw memory stats # Memory statistics
|
||||
|
||||
# Auth profiles
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware peripherals
|
||||
zeroclaw hardware discover # Scan for connected devices
|
||||
zeroclaw peripheral list # List connected peripherals
|
||||
zeroclaw peripheral flash # Flash firmware to device
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell completions
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
সম্পূর্ণ কমান্ড রেফারেন্স: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## পূর্বশর্ত
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### প্রয়োজনীয়
|
||||
|
||||
1. **Visual Studio Build Tools** (MSVC লিঙ্কার এবং Windows SDK প্রদান করে):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
ইনস্টলেশনের সময় (বা Visual Studio Installer এর মাধ্যমে), **"Desktop development with C++"** ওয়ার্কলোড নির্বাচন করুন।
|
||||
|
||||
2. **Rust টুলচেইন:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
ইনস্টলেশনের পরে, একটি নতুন টার্মিনাল খুলুন এবং `rustup default stable` চালান স্থিতিশীল টুলচেইন সক্রিয় করতে।
|
||||
|
||||
3. **যাচাই করুন** উভয়ই কাজ করছে:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### ঐচ্ছিক
|
||||
|
||||
- **Docker Desktop** — শুধুমাত্র [Docker স্যান্ডবক্সড রানটাইম](#রানটাইম-সাপোর্ট-বর্তমান) (`runtime.kind = "docker"`) ব্যবহার করলে প্রয়োজন। `winget install Docker.DockerDesktop` দিয়ে ইনস্টল করুন।
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### প্রয়োজনীয়
|
||||
|
||||
1. **বিল্ড এসেনশিয়ালস:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Xcode Command Line Tools ইনস্টল করুন: `xcode-select --install`
|
||||
|
||||
2. **Rust টুলচেইন:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
বিস্তারিতের জন্য [rustup.rs](https://rustup.rs) দেখুন।
|
||||
|
||||
3. **যাচাই করুন** উভয়ই কাজ করছে:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### এক-লাইন ইনস্টলার
|
||||
|
||||
অথবা উপরের ধাপগুলো এড়িয়ে একটি কমান্ডে সবকিছু (সিস্টেম deps, Rust, ZeroClaw) ইনস্টল করুন:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### কম্পাইলেশন রিসোর্স প্রয়োজনীয়তা
|
||||
|
||||
সোর্স থেকে বিল্ড করতে ফলাফল বাইনারি চালানোর চেয়ে বেশি রিসোর্স প্রয়োজন:
|
||||
|
||||
| রিসোর্স | ন্যূনতম | প্রস্তাবিত |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **ফ্রি ডিস্ক** | 6 GB | 10 GB+ |
|
||||
|
||||
আপনার হোস্ট ন্যূনতমের নিচে হলে, প্রি-বিল্ট বাইনারি ব্যবহার করুন:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
সোর্স ফলব্যাক ছাড়া শুধুমাত্র বাইনারি ইনস্টল করতে:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### ঐচ্ছিক
|
||||
|
||||
- **Docker** — শুধুমাত্র [Docker স্যান্ডবক্সড রানটাইম](#রানটাইম-সাপোর্ট-বর্তমান) (`runtime.kind = "docker"`) ব্যবহার করলে প্রয়োজন। আপনার প্যাকেজ ম্যানেজার বা [docker.com](https://docs.docker.com/engine/install/) থেকে ইনস্টল করুন।
|
||||
|
||||
> **নোট:** ডিফল্ট `cargo build --release` পিক কম্পাইল প্রেশার কমাতে `codegen-units=1` ব্যবহার করে। শক্তিশালী মেশিনে দ্রুত বিল্ডের জন্য, `cargo build --profile release-fast` ব্যবহার করুন।
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### প্রি-বিল্ট বাইনারি
|
||||
|
||||
রিলিজ অ্যাসেট প্রকাশিত হয়:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
সর্বশেষ অ্যাসেট ডাউনলোড করুন:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## ডকুমেন্টেশন
|
||||
|
||||
অনবোর্ডিং প্রবাহের পরে এবং গভীর রেফারেন্স চাইলে এগুলো ব্যবহার করুন।
|
||||
|
||||
- নেভিগেশন এবং "কোথায় কী" এর জন্য [ডকুমেন্টেশন ইনডেক্স](docs/README.md) দিয়ে শুরু করুন।
|
||||
- সম্পূর্ণ সিস্টেম মডেলের জন্য [আর্কিটেকচার ওভারভিউ](docs/architecture.md) পড়ুন।
|
||||
- প্রতিটি কী এবং উদাহরণ প্রয়োজন হলে [কনফিগারেশন রেফারেন্স](docs/reference/api/config-reference.md) ব্যবহার করুন।
|
||||
- [অপারেশনাল রানবুক](docs/ops/operations-runbook.md) অনুযায়ী Gateway চালান।
|
||||
- গাইডেড সেটআপের জন্য [ZeroClaw Onboard](#দ্রুত-শুরু) অনুসরণ করুন।
|
||||
- [সমস্যা সমাধান গাইড](docs/ops/troubleshooting.md) দিয়ে সাধারণ ব্যর্থতা ডিবাগ করুন।
|
||||
- কিছু এক্সপোজ করার আগে [নিরাপত্তা নির্দেশনা](docs/security/README.md) পর্যালোচনা করুন।
|
||||
|
||||
### রেফারেন্স ডকুমেন্টেশন
|
||||
|
||||
- ডকুমেন্টেশন হাব: [docs/README.md](docs/README.md)
|
||||
- একীভূত ডকুমেন্টেশন TOC: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- কমান্ড রেফারেন্স: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- কনফিগ রেফারেন্স: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- প্রদানকারী রেফারেন্স: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- চ্যানেল রেফারেন্স: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- অপারেশনস রানবুক: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- সমস্যা সমাধান: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### সহযোগিতা ডকুমেন্টেশন
|
||||
|
||||
- অবদান গাইড: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR ওয়ার্কফ্লো নীতি: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI ওয়ার্কফ্লো গাইড: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- পর্যালোচক প্লেবুক: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- নিরাপত্তা প্রকাশ নীতি: [SECURITY.md](SECURITY.md)
|
||||
- ডকুমেন্টেশন টেমপ্লেট: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### ডিপ্লয়মেন্ট + অপারেশন
|
||||
|
||||
- নেটওয়ার্ক ডিপ্লয়মেন্ট গাইড: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- প্রক্সি এজেন্ট প্লেবুক: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- হার্ডওয়্যার গাইড: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw smooth crab 🦀 এর জন্য তৈরি হয়েছিল, একটি দ্রুত এবং দক্ষ AI সহকারী। Argenis De La Rosa এবং সম্প্রদায় দ্বারা নির্মিত।
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ZeroClaw সমর্থন করুন
|
||||
|
||||
ZeroClaw আপনার কাজে সাহায্য করলে এবং আপনি চলমান উন্নয়ন সমর্থন করতে চাইলে, এখানে দান করতে পারেন:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 বিশেষ ধন্যবাদ
|
||||
|
||||
যে সম্প্রদায় এবং প্রতিষ্ঠানগুলো এই ওপেন-সোর্স কাজকে অনুপ্রাণিত এবং শক্তি দেয় তাদের প্রতি আন্তরিক ধন্যবাদ:
|
||||
|
||||
- **Harvard University** — বৌদ্ধিক কৌতূহল লালন এবং সম্ভাবনার সীমানা প্রসারিত করার জন্য।
|
||||
- **MIT** — খোলা জ্ঞান, ওপেন সোর্স, এবং প্রযুক্তি সবার জন্য অ্যাক্সেসযোগ্য হওয়া উচিত এই বিশ্বাসের চ্যাম্পিয়ন হওয়ার জন্য।
|
||||
- **Sundai Club** — সম্প্রদায়, শক্তি, এবং গুরুত্বপূর্ণ জিনিস তৈরির অদম্য চেষ্টার জন্য।
|
||||
- **বিশ্ব এবং তার বাইরে** 🌍✨ — প্রতিটি অবদানকারী, স্বপ্নদ্রষ্টা, এবং নির্মাতার জন্য যারা ওপেন সোর্সকে ভালোর শক্তি বানাচ্ছে। এটি আপনার জন্য।
|
||||
|
||||
আমরা খোলামেলাভাবে তৈরি করছি কারণ সেরা ধারণাগুলো সর্বত্র থেকে আসে। আপনি যদি এটি পড়ছেন, আপনি এর অংশ। স্বাগতম। 🦀❤️
|
||||
|
||||
## অবদান
|
||||
|
||||
ZeroClaw এ নতুন? [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) লেবেলযুক্ত ইস্যু খুঁজুন — কিভাবে শুরু করতে হয় তা জানতে আমাদের [অবদান গাইড](CONTRIBUTING.md#first-time-contributors) দেখুন। AI/vibe-coded PR স্বাগত! 🤖
|
||||
|
||||
[CONTRIBUTING.md](CONTRIBUTING.md) এবং [CLA.md](docs/contributing/cla.md) দেখুন। একটি trait বাস্তবায়ন করুন, PR জমা দিন:
|
||||
|
||||
- CI ওয়ার্কফ্লো গাইড: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- নতুন `Provider` → `src/providers/`
|
||||
- নতুন `Channel` → `src/channels/`
|
||||
- নতুন `Observer` → `src/observability/`
|
||||
- নতুন `Tool` → `src/tools/`
|
||||
- নতুন `Memory` → `src/memory/`
|
||||
- নতুন `Tunnel` → `src/tunnel/`
|
||||
- নতুন `Peripheral` → `src/peripherals/`
|
||||
- নতুন `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ অফিসিয়াল রিপোজিটরি এবং ছদ্মবেশ সতর্কতা
|
||||
|
||||
**এটিই একমাত্র অফিসিয়াল ZeroClaw রিপোজিটরি:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
অন্য কোনো রিপোজিটরি, সংগঠন, ডোমেইন, বা প্যাকেজ যা "ZeroClaw" বলে দাবি করে বা ZeroClaw Labs এর সাথে সংযুক্তি ইঙ্গিত করে তা **অননুমোদিত এবং এই প্রকল্পের সাথে সম্পর্কিত নয়**। পরিচিত অননুমোদিত ফর্ক [TRADEMARK.md](docs/maintainers/trademark.md) তে তালিকাভুক্ত করা হবে।
|
||||
|
||||
আপনি ছদ্মবেশ বা ট্রেডমার্ক অপব্যবহারের সম্মুখীন হলে, অনুগ্রহ করে [একটি ইস্যু খুলুন](https://github.com/zeroclaw-labs/zeroclaw/issues)।
|
||||
|
||||
---
|
||||
|
||||
## লাইসেন্স
|
||||
|
||||
ZeroClaw সর্বোচ্চ উন্মুক্ততা এবং অবদানকারী সুরক্ষার জন্য দ্বৈত-লাইসেন্সপ্রাপ্ত:
|
||||
|
||||
| লাইসেন্স | ব্যবহারের ক্ষেত্র |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | ওপেন-সোর্স, গবেষণা, একাডেমিক, ব্যক্তিগত ব্যবহার |
|
||||
| [Apache 2.0](LICENSE-APACHE) | পেটেন্ট সুরক্ষা, প্রাতিষ্ঠানিক, বাণিজ্যিক ডিপ্লয়মেন্ট |
|
||||
|
||||
আপনি যেকোনো লাইসেন্স বেছে নিতে পারেন। **অবদানকারীরা স্বয়ংক্রিয়ভাবে উভয়ের অধীনে অধিকার প্রদান করে** — সম্পূর্ণ অবদানকারী চুক্তির জন্য [CLA.md](docs/contributing/cla.md) দেখুন।
|
||||
|
||||
### ট্রেডমার্ক
|
||||
|
||||
**ZeroClaw** নাম এবং লোগো ZeroClaw Labs এর ট্রেডমার্ক। এই লাইসেন্স সমর্থন বা সংযুক্তি ইঙ্গিত করতে এগুলো ব্যবহারের অনুমতি দেয় না। অনুমোদিত এবং নিষিদ্ধ ব্যবহারের জন্য [TRADEMARK.md](docs/maintainers/trademark.md) দেখুন।
|
||||
|
||||
### অবদানকারী সুরক্ষা
|
||||
|
||||
- আপনি আপনার অবদানের **কপিরাইট ধরে রাখেন**
|
||||
- **পেটেন্ট অনুদান** (Apache 2.0) আপনাকে অন্যান্য অবদানকারীদের পেটেন্ট দাবি থেকে রক্ষা করে
|
||||
- আপনার অবদান কমিট ইতিহাস এবং [NOTICE](NOTICE) এ **স্থায়ীভাবে বিশেষিত**
|
||||
- অবদান করে কোনো ট্রেডমার্ক অধিকার হস্তান্তরিত হয় না
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — শূন্য ওভারহেড। শূন্য আপস। যেকোনো জায়গায় ডিপ্লয় করুন। যেকিছু বিনিময় করুন। 🦀
|
||||
|
||||
## অবদানকারীরা
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
এই তালিকা GitHub অবদানকারী গ্রাফ থেকে তৈরি হয় এবং স্বয়ংক্রিয়ভাবে আপডেট হয়।
|
||||
|
||||
## স্টার ইতিহাস
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.cs.md
755
README.cs.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Osobní AI Asistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nulová režie. Nulový kompromis. 100% Rust. 100% Agnostický.</strong><br>
|
||||
⚡️ <strong>Běží na hardwaru za $10 s <5MB RAM: To je o 99 % méně paměti než OpenClaw a o 98 % levnější než Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Vytvořeno studenty a členy komunit Harvard, MIT a Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Jazyky:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw je osobní AI asistent, který spouštíte na vlastních zařízeních. Odpovídá vám na kanálech, které již používáte (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work a další). Má webový panel pro řízení v reálném čase a může se připojit k hardwarovým periferiím (ESP32, STM32, Arduino, Raspberry Pi). Gateway je pouze řídicí rovina — produktem je asistent.
|
||||
|
||||
Pokud hledáte osobního jednouživatelského asistenta, který je lokální, rychlý a vždy dostupný — toto je ono.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Webové stránky</a> ·
|
||||
<a href="docs/README.md">Dokumentace</a> ·
|
||||
<a href="docs/architecture.md">Architektura</a> ·
|
||||
<a href="#rychlý-start">Začínáme</a> ·
|
||||
<a href="#migrace-z-openclaw">Migrace z OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Řešení problémů</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Doporučené nastavení:** spusťte `zeroclaw onboard` ve vašem terminálu. ZeroClaw Onboard vás krok za krokem provede nastavením gateway, workspace, kanálů a poskytovatele. Je to doporučená cesta nastavení a funguje na macOS, Linux a Windows (přes WSL2). Nová instalace? Začněte zde: [Začínáme](#rychlý-start)
|
||||
|
||||
### Autentizace předplatného (OAuth)
|
||||
|
||||
- **OpenAI Codex** (předplatné ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API klíč nebo autorizační token)
|
||||
|
||||
Poznámka k modelům: ačkoli je podporováno mnoho poskytovatelů/modelů, pro nejlepší zážitek použijte nejsilnější dostupný model nejnovější generace. Viz [Onboarding](#rychlý-start).
|
||||
|
||||
Konfigurace modelů + CLI: [Reference poskytovatelů](docs/reference/api/providers-reference.md)
|
||||
Rotace autorizačních profilů (OAuth vs API klíče) + failover: [Failover modelů](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instalace (doporučená)
|
||||
|
||||
Běhové prostředí: stabilní toolchain Rust. Jeden binární soubor, žádné runtime závislosti.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Instalace jedním kliknutím
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` se automaticky spustí po instalaci pro konfiguraci vašeho workspace a poskytovatele.
|
||||
|
||||
## Rychlý start (TL;DR)
|
||||
|
||||
Kompletní průvodce pro začátečníky (autentizace, párování, kanály): [Začínáme](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instalace + onboarding
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Spuštění gateway (webhook server + webový panel)
|
||||
zeroclaw gateway # výchozí: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # náhodný port (posílené zabezpečení)
|
||||
|
||||
# Komunikace s asistentem
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktivní režim
|
||||
zeroclaw agent
|
||||
|
||||
# Spuštění plného autonomního běhového prostředí (gateway + kanály + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Kontrola stavu
|
||||
zeroclaw status
|
||||
|
||||
# Spuštění diagnostiky
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Aktualizujete? Spusťte `zeroclaw doctor` po aktualizaci.
|
||||
|
||||
### Ze zdrojového kódu (vývoj)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Vývojářský fallback (bez globální instalace):** předřaďte příkazy `cargo run --release --` (příklad: `cargo run --release -- status`).
|
||||
|
||||
## Migrace z OpenClaw
|
||||
|
||||
ZeroClaw může importovat váš workspace, paměť a konfiguraci OpenClaw:
|
||||
|
||||
```bash
|
||||
# Náhled toho, co bude migrováno (bezpečné, pouze čtení)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Spuštění migrace
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Migruje záznamy paměti, soubory workspace a konfiguraci z `~/.openclaw/` do `~/.zeroclaw/`. Konfigurace je automaticky převedena z JSON do TOML.
|
||||
|
||||
## Výchozí nastavení zabezpečení (přístup DM)
|
||||
|
||||
ZeroClaw se připojuje k reálným komunikačním platformám. Zacházejte s příchozími DM jako s nedůvěryhodným vstupem.
|
||||
|
||||
Kompletní průvodce zabezpečením: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Výchozí chování na všech kanálech:
|
||||
|
||||
- **Párování DM** (výchozí): neznámí odesílatelé obdrží krátký párovací kód a bot nezpracovává jejich zprávu.
|
||||
- Schvalte pomocí: `zeroclaw pairing approve <channel> <code>` (poté je odesílatel přidán na lokální allowlist).
|
||||
- Veřejné příchozí DM vyžadují explicitní opt-in v `config.toml`.
|
||||
- Spusťte `zeroclaw doctor` pro odhalení rizikových nebo špatně nakonfigurovaných DM politik.
|
||||
|
||||
**Úrovně autonomie:**
|
||||
|
||||
| Úroveň | Chování |
|
||||
|--------|---------|
|
||||
| `ReadOnly` | Agent může pozorovat, ale nemůže jednat |
|
||||
| `Supervised` (výchozí) | Agent jedná se schválením pro operace se středním/vysokým rizikem |
|
||||
| `Full` | Agent jedná autonomně v rámci hranic politiky |
|
||||
|
||||
**Vrstvy sandboxingu:** izolace workspace, blokování procházení cest, allowlisty příkazů, zakázané cesty (`/etc`, `/root`, `~/.ssh`), omezení rychlosti (max akcí/hodinu, denní limity nákladů).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Oznámení
|
||||
|
||||
Používejte tuto nástěnku pro důležitá oznámení (zlomové změny, bezpečnostní upozornění, okna údržby a blokátory vydání).
|
||||
|
||||
| Datum (UTC) | Úroveň | Oznámení | Akce |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritické_ | **Nejsme spojeni** s `openagen/zeroclaw`, `zeroclaw.org` ani `zeroclaw.net`. Domény `zeroclaw.org` a `zeroclaw.net` aktuálně směřují na fork `openagen/zeroclaw` a tato doména/repozitář se vydávají za naši oficiální stránku/projekt. | Nedůvěřujte informacím, binárním souborům, sbírkám ani oznámením z těchto zdrojů. Používejte pouze [toto repozitárium](https://github.com/zeroclaw-labs/zeroclaw) a naše ověřené sociální účty. |
|
||||
| 2026-02-21 | _Důležité_ | Naše oficiální webové stránky jsou nyní aktivní: [zeroclawlabs.ai](https://zeroclawlabs.ai). Děkujeme za trpělivost při přípravě spuštění. Stále vidíme pokusy o vydávání se za nás, takže se **ne**připojujte k žádným investicím nebo sbírkám pod jménem ZeroClaw, pokud nebyly zveřejněny prostřednictvím našich oficiálních kanálů. | Používejte [toto repozitárium](https://github.com/zeroclaw-labs/zeroclaw) jako jediný zdroj pravdy. Sledujte [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Skupina)](https://www.facebook.com/groups/zeroclawlabs) a [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) pro oficiální aktualizace. |
|
||||
| 2026-02-19 | _Důležité_ | Anthropic aktualizoval podmínky autentizace a použití přihlašovacích údajů 2026-02-19. OAuth tokeny Claude Code (Free, Pro, Max) jsou určeny výhradně pro Claude Code a Claude.ai; používání OAuth tokenů z Claude Free/Pro/Max v jakémkoli jiném produktu, nástroji nebo službě (včetně Agent SDK) není povoleno a může porušovat Podmínky služby. | Prosím dočasně se vyhněte integracím Claude Code OAuth, abyste předešli potenciálním ztrátám. Původní klauzule: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Hlavní rysy
|
||||
|
||||
- **Lehké běhové prostředí ve výchozím stavu** — běžné CLI a statusové workflow běží v obálce paměti několika megabajtů na release buildech.
|
||||
- **Nákladově efektivní nasazení** — navrženo pro desky za $10 a malé cloudové instance, žádné těžké runtime závislosti.
|
||||
- **Rychlé studené starty** — jednobinární Rust runtime udržuje start příkazů a démona téměř okamžitý.
|
||||
- **Přenosná architektura** — jeden binární soubor pro ARM, x86 a RISC-V s vyměnitelnými poskytovateli/kanály/nástroji.
|
||||
- **Lokální gateway** — jednotná řídicí rovina pro relace, kanály, nástroje, cron, SOP a události.
|
||||
- **Vícekanálová schránka** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket a další.
|
||||
- **Orchestrace více agentů (Hands)** — autonomní roje agentů, které běží podle plánu a časem se stávají chytřejšími.
|
||||
- **Standardní operační postupy (SOP)** — automatizace workflow řízená událostmi s triggery MQTT, webhook, cron a periferiemi.
|
||||
- **Webový panel** — rozhraní React 19 + Vite s chatem v reálném čase, prohlížečem paměti, editorem konfigurace, správcem cron a inspektorem nástrojů.
|
||||
- **Hardwarové periferie** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO přes trait `Peripheral`.
|
||||
- **Prvotřídní nástroje** — shell, souborové I/O, prohlížeč, git, web fetch/search, MCP, Jira, Notion, Google Workspace a 70+ dalších.
|
||||
- **Lifecycle hooky** — zachytávejte a upravujte volání LLM, spouštění nástrojů a zprávy v každé fázi.
|
||||
- **Platforma dovedností** — vestavěné, komunitní a workspace dovednosti s bezpečnostním auditem.
|
||||
- **Podpora tunelů** — Cloudflare, Tailscale, ngrok, OpenVPN a vlastní tunely pro vzdálený přístup.
|
||||
|
||||
### Proč týmy volí ZeroClaw
|
||||
|
||||
- **Lehký ve výchozím stavu:** malý Rust binární soubor, rychlý start, nízká paměťová stopa.
|
||||
- **Bezpečný od návrhu:** párování, přísný sandboxing, explicitní allowlisty, izolace workspace.
|
||||
- **Plně vyměnitelný:** základní systémy jsou traity (poskytovatelé, kanály, nástroje, paměť, tunely).
|
||||
- **Žádný vendor lock-in:** podpora poskytovatelů kompatibilních s OpenAI + připojitelné vlastní endpointy.
|
||||
|
||||
## Srovnání výkonu (ZeroClaw vs OpenClaw, reprodukovatelné)
|
||||
|
||||
Rychlý benchmark na lokálním stroji (macOS arm64, únor 2026) normalizovaný pro edge hardware 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Jazyk** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Start (jádro 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Velikost binárky** | ~28MB (dist) | N/A (Skripty) | ~8MB | **~8.8 MB** |
|
||||
| **Náklady** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Jakýkoli hardware $10** |
|
||||
|
||||
> Poznámky: Výsledky ZeroClaw jsou měřeny na release buildech pomocí `/usr/bin/time -l`. OpenClaw vyžaduje běhové prostředí Node.js (typicky ~390MB dodatečné paměťové režie), zatímco NanoBot vyžaduje běhové prostředí Python. PicoClaw a ZeroClaw jsou statické binárky. Výše uvedené hodnoty RAM jsou runtime paměť; požadavky kompilace jsou vyšší.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Reprodukovatelné lokální měření
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Vše, co jsme dosud vytvořili
|
||||
|
||||
### Základní platforma
|
||||
|
||||
- Gateway HTTP/WS/SSE řídicí rovina s relacemi, přítomností, konfigurací, cron, webhooky, webovým panelem a párováním.
|
||||
- CLI rozhraní: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Orchestrační smyčka agenta s dispatchem nástrojů, konstrukcí promptů, klasifikací zpráv a načítáním paměti.
|
||||
- Model relací s vynucováním bezpečnostní politiky, úrovněmi autonomie a schvalovacím gatováním.
|
||||
- Odolný wrapper poskytovatele s failoverem, opakováním a routingem modelů napříč 20+ LLM backendy.
|
||||
|
||||
### Kanály
|
||||
|
||||
Kanály: WhatsApp (nativní), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Za feature gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Webový panel
|
||||
|
||||
Webový panel React 19 + Vite 6 + Tailwind CSS 4 servírovaný přímo z Gateway:
|
||||
|
||||
- **Dashboard** — přehled systému, stav zdraví, uptime, sledování nákladů
|
||||
- **Chat s agentem** — interaktivní chat s agentem
|
||||
- **Paměť** — prohlížení a správa záznamů paměti
|
||||
- **Konfigurace** — zobrazení a úprava konfigurace
|
||||
- **Cron** — správa naplánovaných úloh
|
||||
- **Nástroje** — prohlížení dostupných nástrojů
|
||||
- **Logy** — zobrazení logů aktivity agenta
|
||||
- **Náklady** — využití tokenů a sledování nákladů
|
||||
- **Doctor** — diagnostika zdraví systému
|
||||
- **Integrace** — stav a nastavení integrací
|
||||
- **Párování** — správa párování zařízení
|
||||
|
||||
### Cíle firmwaru
|
||||
|
||||
| Cíl | Platforma | Účel |
|
||||
|-----|-----------|------|
|
||||
| ESP32 | Espressif ESP32 | Bezdrátový periferní agent |
|
||||
| ESP32-UI | ESP32 + Displej | Agent s vizuálním rozhraním |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Průmyslová periferie |
|
||||
| Arduino | Arduino | Základní můstek senzorů/aktuátorů |
|
||||
| Uno Q Bridge | Arduino Uno | Sériový můstek k agentovi |
|
||||
|
||||
### Nástroje + automatizace
|
||||
|
||||
- **Základní:** shell, čtení/zápis/editace souborů, operace git, glob vyhledávání, vyhledávání obsahu
|
||||
- **Web:** ovládání prohlížeče, web fetch, webové vyhledávání, snímek obrazovky, info o obrázku, čtení PDF
|
||||
- **Integrace:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** wrapper nástrojů Model Context Protocol + odložené sady nástrojů
|
||||
- **Plánování:** cron add/remove/update/run, nástroj plánování
|
||||
- **Paměť:** recall, store, forget, knowledge, project intel
|
||||
- **Pokročilé:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Hardware:** board info, memory map, memory read (za feature gate)
|
||||
|
||||
### Běhové prostředí + bezpečnost
|
||||
|
||||
- **Úrovně autonomie:** ReadOnly, Supervised (výchozí), Full.
|
||||
- **Sandboxing:** izolace workspace, blokování procházení cest, allowlisty příkazů, zakázané cesty, Landlock (Linux), Bubblewrap.
|
||||
- **Omezení rychlosti:** max akcí za hodinu, max nákladů za den (konfigurovatelné).
|
||||
- **Schvalovací gatování:** interaktivní schvalování operací se středním/vysokým rizikem.
|
||||
- **E-stop:** schopnost nouzového vypnutí.
|
||||
- **129+ bezpečnostních testů** v automatizovaném CI.
|
||||
|
||||
### Provoz + balíčkování
|
||||
|
||||
- Webový panel servírovaný přímo z Gateway.
|
||||
- Podpora tunelů: Cloudflare, Tailscale, ngrok, OpenVPN, vlastní příkaz.
|
||||
- Docker runtime adaptér pro kontejnerizované spouštění.
|
||||
- CI/CD: beta (auto na push) → stable (ruční dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Předpřipravené binárky pro Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfigurace
|
||||
|
||||
Minimální `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Kompletní reference konfigurace: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Konfigurace kanálů
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Konfigurace tunelu
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # nebo "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Podrobnosti: [Reference kanálů](docs/reference/api/channels-reference.md) · [Reference konfigurace](docs/reference/api/config-reference.md)
|
||||
|
||||
### Podpora runtime (aktuální)
|
||||
|
||||
- **`native`** (výchozí) — přímé spouštění procesů, nejrychlejší cesta, ideální pro důvěryhodná prostředí.
|
||||
- **`docker`** — plná kontejnerová izolace, vynucené bezpečnostní politiky, vyžaduje Docker.
|
||||
|
||||
Nastavte `runtime.kind = "docker"` pro přísný sandboxing nebo síťovou izolaci.
|
||||
|
||||
## Autentizace předplatného (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw podporuje nativní autorizační profily předplatného (více účtů, šifrování v klidu).
|
||||
|
||||
- Soubor úložiště: `~/.zeroclaw/auth-profiles.json`
|
||||
- Šifrovací klíč: `~/.zeroclaw/.secret_key`
|
||||
- Formát ID profilu: `<provider>:<profile_name>` (příklad: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (předplatné ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Kontrola / obnovení / přepnutí profilu
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Spuštění agenta s autentizací předplatného
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace agenta + dovednosti
|
||||
|
||||
Kořenový adresář workspace: `~/.zeroclaw/workspace/` (konfigurovatelné přes config).
|
||||
|
||||
Injektované soubory promptů:
|
||||
- `IDENTITY.md` — osobnost a role agenta
|
||||
- `USER.md` — kontext a preference uživatele
|
||||
- `MEMORY.md` — dlouhodobá fakta a poučení
|
||||
- `AGENTS.md` — konvence relací a inicializační pravidla
|
||||
- `SOUL.md` — základní identita a provozní principy
|
||||
|
||||
Dovednosti: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` nebo `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Seznam nainstalovaných dovedností
|
||||
zeroclaw skills list
|
||||
|
||||
# Instalace z git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Bezpečnostní audit před instalací
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Odebrání dovednosti
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI příkazy
|
||||
|
||||
```bash
|
||||
# Správa workspace
|
||||
zeroclaw onboard # Průvodce nastavením
|
||||
zeroclaw status # Zobrazení stavu démona/agenta
|
||||
zeroclaw doctor # Spuštění diagnostiky systému
|
||||
|
||||
# Gateway + démon
|
||||
zeroclaw gateway # Spuštění gateway serveru (127.0.0.1:42617)
|
||||
zeroclaw daemon # Spuštění plného autonomního runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interaktivní režim chatu
|
||||
zeroclaw agent -m "message" # Režim jedné zprávy
|
||||
|
||||
# Správa služeb
|
||||
zeroclaw service install # Instalace jako služba OS (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanály
|
||||
zeroclaw channel list # Seznam konfigurovaných kanálů
|
||||
zeroclaw channel doctor # Kontrola zdraví kanálů
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + plánování
|
||||
zeroclaw cron list # Seznam naplánovaných úloh
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Paměť
|
||||
zeroclaw memory list # Seznam záznamů paměti
|
||||
zeroclaw memory get <key> # Získání záznamu
|
||||
zeroclaw memory stats # Statistiky paměti
|
||||
|
||||
# Autorizační profily
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardwarové periferie
|
||||
zeroclaw hardware discover # Skenování připojených zařízení
|
||||
zeroclaw peripheral list # Seznam připojených periferií
|
||||
zeroclaw peripheral flash # Flash firmwaru na zařízení
|
||||
|
||||
# Migrace
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Doplňování shellu
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Kompletní reference příkazů: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Předpoklady
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Požadované
|
||||
|
||||
1. **Visual Studio Build Tools** (poskytuje MSVC linker a Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Během instalace (nebo přes Visual Studio Installer) vyberte workload **"Desktop development with C++"**.
|
||||
|
||||
2. **Toolchain Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Po instalaci otevřete nový terminál a spusťte `rustup default stable`, abyste zajistili aktivní stabilní toolchain.
|
||||
|
||||
3. **Ověřte**, že obojí funguje:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Volitelné
|
||||
|
||||
- **Docker Desktop** — požadován pouze při použití [Docker sandboxovaného runtime](#podpora-runtime-aktuální) (`runtime.kind = "docker"`). Instalace přes `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Požadované
|
||||
|
||||
1. **Nástroje pro sestavení:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Instalace Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Toolchain Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Viz [rustup.rs](https://rustup.rs) pro podrobnosti.
|
||||
|
||||
3. **Ověřte**, že obojí funguje:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Jednořádkový instalátor
|
||||
|
||||
Nebo přeskočte výše uvedené kroky a nainstalujte vše (systémové závislosti, Rust, ZeroClaw) jedním příkazem:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Požadavky na zdroje kompilace
|
||||
|
||||
Sestavení ze zdrojového kódu vyžaduje více zdrojů než spuštění výsledné binárky:
|
||||
|
||||
| Zdroj | Minimum | Doporučeno |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Volné místo** | 6 GB | 10 GB+ |
|
||||
|
||||
Pokud je váš host pod minimem, použijte předpřipravené binárky:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Pro vynucení instalace pouze z binárky bez fallbacku na zdrojový kód:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Volitelné
|
||||
|
||||
- **Docker** — požadován pouze při použití [Docker sandboxovaného runtime](#podpora-runtime-aktuální) (`runtime.kind = "docker"`). Instalace přes správce balíčků nebo [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Poznámka:** Výchozí `cargo build --release` používá `codegen-units=1` pro snížení špičkového zatížení kompilace. Pro rychlejší buildy na výkonných strojích použijte `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Předpřipravené binárky
|
||||
|
||||
Vydané assety jsou publikovány pro:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Stáhněte nejnovější assety z:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentace
|
||||
|
||||
Používejte tyto, když jste prošli onboardingem a chcete hlubší referenci.
|
||||
|
||||
- Začněte s [indexem dokumentace](docs/README.md) pro navigaci a „co je kde."
|
||||
- Přečtěte si [přehled architektury](docs/architecture.md) pro úplný model systému.
|
||||
- Použijte [referenci konfigurace](docs/reference/api/config-reference.md), když potřebujete každý klíč a příklad.
|
||||
- Provozujte Gateway podle [provozní příručky](docs/ops/operations-runbook.md).
|
||||
- Následujte [ZeroClaw Onboard](#rychlý-start) pro průvodce nastavením.
|
||||
- Odlaďte běžné chyby s [průvodcem řešením problémů](docs/ops/troubleshooting.md).
|
||||
- Projděte [bezpečnostní pokyny](docs/security/README.md) před vystavením čehokoli.
|
||||
|
||||
### Referenční dokumentace
|
||||
|
||||
- Centrum dokumentace: [docs/README.md](docs/README.md)
|
||||
- Ujednocený obsah: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Reference příkazů: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Reference konfigurace: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Reference poskytovatelů: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Reference kanálů: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Provozní příručka: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Řešení problémů: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Dokumentace spolupráce
|
||||
|
||||
- Průvodce přispíváním: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Politika PR workflow: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Průvodce CI workflow: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Příručka recenzenta: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Politika bezpečnostního zveřejnění: [SECURITY.md](SECURITY.md)
|
||||
- Šablona dokumentace: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Nasazení + provoz
|
||||
|
||||
- Průvodce síťovým nasazením: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Příručka proxy agenta: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hardwarové průvodce: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw byl vytvořen pro smooth crab 🦀, rychlého a efektivního AI asistenta. Vytvořil Argenis De La Rosa a komunita.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Podpořte ZeroClaw
|
||||
|
||||
Pokud vám ZeroClaw pomáhá v práci a chcete podpořit další vývoj, můžete přispět zde:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Speciální poděkování
|
||||
|
||||
Srdečné poděkování komunitám a institucím, které inspirují a pohánějí tuto open-source práci:
|
||||
|
||||
- **Harvard University** — za podporu intelektuální zvědavosti a posouvání hranic toho, co je možné.
|
||||
- **MIT** — za prosazování otevřených znalostí, open source a víry, že technologie by měla být dostupná všem.
|
||||
- **Sundai Club** — za komunitu, energii a neúnavný drive budovat věci, na kterých záleží.
|
||||
- **Svět a dále** 🌍✨ — každému přispěvateli, snílkovi a tvůrci, kteří dělají z open source sílu dobra. Toto je pro vás.
|
||||
|
||||
Stavíme otevřeně, protože nejlepší nápady přicházejí odevšad. Pokud toto čtete, jste toho součástí. Vítejte. 🦀❤️
|
||||
|
||||
## Přispívání
|
||||
|
||||
Jste v ZeroClaw noví? Hledejte issues označené [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — podívejte se na náš [Průvodce přispíváním](CONTRIBUTING.md#first-time-contributors), jak začít. AI/vibe-coded PR vítány! 🤖
|
||||
|
||||
Viz [CONTRIBUTING.md](CONTRIBUTING.md) a [CLA.md](docs/contributing/cla.md). Implementujte trait, odešlete PR:
|
||||
|
||||
- Průvodce CI workflow: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Nový `Provider` → `src/providers/`
|
||||
- Nový `Channel` → `src/channels/`
|
||||
- Nový `Observer` → `src/observability/`
|
||||
- Nový `Tool` → `src/tools/`
|
||||
- Nový `Memory` → `src/memory/`
|
||||
- Nový `Tunnel` → `src/tunnel/`
|
||||
- Nový `Peripheral` → `src/peripherals/`
|
||||
- Nový `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Oficiální repozitář a varování před podvržením identity
|
||||
|
||||
**Toto je jediný oficiální repozitář ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Jakýkoli jiný repozitář, organizace, doména nebo balíček tvrdící, že je „ZeroClaw" nebo naznačující spojení se ZeroClaw Labs je **neautorizovaný a není spojen s tímto projektem**. Známé neautorizované forky budou uvedeny v [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Pokud narazíte na podvržení identity nebo zneužití ochranné známky, prosím [otevřete issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licence
|
||||
|
||||
ZeroClaw je dvojitě licencován pro maximální otevřenost a ochranu přispěvatelů:
|
||||
|
||||
| Licence | Případ použití |
|
||||
|---------|---------------|
|
||||
| [MIT](LICENSE-MIT) | Open-source, výzkum, akademie, osobní použití |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patentová ochrana, institucionální, komerční nasazení |
|
||||
|
||||
Můžete si vybrat kteroukoli licenci. **Přispěvatelé automaticky udělují práva pod oběma** — viz [CLA.md](docs/contributing/cla.md) pro úplnou dohodu přispěvatele.
|
||||
|
||||
### Ochranná známka
|
||||
|
||||
Název **ZeroClaw** a logo jsou ochranné známky ZeroClaw Labs. Tato licence neuděluje povolení k jejich použití pro naznačení podpory nebo spojení. Viz [TRADEMARK.md](docs/maintainers/trademark.md) pro povolená a zakázaná použití.
|
||||
|
||||
### Ochrana přispěvatelů
|
||||
|
||||
- **Zachováváte si autorská práva** ke svým příspěvkům
|
||||
- **Udělení patentu** (Apache 2.0) vás chrání před patentovými nároky jiných přispěvatelů
|
||||
- Vaše příspěvky jsou **trvale připsány** v historii commitů a [NOTICE](NOTICE)
|
||||
- Přispíváním se nepřevádějí žádná práva k ochranné známce
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nulová režie. Nulový kompromis. Nasaďte kdekoli. Vyměňte cokoli. 🦀
|
||||
|
||||
## Přispěvatelé
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Tento seznam je generován z grafu přispěvatelů GitHub a aktualizuje se automaticky.
|
||||
|
||||
## Historie hvězd
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.da.md
755
README.da.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Personlig AI-assistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nul overhead. Nul kompromis. 100% Rust. 100% Agnostisk.</strong><br>
|
||||
⚡️ <strong>Korer pa $10 hardware med <5MB RAM: Det er 99% mindre hukommelse end OpenClaw og 98% billigere end en Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Bygget af studerende og medlemmer af Harvard-, MIT- og Sundai.Club-faellesskaberne.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Sprog:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw er en personlig AI-assistent, du korer pa dine egne enheder. Den svarer dig pa de kanaler, du allerede bruger (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work og flere). Den har et web-dashboard til realtidsstyring og kan forbindes til hardware-periferier (ESP32, STM32, Arduino, Raspberry Pi). Gateway'en er blot kontrolplanet — produktet er assistenten.
|
||||
|
||||
Hvis du vil have en personlig, enkeltbruger-assistent der foeles lokal, hurtig og altid taendt, er dette den.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Hjemmeside</a> ·
|
||||
<a href="docs/README.md">Dokumentation</a> ·
|
||||
<a href="docs/architecture.md">Arkitektur</a> ·
|
||||
<a href="#hurtig-start-tldr">Kom i gang</a> ·
|
||||
<a href="#migrering-fra-openclaw">Migrering fra OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Fejlsoegning</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Anbefalet opsaetning:** kor `zeroclaw onboard` i din terminal. ZeroClaw Onboard guider dig trin for trin gennem opsaetning af gateway, arbejdsomrade, kanaler og udbyder. Det er den anbefalede opsaetningssti og virker pa macOS, Linux og Windows (via WSL2). Ny installation? Start her: [Kom i gang](#hurtig-start-tldr)
|
||||
|
||||
### Abonnementsgodkendelse (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-abonnement)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-noegle eller godkendelsestoken)
|
||||
|
||||
Modelnotat: selvom mange udbydere/modeller understoettes, brug den staerkeste nyeste-generations model tilgaengelig for dig for den bedste oplevelse. Se [Onboarding](#hurtig-start-tldr).
|
||||
|
||||
Modelkonfiguration + CLI: [Udbyderreference](docs/reference/api/providers-reference.md)
|
||||
Auth-profilrotation (OAuth vs API-noegler) + failover: [Model-failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installation (anbefalet)
|
||||
|
||||
Koerselsmiljoe: Rust stable toolchain. Enkelt binaer, ingen koerselsmiljoafhaengigheder.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Et-klik-installation
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` koerer automatisk efter installation for at konfigurere dit arbejdsomrade og din udbyder.
|
||||
|
||||
## Hurtig start (TL;DR)
|
||||
|
||||
Fuld begynderguide (godkendelse, parring, kanaler): [Kom i gang](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installation + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start gateway'en (webhook-server + web-dashboard)
|
||||
zeroclaw gateway # standard: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # tilfaeldig port (sikkerhedshaerdet)
|
||||
|
||||
# Tal med assistenten
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktiv tilstand
|
||||
zeroclaw agent
|
||||
|
||||
# Start fuld autonom koersel (gateway + kanaler + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Tjek status
|
||||
zeroclaw status
|
||||
|
||||
# Koer diagnostik
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Opgradering? Koer `zeroclaw doctor` efter opdatering.
|
||||
|
||||
### Fra kildekode (udvikling)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Udviklingsfallback (ingen global installation):** praefikser kommandoer med `cargo run --release --` (eksempel: `cargo run --release -- status`).
|
||||
|
||||
## Migrering fra OpenClaw
|
||||
|
||||
ZeroClaw kan importere dit OpenClaw-arbejdsomrade, hukommelse og konfiguration:
|
||||
|
||||
```bash
|
||||
# Forhaandsvisning af hvad der vil blive migreret (sikkert, skrivebeskyttet)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Koer migreringen
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Dette migrerer dine hukommelsesposter, arbejdsomradefiler og konfiguration fra `~/.openclaw/` til `~/.zeroclaw/`. Konfiguration konverteres automatisk fra JSON til TOML.
|
||||
|
||||
## Sikkerhedsstandarder (DM-adgang)
|
||||
|
||||
ZeroClaw forbinder til rigtige beskedplatforme. Behandl indgaaende DM'er som utrovaerdigt input.
|
||||
|
||||
Fuld sikkerhedsguide: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Standardadfaerd pa alle kanaler:
|
||||
|
||||
- **DM-parring** (standard): ukendte afsendere modtager en kort parringskode, og botten behandler ikke deres besked.
|
||||
- Godkend med: `zeroclaw pairing approve <channel> <code>` (derefter tilfojes afsenderen til en lokal godkendelsesliste).
|
||||
- Offentlige indgaaende DM'er kraever et eksplicit opt-in i `config.toml`.
|
||||
- Koer `zeroclaw doctor` for at afsloere risikable eller forkert konfigurerede DM-politikker.
|
||||
|
||||
**Autonominiveauer:**
|
||||
|
||||
| Niveau | Adfaerd |
|
||||
|--------|---------|
|
||||
| `ReadOnly` | Agenten kan observere men ikke handle |
|
||||
| `Supervised` (standard) | Agenten handler med godkendelse for mellem/hoej risiko-operationer |
|
||||
| `Full` | Agenten handler autonomt inden for politikgraenser |
|
||||
|
||||
**Sandboxing-lag:** arbejdsomradeisolering, sti-traverseringsblokering, kommandogodkendelseslister, forbudte stier (`/etc`, `/root`, `~/.ssh`), hastighedsbegraensning (maks handlinger/time, omkostninger/dag-lofter).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Meddelelser
|
||||
|
||||
Brug dette board til vigtige meddelelser (aendringsbrydende aendringer, sikkerhedsraadgivning, vedligeholdelsesperioder og udgivelsesblokkeringer).
|
||||
|
||||
| Dato (UTC) | Niveau | Meddelelse | Handling |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritisk_ | Vi er **ikke tilknyttet** `openagen/zeroclaw`, `zeroclaw.org` eller `zeroclaw.net`. Domaenerne `zeroclaw.org` og `zeroclaw.net` peger i oejeblikket pa `openagen/zeroclaw`-forken, og det domaene/repository udgiver sig for at vaere vores officielle hjemmeside/projekt. | Stol ikke pa information, binaerfiler, fundraising eller meddelelser fra disse kilder. Brug kun [dette repository](https://github.com/zeroclaw-labs/zeroclaw) og vores verificerede sociale konti. |
|
||||
| 2026-02-21 | _Vigtigt_ | Vores officielle hjemmeside er nu live: [zeroclawlabs.ai](https://zeroclawlabs.ai). Tak for din talmodighed, mens vi forberedte lanceringen. Vi ser stadig identitetstyveriforsoeg, sa **tilslut dig ikke** nogen investerings- eller fundraisingaktivitet, der haevder ZeroClaw-navnet, medmindre det er offentliggjort via vores officielle kanaler. | Brug [dette repository](https://github.com/zeroclaw-labs/zeroclaw) som den eneste kilde til sandhed. Foelg [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) og [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) for officielle opdateringer. |
|
||||
| 2026-02-19 | _Vigtigt_ | Anthropic opdaterede vilkaarene for Godkendelse og Legitimationsoplysningsbrug den 2026-02-19. Claude Code OAuth-tokens (Free, Pro, Max) er udelukkende beregnet til Claude Code og Claude.ai; brug af OAuth-tokens fra Claude Free/Pro/Max i ethvert andet produkt, vaerktoej eller tjeneste (inklusive Agent SDK) er ikke tilladt og kan overtraede forbrugervilkaarene. | Undga venligst midlertidigt Claude Code OAuth-integrationer for at forebygge potentielt tab. Original klausul: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Hoejdepunkter
|
||||
|
||||
- **Let koerselsmiljoe som standard** — almindelige CLI- og statusarbejdsgange koerer i et hukommelsesfodaftryk pa faa megabytes i release-builds.
|
||||
- **Omkostningseffektiv udrulning** — designet til $10-kort og smaa cloud-instanser, ingen tunge koerselsmiljoafhaengigheder.
|
||||
- **Hurtige koldstarter** — enkelt-binaer Rust-koerselsmiljoe holder kommando- og daemon-opstart naesten oejeblikkelig.
|
||||
- **Portabel arkitektur** — en binaer pa tvaers af ARM, x86 og RISC-V med udskiftelige udbydere/kanaler/vaerktoejer.
|
||||
- **Lokalt-foerst Gateway** — enkelt kontrolplan for sessioner, kanaler, vaerktoejer, cron, SOPs og haendelser.
|
||||
- **Multikanal-indbakke** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket og flere.
|
||||
- **Multi-agent-orkestrering (Hands)** — autonome agentsvaerme, der koerer efter tidsplan og bliver klogere over tid.
|
||||
- **Standardoperationsprocedurer (SOPs)** — haendelsesdrevet workflowautomatisering med MQTT, webhook, cron og periferitriggere.
|
||||
- **Web-dashboard** — React 19 + Vite web-UI med realtidschat, hukommelsesbrowser, konfigurationseditor, cron-manager og vaerktoejsinspektoer.
|
||||
- **Hardware-periferier** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via `Peripheral`-trait'et.
|
||||
- **Foersteklasses vaerktoejer** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace og 70+ flere.
|
||||
- **Livscyklushooks** — opfang og modificer LLM-kald, vaerktoejsudfoerelser og beskeder pa hvert trin.
|
||||
- **Faerdighedsplatform** — medfoelgende, faellesskabs- og arbejdsomraadefaerdigheder med sikkerhedsauditering.
|
||||
- **Tunnelsupport** — Cloudflare, Tailscale, ngrok, OpenVPN og brugerdefinerede tunneler til fjernadgang.
|
||||
|
||||
### Hvorfor hold vaelger ZeroClaw
|
||||
|
||||
- **Let som standard:** lille Rust-binaer, hurtig opstart, lavt hukommelsesfodaftryk.
|
||||
- **Sikkert fra design:** parring, streng sandboxing, eksplicitte godkendelseslister, arbejdsomradeafgraensning.
|
||||
- **Fuldt udskifteligt:** kernesystemer er traits (providers, channels, tools, memory, tunnels).
|
||||
- **Ingen laasning:** OpenAI-kompatibel udbydersupport + tilslutbare brugerdefinerede endepunkter.
|
||||
|
||||
## Benchmark-overblik (ZeroClaw vs OpenClaw, Reproducerbart)
|
||||
|
||||
Lokal maskinens hurtige benchmark (macOS arm64, feb. 2026) normaliseret for 0.8GHz edge-hardware.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Sprog** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Opstart (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binaerstaerrelse** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Omkostning** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Enhver hardware $10** |
|
||||
|
||||
> Notat: ZeroClaw-resultater er maalt pa release-builds ved brug af `/usr/bin/time -l`. OpenClaw kraever Node.js-koerselsmiljoe (typisk ~390MB ekstra hukommelsesoverhead), mens NanoBot kraever Python-koerselsmiljoe. PicoClaw og ZeroClaw er statiske binaerer. RAM-tallene ovenfor er koerselstidshukommelse; kompileringstidskrav er hoejere.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Reproducerbar lokal maaling
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Alt vi har bygget indtil nu
|
||||
|
||||
### Kerneplatform
|
||||
|
||||
- Gateway HTTP/WS/SSE-kontrolplan med sessioner, tilstedevaerelse, konfiguration, cron, webhooks, web-dashboard og parring.
|
||||
- CLI-overflade: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agent-orkestreringsloekke med vaerktoejsafsendelse, prompt-konstruktion, beskedklassificering og hukommelsesindlaesning.
|
||||
- Sessionsmodel med sikkerhedspolitikhaandhaeveelse, autonominiveauer og godkendelsesportering.
|
||||
- Robust udbyderindpakning med failover, genforsoeg og modelrutering pa tvaers af 20+ LLM-backends.
|
||||
|
||||
### Kanaler
|
||||
|
||||
Kanaler: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Web-dashboard
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 web-dashboard serveret direkte fra Gateway'en:
|
||||
|
||||
- **Dashboard** — systemoversigt, sundhedsstatus, oppetid, omkostningsovervaagning
|
||||
- **Agent Chat** — interaktiv chat med agenten
|
||||
- **Memory** — gennemse og administrer hukommelsesposter
|
||||
- **Config** — vis og rediger konfiguration
|
||||
- **Cron** — administrer planlagte opgaver
|
||||
- **Tools** — gennemse tilgaengelige vaerktoejer
|
||||
- **Logs** — vis agentaktivitetslogge
|
||||
- **Cost** — tokenforbrug og omkostningsovervaagning
|
||||
- **Doctor** — systemsundhedsdiagnostik
|
||||
- **Integrations** — integrationsstatus og opsaetning
|
||||
- **Pairing** — enhedsparringsstyring
|
||||
|
||||
### Firmware-maal
|
||||
|
||||
| Maal | Platform | Formaal |
|
||||
|------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | Tradloes periferiagent |
|
||||
| ESP32-UI | ESP32 + Display | Agent med visuel graenseflade |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Industriel periferi |
|
||||
| Arduino | Arduino | Basis sensor-/aktuatorbro |
|
||||
| Uno Q Bridge | Arduino Uno | Seriel bro til agent |
|
||||
|
||||
### Vaerktoejer + automatisering
|
||||
|
||||
- **Kerne:** shell, file read/write/edit, git operations, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Integrationer:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Planlaegning:** cron add/remove/update/run, schedule tool
|
||||
- **Hukommelse:** recall, store, forget, knowledge, project intel
|
||||
- **Avanceret:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Hardware:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Koerselsmiljoe + sikkerhed
|
||||
|
||||
- **Autonominiveauer:** ReadOnly, Supervised (standard), Full.
|
||||
- **Sandboxing:** arbejdsomradeisolering, sti-traverseringsblokering, kommandogodkendelseslister, forbudte stier, Landlock (Linux), Bubblewrap.
|
||||
- **Hastighedsbegraensning:** maks handlinger pr. time, maks omkostninger pr. dag (konfigurerbart).
|
||||
- **Godkendelsesportering:** interaktiv godkendelse for mellem/hoej risiko-operationer.
|
||||
- **E-stop:** noedstopkapabilitet.
|
||||
- **129+ sikkerhedstests** i automatiseret CI.
|
||||
|
||||
### Drift + pakning
|
||||
|
||||
- Web-dashboard serveret direkte fra Gateway'en.
|
||||
- Tunnelsupport: Cloudflare, Tailscale, ngrok, OpenVPN, brugerdefineret kommando.
|
||||
- Docker-koerselsmiljoetilpasning til containeriseret udfoersel.
|
||||
- CI/CD: beta (auto on push) → stable (manual dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Forhaandsbyggede binaerer til Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfiguration
|
||||
|
||||
Minimal `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Fuld konfigurationsreference: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanalkonfiguration
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnelkonfiguration
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detaljer: [Kanalreference](docs/reference/api/channels-reference.md) · [Konfigurationsreference](docs/reference/api/config-reference.md)
|
||||
|
||||
### Koerselsmiljoestoette (aktuel)
|
||||
|
||||
- **`native`** (standard) — direkte procesudfoersel, hurtigste sti, ideel til betroede miljoeer.
|
||||
- **`docker`** — fuld containerisolering, haandhaevede sikkerhedspolitikker, kraever Docker.
|
||||
|
||||
Saet `runtime.kind = "docker"` for streng sandboxing eller netvaerksisolering.
|
||||
|
||||
## Abonnementsgodkendelse (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw understoetter abonnements-native godkendelsesprofiler (flere konti, krypteret i hvile).
|
||||
|
||||
- Lagerfil: `~/.zeroclaw/auth-profiles.json`
|
||||
- Krypteringsnoegle: `~/.zeroclaw/.secret_key`
|
||||
- Profil-id-format: `<provider>:<profile_name>` (eksempel: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agent-arbejdsomrade + faerdigheder
|
||||
|
||||
Arbejdsomraderod: `~/.zeroclaw/workspace/` (konfigurerbart via config).
|
||||
|
||||
Injicerede promptfiler:
|
||||
- `IDENTITY.md` — agentens personlighed og rolle
|
||||
- `USER.md` — brugerkontekst og praeferencer
|
||||
- `MEMORY.md` — langsigtede fakta og laerdommer
|
||||
- `AGENTS.md` — sessionskonventioner og initialiseringsregler
|
||||
- `SOUL.md` — kerneidentitet og driftsprincipper
|
||||
|
||||
Faerdigheder: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` eller `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-kommandoer
|
||||
|
||||
```bash
|
||||
# Arbejdsomraadestyring
|
||||
zeroclaw onboard # Guidet opsaetningsguide
|
||||
zeroclaw status # Vis daemon/agent-status
|
||||
zeroclaw doctor # Koer systemdiagnostik
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway-server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start fuld autonom koersel
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interaktiv chattilstand
|
||||
zeroclaw agent -m "message" # Enkeltbeskedtilstand
|
||||
|
||||
# Servicestyring
|
||||
zeroclaw service install # Installer som OS-service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanaler
|
||||
zeroclaw channel list # List konfigurerede kanaler
|
||||
zeroclaw channel doctor # Tjek kanalsundhed
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + planlaegning
|
||||
zeroclaw cron list # List planlagte opgaver
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Hukommelse
|
||||
zeroclaw memory list # List hukommelsesposter
|
||||
zeroclaw memory get <key> # Hent en hukommelse
|
||||
zeroclaw memory stats # Hukommelsesstatistik
|
||||
|
||||
# Godkendelsesprofiler
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware-periferier
|
||||
zeroclaw hardware discover # Skan efter tilsluttede enheder
|
||||
zeroclaw peripheral list # List tilsluttede periferier
|
||||
zeroclaw peripheral flash # Flash firmware til enhed
|
||||
|
||||
# Migrering
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-fuldfoerelser
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Fuld kommandoreference: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Forudsaetninger
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Paakraevet
|
||||
|
||||
1. **Visual Studio Build Tools** (giver MSVC-linker og Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Under installation (eller via Visual Studio Installer) vaelg workloaden **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Efter installation, aabn en ny terminal og koer `rustup default stable` for at sikre, at den stabile toolchain er aktiv.
|
||||
|
||||
3. **Verificer**, at begge virker:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Valgfrit
|
||||
|
||||
- **Docker Desktop** — paakraevet kun ved brug af [Docker sandboxed runtime](#koerselsmiljoestoette-aktuel) (`runtime.kind = "docker"`). Installer via `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Paakraevet
|
||||
|
||||
1. **Byggevaerktoejer:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Installer Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Se [rustup.rs](https://rustup.rs) for detaljer.
|
||||
|
||||
3. **Verificer**, at begge virker:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### En-linje-installationsprogram
|
||||
|
||||
Eller spring trinnene ovenfor over og installer alt (systemafhaengigheder, Rust, ZeroClaw) med en enkelt kommando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Kompileringsressourcekrav
|
||||
|
||||
Bygning fra kildekode kraever flere ressourcer end at koere den resulterende binaer:
|
||||
|
||||
| Ressource | Minimum | Anbefalet |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Ledig disk** | 6 GB | 10 GB+ |
|
||||
|
||||
Hvis din vaert er under minimum, brug forhaandsbyggede binaerer:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
For kun-binaer-installation uden kildekodefallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Valgfrit
|
||||
|
||||
- **Docker** — paakraevet kun ved brug af [Docker sandboxed runtime](#koerselsmiljoestoette-aktuel) (`runtime.kind = "docker"`). Installer via din pakkehaandtering eller [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Notat:** Standard `cargo build --release` bruger `codegen-units=1` for at reducere spidskompileringspresset. For hurtigere builds pa kraftige maskiner, brug `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Forhaandsbyggede binaerer
|
||||
|
||||
Udgivelsesaktiver udgives for:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Download de seneste aktiver fra:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Brug disse, naar du er forbi onboarding-flowet og vil have den dybere reference.
|
||||
|
||||
- Start med [dokumentationsindekset](docs/README.md) til navigation og "hvad er hvor."
|
||||
- Laes [arkitekturoversigten](docs/architecture.md) for den fulde systemmodel.
|
||||
- Brug [konfigurationsreferencen](docs/reference/api/config-reference.md), naar du har brug for hver noegle og eksempel.
|
||||
- Koer Gateway'en efter bogen med [driftsrunbooken](docs/ops/operations-runbook.md).
|
||||
- Foelg [ZeroClaw Onboard](#hurtig-start-tldr) for en guidet opsaetning.
|
||||
- Fejlsoeg almindelige fejl med [fejlsoegningsguiden](docs/ops/troubleshooting.md).
|
||||
- Gennemgaa [sikkerhedsvejledning](docs/security/README.md) foer du eksponerer noget.
|
||||
|
||||
### Referencedokumentation
|
||||
|
||||
- Dokumentationscentral: [docs/README.md](docs/README.md)
|
||||
- Samlet indholdsfortegnelse: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Kommandoreference: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Konfigurationsreference: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Udbyderreference: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanalreference: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Driftsrunbook: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Fejlsoegning: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Samarbejdsdokumentation
|
||||
|
||||
- Bidragsguide: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-arbejdsgangspolitik: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-arbejdsgangsguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Anmelderhaandbog: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Sikkerhedsoplysningspolitik: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentationsskabelon: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Udrulning + drift
|
||||
|
||||
- Netvaerksudrulningsguide: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-agent-haandbog: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hardwareguider: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw blev bygget til smooth crab 🦀, en hurtig og effektiv AI-assistent. Bygget af Argenis De La Rosa og faellesskabet.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Stoet ZeroClaw
|
||||
|
||||
Hvis ZeroClaw hjaelper dit arbejde, og du vil stoette den igangvaerende udvikling, kan du donere her:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Saerlig tak
|
||||
|
||||
En hjertelig tak til de faellesskaber og institutioner, der inspirerer og naerer dette open source-arbejde:
|
||||
|
||||
- **Harvard University** — for at fremme intellektuel nysgerrighed og skubbe graenserne for hvad der er muligt.
|
||||
- **MIT** — for at kaempe for aben viden, open source og troen pa, at teknologi skal vaere tilgaengelig for alle.
|
||||
- **Sundai Club** — for faellesskabet, energien og den utraettelige drift til at bygge ting, der betyder noget.
|
||||
- **Verden & Hinsides** 🌍✨ — til enhver bidragyder, droommer og bygger derude, der goer open source til en kraft for det gode. Dette er for dig.
|
||||
|
||||
Vi bygger i det aabne, fordi de bedste ideer kommer fra alle steder. Hvis du laeser dette, er du en del af det. Velkommen. 🦀❤️
|
||||
|
||||
## Bidrag
|
||||
|
||||
Ny til ZeroClaw? Kig efter issues maerket [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — se vores [Bidragsguide](CONTRIBUTING.md#first-time-contributors) for at komme i gang. AI/vibe-kodede PR'er velkomne! 🤖
|
||||
|
||||
Se [CONTRIBUTING.md](CONTRIBUTING.md) og [CLA.md](docs/contributing/cla.md). Implementer et trait, indsend en PR:
|
||||
|
||||
- CI-arbejdsgangsguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Ny `Provider` → `src/providers/`
|
||||
- Ny `Channel` → `src/channels/`
|
||||
- Ny `Observer` → `src/observability/`
|
||||
- Nyt `Tool` → `src/tools/`
|
||||
- Ny `Memory` → `src/memory/`
|
||||
- Ny `Tunnel` → `src/tunnel/`
|
||||
- Ny `Peripheral` → `src/peripherals/`
|
||||
- Ny `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Officielt repository og advarsel om identitetstyveri
|
||||
|
||||
**Dette er det eneste officielle ZeroClaw-repository:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Ethvert andet repository, organisation, domaene eller pakke, der haevder at vaere "ZeroClaw" eller antyder tilknytning til ZeroClaw Labs, er **uautoriseret og ikke tilknyttet dette projekt**. Kendte uautoriserede forks vil blive opfoert i [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Hvis du stoeder pa identitetstyveri eller varemaerkemisbrug, bedes du [aabne et issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licens
|
||||
|
||||
ZeroClaw er dobbeltlicenseret for maksimal aabenhed og bidragyderbeskyttelse:
|
||||
|
||||
| Licens | Anvendelse |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open source, forskning, akademisk, personligt brug |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patentbeskyttelse, institutionel, kommerciel udrulning |
|
||||
|
||||
Du kan vaelge enten licens. **Bidragydere giver automatisk rettigheder under begge** — se [CLA.md](docs/contributing/cla.md) for den fulde bidragsaftale.
|
||||
|
||||
### Varemaerke
|
||||
|
||||
Navnet **ZeroClaw** og logoet er varemaerker tilhoerende ZeroClaw Labs. Denne licens giver ikke tilladelse til at bruge dem til at antyde stoette eller tilknytning. Se [TRADEMARK.md](docs/maintainers/trademark.md) for tilladte og forbudte anvendelser.
|
||||
|
||||
### Bidragyderbeskyttelser
|
||||
|
||||
- Du **beholder ophavsretten** til dine bidrag
|
||||
- **Patentbevilling** (Apache 2.0) beskytter dig mod patentkrav fra andre bidragydere
|
||||
- Dine bidrag er **permanent attribueret** i commit-historik og [NOTICE](NOTICE)
|
||||
- Ingen varemaerkerettigheder overfoeres ved at bidrage
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nul overhead. Nul kompromis. Udrulning overalt. Udskift hvad som helst. 🦀
|
||||
|
||||
## Bidragydere
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Denne liste genereres fra GitHub-bidragydergrafiken og opdateres automatisk.
|
||||
|
||||
## Stjernehistorik
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.de.md
755
README.de.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Persönlicher KI-Assistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Null Overhead. Null Kompromisse. 100% Rust. 100% Agnostisch.</strong><br>
|
||||
⚡️ <strong>Läuft auf $10-Hardware mit <5MB RAM: 99% weniger Speicher als OpenClaw und 98% günstiger als ein Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Entwickelt von Studenten und Mitgliedern der Communitys von Harvard, MIT und Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Sprachen:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw ist ein persönlicher KI-Assistent, den du auf deinen eigenen Geräten ausführst. Er antwortet dir auf den Kanälen, die du bereits nutzt (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work und mehr). Er verfügt über ein Web-Dashboard für Echtzeitkontrolle und kann sich mit Hardware-Peripheriegeräten verbinden (ESP32, STM32, Arduino, Raspberry Pi). Das Gateway ist nur die Steuerungsebene — das Produkt ist der Assistent.
|
||||
|
||||
Wenn du einen persönlichen Einzelbenutzer-Assistenten willst, der sich lokal, schnell und immer verfügbar anfühlt, ist das genau das Richtige.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Website</a> ·
|
||||
<a href="docs/README.md">Dokumentation</a> ·
|
||||
<a href="docs/architecture.md">Architektur</a> ·
|
||||
<a href="#schnellstart">Erste Schritte</a> ·
|
||||
<a href="#migration-von-openclaw">Migration von OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Fehlerbehebung</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Empfohlene Einrichtung:** Führe `zeroclaw onboard` in deinem Terminal aus. ZeroClaw Onboard führt dich Schritt für Schritt durch die Einrichtung von Gateway, Workspace, Kanälen und Provider. Es ist der empfohlene Einrichtungspfad und funktioniert auf macOS, Linux und Windows (über WSL2). Neue Installation? Starte hier: [Erste Schritte](#schnellstart)
|
||||
|
||||
### Abonnement-Authentifizierung (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-Abonnement)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-Schlüssel oder Auth-Token)
|
||||
|
||||
Modellhinweis: Obwohl viele Provider/Modelle unterstützt werden, verwende für die beste Erfahrung das stärkste verfügbare Modell der neuesten Generation. Siehe [Onboarding](#schnellstart).
|
||||
|
||||
Modellkonfiguration + CLI: [Provider-Referenz](docs/reference/api/providers-reference.md)
|
||||
Auth-Profilrotation (OAuth vs API-Schlüssel) + Failover: [Modell-Failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installation (empfohlen)
|
||||
|
||||
Voraussetzung: Stabile Rust-Toolchain. Einzelnes Binary, keine Laufzeitabhängigkeiten.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Ein-Klick-Bootstrap
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` wird nach der Installation automatisch ausgeführt, um deinen Workspace und Provider zu konfigurieren.
|
||||
|
||||
## Schnellstart (TL;DR)
|
||||
|
||||
Vollständige Einsteiger-Anleitung (Authentifizierung, Pairing, Kanäle): [Erste Schritte](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installieren + Onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Gateway starten (Webhook-Server + Web-Dashboard)
|
||||
zeroclaw gateway # Standard: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # Zufälliger Port (gehärtete Sicherheit)
|
||||
|
||||
# Mit dem Assistenten sprechen
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktiver Modus
|
||||
zeroclaw agent
|
||||
|
||||
# Vollständige autonome Laufzeit starten (Gateway + Kanäle + Cron + Hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Status prüfen
|
||||
zeroclaw status
|
||||
|
||||
# Diagnose ausführen
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Aktualisierung? Führe `zeroclaw doctor` nach dem Update aus.
|
||||
|
||||
### Aus dem Quellcode (Entwicklung)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Entwicklungs-Fallback (ohne globale Installation):** Stelle Befehlen `cargo run --release --` voran (Beispiel: `cargo run --release -- status`).
|
||||
|
||||
## Migration von OpenClaw
|
||||
|
||||
ZeroClaw kann deinen OpenClaw-Workspace, Speicher und Konfiguration importieren:
|
||||
|
||||
```bash
|
||||
# Vorschau, was migriert wird (sicher, nur lesen)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Migration ausführen
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Dies migriert deine Speichereinträge, Workspace-Dateien und Konfiguration von `~/.openclaw/` nach `~/.zeroclaw/`. Die Konfiguration wird automatisch von JSON nach TOML konvertiert.
|
||||
|
||||
## Sicherheitsstandards (DM-Zugriff)
|
||||
|
||||
ZeroClaw verbindet sich mit echten Messaging-Oberflächen. Behandle eingehende DMs als nicht vertrauenswürdige Eingabe.
|
||||
|
||||
Vollständiger Sicherheitsleitfaden: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Standardverhalten auf allen Kanälen:
|
||||
|
||||
- **DM-Pairing** (Standard): Unbekannte Absender erhalten einen kurzen Pairing-Code und der Bot verarbeitet ihre Nachricht nicht.
|
||||
- Genehmige mit: `zeroclaw pairing approve <channel> <code>` (der Absender wird dann zu einer lokalen Allowlist hinzugefügt).
|
||||
- Öffentliche eingehende DMs erfordern eine explizite Aktivierung in `config.toml`.
|
||||
- Führe `zeroclaw doctor` aus, um riskante oder falsch konfigurierte DM-Richtlinien aufzudecken.
|
||||
|
||||
**Autonomiestufen:**
|
||||
|
||||
| Stufe | Verhalten |
|
||||
|-------|-----------|
|
||||
| `ReadOnly` | Der Agent kann beobachten, aber nicht handeln |
|
||||
| `Supervised` (Standard) | Der Agent handelt mit Genehmigung für Operationen mit mittlerem/hohem Risiko |
|
||||
| `Full` | Der Agent handelt autonom innerhalb der Richtliniengrenzen |
|
||||
|
||||
**Sandboxing-Schichten:** Workspace-Isolation, Pfad-Traversal-Blockierung, Befehls-Allowlisting, verbotene Pfade (`/etc`, `/root`, `~/.ssh`), Ratenbegrenzung (max. Aktionen/Stunde, Kosten/Tag-Obergrenzen).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Ankündigungen
|
||||
|
||||
Verwende dieses Board für wichtige Hinweise (Breaking Changes, Sicherheitshinweise, Wartungsfenster und Release-Blocker).
|
||||
|
||||
| Datum (UTC) | Stufe | Hinweis | Aktion |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritisch_ | Wir sind **nicht verbunden** mit `openagen/zeroclaw`, `zeroclaw.org` oder `zeroclaw.net`. Die Domains `zeroclaw.org` und `zeroclaw.net` verweisen derzeit auf den Fork `openagen/zeroclaw`, und diese Domain/dieses Repository geben sich als unsere offizielle Website/unser offizielles Projekt aus. | Vertraue keinen Informationen, Binaries, Spendenaktionen oder Ankündigungen aus diesen Quellen. Verwende nur [dieses Repository](https://github.com/zeroclaw-labs/zeroclaw) und unsere verifizierten Social-Media-Konten. |
|
||||
| 2026-02-21 | _Wichtig_ | Unsere offizielle Website ist jetzt online: [zeroclawlabs.ai](https://zeroclawlabs.ai). Danke für deine Geduld während wir den Launch vorbereitet haben. Wir sehen weiterhin Identitätsdiebstahlversuche, also nimm **nicht** an Investitions- oder Spendenaktivitäten teil, die den Namen ZeroClaw verwenden, es sei denn, sie werden über unsere offiziellen Kanäle veröffentlicht. | Verwende [dieses Repository](https://github.com/zeroclaw-labs/zeroclaw) als einzige Wahrheitsquelle. Folge [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Gruppe)](https://www.facebook.com/groups/zeroclawlabs) und [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) für offizielle Updates. |
|
||||
| 2026-02-19 | _Wichtig_ | Anthropic hat die Bedingungen zur Authentifizierung und Nutzung von Zugangsdaten am 2026-02-19 aktualisiert. Claude Code OAuth-Tokens (Free, Pro, Max) sind ausschließlich für Claude Code und Claude.ai bestimmt; die Verwendung von OAuth-Tokens von Claude Free/Pro/Max in anderen Produkten, Tools oder Diensten (einschließlich Agent SDK) ist nicht gestattet und kann gegen die Verbrauchernutzungsbedingungen verstoßen. | Bitte vermeide vorübergehend Claude Code OAuth-Integrationen, um potenzielle Verluste zu vermeiden. Originalklausel: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Highlights
|
||||
|
||||
- **Leichte Laufzeitumgebung standardmäßig** — gängige CLI- und Status-Workflows laufen in einem Speicherumfang von wenigen Megabyte bei Release-Builds.
|
||||
- **Kosteneffiziente Bereitstellung** — entwickelt für $10-Boards und kleine Cloud-Instanzen, keine schwergewichtigen Laufzeitabhängigkeiten.
|
||||
- **Schnelle Kaltstarts** — die Rust-Single-Binary-Laufzeit hält den Start von Befehlen und Daemon nahezu sofortig.
|
||||
- **Portable Architektur** — ein Binary für ARM, x86 und RISC-V mit austauschbaren Providern/Kanälen/Tools.
|
||||
- **Local-first Gateway** — einzelne Steuerungsebene für Sitzungen, Kanäle, Tools, Cron, SOPs und Events.
|
||||
- **Multi-Kanal-Posteingang** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket und mehr.
|
||||
- **Multi-Agenten-Orchestrierung (Hands)** — autonome Agentenschwärme, die nach Zeitplan laufen und mit der Zeit intelligenter werden.
|
||||
- **Standardbetriebsverfahren (SOPs)** — ereignisgesteuerte Workflow-Automatisierung mit MQTT, Webhook, Cron und Peripherie-Triggern.
|
||||
- **Web-Dashboard** — React 19 + Vite Web-UI mit Echtzeit-Chat, Speicher-Browser, Konfigurationseditor, Cron-Manager und Tool-Inspektor.
|
||||
- **Hardware-Peripheriegeräte** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO über den `Peripheral`-Trait.
|
||||
- **Erstklassige Tools** — Shell, Datei-I/O, Browser, Git, Web Fetch/Search, MCP, Jira, Notion, Google Workspace und über 70 weitere.
|
||||
- **Lifecycle-Hooks** — LLM-Aufrufe, Tool-Ausführungen und Nachrichten in jeder Phase abfangen und modifizieren.
|
||||
- **Skills-Plattform** — mitgelieferte, Community- und Workspace-Skills mit Sicherheitsaudit.
|
||||
- **Tunnel-Unterstützung** — Cloudflare, Tailscale, ngrok, OpenVPN und benutzerdefinierte Tunnel für Remote-Zugriff.
|
||||
|
||||
### Warum Teams ZeroClaw wählen
|
||||
|
||||
- **Standardmäßig leicht:** kleines Rust-Binary, schneller Start, geringer Speicherverbrauch.
|
||||
- **Sicher by Design:** Pairing, striktes Sandboxing, explizite Allowlists, Workspace-Scoping.
|
||||
- **Vollständig austauschbar:** Kernsysteme sind Traits (Provider, Kanäle, Tools, Speicher, Tunnel).
|
||||
- **Kein Vendor Lock-in:** OpenAI-kompatible Provider-Unterstützung + steckbare benutzerdefinierte Endpunkte.
|
||||
|
||||
## Benchmark-Übersicht (ZeroClaw vs OpenClaw, reproduzierbar)
|
||||
|
||||
Schneller lokaler Benchmark (macOS arm64, Feb 2026), normalisiert für 0,8GHz Edge-Hardware.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Sprache** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Start (0,8GHz Core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binary-Größe** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Kosten** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Beliebige Hardware $10** |
|
||||
|
||||
> Hinweise: ZeroClaw-Ergebnisse werden bei Release-Builds mit `/usr/bin/time -l` gemessen. OpenClaw benötigt die Node.js-Laufzeit (typischerweise ~390MB zusätzlicher Speicherverbrauch), während NanoBot die Python-Laufzeit benötigt. PicoClaw und ZeroClaw sind statische Binaries. Die RAM-Zahlen oben sind Laufzeitspeicher; die Kompilierungsanforderungen sind höher.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Reproduzierbare lokale Messung
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Alles, was wir bisher gebaut haben
|
||||
|
||||
### Kernplattform
|
||||
|
||||
- Gateway HTTP/WS/SSE-Steuerungsebene mit Sitzungen, Präsenz, Konfiguration, Cron, Webhooks, Web-Dashboard und Pairing.
|
||||
- CLI-Oberfläche: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agenten-Orchestrierungsschleife mit Tool-Dispatch, Prompt-Konstruktion, Nachrichtenklassifizierung und Speicherladung.
|
||||
- Sitzungsmodell mit Durchsetzung von Sicherheitsrichtlinien, Autonomiestufen und Genehmigungsgating.
|
||||
- Resiliente Provider-Wrapper mit Failover, Retry und Modell-Routing über 20+ LLM-Backends.
|
||||
|
||||
### Kanäle
|
||||
|
||||
Kanäle: WhatsApp (nativ), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Web-Dashboard
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 Web-Dashboard, direkt vom Gateway bereitgestellt:
|
||||
|
||||
- **Dashboard** — Systemübersicht, Gesundheitsstatus, Betriebszeit, Kostenverfolgung
|
||||
- **Agenten-Chat** — interaktiver Chat mit dem Agenten
|
||||
- **Speicher** — Speichereinträge durchsuchen und verwalten
|
||||
- **Konfiguration** — Konfiguration anzeigen und bearbeiten
|
||||
- **Cron** — geplante Aufgaben verwalten
|
||||
- **Tools** — verfügbare Tools durchsuchen
|
||||
- **Logs** — Aktivitätsprotokolle des Agenten anzeigen
|
||||
- **Kosten** — Token-Nutzung und Kostenverfolgung
|
||||
- **Doctor** — Systemdiagnose
|
||||
- **Integrationen** — Integrationsstatus und Einrichtung
|
||||
- **Pairing** — Gerätekopplung verwalten
|
||||
|
||||
### Firmware-Ziele
|
||||
|
||||
| Ziel | Plattform | Zweck |
|
||||
|------|-----------|-------|
|
||||
| ESP32 | Espressif ESP32 | Drahtloser Peripherie-Agent |
|
||||
| ESP32-UI | ESP32 + Display | Agent mit visueller Oberfläche |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Industrielle Peripherie |
|
||||
| Arduino | Arduino | Grundlegende Sensor-/Aktor-Brücke |
|
||||
| Uno Q Bridge | Arduino Uno | Serielle Brücke zum Agenten |
|
||||
|
||||
### Tools + Automatisierung
|
||||
|
||||
- **Core:** Shell, Datei lesen/schreiben/bearbeiten, Git-Operationen, Glob-Suche, Inhaltssuche
|
||||
- **Web:** Browser-Steuerung, Web Fetch, Web Search, Screenshot, Bildinformation, PDF-Lesen
|
||||
- **Integrationen:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol Tool-Wrapper + verzögerte Tool-Sets
|
||||
- **Planung:** cron add/remove/update/run, Planungstool
|
||||
- **Speicher:** recall, store, forget, knowledge, project intel
|
||||
- **Erweitert:** delegate (Agent-zu-Agent), swarm, Modellwechsel/-routing, Sicherheitsoperationen, Cloud-Operationen
|
||||
- **Hardware:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Laufzeit + Sicherheit
|
||||
|
||||
- **Autonomiestufen:** ReadOnly, Supervised (Standard), Full.
|
||||
- **Sandboxing:** Workspace-Isolation, Pfad-Traversal-Blockierung, Befehls-Allowlists, verbotene Pfade, Landlock (Linux), Bubblewrap.
|
||||
- **Ratenbegrenzung:** max. Aktionen pro Stunde, max. Kosten pro Tag (konfigurierbar).
|
||||
- **Genehmigungsgating:** interaktive Genehmigung für Operationen mit mittlerem/hohem Risiko.
|
||||
- **Notfall-Stopp:** Notabschaltungsfähigkeit.
|
||||
- **129+ Sicherheitstests** in automatisiertem CI.
|
||||
|
||||
### Betrieb + Paketierung
|
||||
|
||||
- Web-Dashboard direkt vom Gateway bereitgestellt.
|
||||
- Tunnel-Unterstützung: Cloudflare, Tailscale, ngrok, OpenVPN, benutzerdefinierter Befehl.
|
||||
- Docker-Laufzeitadapter für containerisierte Ausführung.
|
||||
- CI/CD: beta (automatisch bei Push) → stable (manueller Dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, Tweet.
|
||||
- Vorgefertigte Binaries für Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfiguration
|
||||
|
||||
Minimale `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Vollständige Konfigurationsreferenz: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanalkonfiguration
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnel-Konfiguration
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # oder "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Details: [Kanal-Referenz](docs/reference/api/channels-reference.md) · [Konfigurationsreferenz](docs/reference/api/config-reference.md)
|
||||
|
||||
### Laufzeitunterstützung (aktuell)
|
||||
|
||||
- **`native`** (Standard) — direkte Prozessausführung, schnellster Pfad, ideal für vertrauenswürdige Umgebungen.
|
||||
- **`docker`** — vollständige Container-Isolation, erzwungene Sicherheitsrichtlinien, erfordert Docker.
|
||||
|
||||
Setze `runtime.kind = "docker"` für striktes Sandboxing oder Netzwerkisolation.
|
||||
|
||||
## Abonnement-Authentifizierung (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw unterstützt native Abonnement-Authentifizierungsprofile (Multi-Account, verschlüsselt im Ruhezustand).
|
||||
|
||||
- Speicherdatei: `~/.zeroclaw/auth-profiles.json`
|
||||
- Verschlüsselungsschlüssel: `~/.zeroclaw/.secret_key`
|
||||
- Profil-ID-Format: `<provider>:<profile_name>` (Beispiel: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT-Abonnement)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Prüfen / aktualisieren / Profil wechseln
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Agenten mit Abonnement-Auth ausführen
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agenten-Workspace + Skills
|
||||
|
||||
Workspace-Root: `~/.zeroclaw/workspace/` (konfigurierbar über Config).
|
||||
|
||||
Injizierte Prompt-Dateien:
|
||||
- `IDENTITY.md` — Persönlichkeit und Rolle des Agenten
|
||||
- `USER.md` — Benutzerkontext und Präferenzen
|
||||
- `MEMORY.md` — Langzeitfakten und Lektionen
|
||||
- `AGENTS.md` — Sitzungskonventionen und Initialisierungsregeln
|
||||
- `SOUL.md` — Kernidentität und Betriebsprinzipien
|
||||
|
||||
Skills: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` oder `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Installierte Skills auflisten
|
||||
zeroclaw skills list
|
||||
|
||||
# Von Git installieren
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Sicherheitsaudit vor der Installation
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Einen Skill entfernen
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-Befehle
|
||||
|
||||
```bash
|
||||
# Workspace-Verwaltung
|
||||
zeroclaw onboard # Geführter Einrichtungsassistent
|
||||
zeroclaw status # Daemon/Agenten-Status anzeigen
|
||||
zeroclaw doctor # Systemdiagnose ausführen
|
||||
|
||||
# Gateway + Daemon
|
||||
zeroclaw gateway # Gateway-Server starten (127.0.0.1:42617)
|
||||
zeroclaw daemon # Vollständige autonome Laufzeit starten
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interaktiver Chat-Modus
|
||||
zeroclaw agent -m "message" # Einzelnachrichten-Modus
|
||||
|
||||
# Service-Verwaltung
|
||||
zeroclaw service install # Als OS-Dienst installieren (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanäle
|
||||
zeroclaw channel list # Konfigurierte Kanäle auflisten
|
||||
zeroclaw channel doctor # Kanalgesundheit prüfen
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + Planung
|
||||
zeroclaw cron list # Geplante Aufgaben auflisten
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Speicher
|
||||
zeroclaw memory list # Speichereinträge auflisten
|
||||
zeroclaw memory get <key> # Speicher abrufen
|
||||
zeroclaw memory stats # Speicherstatistiken
|
||||
|
||||
# Auth-Profile
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware-Peripherie
|
||||
zeroclaw hardware discover # Angeschlossene Geräte scannen
|
||||
zeroclaw peripheral list # Angeschlossene Peripherie auflisten
|
||||
zeroclaw peripheral flash # Firmware auf Gerät flashen
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-Vervollständigung
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Vollständige Befehlsreferenz: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Voraussetzungen
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Erforderlich
|
||||
|
||||
1. **Visual Studio Build Tools** (stellt den MSVC-Linker und das Windows SDK bereit):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Wähle während der Installation (oder über den Visual Studio Installer) den Workload **"Desktopentwicklung mit C++"** aus.
|
||||
|
||||
2. **Rust-Toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Öffne nach der Installation ein neues Terminal und führe `rustup default stable` aus, um sicherzustellen, dass die stabile Toolchain aktiv ist.
|
||||
|
||||
3. **Überprüfe**, dass beide funktionieren:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Optional
|
||||
|
||||
- **Docker Desktop** — nur erforderlich bei Verwendung der [Docker-Sandbox-Laufzeit](#laufzeitunterstützung-aktuell) (`runtime.kind = "docker"`). Installation über `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Erforderlich
|
||||
|
||||
1. **Grundlegende Build-Tools:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Xcode Command Line Tools installieren: `xcode-select --install`
|
||||
|
||||
2. **Rust-Toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Siehe [rustup.rs](https://rustup.rs) für Details.
|
||||
|
||||
3. **Überprüfe**, dass beide funktionieren:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Ein-Zeilen-Installer
|
||||
|
||||
Oder überspringe die obigen Schritte und installiere alles (Systemabhängigkeiten, Rust, ZeroClaw) mit einem einzigen Befehl:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Ressourcenanforderungen für die Kompilierung
|
||||
|
||||
Das Kompilieren aus dem Quellcode benötigt mehr Ressourcen als das Ausführen des resultierenden Binary:
|
||||
|
||||
| Ressource | Minimum | Empfohlen |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + Swap** | 2 GB | 4 GB+ |
|
||||
| **Freier Speicher** | 6 GB | 10 GB+ |
|
||||
|
||||
Wenn dein Host unter dem Minimum liegt, verwende vorgefertigte Binaries:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Um eine reine Binary-Installation ohne Quellcode-Fallback zu erfordern:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Optional
|
||||
|
||||
- **Docker** — nur erforderlich bei Verwendung der [Docker-Sandbox-Laufzeit](#laufzeitunterstützung-aktuell) (`runtime.kind = "docker"`). Installation über deinen Paketmanager oder [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Hinweis:** Der Standard `cargo build --release` verwendet `codegen-units=1`, um den maximalen Kompilierungsdruck zu senken. Für schnellere Builds auf leistungsstarken Maschinen verwende `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Vorgefertigte Binaries
|
||||
|
||||
Release-Assets werden veröffentlicht für:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Lade die neuesten Assets herunter von:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Verwende diese Ressourcen, wenn du den Onboarding-Prozess abgeschlossen hast und die tiefere Referenz benötigst.
|
||||
|
||||
- Starte mit dem [Docs-Index](docs/README.md) für die Navigation und "was ist wo."
|
||||
- Lies die [Architekturübersicht](docs/architecture.md) für das vollständige Systemmodell.
|
||||
- Verwende die [Konfigurationsreferenz](docs/reference/api/config-reference.md), wenn du jede Einstellung und jedes Beispiel brauchst.
|
||||
- Betreibe das Gateway nach Buch mit dem [Betriebs-Runbook](docs/ops/operations-runbook.md).
|
||||
- Folge [ZeroClaw Onboard](#schnellstart) für eine geführte Einrichtung.
|
||||
- Behebe häufige Fehler mit der [Fehlerbehebungsanleitung](docs/ops/troubleshooting.md).
|
||||
- Überprüfe die [Sicherheitshinweise](docs/security/README.md), bevor du etwas exponierst.
|
||||
|
||||
### Referenzdokumentation
|
||||
|
||||
- Dokumentations-Hub: [docs/README.md](docs/README.md)
|
||||
- Einheitliches Docs-TOC: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Befehlsreferenz: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Konfigurationsreferenz: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Provider-Referenz: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanal-Referenz: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Betriebs-Runbook: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Fehlerbehebung: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Zusammenarbeitsdokumentation
|
||||
|
||||
- Beitragsleitfaden: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-Workflow-Richtlinie: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-Workflow-Leitfaden: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Reviewer-Handbuch: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Sicherheitsoffenlegungsrichtlinie: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentationsvorlage: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Bereitstellung + Betrieb
|
||||
|
||||
- Netzwerk-Bereitstellungsleitfaden: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-Agent-Handbuch: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hardware-Leitfäden: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw wurde für den glatten Krebs 🦀 gebaut, einen schnellen und effizienten KI-Assistenten. Entwickelt von Argenis De La Rosa und der Community.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ZeroClaw unterstützen
|
||||
|
||||
Wenn ZeroClaw bei deiner Arbeit hilft und du die laufende Entwicklung unterstützen möchtest, kannst du hier spenden:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Besonderer Dank
|
||||
|
||||
Ein herzliches Dankeschön an die Communitys und Institutionen, die diese Open-Source-Arbeit inspirieren und antreiben:
|
||||
|
||||
- **Harvard University** — für die Förderung intellektueller Neugier und das Verschieben der Grenzen des Möglichen.
|
||||
- **MIT** — für den Einsatz für offenes Wissen, Open Source und den Glauben, dass Technologie für alle zugänglich sein sollte.
|
||||
- **Sundai Club** — für die Community, die Energie und den unermüdlichen Antrieb, Dinge zu bauen, die wichtig sind.
|
||||
- **Die Welt und darüber hinaus** 🌍✨ — an jeden Mitwirkenden, Träumer und Erbauer, der Open Source zu einer Kraft für das Gute macht. Das ist für dich.
|
||||
|
||||
Wir bauen offen, weil die besten Ideen von überall kommen. Wenn du das hier liest, bist du Teil davon. Willkommen. 🦀❤️
|
||||
|
||||
## Beitragen
|
||||
|
||||
Neu bei ZeroClaw? Suche nach Issues mit dem Label [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — siehe unseren [Beitragsleitfaden](CONTRIBUTING.md#first-time-contributors) für den Einstieg. KI-/Vibe-coded PRs willkommen! 🤖
|
||||
|
||||
Siehe [CONTRIBUTING.md](CONTRIBUTING.md) und [CLA.md](docs/contributing/cla.md). Implementiere einen Trait, reiche einen PR ein:
|
||||
|
||||
- CI-Workflow-Leitfaden: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Neuer `Provider` → `src/providers/`
|
||||
- Neuer `Channel` → `src/channels/`
|
||||
- Neuer `Observer` → `src/observability/`
|
||||
- Neues `Tool` → `src/tools/`
|
||||
- Neuer `Memory` → `src/memory/`
|
||||
- Neuer `Tunnel` → `src/tunnel/`
|
||||
- Neues `Peripheral` → `src/peripherals/`
|
||||
- Neuer `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Offizielles Repository & Warnung vor Identitätsdiebstahl
|
||||
|
||||
**Dies ist das einzige offizielle ZeroClaw-Repository:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Jedes andere Repository, jede Organisation, Domain oder jedes Paket, das behauptet, "ZeroClaw" zu sein oder eine Zugehörigkeit zu ZeroClaw Labs impliziert, ist **nicht autorisiert und nicht mit diesem Projekt verbunden**. Bekannte nicht autorisierte Forks werden in [TRADEMARK.md](docs/maintainers/trademark.md) aufgelistet.
|
||||
|
||||
Wenn du auf Identitätsdiebstahl oder Markenrechtsmissbrauch stößt, [eröffne bitte ein Issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Lizenz
|
||||
|
||||
ZeroClaw ist doppelt lizenziert für maximale Offenheit und Schutz der Mitwirkenden:
|
||||
|
||||
| Lizenz | Anwendungsfall |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open Source, Forschung, akademisch, persönliche Nutzung |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patentschutz, institutionell, kommerzielle Bereitstellung |
|
||||
|
||||
Du kannst eine der beiden Lizenzen wählen. **Mitwirkende gewähren automatisch Rechte unter beiden** — siehe [CLA.md](docs/contributing/cla.md) für die vollständige Mitwirkendenvereinbarung.
|
||||
|
||||
### Markenrecht
|
||||
|
||||
Der **ZeroClaw**-Name und das Logo sind Marken von ZeroClaw Labs. Diese Lizenz gewährt keine Erlaubnis, sie zu verwenden, um Unterstützung oder Zugehörigkeit zu implizieren. Siehe [TRADEMARK.md](docs/maintainers/trademark.md) für erlaubte und verbotene Verwendungen.
|
||||
|
||||
### Schutz für Mitwirkende
|
||||
|
||||
- Du **behältst das Urheberrecht** deiner Beiträge
|
||||
- **Patentgewährung** (Apache 2.0) schützt dich vor Patentansprüchen anderer Mitwirkender
|
||||
- Deine Beiträge werden **dauerhaft** in der Commit-Historie und [NOTICE](NOTICE) zugeordnet
|
||||
- Keine Markenrechte werden durch Beiträge übertragen
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Null Overhead. Null Kompromisse. Überall bereitstellen. Alles austauschen. 🦀
|
||||
|
||||
## Mitwirkende
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Diese Liste wird aus dem GitHub-Mitwirkendengraph generiert und aktualisiert sich automatisch.
|
||||
|
||||
## Stern-Verlauf
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.el.md
755
README.el.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Προσωπικός Βοηθός Τεχνητής Νοημοσύνης</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Μηδενική επιβάρυνση. Μηδενικοί συμβιβασμοί. 100% Rust. 100% Αγνωστικός.</strong><br>
|
||||
⚡️ <strong>Τρέχει σε υλικό $10 με <5MB RAM: Αυτό σημαίνει 99% λιγότερη μνήμη από το OpenClaw και 98% φθηνότερο από ένα Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Δημιουργήθηκε από φοιτητές και μέλη των κοινοτήτων Harvard, MIT και Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Γλώσσες:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
Το ZeroClaw είναι ένας προσωπικός βοηθός τεχνητής νοημοσύνης που τρέχει στις δικές σας συσκευές. Σας απαντά στα κανάλια που ήδη χρησιμοποιείτε (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work και περισσότερα). Διαθέτει πίνακα ελέγχου web για έλεγχο σε πραγματικό χρόνο και μπορεί να συνδεθεί με περιφερειακά υλικού (ESP32, STM32, Arduino, Raspberry Pi). Το Gateway είναι απλώς το επίπεδο ελέγχου — το προϊόν είναι ο βοηθός.
|
||||
|
||||
Αν θέλετε έναν προσωπικό βοηθό ενός χρήστη που αισθάνεται τοπικός, γρήγορος και πάντα ενεργός, αυτό είναι.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Ιστοσελίδα</a> ·
|
||||
<a href="docs/README.md">Τεκμηρίωση</a> ·
|
||||
<a href="docs/architecture.md">Αρχιτεκτονική</a> ·
|
||||
<a href="#γρήγορη-εκκίνηση-tldr">Ξεκινήστε</a> ·
|
||||
<a href="#μετεγκατάσταση-από-openclaw">Μετεγκατάσταση από OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Αντιμετώπιση προβλημάτων</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Προτεινόμενη ρύθμιση:** εκτελέστε `zeroclaw onboard` στο τερματικό σας. Το ZeroClaw Onboard σας καθοδηγεί βήμα προς βήμα στη ρύθμιση του gateway, του χώρου εργασίας, των καναλιών και του παρόχου. Είναι η συνιστώμενη διαδρομή ρύθμισης και λειτουργεί σε macOS, Linux και Windows (μέσω WSL2). Νέα εγκατάσταση; Ξεκινήστε εδώ: [Ξεκινήστε](#γρήγορη-εκκίνηση-tldr)
|
||||
|
||||
### Πιστοποίηση Συνδρομής (OAuth)
|
||||
|
||||
- **OpenAI Codex** (συνδρομή ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (κλειδί API ή token πιστοποίησης)
|
||||
|
||||
Σημείωση μοντέλου: ενώ υποστηρίζονται πολλοί πάροχοι/μοντέλα, για την καλύτερη εμπειρία χρησιμοποιήστε το ισχυρότερο μοντέλο τελευταίας γενιάς που έχετε στη διάθεσή σας. Δείτε [Onboarding](#γρήγορη-εκκίνηση-tldr).
|
||||
|
||||
Ρύθμιση μοντέλων + CLI: [Αναφορά παρόχων](docs/reference/api/providers-reference.md)
|
||||
Εναλλαγή προφίλ πιστοποίησης (OAuth vs κλειδιά API) + failover: [Failover μοντέλων](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Εγκατάσταση (συνιστάται)
|
||||
|
||||
Χρόνος εκτέλεσης: Rust stable toolchain. Ένα μόνο δυαδικό αρχείο, χωρίς εξαρτήσεις χρόνου εκτέλεσης.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Εγκατάσταση με ένα κλικ
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
Το `zeroclaw onboard` εκτελείται αυτόματα μετά την εγκατάσταση για τη ρύθμιση του χώρου εργασίας και του παρόχου.
|
||||
|
||||
## Γρήγορη εκκίνηση (TL;DR)
|
||||
|
||||
Πλήρης οδηγός για αρχάριους (πιστοποίηση, σύζευξη, κανάλια): [Ξεκινήστε](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Εγκατάσταση + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Εκκίνηση του gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # προεπιλογή: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # τυχαία θύρα (ενισχυμένη ασφάλεια)
|
||||
|
||||
# Μιλήστε στον βοηθό
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Διαδραστική λειτουργία
|
||||
zeroclaw agent
|
||||
|
||||
# Εκκίνηση πλήρους αυτόνομου χρόνου εκτέλεσης (gateway + κανάλια + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Έλεγχος κατάστασης
|
||||
zeroclaw status
|
||||
|
||||
# Εκτέλεση διαγνωστικών
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Αναβάθμιση; Εκτελέστε `zeroclaw doctor` μετά την ενημέρωση.
|
||||
|
||||
### Από πηγαίο κώδικα (ανάπτυξη)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Εναλλακτική ανάπτυξης (χωρίς καθολική εγκατάσταση):** προθέστε τις εντολές με `cargo run --release --` (παράδειγμα: `cargo run --release -- status`).
|
||||
|
||||
## Μετεγκατάσταση από OpenClaw
|
||||
|
||||
Το ZeroClaw μπορεί να εισάγει τον χώρο εργασίας, τη μνήμη και τη ρύθμιση παραμέτρων του OpenClaw:
|
||||
|
||||
```bash
|
||||
# Προεπισκόπηση τι θα μετεγκατασταθεί (ασφαλές, μόνο ανάγνωση)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Εκτέλεση της μετεγκατάστασης
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Αυτό μετεγκαθιστά τις εγγραφές μνήμης, τα αρχεία χώρου εργασίας και τη ρύθμιση παραμέτρων από `~/.openclaw/` σε `~/.zeroclaw/`. Η ρύθμιση μετατρέπεται αυτόματα από JSON σε TOML.
|
||||
|
||||
## Προεπιλογές ασφάλειας (πρόσβαση DM)
|
||||
|
||||
Το ZeroClaw συνδέεται σε πραγματικές επιφάνειες μηνυμάτων. Αντιμετωπίστε τα εισερχόμενα DM ως μη αξιόπιστη είσοδο.
|
||||
|
||||
Πλήρης οδηγός ασφάλειας: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Προεπιλεγμένη συμπεριφορά σε όλα τα κανάλια:
|
||||
|
||||
- **Σύζευξη DM** (προεπιλογή): οι άγνωστοι αποστολείς λαμβάνουν έναν σύντομο κωδικό σύζευξης και ο bot δεν επεξεργάζεται το μήνυμά τους.
|
||||
- Εγκρίνετε με: `zeroclaw pairing approve <channel> <code>` (τότε ο αποστολέας προστίθεται σε τοπική λίστα επιτρεπόμενων).
|
||||
- Τα δημόσια εισερχόμενα DM απαιτούν ρητή ενεργοποίηση στο `config.toml`.
|
||||
- Εκτελέστε `zeroclaw doctor` για να εντοπίσετε επικίνδυνες ή εσφαλμένες πολιτικές DM.
|
||||
|
||||
**Επίπεδα αυτονομίας:**
|
||||
|
||||
| Επίπεδο | Συμπεριφορά |
|
||||
|---------|-------------|
|
||||
| `ReadOnly` | Ο πράκτορας μπορεί να παρατηρεί αλλά όχι να ενεργεί |
|
||||
| `Supervised` (προεπιλογή) | Ο πράκτορας ενεργεί με έγκριση για λειτουργίες μεσαίου/υψηλού κινδύνου |
|
||||
| `Full` | Ο πράκτορας ενεργεί αυτόνομα εντός ορίων πολιτικής |
|
||||
|
||||
**Επίπεδα sandboxing:** απομόνωση χώρου εργασίας, αποκλεισμός διέλευσης διαδρομής, λίστες επιτρεπόμενων εντολών, απαγορευμένες διαδρομές (`/etc`, `/root`, `~/.ssh`), περιορισμός ρυθμού (μέγιστες ενέργειες/ώρα, όρια κόστους/ημέρα).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Ανακοινώσεις
|
||||
|
||||
Χρησιμοποιήστε αυτόν τον πίνακα για σημαντικές ειδοποιήσεις (αλλαγές που σπάνε τη συμβατότητα, συμβουλές ασφαλείας, παράθυρα συντήρησης και αποκλεισμοί έκδοσης).
|
||||
|
||||
| Ημερομηνία (UTC) | Επίπεδο | Ειδοποίηση | Ενέργεια |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Κρίσιμο_ | **Δεν** είμαστε συνδεδεμένοι με `openagen/zeroclaw`, `zeroclaw.org` ή `zeroclaw.net`. Οι τομείς `zeroclaw.org` και `zeroclaw.net` δείχνουν αυτή τη στιγμή στο fork `openagen/zeroclaw`, και αυτός ο τομέας/αποθετήριο υποδύονται τον επίσημο ιστότοπο/έργο μας. | Μην εμπιστεύεστε πληροφορίες, δυαδικά αρχεία, εκστρατείες χρηματοδότησης ή ανακοινώσεις από αυτές τις πηγές. Χρησιμοποιήστε μόνο [αυτό το αποθετήριο](https://github.com/zeroclaw-labs/zeroclaw) και τους επαληθευμένους λογαριασμούς μας στα μέσα κοινωνικής δικτύωσης. |
|
||||
| 2026-02-21 | _Σημαντικό_ | Ο επίσημος ιστότοπός μας είναι πλέον ζωντανός: [zeroclawlabs.ai](https://zeroclawlabs.ai). Ευχαριστούμε για την υπομονή σας ενώ ετοιμάζαμε την εκκίνηση. Εξακολουθούμε να βλέπουμε απόπειρες πλαστοπροσωπίας, οπότε **μην** συμμετέχετε σε καμία επενδυτική ή χρηματοδοτική δραστηριότητα που ισχυρίζεται το όνομα ZeroClaw εκτός αν δημοσιεύεται μέσω των επίσημων καναλιών μας. | Χρησιμοποιήστε [αυτό το αποθετήριο](https://github.com/zeroclaw-labs/zeroclaw) ως τη μοναδική πηγή αλήθειας. Ακολουθήστε [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) και [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) για επίσημες ενημερώσεις. |
|
||||
| 2026-02-19 | _Σημαντικό_ | Η Anthropic ενημέρωσε τους Όρους Πιστοποίησης και Χρήσης Διαπιστευτηρίων στις 2026-02-19. Τα OAuth tokens του Claude Code (Free, Pro, Max) προορίζονται αποκλειστικά για το Claude Code και το Claude.ai· η χρήση OAuth tokens από Claude Free/Pro/Max σε οποιοδήποτε άλλο προϊόν, εργαλείο ή υπηρεσία (συμπεριλαμβανομένου του Agent SDK) δεν επιτρέπεται και ενδέχεται να παραβιάζει τους Όρους Χρήσης Καταναλωτή. | Παρακαλούμε αποφύγετε προσωρινά τις ενσωματώσεις Claude Code OAuth για να αποτρέψετε πιθανή απώλεια. Αρχική ρήτρα: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Χαρακτηριστικά
|
||||
|
||||
- **Ελαφρύς χρόνος εκτέλεσης από προεπιλογή** — οι συνήθεις ροές εργασίας CLI και κατάστασης τρέχουν σε φάκελο μνήμης λίγων megabyte σε release builds.
|
||||
- **Οικονομική ανάπτυξη** — σχεδιασμένο για πλακέτες $10 και μικρές cloud instances, χωρίς βαριές εξαρτήσεις χρόνου εκτέλεσης.
|
||||
- **Γρήγορες κρύες εκκινήσεις** — ο χρόνος εκτέλεσης Rust με ένα δυαδικό αρχείο κρατά την εκκίνηση εντολών και daemon σχεδόν στιγμιαία.
|
||||
- **Φορητή αρχιτεκτονική** — ένα δυαδικό αρχείο σε ARM, x86 και RISC-V με εναλλάξιμους παρόχους/κανάλια/εργαλεία.
|
||||
- **Τοπικό-πρώτα Gateway** — ένα μόνο επίπεδο ελέγχου για sessions, κανάλια, εργαλεία, cron, SOPs και events.
|
||||
- **Εισερχόμενα πολλαπλών καναλιών** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket και περισσότερα.
|
||||
- **Ενορχήστρωση πολλαπλών πρακτόρων (Hands)** — αυτόνομα σμήνη πρακτόρων που τρέχουν σε πρόγραμμα και γίνονται πιο έξυπνα με τον χρόνο.
|
||||
- **Τυπικές Διαδικασίες Λειτουργίας (SOPs)** — αυτοματοποίηση ροών εργασίας βάσει γεγονότων με MQTT, webhook, cron και triggers περιφερειακών.
|
||||
- **Πίνακας ελέγχου Web** — React 19 + Vite web UI με συνομιλία σε πραγματικό χρόνο, περιηγητή μνήμης, επεξεργαστή ρυθμίσεων, διαχειριστή cron και επιθεωρητή εργαλείων.
|
||||
- **Περιφερειακά υλικού** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO μέσω του trait `Peripheral`.
|
||||
- **Εργαλεία πρώτης κατηγορίας** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace και 70+ ακόμη.
|
||||
- **Hooks κύκλου ζωής** — παρεμβολή και τροποποίηση κλήσεων LLM, εκτελέσεων εργαλείων και μηνυμάτων σε κάθε στάδιο.
|
||||
- **Πλατφόρμα δεξιοτήτων** — ενσωματωμένες, κοινοτικές και δεξιότητες χώρου εργασίας με έλεγχο ασφαλείας.
|
||||
- **Υποστήριξη tunnel** — Cloudflare, Tailscale, ngrok, OpenVPN και custom tunnels για απομακρυσμένη πρόσβαση.
|
||||
|
||||
### Γιατί οι ομάδες επιλέγουν το ZeroClaw
|
||||
|
||||
- **Ελαφρύ από προεπιλογή:** μικρό δυαδικό αρχείο Rust, γρήγορη εκκίνηση, χαμηλό αποτύπωμα μνήμης.
|
||||
- **Ασφαλές από σχεδιασμό:** σύζευξη, αυστηρό sandboxing, ρητές λίστες επιτρεπόμενων, οριοθέτηση χώρου εργασίας.
|
||||
- **Πλήρως εναλλάξιμο:** τα βασικά συστήματα είναι traits (providers, channels, tools, memory, tunnels).
|
||||
- **Χωρίς εγκλωβισμό:** υποστήριξη παρόχου συμβατού με OpenAI + pluggable custom endpoints.
|
||||
|
||||
## Στιγμιότυπο Benchmark (ZeroClaw vs OpenClaw, Αναπαραγώγιμο)
|
||||
|
||||
Γρήγορο benchmark τοπικού μηχανήματος (macOS arm64, Φεβ 2026) κανονικοποιημένο για υλικό edge 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Γλώσσα** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Εκκίνηση (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Μέγεθος δυαδικού** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Κόστος** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Οποιοδήποτε υλικό $10** |
|
||||
|
||||
> Σημειώσεις: Τα αποτελέσματα του ZeroClaw μετρήθηκαν σε release builds χρησιμοποιώντας `/usr/bin/time -l`. Το OpenClaw απαιτεί Node.js runtime (τυπικά ~390MB επιπλέον επιβάρυνση μνήμης), ενώ το NanoBot απαιτεί Python runtime. Τα PicoClaw και ZeroClaw είναι στατικά δυαδικά. Τα στοιχεία RAM παραπάνω αφορούν μνήμη χρόνου εκτέλεσης· οι απαιτήσεις μεταγλώττισης κατά τον χρόνο κατασκευής είναι υψηλότερες.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Αναπαραγώγιμη τοπική μέτρηση
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Όλα όσα δημιουργήσαμε μέχρι τώρα
|
||||
|
||||
### Βασική πλατφόρμα
|
||||
|
||||
- Επίπεδο ελέγχου Gateway HTTP/WS/SSE με sessions, παρουσία, ρύθμιση, cron, webhooks, web dashboard και σύζευξη.
|
||||
- Επιφάνεια CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Βρόχος ενορχήστρωσης πράκτορα με αποστολή εργαλείων, κατασκευή prompt, ταξινόμηση μηνυμάτων και φόρτωση μνήμης.
|
||||
- Μοντέλο session με επιβολή πολιτικής ασφάλειας, επίπεδα αυτονομίας και πύλη έγκρισης.
|
||||
- Ανθεκτικό περιτύλιγμα παρόχου με failover, retry και δρομολόγηση μοντέλων σε 20+ backends LLM.
|
||||
|
||||
### Κανάλια
|
||||
|
||||
Κανάλια: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Με feature-gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Πίνακας ελέγχου Web
|
||||
|
||||
Πίνακας ελέγχου web React 19 + Vite 6 + Tailwind CSS 4 που εξυπηρετείται απευθείας από το Gateway:
|
||||
|
||||
- **Dashboard** — επισκόπηση συστήματος, κατάσταση υγείας, uptime, παρακολούθηση κόστους
|
||||
- **Agent Chat** — διαδραστική συνομιλία με τον πράκτορα
|
||||
- **Memory** — περιήγηση και διαχείριση εγγραφών μνήμης
|
||||
- **Config** — προβολή και επεξεργασία ρυθμίσεων
|
||||
- **Cron** — διαχείριση προγραμματισμένων εργασιών
|
||||
- **Tools** — περιήγηση διαθέσιμων εργαλείων
|
||||
- **Logs** — προβολή αρχείων καταγραφής δραστηριότητας πράκτορα
|
||||
- **Cost** — χρήση tokens και παρακολούθηση κόστους
|
||||
- **Doctor** — διαγνωστικά υγείας συστήματος
|
||||
- **Integrations** — κατάσταση ενσωμάτωσης και ρύθμιση
|
||||
- **Pairing** — διαχείριση σύζευξης συσκευών
|
||||
|
||||
### Στόχοι firmware
|
||||
|
||||
| Στόχος | Πλατφόρμα | Σκοπός |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | Ασύρματος περιφερειακός πράκτορας |
|
||||
| ESP32-UI | ESP32 + Display | Πράκτορας με οπτική διεπαφή |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Βιομηχανικό περιφερειακό |
|
||||
| Arduino | Arduino | Βασική γέφυρα αισθητήρα/ενεργοποιητή |
|
||||
| Uno Q Bridge | Arduino Uno | Σειριακή γέφυρα προς τον πράκτορα |
|
||||
|
||||
### Εργαλεία + αυτοματοποίηση
|
||||
|
||||
- **Βασικά:** shell, file read/write/edit, git operations, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Ενσωματώσεις:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Προγραμματισμός:** cron add/remove/update/run, schedule tool
|
||||
- **Μνήμη:** recall, store, forget, knowledge, project intel
|
||||
- **Προηγμένα:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Υλικό:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Χρόνος εκτέλεσης + ασφάλεια
|
||||
|
||||
- **Επίπεδα αυτονομίας:** ReadOnly, Supervised (προεπιλογή), Full.
|
||||
- **Sandboxing:** απομόνωση χώρου εργασίας, αποκλεισμός διέλευσης διαδρομής, λίστες επιτρεπόμενων εντολών, απαγορευμένες διαδρομές, Landlock (Linux), Bubblewrap.
|
||||
- **Περιορισμός ρυθμού:** μέγιστες ενέργειες ανά ώρα, μέγιστο κόστος ανά ημέρα (ρυθμιζόμενο).
|
||||
- **Πύλη έγκρισης:** διαδραστική έγκριση για λειτουργίες μεσαίου/υψηλού κινδύνου.
|
||||
- **E-stop:** δυνατότητα έκτακτης διακοπής.
|
||||
- **129+ τεστ ασφαλείας** σε αυτοματοποιημένο CI.
|
||||
|
||||
### Λειτουργίες + πακετάρισμα
|
||||
|
||||
- Πίνακας ελέγχου web που εξυπηρετείται απευθείας από το Gateway.
|
||||
- Υποστήριξη tunnel: Cloudflare, Tailscale, ngrok, OpenVPN, custom command.
|
||||
- Docker runtime adapter για containerized εκτέλεση.
|
||||
- CI/CD: beta (auto on push) → stable (manual dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Προκατασκευασμένα δυαδικά για Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Ρύθμιση παραμέτρων
|
||||
|
||||
Ελάχιστο `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Πλήρης αναφορά ρύθμισης: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Ρύθμιση καναλιών
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Ρύθμιση tunnel
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Λεπτομέρειες: [Αναφορά καναλιών](docs/reference/api/channels-reference.md) · [Αναφορά ρυθμίσεων](docs/reference/api/config-reference.md)
|
||||
|
||||
### Υποστήριξη χρόνου εκτέλεσης (τρέχουσα)
|
||||
|
||||
- **`native`** (προεπιλογή) — άμεση εκτέλεση διεργασίας, ταχύτερη διαδρομή, ιδανική για αξιόπιστα περιβάλλοντα.
|
||||
- **`docker`** — πλήρης απομόνωση container, επιβαλλόμενες πολιτικές ασφάλειας, απαιτεί Docker.
|
||||
|
||||
Ορίστε `runtime.kind = "docker"` για αυστηρό sandboxing ή απομόνωση δικτύου.
|
||||
|
||||
## Πιστοποίηση Συνδρομής (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
Το ZeroClaw υποστηρίζει native προφίλ πιστοποίησης συνδρομής (πολλαπλοί λογαριασμοί, κρυπτογραφημένα σε αδράνεια).
|
||||
|
||||
- Αρχείο αποθήκευσης: `~/.zeroclaw/auth-profiles.json`
|
||||
- Κλειδί κρυπτογράφησης: `~/.zeroclaw/.secret_key`
|
||||
- Μορφή αναγνωριστικού προφίλ: `<provider>:<profile_name>` (παράδειγμα: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Χώρος εργασίας πράκτορα + δεξιότητες
|
||||
|
||||
Ρίζα χώρου εργασίας: `~/.zeroclaw/workspace/` (ρυθμιζόμενο μέσω config).
|
||||
|
||||
Ενσωματωμένα αρχεία prompt:
|
||||
- `IDENTITY.md` — προσωπικότητα και ρόλος πράκτορα
|
||||
- `USER.md` — πλαίσιο χρήστη και προτιμήσεις
|
||||
- `MEMORY.md` — μακροπρόθεσμα γεγονότα και μαθήματα
|
||||
- `AGENTS.md` — συμβάσεις session και κανόνες αρχικοποίησης
|
||||
- `SOUL.md` — βασική ταυτότητα και αρχές λειτουργίας
|
||||
|
||||
Δεξιότητες: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` ή `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Εντολές CLI
|
||||
|
||||
```bash
|
||||
# Διαχείριση χώρου εργασίας
|
||||
zeroclaw onboard # Οδηγός καθοδηγούμενης ρύθμισης
|
||||
zeroclaw status # Εμφάνιση κατάστασης daemon/agent
|
||||
zeroclaw doctor # Εκτέλεση διαγνωστικών συστήματος
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Εκκίνηση gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Εκκίνηση πλήρους αυτόνομου χρόνου εκτέλεσης
|
||||
|
||||
# Πράκτορας
|
||||
zeroclaw agent # Διαδραστική λειτουργία συνομιλίας
|
||||
zeroclaw agent -m "message" # Λειτουργία μεμονωμένου μηνύματος
|
||||
|
||||
# Διαχείριση υπηρεσίας
|
||||
zeroclaw service install # Εγκατάσταση ως υπηρεσία OS (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Κανάλια
|
||||
zeroclaw channel list # Λίστα ρυθμισμένων καναλιών
|
||||
zeroclaw channel doctor # Έλεγχος υγείας καναλιών
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + προγραμματισμός
|
||||
zeroclaw cron list # Λίστα προγραμματισμένων εργασιών
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Μνήμη
|
||||
zeroclaw memory list # Λίστα εγγραφών μνήμης
|
||||
zeroclaw memory get <key> # Ανάκτηση μνήμης
|
||||
zeroclaw memory stats # Στατιστικά μνήμης
|
||||
|
||||
# Προφίλ πιστοποίησης
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Περιφερειακά υλικού
|
||||
zeroclaw hardware discover # Σάρωση για συνδεδεμένες συσκευές
|
||||
zeroclaw peripheral list # Λίστα συνδεδεμένων περιφερειακών
|
||||
zeroclaw peripheral flash # Flash firmware σε συσκευή
|
||||
|
||||
# Μετεγκατάσταση
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Συμπληρώσεις shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Πλήρης αναφορά εντολών: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Προαπαιτούμενα
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Απαιτούμενα
|
||||
|
||||
1. **Visual Studio Build Tools** (παρέχει τον MSVC linker και το Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Κατά την εγκατάσταση (ή μέσω του Visual Studio Installer), επιλέξτε το workload **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Μετά την εγκατάσταση, ανοίξτε ένα νέο τερματικό και εκτελέστε `rustup default stable` για να βεβαιωθείτε ότι είναι ενεργό το stable toolchain.
|
||||
|
||||
3. **Επαλήθευση** ότι λειτουργούν και τα δύο:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Προαιρετικά
|
||||
|
||||
- **Docker Desktop** — απαιτείται μόνο αν χρησιμοποιείτε τον [Docker sandboxed runtime](#υποστήριξη-χρόνου-εκτέλεσης-τρέχουσα) (`runtime.kind = "docker"`). Εγκατάσταση μέσω `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Απαιτούμενα
|
||||
|
||||
1. **Βασικά εργαλεία κατασκευής:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Εγκαταστήστε Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Δείτε [rustup.rs](https://rustup.rs) για λεπτομέρειες.
|
||||
|
||||
3. **Επαλήθευση** ότι λειτουργούν και τα δύο:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Εγκατάσταση με μία εντολή
|
||||
|
||||
Ή παραλείψτε τα παραπάνω βήματα και εγκαταστήστε τα πάντα (εξαρτήσεις συστήματος, Rust, ZeroClaw) με μία εντολή:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Απαιτήσεις πόρων μεταγλώττισης
|
||||
|
||||
Η κατασκευή από πηγαίο κώδικα χρειάζεται περισσότερους πόρους από την εκτέλεση του τελικού δυαδικού:
|
||||
|
||||
| Πόρος | Ελάχιστο | Συνιστώμενο |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Ελεύθερος δίσκος** | 6 GB | 10 GB+ |
|
||||
|
||||
Αν ο host σας είναι κάτω από το ελάχιστο, χρησιμοποιήστε προκατασκευασμένα δυαδικά:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Για εγκατάσταση αποκλειστικά δυαδικού χωρίς εναλλακτική πηγαίου κώδικα:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Προαιρετικά
|
||||
|
||||
- **Docker** — απαιτείται μόνο αν χρησιμοποιείτε τον [Docker sandboxed runtime](#υποστήριξη-χρόνου-εκτέλεσης-τρέχουσα) (`runtime.kind = "docker"`). Εγκατάσταση μέσω του package manager σας ή [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Σημείωση:** Η προεπιλεγμένη `cargo build --release` χρησιμοποιεί `codegen-units=1` για μείωση της μέγιστης πίεσης μεταγλώττισης. Για ταχύτερες κατασκευές σε ισχυρά μηχανήματα, χρησιμοποιήστε `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Προκατασκευασμένα δυαδικά
|
||||
|
||||
Τα assets έκδοσης δημοσιεύονται για:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Κατεβάστε τα τελευταία assets από:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Τεκμηρίωση
|
||||
|
||||
Χρησιμοποιήστε τα όταν έχετε ολοκληρώσει τη ροή onboarding και θέλετε τη βαθύτερη αναφορά.
|
||||
|
||||
- Ξεκινήστε με το [ευρετήριο τεκμηρίωσης](docs/README.md) για πλοήγηση και "τι βρίσκεται πού."
|
||||
- Διαβάστε την [επισκόπηση αρχιτεκτονικής](docs/architecture.md) για το πλήρες μοντέλο συστήματος.
|
||||
- Χρησιμοποιήστε την [αναφορά ρυθμίσεων](docs/reference/api/config-reference.md) όταν χρειάζεστε κάθε κλειδί και παράδειγμα.
|
||||
- Εκτελέστε το Gateway σύμφωνα με το βιβλίο με το [εγχειρίδιο λειτουργίας](docs/ops/operations-runbook.md).
|
||||
- Ακολουθήστε [ZeroClaw Onboard](#γρήγορη-εκκίνηση-tldr) για καθοδηγούμενη ρύθμιση.
|
||||
- Αντιμετωπίστε κοινά σφάλματα με τον [οδηγό αντιμετώπισης προβλημάτων](docs/ops/troubleshooting.md).
|
||||
- Ελέγξτε τις [οδηγίες ασφάλειας](docs/security/README.md) πριν εκθέσετε οτιδήποτε.
|
||||
|
||||
### Αναφορά τεκμηρίωσης
|
||||
|
||||
- Κόμβος τεκμηρίωσης: [docs/README.md](docs/README.md)
|
||||
- Ενοποιημένος πίνακας περιεχομένων: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Αναφορά εντολών: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Αναφορά ρυθμίσεων: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Αναφορά παρόχων: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Αναφορά καναλιών: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Εγχειρίδιο λειτουργίας: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Αντιμετώπιση προβλημάτων: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Τεκμηρίωση συνεργασίας
|
||||
|
||||
- Οδηγός συνεισφοράς: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Πολιτική ροής εργασίας PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Οδηγός ροής εργασίας CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Εγχειρίδιο αξιολογητή: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Πολιτική αποκάλυψης ασφάλειας: [SECURITY.md](SECURITY.md)
|
||||
- Πρότυπο τεκμηρίωσης: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Ανάπτυξη + λειτουργίες
|
||||
|
||||
- Οδηγός ανάπτυξης δικτύου: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Εγχειρίδιο proxy agent: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Οδηγοί υλικού: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
Το ZeroClaw δημιουργήθηκε για τον smooth crab 🦀, έναν γρήγορο και αποδοτικό βοηθό AI. Δημιουργήθηκε από τον Argenis De La Rosa και την κοινότητα.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Υποστήριξη ZeroClaw
|
||||
|
||||
Αν το ZeroClaw βοηθά τη δουλειά σας και θέλετε να υποστηρίξετε τη συνεχιζόμενη ανάπτυξη, μπορείτε να κάνετε δωρεά εδώ:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Ειδικές Ευχαριστίες
|
||||
|
||||
Ένα εγκάρδιο ευχαριστώ στις κοινότητες και τα ιδρύματα που εμπνέουν και τροφοδοτούν αυτό το έργο ανοιχτού κώδικα:
|
||||
|
||||
- **Harvard University** — για την καλλιέργεια πνευματικής περιέργειας και την ώθηση των ορίων του εφικτού.
|
||||
- **MIT** — για την υπεράσπιση της ανοιχτής γνώσης, του ανοιχτού κώδικα και της πεποίθησης ότι η τεχνολογία πρέπει να είναι προσβάσιμη σε όλους.
|
||||
- **Sundai Club** — για την κοινότητα, την ενέργεια και την ακατάπαυστη επιθυμία να χτίζουμε πράγματα που έχουν σημασία.
|
||||
- **Ο Κόσμος & Πέρα** 🌍✨ — σε κάθε συνεισφέροντα, ονειροπόλο και δημιουργό εκεί έξω που κάνει τον ανοιχτό κώδικα δύναμη για το καλό. Αυτό είναι για εσένα.
|
||||
|
||||
Χτίζουμε ανοιχτά γιατί οι καλύτερες ιδέες έρχονται από παντού. Αν διαβάζεις αυτό, είσαι μέρος του. Καλωσήρθες. 🦀❤️
|
||||
|
||||
## Συνεισφορά
|
||||
|
||||
Νέος στο ZeroClaw; Ψάξτε για issues με ετικέτα [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — δείτε τον [Οδηγό Συνεισφοράς](CONTRIBUTING.md#first-time-contributors) για το πώς να ξεκινήσετε. PR με AI/vibe-coding καλοδεχούμενα! 🤖
|
||||
|
||||
Δείτε [CONTRIBUTING.md](CONTRIBUTING.md) και [CLA.md](docs/contributing/cla.md). Υλοποιήστε ένα trait, υποβάλετε ένα PR:
|
||||
|
||||
- Οδηγός ροής εργασίας CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Νέο `Provider` → `src/providers/`
|
||||
- Νέο `Channel` → `src/channels/`
|
||||
- Νέο `Observer` → `src/observability/`
|
||||
- Νέο `Tool` → `src/tools/`
|
||||
- Νέο `Memory` → `src/memory/`
|
||||
- Νέο `Tunnel` → `src/tunnel/`
|
||||
- Νέο `Peripheral` → `src/peripherals/`
|
||||
- Νέο `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Επίσημο Αποθετήριο & Προειδοποίηση Πλαστοπροσωπίας
|
||||
|
||||
**Αυτό είναι το μόνο επίσημο αποθετήριο ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Οποιοδήποτε άλλο αποθετήριο, οργανισμός, τομέας ή πακέτο που ισχυρίζεται ότι είναι "ZeroClaw" ή υπονοεί σχέση με τα ZeroClaw Labs είναι **μη εξουσιοδοτημένο και δεν σχετίζεται με αυτό το έργο**. Τα γνωστά μη εξουσιοδοτημένα forks θα αναφέρονται στο [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Αν αντιμετωπίσετε πλαστοπροσωπία ή κατάχρηση εμπορικού σήματος, παρακαλούμε [ανοίξτε ένα issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Άδεια
|
||||
|
||||
Το ZeroClaw έχει διπλή άδεια για μέγιστη ανοιχτότητα και προστασία συνεισφερόντων:
|
||||
|
||||
| Άδεια | Περίπτωση χρήσης |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Ανοιχτός κώδικας, έρευνα, ακαδημαϊκή, προσωπική χρήση |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Προστασία πατεντών, θεσμική, εμπορική ανάπτυξη |
|
||||
|
||||
Μπορείτε να επιλέξετε οποιαδήποτε άδεια. **Οι συνεισφέροντες παρέχουν αυτόματα δικαιώματα και στις δύο** — δείτε [CLA.md](docs/contributing/cla.md) για την πλήρη συμφωνία συνεισφοράς.
|
||||
|
||||
### Εμπορικό σήμα
|
||||
|
||||
Το όνομα **ZeroClaw** και το λογότυπο είναι εμπορικά σήματα της ZeroClaw Labs. Αυτή η άδεια δεν παρέχει δικαίωμα χρήσης τους για να υπονοήσετε υποστήριξη ή σχέση. Δείτε [TRADEMARK.md](docs/maintainers/trademark.md) για επιτρεπόμενες και απαγορευμένες χρήσεις.
|
||||
|
||||
### Προστασίες Συνεισφερόντων
|
||||
|
||||
- **Διατηρείτε τα πνευματικά δικαιώματα** των συνεισφορών σας
|
||||
- **Χορήγηση πατεντών** (Apache 2.0) σας προστατεύει από αξιώσεις πατεντών άλλων συνεισφερόντων
|
||||
- Οι συνεισφορές σας **αποδίδονται μόνιμα** στο ιστορικό commit και στο [NOTICE](NOTICE)
|
||||
- Δεν μεταβιβάζονται δικαιώματα εμπορικού σήματος με τη συνεισφορά
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Μηδενική επιβάρυνση. Μηδενικοί συμβιβασμοί. Ανάπτυξη οπουδήποτε. Εναλλαγή οτιδήποτε. 🦀
|
||||
|
||||
## Συνεισφέροντες
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Αυτή η λίστα δημιουργείται από το γράφημα συνεισφερόντων του GitHub και ενημερώνεται αυτόματα.
|
||||
|
||||
## Ιστορικό Αστεριών
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.es.md
755
README.es.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Asistente Personal de IA</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Cero sobrecarga. Cero compromisos. 100% Rust. 100% Agnóstico.</strong><br>
|
||||
⚡️ <strong>Funciona en hardware de $10 con <5MB de RAM: ¡99% menos memoria que OpenClaw y 98% más barato que un Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Construido por estudiantes y miembros de las comunidades de Harvard, MIT y Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Idiomas:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw es un asistente personal de IA que ejecutas en tus propios dispositivos. Te responde en los canales que ya usas (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work y más). Tiene un panel web para control en tiempo real y puede conectarse a periféricos de hardware (ESP32, STM32, Arduino, Raspberry Pi). El Gateway es solo el plano de control — el producto es el asistente.
|
||||
|
||||
Si quieres un asistente personal, de un solo usuario, que se sienta local, rápido y siempre activo, esto es lo que buscas.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Sitio web</a> ·
|
||||
<a href="docs/README.md">Documentación</a> ·
|
||||
<a href="docs/architecture.md">Arquitectura</a> ·
|
||||
<a href="#inicio-rápido">Primeros pasos</a> ·
|
||||
<a href="#migración-desde-openclaw">Migración desde OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Solución de problemas</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Configuración recomendada:** ejecuta `zeroclaw onboard` en tu terminal. ZeroClaw Onboard te guía paso a paso en la configuración del gateway, workspace, canales y proveedor. Es la ruta de configuración recomendada y funciona en macOS, Linux y Windows (vía WSL2). ¿Nueva instalación? Empieza aquí: [Primeros pasos](#inicio-rápido)
|
||||
|
||||
### Autenticación por suscripción (OAuth)
|
||||
|
||||
- **OpenAI Codex** (suscripción ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (clave API o token de autenticación)
|
||||
|
||||
Nota sobre modelos: aunque se soportan muchos proveedores/modelos, para la mejor experiencia usa el modelo de última generación más potente disponible. Ver [Onboarding](#inicio-rápido).
|
||||
|
||||
Configuración de modelos + CLI: [Referencia de proveedores](docs/reference/api/providers-reference.md)
|
||||
Rotación de perfiles de autenticación (OAuth vs claves API) + failover: [Failover de modelos](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instalación (recomendada)
|
||||
|
||||
Requisito: toolchain estable de Rust. Un solo binario, sin dependencias de runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Bootstrap con un clic
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` se ejecuta automáticamente después de la instalación para configurar tu workspace y proveedor.
|
||||
|
||||
## Inicio rápido (TL;DR)
|
||||
|
||||
Guía completa para principiantes (autenticación, emparejamiento, canales): [Primeros pasos](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instalar + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Iniciar el gateway (servidor webhook + panel web)
|
||||
zeroclaw gateway # por defecto: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # puerto aleatorio (seguridad reforzada)
|
||||
|
||||
# Hablar con el asistente
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Modo interactivo
|
||||
zeroclaw agent
|
||||
|
||||
# Iniciar runtime autónomo completo (gateway + canales + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Verificar estado
|
||||
zeroclaw status
|
||||
|
||||
# Ejecutar diagnósticos
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
¿Actualizando? Ejecuta `zeroclaw doctor` después de actualizar.
|
||||
|
||||
### Desde el código fuente (desarrollo)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Alternativa para desarrollo (sin instalación global):** antepón `cargo run --release --` a los comandos (ejemplo: `cargo run --release -- status`).
|
||||
|
||||
## Migración desde OpenClaw
|
||||
|
||||
ZeroClaw puede importar tu workspace, memoria y configuración de OpenClaw:
|
||||
|
||||
```bash
|
||||
# Vista previa de lo que se migrará (seguro, solo lectura)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Ejecutar la migración
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Esto migra tus entradas de memoria, archivos del workspace y configuración de `~/.openclaw/` a `~/.zeroclaw/`. La configuración se convierte de JSON a TOML automáticamente.
|
||||
|
||||
## Valores predeterminados de seguridad (acceso por DM)
|
||||
|
||||
ZeroClaw se conecta a superficies de mensajería reales. Trata los DMs entrantes como entrada no confiable.
|
||||
|
||||
Guía completa de seguridad: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Comportamiento predeterminado en todos los canales:
|
||||
|
||||
- **Emparejamiento por DM** (predeterminado): los remitentes desconocidos reciben un código de emparejamiento corto y el bot no procesa su mensaje.
|
||||
- Aprobar con: `zeroclaw pairing approve <channel> <code>` (luego el remitente se agrega a una lista de permitidos local).
|
||||
- Los DMs públicos entrantes requieren una activación explícita en `config.toml`.
|
||||
- Ejecuta `zeroclaw doctor` para detectar políticas de DM riesgosas o mal configuradas.
|
||||
|
||||
**Niveles de autonomía:**
|
||||
|
||||
| Nivel | Comportamiento |
|
||||
|-------|----------------|
|
||||
| `ReadOnly` | El agente puede observar pero no actuar |
|
||||
| `Supervised` (predeterminado) | El agente actúa con aprobación para operaciones de riesgo medio/alto |
|
||||
| `Full` | El agente actúa autónomamente dentro de los límites de la política |
|
||||
|
||||
**Capas de sandboxing:** aislamiento del workspace, bloqueo de traversal de rutas, listas de comandos permitidos, rutas prohibidas (`/etc`, `/root`, `~/.ssh`), limitación de velocidad (máximo de acciones/hora, topes de costo/día).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Anuncios
|
||||
|
||||
Usa este tablero para avisos importantes (cambios incompatibles, avisos de seguridad, ventanas de mantenimiento y bloqueadores de lanzamiento).
|
||||
|
||||
| Fecha (UTC) | Nivel | Aviso | Acción |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Crítico_ | **No estamos afiliados** con `openagen/zeroclaw`, `zeroclaw.org` ni `zeroclaw.net`. Los dominios `zeroclaw.org` y `zeroclaw.net` actualmente apuntan al fork `openagen/zeroclaw`, y ese dominio/repositorio están suplantando nuestro sitio web/proyecto oficial. | No confíes en información, binarios, recaudaciones de fondos o anuncios de esas fuentes. Usa solo [este repositorio](https://github.com/zeroclaw-labs/zeroclaw) y nuestras cuentas sociales verificadas. |
|
||||
| 2026-02-21 | _Importante_ | Nuestro sitio web oficial ya está en línea: [zeroclawlabs.ai](https://zeroclawlabs.ai). Gracias por tu paciencia mientras preparábamos el lanzamiento. Seguimos viendo intentos de suplantación, así que **no** te unas a ninguna actividad de inversión o recaudación que use el nombre de ZeroClaw a menos que se publique a través de nuestros canales oficiales. | Usa [este repositorio](https://github.com/zeroclaw-labs/zeroclaw) como la única fuente de verdad. Sigue [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupo)](https://www.facebook.com/groups/zeroclawlabs) y [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) para actualizaciones oficiales. |
|
||||
| 2026-02-19 | _Importante_ | Anthropic actualizó los términos de Autenticación y Uso de Credenciales el 2026-02-19. Los tokens OAuth de Claude Code (Free, Pro, Max) están destinados exclusivamente para Claude Code y Claude.ai; usar tokens OAuth de Claude Free/Pro/Max en cualquier otro producto, herramienta o servicio (incluyendo Agent SDK) no está permitido y puede violar los Términos de Servicio del Consumidor. | Por favor, evita temporalmente las integraciones OAuth de Claude Code para prevenir pérdidas potenciales. Cláusula original: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Características destacadas
|
||||
|
||||
- **Runtime ligero por defecto** — los flujos de trabajo comunes de CLI y estado se ejecutan en una envolvente de memoria de pocos megabytes en compilaciones release.
|
||||
- **Despliegue económico** — diseñado para placas de $10 e instancias pequeñas en la nube, sin dependencias de runtime pesadas.
|
||||
- **Arranque en frío rápido** — el runtime de Rust con un solo binario mantiene el inicio de comandos y del daemon casi instantáneo.
|
||||
- **Arquitectura portable** — un binario para ARM, x86 y RISC-V con proveedores/canales/herramientas intercambiables.
|
||||
- **Gateway local-first** — un solo plano de control para sesiones, canales, herramientas, cron, SOPs y eventos.
|
||||
- **Bandeja de entrada multicanal** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket y más.
|
||||
- **Orquestación multi-agente (Hands)** — enjambres de agentes autónomos que se ejecutan según programación y se vuelven más inteligentes con el tiempo.
|
||||
- **Procedimientos Operativos Estándar (SOPs)** — automatización de flujos de trabajo dirigida por eventos con MQTT, webhook, cron y disparadores de periféricos.
|
||||
- **Panel web** — interfaz web React 19 + Vite con chat en tiempo real, explorador de memoria, editor de configuración, gestor de cron e inspector de herramientas.
|
||||
- **Periféricos de hardware** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO a través del trait `Peripheral`.
|
||||
- **Herramientas de primera clase** — shell, E/S de archivos, navegador, git, web fetch/search, MCP, Jira, Notion, Google Workspace y más de 70 más.
|
||||
- **Hooks de ciclo de vida** — intercepta y modifica llamadas LLM, ejecuciones de herramientas y mensajes en cada etapa.
|
||||
- **Plataforma de skills** — skills incluidos, comunitarios y del workspace con auditoría de seguridad.
|
||||
- **Soporte de túneles** — Cloudflare, Tailscale, ngrok, OpenVPN y túneles personalizados para acceso remoto.
|
||||
|
||||
### Por qué los equipos eligen ZeroClaw
|
||||
|
||||
- **Ligero por defecto:** binario pequeño de Rust, arranque rápido, bajo consumo de memoria.
|
||||
- **Seguro por diseño:** emparejamiento, sandboxing estricto, listas de permitidos explícitas, alcance del workspace.
|
||||
- **Totalmente intercambiable:** los sistemas centrales son traits (proveedores, canales, herramientas, memoria, túneles).
|
||||
- **Sin dependencia de proveedor:** soporte de proveedores compatibles con OpenAI + endpoints personalizados conectables.
|
||||
|
||||
## Resumen de benchmarks (ZeroClaw vs OpenClaw, reproducible)
|
||||
|
||||
Benchmark rápido en máquina local (macOS arm64, febrero 2026) normalizado para hardware edge de 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Lenguaje** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Arranque (core 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Tamaño del binario** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Costo** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Cualquier hardware $10** |
|
||||
|
||||
> Notas: Los resultados de ZeroClaw se miden en compilaciones release usando `/usr/bin/time -l`. OpenClaw requiere el runtime de Node.js (típicamente ~390MB de sobrecarga adicional de memoria), mientras que NanoBot requiere el runtime de Python. PicoClaw y ZeroClaw son binarios estáticos. Las cifras de RAM anteriores son de memoria en runtime; los requisitos de compilación son mayores.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Medición local reproducible
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Todo lo que hemos construido hasta ahora
|
||||
|
||||
### Plataforma central
|
||||
|
||||
- Plano de control Gateway HTTP/WS/SSE con sesiones, presencia, configuración, cron, webhooks, panel web y emparejamiento.
|
||||
- Superficie CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Bucle de orquestación del agente con despacho de herramientas, construcción de prompts, clasificación de mensajes y carga de memoria.
|
||||
- Modelo de sesión con aplicación de políticas de seguridad, niveles de autonomía y aprobación condicional.
|
||||
- Wrapper de proveedor resiliente con failover, reintentos y enrutamiento de modelos a través de más de 20 backends LLM.
|
||||
|
||||
### Canales
|
||||
|
||||
Canales: WhatsApp (nativo), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Habilitados por feature gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Panel web
|
||||
|
||||
Panel web React 19 + Vite 6 + Tailwind CSS 4 servido directamente desde el Gateway:
|
||||
|
||||
- **Dashboard** — resumen del sistema, estado de salud, tiempo de actividad, seguimiento de costos
|
||||
- **Chat del agente** — chat interactivo con el agente
|
||||
- **Memoria** — explorar y gestionar entradas de memoria
|
||||
- **Configuración** — ver y editar configuración
|
||||
- **Cron** — gestionar tareas programadas
|
||||
- **Herramientas** — explorar herramientas disponibles
|
||||
- **Registros** — ver registros de actividad del agente
|
||||
- **Costos** — uso de tokens y seguimiento de costos
|
||||
- **Doctor** — diagnósticos de salud del sistema
|
||||
- **Integraciones** — estado y configuración de integraciones
|
||||
- **Emparejamiento** — gestión de emparejamiento de dispositivos
|
||||
|
||||
### Objetivos de firmware
|
||||
|
||||
| Objetivo | Plataforma | Propósito |
|
||||
|----------|------------|-----------|
|
||||
| ESP32 | Espressif ESP32 | Agente periférico inalámbrico |
|
||||
| ESP32-UI | ESP32 + Display | Agente con interfaz visual |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periférico industrial |
|
||||
| Arduino | Arduino | Puente básico de sensores/actuadores |
|
||||
| Uno Q Bridge | Arduino Uno | Puente serial al agente |
|
||||
|
||||
### Herramientas + automatización
|
||||
|
||||
- **Core:** shell, lectura/escritura/edición de archivos, operaciones git, búsqueda glob, búsqueda de contenido
|
||||
- **Web:** control de navegador, web fetch, web search, captura de pantalla, información de imagen, lectura de PDF
|
||||
- **Integraciones:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + conjuntos de herramientas diferidos
|
||||
- **Programación:** cron add/remove/update/run, herramienta de programación
|
||||
- **Memoria:** recall, store, forget, knowledge, project intel
|
||||
- **Avanzado:** delegate (agente a agente), swarm, cambio/enrutamiento de modelos, operaciones de seguridad, operaciones en la nube
|
||||
- **Hardware:** board info, memory map, memory read (habilitado por feature gate)
|
||||
|
||||
### Runtime + seguridad
|
||||
|
||||
- **Niveles de autonomía:** ReadOnly, Supervised (predeterminado), Full.
|
||||
- **Sandboxing:** aislamiento del workspace, bloqueo de traversal de rutas, listas de comandos permitidos, rutas prohibidas, Landlock (Linux), Bubblewrap.
|
||||
- **Limitación de velocidad:** máximo de acciones por hora, máximo de costo por día (configurable).
|
||||
- **Aprobación condicional:** aprobación interactiva para operaciones de riesgo medio/alto.
|
||||
- **Parada de emergencia:** capacidad de apagado de emergencia.
|
||||
- **129+ pruebas de seguridad** en CI automatizado.
|
||||
|
||||
### Operaciones + empaquetado
|
||||
|
||||
- Panel web servido directamente desde el Gateway.
|
||||
- Soporte de túneles: Cloudflare, Tailscale, ngrok, OpenVPN, comando personalizado.
|
||||
- Adaptador de runtime Docker para ejecución en contenedores.
|
||||
- CI/CD: beta (automático al hacer push) → stable (dispatch manual) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Binarios preconstruidos para Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Configuración
|
||||
|
||||
`~/.zeroclaw/config.toml` mínimo:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Referencia completa de configuración: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Configuración de canales
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Configuración de túneles
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # o "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detalles: [Referencia de canales](docs/reference/api/channels-reference.md) · [Referencia de configuración](docs/reference/api/config-reference.md)
|
||||
|
||||
### Soporte de runtime (actual)
|
||||
|
||||
- **`native`** (predeterminado) — ejecución directa de procesos, la ruta más rápida, ideal para entornos de confianza.
|
||||
- **`docker`** — aislamiento completo en contenedores, políticas de seguridad forzadas, requiere Docker.
|
||||
|
||||
Establece `runtime.kind = "docker"` para sandboxing estricto o aislamiento de red.
|
||||
|
||||
## Autenticación por suscripción (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw soporta perfiles de autenticación nativos de suscripción (multi-cuenta, cifrados en reposo).
|
||||
|
||||
- Archivo de almacenamiento: `~/.zeroclaw/auth-profiles.json`
|
||||
- Clave de cifrado: `~/.zeroclaw/.secret_key`
|
||||
- Formato de id de perfil: `<provider>:<profile_name>` (ejemplo: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (suscripción ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Verificar / refrescar / cambiar perfil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Ejecutar el agente con autenticación por suscripción
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace del agente + skills
|
||||
|
||||
Raíz del workspace: `~/.zeroclaw/workspace/` (configurable vía config).
|
||||
|
||||
Archivos de prompt inyectados:
|
||||
- `IDENTITY.md` — personalidad y rol del agente
|
||||
- `USER.md` — contexto y preferencias del usuario
|
||||
- `MEMORY.md` — hechos y lecciones a largo plazo
|
||||
- `AGENTS.md` — convenciones de sesión y reglas de inicialización
|
||||
- `SOUL.md` — identidad central y principios operativos
|
||||
|
||||
Skills: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` o `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Listar skills instalados
|
||||
zeroclaw skills list
|
||||
|
||||
# Instalar desde git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Auditoría de seguridad antes de instalar
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Eliminar un skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Comandos CLI
|
||||
|
||||
```bash
|
||||
# Gestión del workspace
|
||||
zeroclaw onboard # Asistente de configuración guiada
|
||||
zeroclaw status # Mostrar estado del daemon/agente
|
||||
zeroclaw doctor # Ejecutar diagnósticos del sistema
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Iniciar servidor gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Iniciar runtime autónomo completo
|
||||
|
||||
# Agente
|
||||
zeroclaw agent # Modo de chat interactivo
|
||||
zeroclaw agent -m "message" # Modo de mensaje único
|
||||
|
||||
# Gestión de servicios
|
||||
zeroclaw service install # Instalar como servicio del SO (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Canales
|
||||
zeroclaw channel list # Listar canales configurados
|
||||
zeroclaw channel doctor # Verificar salud de los canales
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + programación
|
||||
zeroclaw cron list # Listar trabajos programados
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memoria
|
||||
zeroclaw memory list # Listar entradas de memoria
|
||||
zeroclaw memory get <key> # Recuperar una memoria
|
||||
zeroclaw memory stats # Estadísticas de memoria
|
||||
|
||||
# Perfiles de autenticación
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Periféricos de hardware
|
||||
zeroclaw hardware discover # Escanear dispositivos conectados
|
||||
zeroclaw peripheral list # Listar periféricos conectados
|
||||
zeroclaw peripheral flash # Flashear firmware al dispositivo
|
||||
|
||||
# Migración
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Completado de shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Referencia completa de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Prerrequisitos
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Requerido
|
||||
|
||||
1. **Visual Studio Build Tools** (proporciona el enlazador MSVC y el SDK de Windows):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Durante la instalación (o a través del Visual Studio Installer), selecciona la carga de trabajo **"Desarrollo de escritorio con C++"**.
|
||||
|
||||
2. **Toolchain de Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Después de la instalación, abre una nueva terminal y ejecuta `rustup default stable` para asegurarte de que el toolchain estable esté activo.
|
||||
|
||||
3. **Verifica** que ambos funcionen:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opcional
|
||||
|
||||
- **Docker Desktop** — requerido solo si usas el [runtime sandbox con Docker](#soporte-de-runtime-actual) (`runtime.kind = "docker"`). Instala vía `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Requerido
|
||||
|
||||
1. **Herramientas de compilación esenciales:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Instala Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Toolchain de Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Ver [rustup.rs](https://rustup.rs) para detalles.
|
||||
|
||||
3. **Verifica** que ambos funcionen:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Instalador en una línea
|
||||
|
||||
O salta los pasos anteriores e instala todo (dependencias del sistema, Rust, ZeroClaw) en un solo comando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Requisitos de recursos para compilación
|
||||
|
||||
Compilar desde el código fuente necesita más recursos que ejecutar el binario resultante:
|
||||
|
||||
| Recurso | Mínimo | Recomendado |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Disco libre**| 6 GB | 10 GB+ |
|
||||
|
||||
Si tu host está por debajo del mínimo, usa binarios preconstruidos:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Para requerir instalación solo de binarios sin compilación de respaldo:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opcional
|
||||
|
||||
- **Docker** — requerido solo si usas el [runtime sandbox con Docker](#soporte-de-runtime-actual) (`runtime.kind = "docker"`). Instala vía tu gestor de paquetes o [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Nota:** El `cargo build --release` predeterminado usa `codegen-units=1` para reducir la presión máxima de compilación. Para compilaciones más rápidas en máquinas potentes, usa `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Binarios preconstruidos
|
||||
|
||||
Los assets de release se publican para:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Descarga los últimos assets desde:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Documentación
|
||||
|
||||
Usa estos recursos cuando hayas pasado el flujo de onboarding y quieras la referencia más profunda.
|
||||
|
||||
- Comienza con el [índice de docs](docs/README.md) para navegación y "qué hay dónde."
|
||||
- Lee la [visión general de la arquitectura](docs/architecture.md) para el modelo completo del sistema.
|
||||
- Usa la [referencia de configuración](docs/reference/api/config-reference.md) cuando necesites cada clave y ejemplo.
|
||||
- Ejecuta el Gateway según el libro con el [runbook operativo](docs/ops/operations-runbook.md).
|
||||
- Sigue [ZeroClaw Onboard](#inicio-rápido) para una configuración guiada.
|
||||
- Depura errores comunes con la [guía de solución de problemas](docs/ops/troubleshooting.md).
|
||||
- Revisa la [guía de seguridad](docs/security/README.md) antes de exponer cualquier cosa.
|
||||
|
||||
### Documentación de referencia
|
||||
|
||||
- Hub de documentación: [docs/README.md](docs/README.md)
|
||||
- TOC unificado de docs: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Referencia de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Referencia de configuración: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Referencia de proveedores: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Referencia de canales: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Runbook operativo: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Solución de problemas: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Documentación de colaboración
|
||||
|
||||
- Guía de contribución: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Política de flujo de trabajo de PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Guía de flujo de trabajo CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Manual del revisor: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Política de divulgación de seguridad: [SECURITY.md](SECURITY.md)
|
||||
- Plantilla de documentación: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Despliegue + operaciones
|
||||
|
||||
- Guía de despliegue en red: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Manual de agente proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Guías de hardware: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw fue construido para el cangrejo suave 🦀, un asistente de IA rápido y eficiente. Construido por Argenis De La Rosa y la comunidad.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Apoya a ZeroClaw
|
||||
|
||||
Si ZeroClaw ayuda en tu trabajo y quieres apoyar el desarrollo continuo, puedes donar aquí:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Agradecimientos especiales
|
||||
|
||||
Un sincero agradecimiento a las comunidades e instituciones que inspiran e impulsan este trabajo de código abierto:
|
||||
|
||||
- **Harvard University** — por fomentar la curiosidad intelectual y empujar los límites de lo posible.
|
||||
- **MIT** — por defender el conocimiento abierto, el código abierto y la creencia de que la tecnología debe ser accesible para todos.
|
||||
- **Sundai Club** — por la comunidad, la energía y el impulso incansable de construir cosas que importan.
|
||||
- **El Mundo y Más Allá** 🌍✨ — a cada contribuidor, soñador y constructor que hace del código abierto una fuerza para el bien. Esto es para ti.
|
||||
|
||||
Estamos construyendo en abierto porque las mejores ideas vienen de todas partes. Si estás leyendo esto, eres parte de ello. Bienvenido. 🦀❤️
|
||||
|
||||
## Contribuir
|
||||
|
||||
¿Nuevo en ZeroClaw? Busca issues etiquetados como [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — consulta nuestra [Guía de contribución](CONTRIBUTING.md#first-time-contributors) para saber cómo empezar. ¡PRs con IA/vibe-coded son bienvenidos! 🤖
|
||||
|
||||
Ver [CONTRIBUTING.md](CONTRIBUTING.md) y [CLA.md](docs/contributing/cla.md). Implementa un trait, envía un PR:
|
||||
|
||||
- Guía de flujo de trabajo CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Nuevo `Provider` → `src/providers/`
|
||||
- Nuevo `Channel` → `src/channels/`
|
||||
- Nuevo `Observer` → `src/observability/`
|
||||
- Nuevo `Tool` → `src/tools/`
|
||||
- Nuevo `Memory` → `src/memory/`
|
||||
- Nuevo `Tunnel` → `src/tunnel/`
|
||||
- Nuevo `Peripheral` → `src/peripherals/`
|
||||
- Nuevo `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Repositorio oficial y advertencia de suplantación
|
||||
|
||||
**Este es el único repositorio oficial de ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Cualquier otro repositorio, organización, dominio o paquete que afirme ser "ZeroClaw" o implique afiliación con ZeroClaw Labs **no está autorizado y no está afiliado con este proyecto**. Los forks no autorizados conocidos se listarán en [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Si encuentras suplantación o uso indebido de marca, por favor [abre un issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licencia
|
||||
|
||||
ZeroClaw tiene doble licencia para máxima apertura y protección de los contribuidores:
|
||||
|
||||
| Licencia | Caso de uso |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Código abierto, investigación, académico, uso personal |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Protección de patentes, institucional, despliegue comercial |
|
||||
|
||||
Puedes elegir cualquiera de las licencias. **Los contribuidores otorgan automáticamente derechos bajo ambas** — ver [CLA.md](docs/contributing/cla.md) para el acuerdo completo de contribuidores.
|
||||
|
||||
### Marca registrada
|
||||
|
||||
El nombre y logo de **ZeroClaw** son marcas registradas de ZeroClaw Labs. Esta licencia no otorga permiso para usarlos para implicar respaldo o afiliación. Ver [TRADEMARK.md](docs/maintainers/trademark.md) para usos permitidos y prohibidos.
|
||||
|
||||
### Protecciones para contribuidores
|
||||
|
||||
- **Conservas el copyright** de tus contribuciones
|
||||
- **Concesión de patentes** (Apache 2.0) te protege de reclamaciones de patentes de otros contribuidores
|
||||
- Tus contribuciones son **permanentemente atribuidas** en el historial de commits y [NOTICE](NOTICE)
|
||||
- No se transfieren derechos de marca registrada al contribuir
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Cero sobrecarga. Cero compromisos. Despliega en cualquier lugar. Intercambia cualquier cosa. 🦀
|
||||
|
||||
## Contribuidores
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Esta lista se genera a partir del gráfico de contribuidores de GitHub y se actualiza automáticamente.
|
||||
|
||||
## Historial de estrellas
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.fi.md
755
README.fi.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Henkilokohtainen tekoalyavustaja</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nolla ylimaaraa. Nolla kompromisseja. 100% Rust. 100% Agnostinen.</strong><br>
|
||||
⚡️ <strong>Toimii $10 laitteistolla alle 5MB RAM:lla: Se on 99% vahemman muistia kuin OpenClaw ja 98% halvempaa kuin Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Rakennettu Harvardin, MIT:n ja Sundai.Club-yhteisöjen opiskelijoiden ja jasenien toimesta.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Kielet:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw on henkilokohtainen tekoalyavustaja, jota kaytat omilla laitteillasi. Se vastaa sinulle jo kayttamillasi kanavilla (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work ja muut). Silla on web-hallintapaneeli reaaliaikaiseen ohjaukseen ja se voi yhdistaa laitteistoperiferioihin (ESP32, STM32, Arduino, Raspberry Pi). Gateway on vain ohjaustaaso — tuote on avustaja.
|
||||
|
||||
Jos haluat henkilokohtaisen, yhden kayttajan avustajan, joka tuntuu paikalliselta, nopealta ja aina paalla olevalta, tama on se.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Verkkosivusto</a> ·
|
||||
<a href="docs/README.md">Dokumentaatio</a> ·
|
||||
<a href="docs/architecture.md">Arkkitehtuuri</a> ·
|
||||
<a href="#pikaaloitus-tldr">Aloita</a> ·
|
||||
<a href="#siirtyminen-openclawsta">Siirtyminen OpenClawsta</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Vianetsinta</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Suositeltu asennus:** suorita `zeroclaw onboard` terminaalissasi. ZeroClaw Onboard opastaa sinut vaihe vaiheelta gatewayn, tyotilan, kanavien ja palveluntarjoajan asennuksessa. Se on suositeltu asennuspolku ja toimii macOS:lla, Linuxilla ja Windowsilla (WSL2:n kautta). Uusi asennus? Aloita tasta: [Aloita](#pikaaloitus-tldr)
|
||||
|
||||
### Tilaustunnistautuminen (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-tilaus)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-avain tai tunnistautumistokeni)
|
||||
|
||||
Mallien huomautus: vaikka monia palveluntarjoajia/malleja tuetaan, parhaan kokemuksen saamiseksi kayta vahvinta saatavilla olevaa uusimman sukupolven mallia. Katso [Onboarding](#pikaaloitus-tldr).
|
||||
|
||||
Mallien konfiguraatio + CLI: [Palveluntarjoajien viite](docs/reference/api/providers-reference.md)
|
||||
Tunnistautumisprofiilin kierto (OAuth vs API-avaimet) + failover: [Mallien failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Asennus (suositeltu)
|
||||
|
||||
Ajoymparisto: Rust stable toolchain. Yksi binaari, ei ajoympariston riippuvuuksia.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Yhden napsautuksen asennus
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` suoritetaan automaattisesti asennuksen jalkeen tyotilan ja palveluntarjoajan konfiguroimiseksi.
|
||||
|
||||
## Pikaaloitus (TL;DR)
|
||||
|
||||
Taysi aloittelijan opas (tunnistautuminen, paritus, kanavat): [Aloita](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Asennus + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Kaynnista gateway (webhook-palvelin + web-hallintapaneeli)
|
||||
zeroclaw gateway # oletus: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # satunnainen portti (turvallisuuskovennettu)
|
||||
|
||||
# Puhu avustajalle
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktiivinen tila
|
||||
zeroclaw agent
|
||||
|
||||
# Kaynnista taysi autonominen ajoymparisto (gateway + kanavat + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Tarkista tila
|
||||
zeroclaw status
|
||||
|
||||
# Suorita diagnostiikka
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Paivitat? Suorita `zeroclaw doctor` paivityksen jalkeen.
|
||||
|
||||
### Lahdekoodista (kehitys)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Kehitysvaihtoehto (ei globaalia asennusta):** lisaa komentoihin etuliite `cargo run --release --` (esimerkki: `cargo run --release -- status`).
|
||||
|
||||
## Siirtyminen OpenClawsta
|
||||
|
||||
ZeroClaw voi tuoda OpenClaw-tyotilasi, muistisi ja maaritykset:
|
||||
|
||||
```bash
|
||||
# Esikatsele mita siirretaan (turvallinen, vain luku)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Suorita siirto
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Tama siirtaa muistimerkinnot, tyotilan tiedostot ja maaritykset hakemistosta `~/.openclaw/` hakemistoon `~/.zeroclaw/`. Maaritykset muunnetaan automaattisesti JSON:sta TOML:ksi.
|
||||
|
||||
## Turvallisuuden oletusasetukset (DM-paasy)
|
||||
|
||||
ZeroClaw yhdistaa todellisiin viestintapintoihin. Kasittele saapuvia DM-viesteja luottamattomana syotteena.
|
||||
|
||||
Taysi turvallisuusopas: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Oletuskayttaytyminen kaikilla kanavilla:
|
||||
|
||||
- **DM-paritus** (oletus): tuntemattomat lahettajat saavat lyhyen parituskoodin ja botti ei kasittele heidan viestiaan.
|
||||
- Hyvaksy komennolla: `zeroclaw pairing approve <channel> <code>` (jonka jalkeen lahettaja lisataan paikalliselle sallittujen listalle).
|
||||
- Julkiset saapuvat DM:t vaativat nimenomaisen opt-in-asetuksen `config.toml`-tiedostossa.
|
||||
- Suorita `zeroclaw doctor` tunnistaaksesi riskilliset tai vaarinkonfiguroidut DM-kaytannot.
|
||||
|
||||
**Autonomiatasot:**
|
||||
|
||||
| Taso | Kayttaytyminen |
|
||||
|------|----------------|
|
||||
| `ReadOnly` | Agentti voi tarkkailla mutta ei toimia |
|
||||
| `Supervised` (oletus) | Agentti toimii hyvaksynnalla keskitason/korkean riskin toiminnoissa |
|
||||
| `Full` | Agentti toimii itsenaisesti kaytantorajojen sisalla |
|
||||
|
||||
**Sandboxing-kerrokset:** tyotilan eristys, polun lapikulun esto, komentojen sallittujen listat, kielletyt polut (`/etc`, `/root`, `~/.ssh`), nopeusrajoitus (max toiminnot/tunti, kustannus/paiva-rajoitukset).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Ilmoitukset
|
||||
|
||||
Kayta tata taulua tarkeisiin ilmoituksiin (yhteensopivuutta rikkovat muutokset, turvallisuustiedotteet, yllapitoikkunat ja julkaisun estajat).
|
||||
|
||||
| Paivamaara (UTC) | Taso | Ilmoitus | Toimenpide |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kriittinen_ | **Emme** ole yhteydessa `openagen/zeroclaw`-, `zeroclaw.org`- tai `zeroclaw.net`-sivustoihin. `zeroclaw.org`- ja `zeroclaw.net`-verkkotunnukset osoittavat talla hetkella `openagen/zeroclaw`-haaraan, ja tuo verkkotunnus/varasto esiintyy virallisen verkkosivustomme/projektimme nimissa. | Ala luota naista lahteista perasin oleviin tietoihin, binaareihin, varainkeruuseen tai ilmoituksiin. Kayta vain [tata varastoa](https://github.com/zeroclaw-labs/zeroclaw) ja vahvistettuja sosiaalisen median tilejamme. |
|
||||
| 2026-02-21 | _Tarkea_ | Virallinen verkkosivustomme on nyt toiminnassa: [zeroclawlabs.ai](https://zeroclawlabs.ai). Kiitos karsivallisyydestanne julkaisun valmistelun aikana. Nakemme edelleen esiintymisyrityksia, joten **ala** liity mihinkaan sijoitus- tai varainkeruutoimintaan, joka vaittaa ZeroClaw-nimea, ellei se ole julkaistu virallisten kanaviemme kautta. | Kayta [tata varastoa](https://github.com/zeroclaw-labs/zeroclaw) ainoana totuuden lahteena. Seuraa [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) ja [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) virallisia paivityksia varten. |
|
||||
| 2026-02-19 | _Tarkea_ | Anthropic paivitti tunnistautumis- ja tunnistetietojen kaytonehdat 2026-02-19. Claude Code OAuth -tokenit (Free, Pro, Max) on tarkoitettu yksinomaan Claude Codelle ja Claude.ai:lle; OAuth-tokenien kayttaminen Claude Free/Pro/Max -palvelusta missaan muussa tuotteessa, tyokalussa tai palvelussa (mukaan lukien Agent SDK) ei ole sallittua ja voi rikkoa kuluttajakayttoehtoja. | Ole hyva ja valta valikaisesti Claude Code OAuth -integraatioita mahdollisen menetyksen estamiseksi. Alkuperainen lauseke: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Kohokodat
|
||||
|
||||
- **Kevyt ajoymparisto oletuksena** — tavalliset CLI- ja tilatyonkulut toimivat muutaman megatavun muistibudjetissa release-buildeissa.
|
||||
- **Kustannustehokas kayttoönotto** — suunniteltu $10-korteille ja pienille pilvi-instansseille, ilman raskaita ajoympariston riippuvuuksia.
|
||||
- **Nopeat kylmakaunnistykset** — yhden binaarin Rust-ajoymparisto pitaa komento- ja daemon-kaynnistyksen lahes valittomana.
|
||||
- **Siirrettava arkkitehtuuri** — yksi binaari ARM-, x86- ja RISC-V-alustoilla vaihdettavilla palveluntarjoajilla/kanavilla/tyokaluilla.
|
||||
- **Paikallinen-ensin Gateway** — yksi ohjaustaaso istunnoille, kanaville, tyokaluille, cronille, SOP:ille ja tapahtumille.
|
||||
- **Monikanavainen saapuva** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket ja muut.
|
||||
- **Moniagentin orkestrointi (Hands)** — autonomiset agenttiparvet, jotka toimivat aikataulutettusti ja alykkyytyvat ajan myota.
|
||||
- **Vakiotoimintamenettelyt (SOPs)** — tapahtumapohjainen tyonkulun automatisointi MQTT-, webhook-, cron- ja periferia-laukaisijoilla.
|
||||
- **Web-hallintapaneeli** — React 19 + Vite web-kayttoliittyma reaaliaikaisella chatilla, muistiselaimella, maaritysten muokkaimella, cron-hallinnalla ja tyokalujen tarkastimella.
|
||||
- **Laitteistoperiferiat** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO `Peripheral`-traitin kautta.
|
||||
- **Ensiluokkaiset tyokalut** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace ja 70+ lisaa.
|
||||
- **Elinkaarikoukut** — LLM-kutsujen, tyokalujen suoritusten ja viestien sieppaus ja muokkaus joka vaiheessa.
|
||||
- **Taitoplattformi** — sisaanrakennetut, yhteison ja tyotilan taidot turvallisuustarkastuksella.
|
||||
- **Tunnelituki** — Cloudflare, Tailscale, ngrok, OpenVPN ja mukautetut tunnelit etapaasyyn.
|
||||
|
||||
### Miksi tiimit valitsevat ZeroClaw:n
|
||||
|
||||
- **Kevyt oletuksena:** pieni Rust-binaari, nopea kaynnistys, alhainen muistijalanjalki.
|
||||
- **Turvallinen suunnittelulla:** paritus, tiukka sandboxing, nimenomaiset sallittujen listat, tyotilan rajaus.
|
||||
- **Taysin vaihdettava:** ydinjarjestelmat ovat traiteja (providers, channels, tools, memory, tunnels).
|
||||
- **Ei lukkiutumista:** OpenAI-yhteensopiva palveluntarjoajatuki + liitettavat mukautetut paatepisteet.
|
||||
|
||||
## Vertailun tilannekuva (ZeroClaw vs OpenClaw, Toistettava)
|
||||
|
||||
Paikallisen koneen pikavertailu (macOS arm64, helmi 2026) normalisoitu 0.8GHz reunalaitteistolle.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Kieli** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Kaynnistys (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binaarin koko** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Kustannus** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Mika tahansa laitteisto $10** |
|
||||
|
||||
> Huomautukset: ZeroClaw-tulokset mitattu release-buildeilla kayttaen `/usr/bin/time -l`. OpenClaw vaatii Node.js-ajoympariston (tyypillisesti ~390MB ylimaaraista muistikuormaa), kun taas NanoBot vaatii Python-ajoympariston. PicoClaw ja ZeroClaw ovat staattisia binaareja. Yllaolevat RAM-luvut ovat ajoaikaista muistia; kaannosaikaiset vaatimukset ovat korkeammat.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Toistettava paikallinen mittaus
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Kaikki mita olemme rakentaneet tahan mennessa
|
||||
|
||||
### Ydinplattformi
|
||||
|
||||
- Gateway HTTP/WS/SSE -ohjaustaaso istunnoilla, lasnaololla, maarityksilla, cronilla, webhookeilla, web-hallintapaneelilla ja parituksella.
|
||||
- CLI-pinta: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agentin orkestroinnin silmukka tyokalujen lahettamisella, kehotteen rakentamisella, viestien luokittelulla ja muistin lataamisella.
|
||||
- Istuntomalli turvallisuuskaytannon noudattamisella, autonomiatasoilla ja hyvaksyntaporttauksella.
|
||||
- Kestava palveluntarjoajan kapselointi failoverilla, uudelleenyrityksella ja mallien reitityksella 20+ LLM-taustalle.
|
||||
|
||||
### Kanavat
|
||||
|
||||
Kanavat: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Web-hallintapaneeli
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 web-hallintapaneeli, jota tarjoillaan suoraan Gatewaysta:
|
||||
|
||||
- **Dashboard** — jarjestelman yleiskatsaus, terveydentila, kaynnissaoloaika, kustannusten seuranta
|
||||
- **Agent Chat** — interaktiivinen keskustelu agentin kanssa
|
||||
- **Memory** — muistimerkintöjen selaus ja hallinta
|
||||
- **Config** — maaritysten katselu ja muokkaus
|
||||
- **Cron** — ajastettujen tehtavien hallinta
|
||||
- **Tools** — kaytettavissa olevien tyokalujen selaus
|
||||
- **Logs** — agentin toimintalokien katselu
|
||||
- **Cost** — tokenien kaytto ja kustannusten seuranta
|
||||
- **Doctor** — jarjestelman terveysdiagnostiikka
|
||||
- **Integrations** — integraatioiden tila ja asennus
|
||||
- **Pairing** — laiteparituksen hallinta
|
||||
|
||||
### Firmware-kohteet
|
||||
|
||||
| Kohde | Alusta | Tarkoitus |
|
||||
|-------|--------|-----------|
|
||||
| ESP32 | Espressif ESP32 | Langaton periferia-agentti |
|
||||
| ESP32-UI | ESP32 + Display | Agentti visuaalisella kayttoliittymalla |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Teollinen periferia |
|
||||
| Arduino | Arduino | Perusanturi-/toimilaitesilta |
|
||||
| Uno Q Bridge | Arduino Uno | Sarjasilta agenttiin |
|
||||
|
||||
### Tyokalut + automatisointi
|
||||
|
||||
- **Ydin:** shell, file read/write/edit, git operations, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Integraatiot:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Ajastus:** cron add/remove/update/run, schedule tool
|
||||
- **Muisti:** recall, store, forget, knowledge, project intel
|
||||
- **Edistyneet:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Laitteisto:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Ajoymparisto + turvallisuus
|
||||
|
||||
- **Autonomiatasot:** ReadOnly, Supervised (oletus), Full.
|
||||
- **Sandboxing:** tyotilan eristys, polun lapikulun esto, komentojen sallittujen listat, kielletyt polut, Landlock (Linux), Bubblewrap.
|
||||
- **Nopeusrajoitus:** max toiminnot tunnissa, max kustannus paivassa (konfiguroitavissa).
|
||||
- **Hyvaksyntaporttaus:** interaktiivinen hyvaksynta keskitason/korkean riskin toiminnoille.
|
||||
- **E-stop:** hatapysaytysmahdollisuus.
|
||||
- **129+ turvallisuustestia** automatisoidussa CI:ssa.
|
||||
|
||||
### Toiminnot + paketointi
|
||||
|
||||
- Web-hallintapaneeli tarjoillaan suoraan Gatewaysta.
|
||||
- Tunnelituki: Cloudflare, Tailscale, ngrok, OpenVPN, mukautettu komento.
|
||||
- Docker runtime -adapteri konttiin ajettuun suoritukseen.
|
||||
- CI/CD: beta (auto on push) → stable (manual dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Valmiit binaarit Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Maaritykset
|
||||
|
||||
Minimaalinen `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Taysi maaritysviite: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanavan maaritys
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnelin maaritys
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Lisatietoja: [Kanavaviite](docs/reference/api/channels-reference.md) · [Maaritysviite](docs/reference/api/config-reference.md)
|
||||
|
||||
### Ajoymparistotuki (nykyinen)
|
||||
|
||||
- **`native`** (oletus) — suora prosessin suoritus, nopein polku, ihanteellinen luotetuissa ymparistoissa.
|
||||
- **`docker`** — taysi konttieristys, pakotetut turvallisuuskaytannot, vaatii Dockerin.
|
||||
|
||||
Aseta `runtime.kind = "docker"` tiukkaan sandboxingiin tai verkon eristykseen.
|
||||
|
||||
## Tilaustunnistautuminen (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw tukee tilausnatiiveja tunnistautumisprofiileja (useita tileja, salattu levossa).
|
||||
|
||||
- Tallennustiedosto: `~/.zeroclaw/auth-profiles.json`
|
||||
- Salausavain: `~/.zeroclaw/.secret_key`
|
||||
- Profiilin tunnistemuoto: `<provider>:<profile_name>` (esimerkki: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agentin tyotila + taidot
|
||||
|
||||
Tyotilan juuri: `~/.zeroclaw/workspace/` (konfiguroitavissa maaritysten kautta).
|
||||
|
||||
Injektoidut kehotetiedostot:
|
||||
- `IDENTITY.md` — agentin persoona ja rooli
|
||||
- `USER.md` — kayttajan konteksti ja mieltymykset
|
||||
- `MEMORY.md` — pitkaaikaiset tosiasiat ja opit
|
||||
- `AGENTS.md` — istuntokonventiot ja alustussaannot
|
||||
- `SOUL.md` — ydinidentiteetti ja toimintaperiaatteet
|
||||
|
||||
Taidot: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` tai `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-komennot
|
||||
|
||||
```bash
|
||||
# Tyotilan hallinta
|
||||
zeroclaw onboard # Opastettu asennusvelho
|
||||
zeroclaw status # Nayta daemon/agentin tila
|
||||
zeroclaw doctor # Suorita jarjestelman diagnostiikka
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Kaynnista gateway-palvelin (127.0.0.1:42617)
|
||||
zeroclaw daemon # Kaynnista taysi autonominen ajoymparisto
|
||||
|
||||
# Agentti
|
||||
zeroclaw agent # Interaktiivinen keskustelutila
|
||||
zeroclaw agent -m "message" # Yksittaisen viestin tila
|
||||
|
||||
# Palvelun hallinta
|
||||
zeroclaw service install # Asenna OS-palveluna (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanavat
|
||||
zeroclaw channel list # Listaa konfiguroidut kanavat
|
||||
zeroclaw channel doctor # Tarkista kanavien terveys
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + ajastus
|
||||
zeroclaw cron list # Listaa ajastetut tehtavat
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Muisti
|
||||
zeroclaw memory list # Listaa muistimerkinnot
|
||||
zeroclaw memory get <key> # Hae muisti
|
||||
zeroclaw memory stats # Muistin tilastot
|
||||
|
||||
# Tunnistautumisprofiilit
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Laitteistoperiferiat
|
||||
zeroclaw hardware discover # Etsi yhdistettuja laitteita
|
||||
zeroclaw peripheral list # Listaa yhdistetyt periferiat
|
||||
zeroclaw peripheral flash # Flash-ohjelma laitteeseen
|
||||
|
||||
# Siirto
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-taydennykset
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Taysi komentoreferenssi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Esivaatimukset
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Vaaditut
|
||||
|
||||
1. **Visual Studio Build Tools** (tarjoaa MSVC-linkerin ja Windows SDK:n):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Asennuksen aikana (tai Visual Studio Installerin kautta) valitse **"Desktop development with C++"** -tyokuorma.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Asennuksen jalkeen avaa uusi terminaali ja suorita `rustup default stable` varmistaaksesi, etta vakaa toolchain on aktiivinen.
|
||||
|
||||
3. **Vahvista**, etta molemmat toimivat:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Valinnainen
|
||||
|
||||
- **Docker Desktop** — vaaditaan vain kaytettaessa [Docker sandboxed runtime](#ajoymparistotuki-nykyinen) (`runtime.kind = "docker"`). Asenna komennolla `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Vaaditut
|
||||
|
||||
1. **Kaannostyokalut:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Asenna Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Katso [rustup.rs](https://rustup.rs) lisatietoja varten.
|
||||
|
||||
3. **Vahvista**, etta molemmat toimivat:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Yhden rivin asentaja
|
||||
|
||||
Tai ohita yllaolevat vaiheet ja asenna kaikki (jarjestelmariippuvuudet, Rust, ZeroClaw) yhdella komennolla:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Kaannosresurssivaatimukset
|
||||
|
||||
Lahdekoodista rakentaminen vaatii enemman resursseja kuin tuloksena olevan binaarin suorittaminen:
|
||||
|
||||
| Resurssi | Vahimmais | Suositeltu |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Vapaa levy** | 6 GB | 10 GB+ |
|
||||
|
||||
Jos isantasi on vahimmaisvaatimuksen alla, kayta valmiita binaareja:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Pelkan binaarin asennukseen ilman lahdekoodi-vaihtoehtoa:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Valinnainen
|
||||
|
||||
- **Docker** — vaaditaan vain kaytettaessa [Docker sandboxed runtime](#ajoymparistotuki-nykyinen) (`runtime.kind = "docker"`). Asenna paketinhallintasi kautta tai [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Huomautus:** Oletus `cargo build --release` kayttaa `codegen-units=1` kaannoshuippupaineen vahentamiseksi. Nopeampiin kaanntöihin tehokkailla koneilla kayta `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Valmiit binaarit
|
||||
|
||||
Julkaisuresurssit julkaistaan seuraaville:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Lataa uusimmat resurssit osoitteesta:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentaatio
|
||||
|
||||
Kayta naita, kun olet ohittanut onboarding-kulun ja haluat syvemman viitteen.
|
||||
|
||||
- Aloita [dokumentaatioindeksista](docs/README.md) navigointiin ja "mika on missa" -tietoon.
|
||||
- Lue [arkkitehtuurin yleiskatsaus](docs/architecture.md) taydelliseen jarjestelmamalliin.
|
||||
- Kayta [maaritysviitetta](docs/reference/api/config-reference.md), kun tarvitset jokaisen avaimen ja esimerkin.
|
||||
- Suorita Gateway kirjan mukaan [kayttokirjalla](docs/ops/operations-runbook.md).
|
||||
- Noudata [ZeroClaw Onboard](#pikaaloitus-tldr) -palvelua opastettuun asennukseen.
|
||||
- Korjaa yleisia vikoja [vianetsintaoppaalla](docs/ops/troubleshooting.md).
|
||||
- Tarkista [turvallisuusohjeet](docs/security/README.md) ennen kuin paljastat mitaan.
|
||||
|
||||
### Viitedokumentaatio
|
||||
|
||||
- Dokumentaatiokeskus: [docs/README.md](docs/README.md)
|
||||
- Yhtenaistetty sisallysluettelo: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Komentoreferenssi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Maaritysviite: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Palveluntarjoajien viite: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanavaviite: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Kayttokirja: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Vianetsinta: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Yhteistyodokumentaatio
|
||||
|
||||
- Osallistumisopas: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-tyonkulun kaytanto: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-tyonkulun opas: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Arvioijan kasikirja: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Turvallisuuden julkistuskaytanto: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentaatiomalli: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Kayttoönotto + toiminnot
|
||||
|
||||
- Verkkokayyttoönotto-opas: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-agentin kasikirja: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Laitteisto-oppaat: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw rakennettiin smooth crab 🦀 -kaveria varten, nopea ja tehokas tekoalyavustaja. Rakennettu Argenis De La Rosan ja yhteison toimesta.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Tue ZeroClaw:ta
|
||||
|
||||
Jos ZeroClaw auttaa tyossasi ja haluat tukea jatkuvaa kehitysta, voit lahjoittaa tassa:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Erityiskiitokset
|
||||
|
||||
Sydamellinen kiitos yhteisöille ja instituutioille, jotka inspiroivat ja ruokkivat tata avoimen lahdekoodin tyota:
|
||||
|
||||
- **Harvard University** — alyllisen uteliaisuuden edistamisesta ja mahdollisuuksien rajojen tyontamisesta.
|
||||
- **MIT** — avoimen tiedon, avoimen lahdekoodin ja uskon puolustamisesta, etta teknologian tulisi olla kaikkien saatavilla.
|
||||
- **Sundai Club** — yhteisosta, energiasta ja leppymattomasta halusta rakentaa tarkeita asioita.
|
||||
- **Maailma ja sen tuolla puolen** 🌍✨ — jokaiselle osallistujalle, haaveilijalle ja rakentajalle, joka tekee avoimesta lahdekoodista hyvan voiman. Tama on sinulle.
|
||||
|
||||
Rakennamme avoimesti, koska parhaat ideat tulevat kaikkialta. Jos luet taman, olet osa sita. Tervetuloa. 🦀❤️
|
||||
|
||||
## Osallistuminen
|
||||
|
||||
Uusi ZeroClaw:ssa? Etsi issueita merkinnalla [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — katso [Osallistumisoppaamme](CONTRIBUTING.md#first-time-contributors) aloittaaksesi. AI/vibe-koodatut PR:t tervetulleita! 🤖
|
||||
|
||||
Katso [CONTRIBUTING.md](CONTRIBUTING.md) ja [CLA.md](docs/contributing/cla.md). Toteuta trait, laheta PR:
|
||||
|
||||
- CI-tyonkulun opas: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Uusi `Provider` → `src/providers/`
|
||||
- Uusi `Channel` → `src/channels/`
|
||||
- Uusi `Observer` → `src/observability/`
|
||||
- Uusi `Tool` → `src/tools/`
|
||||
- Uusi `Memory` → `src/memory/`
|
||||
- Uusi `Tunnel` → `src/tunnel/`
|
||||
- Uusi `Peripheral` → `src/peripherals/`
|
||||
- Uusi `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Virallinen varasto ja esiintymisvaroitus
|
||||
|
||||
**Tama on ainoa virallinen ZeroClaw-varasto:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Mika tahansa muu varasto, organisaatio, verkkotunnus tai paketti, joka vaittaa olevansa "ZeroClaw" tai viittaa yhteyteen ZeroClaw Labsin kanssa, on **luvaton eika liity tahan projektiin**. Tunnetut luvattomat forkit listataan [TRADEMARK.md](docs/maintainers/trademark.md)-tiedostossa.
|
||||
|
||||
Jos kohtaat esiintymista tai tavaramerkin vaarinkayttoa, ole hyva ja [avaa issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Lisenssi
|
||||
|
||||
ZeroClaw on kaksoislisenssoitu maksimaalisen avoimuuden ja osallistujien suojan takaamiseksi:
|
||||
|
||||
| Lisenssi | Kayttotapaus |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Avoin lahdekoodi, tutkimus, akateeminen, henkilokohtainen kaytto |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patenttisuoja, institutionaalinen, kaupallinen kayttoönotto |
|
||||
|
||||
Voit valita kumman tahansa lisenssin. **Osallistujat myontavat automaattisesti oikeudet molempien alla** — katso [CLA.md](docs/contributing/cla.md) tayden osallistujasopimuksen.
|
||||
|
||||
### Tavaramerkki
|
||||
|
||||
**ZeroClaw**-nimi ja logo ovat ZeroClaw Labsin tavaramerkkeja. Tama lisenssi ei anna lupaa kayttaa niita tuen tai yhteyden vihjamiseen. Katso [TRADEMARK.md](docs/maintainers/trademark.md) sallittujen ja kiellettyjen kayttojen osalta.
|
||||
|
||||
### Osallistujien suojat
|
||||
|
||||
- **Sailytat tekijanoikeuden** osallistumisiisi
|
||||
- **Patenttimyonnos** (Apache 2.0) suojaa sinua muiden osallistujien patenttivaatimuksilta
|
||||
- Osallistumisesi ovat **pysyvasti attribuoitu** commit-historiassa ja [NOTICE](NOTICE)-tiedostossa
|
||||
- Tavaramerkkioikeuksia ei siirreta osallistumalla
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nolla ylimaaraa. Nolla kompromisseja. Kayttoönotto minne tahansa. Vaihda mita tahansa. 🦀
|
||||
|
||||
## Osallistujat
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Tama lista luodaan GitHubin osallistujakaaviosta ja paivittyy automaattisesti.
|
||||
|
||||
## Tahtihistoria
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
1317
README.fr.md
1317
README.fr.md
File diff suppressed because it is too large
Load Diff
755
README.he.md
755
README.he.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — עוזר AI אישי</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>אפס תקורה. אפס פשרות. 100% Rust. 100% אגנוסטי.</strong><br>
|
||||
⚡️ <strong>רץ על חומרה של $10 עם פחות מ-5MB RAM: זה 99% פחות זיכרון מ-OpenClaw ו-98% זול יותר מ-Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
נבנה על ידי סטודנטים וחברים מקהילות Harvard, MIT ו-Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>שפות:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw הוא עוזר AI אישי שאתה מריץ על המכשירים שלך. הוא עונה לך בערוצים שאתה כבר משתמש בהם (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, ועוד). יש לו לוח בקרה אינטרנטי לשליטה בזמן אמת ויכול להתחבר להתקנים היקפיים (ESP32, STM32, Arduino, Raspberry Pi). ה-Gateway הוא רק מישור הבקרה — המוצר הוא העוזר.
|
||||
|
||||
אם אתה רוצה עוזר אישי למשתמש יחיד שמרגיש מקומי, מהיר ותמיד פעיל, זה הוא.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">אתר</a> ·
|
||||
<a href="docs/README.md">תיעוד</a> ·
|
||||
<a href="docs/architecture.md">ארכיטקטורה</a> ·
|
||||
<a href="#התחלה-מהירה">התחלה</a> ·
|
||||
<a href="#מיגרציה-מ-openclaw">מיגרציה מ-OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">פתרון בעיות</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **הגדרה מועדפת:** הרץ `zeroclaw onboard` בטרמינל שלך. ZeroClaw Onboard מנחה אותך שלב אחר שלב בהגדרת ה-gateway, סביבת העבודה, הערוצים והספק. זהו נתיב ההגדרה המומלץ ועובד על macOS, Linux ו-Windows (דרך WSL2). התקנה חדשה? התחל כאן: [התחלה](#התחלה-מהירה)
|
||||
|
||||
### אימות מנוי (OAuth)
|
||||
|
||||
- **OpenAI Codex** (מנוי ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (מפתח API או אסימון אימות)
|
||||
|
||||
הערה על מודלים: בעוד שספקים/מודלים רבים נתמכים, לחוויה הטובה ביותר השתמש במודל הדור האחרון החזק ביותר הזמין לך. ראה [הכניסה](#התחלה-מהירה).
|
||||
|
||||
הגדרות מודלים + CLI: [מדריך ספקים](docs/reference/api/providers-reference.md)
|
||||
רוטציית פרופיל אימות (OAuth מול מפתחות API) + מעבר בכשל: [מעבר מודלים בכשל](docs/reference/api/providers-reference.md)
|
||||
|
||||
## התקנה (מומלץ)
|
||||
|
||||
סביבת ריצה: שרשרת כלים יציבה של Rust. בינארי יחיד, ללא תלויות סביבת ריצה.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### התקנה בלחיצה אחת
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` רץ אוטומטית לאחר ההתקנה כדי להגדיר את סביבת העבודה והספק שלך.
|
||||
|
||||
## התחלה מהירה (TL;DR)
|
||||
|
||||
מדריך מתחילים מלא (אימות, צימוד, ערוצים): [התחלה](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Install + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start the gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Talk to the assistant
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonomous runtime (gateway + channels + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
zeroclaw status
|
||||
|
||||
# Run diagnostics
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
משדרג? הרץ `zeroclaw doctor` לאחר העדכון.
|
||||
|
||||
### מקוד מקור (פיתוח)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **חלופת פיתוח (ללא התקנה גלובלית):** הוסף `cargo run --release --` לפני פקודות (דוגמה: `cargo run --release -- status`).
|
||||
|
||||
## מיגרציה מ-OpenClaw
|
||||
|
||||
ZeroClaw יכול לייבא את סביבת העבודה, הזיכרון וההגדרות של OpenClaw שלך:
|
||||
|
||||
```bash
|
||||
# Preview what will be migrated (safe, read-only)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Run the migration
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
זה מעביר את רשומות הזיכרון, קבצי סביבת העבודה וההגדרות מ-`~/.openclaw/` ל-`~/.zeroclaw/`. ההגדרות מומרות אוטומטית מ-JSON ל-TOML.
|
||||
|
||||
## ברירות מחדל אבטחה (גישת DM)
|
||||
|
||||
ZeroClaw מתחבר למשטחי הודעות אמיתיים. התייחס ל-DM נכנסים כקלט לא מהימן.
|
||||
|
||||
מדריך אבטחה מלא: [SECURITY.md](SECURITY.md)
|
||||
|
||||
התנהגות ברירת מחדל בכל הערוצים:
|
||||
|
||||
- **צימוד DM** (ברירת מחדל): שולחים לא מוכרים מקבלים קוד צימוד קצר והבוט לא מעבד את ההודעה שלהם.
|
||||
- אשר עם: `zeroclaw pairing approve <channel> <code>` (ואז השולח נוסף לרשימת היתרים מקומית).
|
||||
- DM נכנסים ציבוריים דורשים הסכמה מפורשת ב-`config.toml`.
|
||||
- הרץ `zeroclaw doctor` כדי לחשוף מדיניות DM מסוכנת או שגויה.
|
||||
|
||||
**רמות אוטונומיה:**
|
||||
|
||||
| רמה | התנהגות |
|
||||
|------|----------|
|
||||
| `ReadOnly` | הסוכן יכול לצפות אבל לא לפעול |
|
||||
| `Supervised` (ברירת מחדל) | הסוכן פועל עם אישור לפעולות בסיכון בינוני/גבוה |
|
||||
| `Full` | הסוכן פועל באופן אוטונומי בגבולות המדיניות |
|
||||
|
||||
**שכבות ארגז חול:** בידוד סביבת עבודה, חסימת מעבר נתיבים, רשימות היתר לפקודות, נתיבים אסורים (`/etc`, `/root`, `~/.ssh`), הגבלת קצב (מקסימום פעולות/שעה, מגבלות עלות/יום).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 הודעות
|
||||
|
||||
השתמש בלוח זה להודעות חשובות (שינויים שוברים, ייעוץ אבטחה, חלונות תחזוקה וחוסמי שחרור).
|
||||
|
||||
| תאריך (UTC) | רמה | הודעה | פעולה |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _קריטי_ | אנחנו **לא מזוהים** עם `openagen/zeroclaw`, `zeroclaw.org` או `zeroclaw.net`. הדומיינים `zeroclaw.org` ו-`zeroclaw.net` מפנים כרגע ל-fork `openagen/zeroclaw`, ואותו דומיין/מאגר מתחזים לאתר/פרויקט הרשמי שלנו. | אל תסמוך על מידע, בינאריים, גיוס כספים או הודעות ממקורות אלה. השתמש רק ב[מאגר זה](https://github.com/zeroclaw-labs/zeroclaw) ובחשבונות החברתיים המאומתים שלנו. |
|
||||
| 2026-02-21 | _חשוב_ | האתר הרשמי שלנו כעת פעיל: [zeroclawlabs.ai](https://zeroclawlabs.ai). תודה על הסבלנות בזמן שהכנו את ההשקה. אנחנו עדיין רואים ניסיונות התחזות, לכן **אל** תצטרפו לפעילות השקעה או גיוס כספים הטוענת לשם ZeroClaw אלא אם היא מפורסמת דרך הערוצים הרשמיים שלנו. | השתמש ב[מאגר זה](https://github.com/zeroclaw-labs/zeroclaw) כמקור האמת היחיד. עקוב אחרי [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) ו-[Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) לעדכונים רשמיים. |
|
||||
| 2026-02-19 | _חשוב_ | Anthropic עדכנה את תנאי Authentication and Credential Use ב-2026-02-19. אסימוני Claude Code OAuth (Free, Pro, Max) מיועדים אך ורק ל-Claude Code ול-Claude.ai; שימוש באסימוני OAuth מ-Claude Free/Pro/Max בכל מוצר, כלי או שירות אחר (כולל Agent SDK) אינו מותר ועלול להפר את תנאי השירות לצרכן. | אנא הימנעו זמנית מאינטגרציות Claude Code OAuth כדי למנוע אובדן פוטנציאלי. סעיף מקורי: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## יתרונות עיקריים
|
||||
|
||||
- **סביבת ריצה קלה כברירת מחדל** — תהליכי CLI וסטטוס שגרתיים רצים במעטפת זיכרון של כמה מגה-בייט על בנייות שחרור.
|
||||
- **פריסה חסכונית** — מתוכנן ללוחות של $10 ומופעי ענן קטנים, ללא תלויות סביבת ריצה כבדות.
|
||||
- **התחלה קרה מהירה** — סביבת ריצה Rust בבינארי יחיד שומרת על הפעלת פקודות ודמון כמעט מיידית.
|
||||
- **ארכיטקטורה ניידת** — בינארי אחד על ARM, x86 ו-RISC-V עם ספקים/ערוצים/כלים להחלפה.
|
||||
- **Gateway מקומי-תחילה** — מישור בקרה יחיד לסשנים, ערוצים, כלים, cron, SOPs ואירועים.
|
||||
- **תיבת דואר רב-ערוצית** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket, ועוד.
|
||||
- **תזמור רב-סוכנים (Hands)** — נחילי סוכנים אוטונומיים הפועלים לפי לוח זמנים ומשתפרים עם הזמן.
|
||||
- **נהלי הפעלה סטנדרטיים (SOPs)** — אוטומציית תהליכי עבודה מונעת אירועים עם MQTT, webhook, cron וטריגרים של התקנים היקפיים.
|
||||
- **לוח בקרה אינטרנטי** — ממשק משתמש React 19 + Vite עם צ'אט בזמן אמת, דפדפן זיכרון, עורך הגדרות, מנהל cron ומפקח כלים.
|
||||
- **התקנים היקפיים** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO דרך trait `Peripheral`.
|
||||
- **כלים מדרגה ראשונה** — shell, קריאה/כתיבה/עריכת קבצים, git, שליפת/חיפוש אינטרנט, MCP, Jira, Notion, Google Workspace, ו-70+ נוספים.
|
||||
- **הוקים של מחזור חיים** — יירוט ושינוי קריאות LLM, הרצות כלים והודעות בכל שלב.
|
||||
- **פלטפורמת מיומנויות** — מיומנויות מובנות, קהילתיות וסביבת עבודה עם ביקורת אבטחה.
|
||||
- **תמיכה במנהרות** — Cloudflare, Tailscale, ngrok, OpenVPN ומנהרות מותאמות לגישה מרחוק.
|
||||
|
||||
### למה צוותים בוחרים ב-ZeroClaw
|
||||
|
||||
- **קל כברירת מחדל:** בינארי Rust קטן, הפעלה מהירה, טביעת רגל זיכרון נמוכה.
|
||||
- **מאובטח מהתכנון:** צימוד, ארגז חול מחמיר, רשימות היתר מפורשות, תיחום סביבת עבודה.
|
||||
- **ניתן להחלפה מלאה:** מערכות ליבה הן traits (ספקים, ערוצים, כלים, זיכרון, מנהרות).
|
||||
- **ללא נעילת ספק:** תמיכה בספקים תואמי OpenAI + נקודות קצה מותאמות הניתנות לחיבור.
|
||||
|
||||
## תמונת מצב של ביצועים (ZeroClaw מול OpenClaw, ניתן לשחזור)
|
||||
|
||||
מדד מהיר על מכונה מקומית (macOS arm64, פברואר 2026) מנורמל לחומרת edge בתדר 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **שפה** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **הפעלה (ליבת 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **גודל בינארי** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **עלות** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **כל חומרה $10** |
|
||||
|
||||
> הערות: תוצאות ZeroClaw נמדדו על בנייות שחרור באמצעות `/usr/bin/time -l`. OpenClaw דורש סביבת ריצה Node.js (בדרך כלל ~390MB תקורת זיכרון נוספת), בעוד NanoBot דורש סביבת ריצה Python. PicoClaw ו-ZeroClaw הם בינאריים סטטיים. נתוני ה-RAM למעלה הם זיכרון סביבת ריצה; דרישות קומפילציה בזמן בנייה גבוהות יותר.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### מדידה מקומית ניתנת לשחזור
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## כל מה שבנינו עד כה
|
||||
|
||||
### פלטפורמת ליבה
|
||||
|
||||
- Gateway HTTP/WS/SSE מישור בקרה עם סשנים, נוכחות, הגדרות, cron, webhooks, לוח בקרה אינטרנטי וצימוד.
|
||||
- משטח CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- לולאת תזמור סוכן עם שליחת כלים, בניית פרומפט, סיווג הודעות וטעינת זיכרון.
|
||||
- מודל סשנים עם אכיפת מדיניות אבטחה, רמות אוטונומיה ושער אישור.
|
||||
- מעטפת ספק עמידה עם מעבר בכשל, ניסיון חוזר וניתוב מודלים על פני 20+ ממשקי LLM.
|
||||
|
||||
### ערוצים
|
||||
|
||||
ערוצים: WhatsApp (מקורי), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
מוגבלי-תכונה: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### לוח בקרה אינטרנטי
|
||||
|
||||
לוח בקרה React 19 + Vite 6 + Tailwind CSS 4 מוגש ישירות מה-Gateway:
|
||||
|
||||
- **לוח בקרה** — סקירת מערכת, מצב בריאות, זמן פעילות, מעקב עלויות
|
||||
- **צ'אט סוכן** — צ'אט אינטראקטיבי עם הסוכן
|
||||
- **זיכרון** — דפדוף וניהול רשומות זיכרון
|
||||
- **הגדרות** — צפייה ועריכת הגדרות
|
||||
- **Cron** — ניהול משימות מתוזמנות
|
||||
- **כלים** — דפדוף בכלים זמינים
|
||||
- **יומנים** — צפייה ביומני פעילות הסוכן
|
||||
- **עלות** — שימוש בטוקנים ומעקב עלויות
|
||||
- **דוקטור** — אבחון בריאות המערכת
|
||||
- **אינטגרציות** — מצב אינטגרציות והגדרה
|
||||
- **צימוד** — ניהול צימוד מכשירים
|
||||
|
||||
### יעדי קושחה
|
||||
|
||||
| יעד | פלטפורמה | מטרה |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | סוכן היקפי אלחוטי |
|
||||
| ESP32-UI | ESP32 + Display | סוכן עם ממשק חזותי |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | התקן היקפי תעשייתי |
|
||||
| Arduino | Arduino | גשר חיישן/מפעיל בסיסי |
|
||||
| Uno Q Bridge | Arduino Uno | גשר סריאלי לסוכן |
|
||||
|
||||
### כלים + אוטומציה
|
||||
|
||||
- **ליבה:** shell, קריאה/כתיבה/עריכת קבצים, פעולות git, חיפוש glob, חיפוש תוכן
|
||||
- **אינטרנט:** שליטה בדפדפן, web fetch, web search, צילום מסך, מידע תמונה, קריאת PDF
|
||||
- **אינטגרציות:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** מעטפת כלי Model Context Protocol + סטים של כלים מושהים
|
||||
- **תזמון:** cron add/remove/update/run, כלי תזמון
|
||||
- **זיכרון:** recall, store, forget, knowledge, project intel
|
||||
- **מתקדם:** delegate (סוכן-לסוכן), swarm, החלפת/ניתוב מודל, פעולות אבטחה, פעולות ענן
|
||||
- **חומרה:** מידע לוח, מפת זיכרון, קריאת זיכרון (מוגבל-תכונה)
|
||||
|
||||
### סביבת ריצה + אבטחה
|
||||
|
||||
- **רמות אוטונומיה:** ReadOnly, Supervised (ברירת מחדל), Full.
|
||||
- **ארגז חול:** בידוד סביבת עבודה, חסימת מעבר נתיבים, רשימות היתר לפקודות, נתיבים אסורים, Landlock (Linux), Bubblewrap.
|
||||
- **הגבלת קצב:** מקסימום פעולות בשעה, מקסימום עלות ביום (ניתן להגדרה).
|
||||
- **שער אישור:** אישור אינטראקטיבי לפעולות בסיכון בינוני/גבוה.
|
||||
- **עצירת חירום:** יכולת כיבוי חירום.
|
||||
- **129+ מבחני אבטחה** ב-CI אוטומטי.
|
||||
|
||||
### תפעול + אריזה
|
||||
|
||||
- לוח בקרה אינטרנטי מוגש ישירות מה-Gateway.
|
||||
- תמיכה במנהרות: Cloudflare, Tailscale, ngrok, OpenVPN, פקודה מותאמת.
|
||||
- מתאם סביבת ריצה Docker להרצה בקונטיינרים.
|
||||
- CI/CD: בטא (אוטומטי בדחיפה) → יציב (שליחה ידנית) → Docker, crates.io, Scoop, AUR, Homebrew, ציוץ.
|
||||
- בינאריים מוכנים מראש ל-Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## הגדרות
|
||||
|
||||
מינימלי `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
מדריך הגדרות מלא: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### הגדרת ערוצים
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### הגדרת מנהרות
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
פרטים: [מדריך ערוצים](docs/reference/api/channels-reference.md) · [מדריך הגדרות](docs/reference/api/config-reference.md)
|
||||
|
||||
### תמיכה בסביבת ריצה (נוכחי)
|
||||
|
||||
- **`native`** (ברירת מחדל) — הרצת תהליך ישירה, הנתיב המהיר ביותר, אידיאלי לסביבות מהימנות.
|
||||
- **`docker`** — בידוד קונטיינר מלא, מדיניות אבטחה נאכפת, דורש Docker.
|
||||
|
||||
הגדר `runtime.kind = "docker"` לארגז חול מחמיר או בידוד רשת.
|
||||
|
||||
## אימות מנוי (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw תומך בפרופילי אימות מקוריים למנוי (רב-חשבוני, מוצפן במנוחה).
|
||||
|
||||
- קובץ אחסון: `~/.zeroclaw/auth-profiles.json`
|
||||
- מפתח הצפנה: `~/.zeroclaw/.secret_key`
|
||||
- פורמט מזהה פרופיל: `<provider>:<profile_name>` (דוגמה: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## סביבת עבודה של הסוכן + מיומנויות
|
||||
|
||||
שורש סביבת עבודה: `~/.zeroclaw/workspace/` (ניתן להגדרה דרך ההגדרות).
|
||||
|
||||
קבצי פרומפט מוזרקים:
|
||||
- `IDENTITY.md` — אישיות ותפקיד הסוכן
|
||||
- `USER.md` — הקשר והעדפות המשתמש
|
||||
- `MEMORY.md` — עובדות ולקחים לטווח ארוך
|
||||
- `AGENTS.md` — מוסכמות סשן וכללי אתחול
|
||||
- `SOUL.md` — זהות ליבה ועקרונות הפעלה
|
||||
|
||||
מיומנויות: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` או `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## פקודות CLI
|
||||
|
||||
```bash
|
||||
# Workspace management
|
||||
zeroclaw onboard # Guided setup wizard
|
||||
zeroclaw status # Show daemon/agent status
|
||||
zeroclaw doctor # Run system diagnostics
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonomous runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactive chat mode
|
||||
zeroclaw agent -m "message" # Single message mode
|
||||
|
||||
# Service management
|
||||
zeroclaw service install # Install as OS service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Channels
|
||||
zeroclaw channel list # List configured channels
|
||||
zeroclaw channel doctor # Check channel health
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + scheduling
|
||||
zeroclaw cron list # List scheduled jobs
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memory
|
||||
zeroclaw memory list # List memory entries
|
||||
zeroclaw memory get <key> # Retrieve a memory
|
||||
zeroclaw memory stats # Memory statistics
|
||||
|
||||
# Auth profiles
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware peripherals
|
||||
zeroclaw hardware discover # Scan for connected devices
|
||||
zeroclaw peripheral list # List connected peripherals
|
||||
zeroclaw peripheral flash # Flash firmware to device
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell completions
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
מדריך פקודות מלא: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## דרישות מקדימות
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### נדרש
|
||||
|
||||
1. **Visual Studio Build Tools** (מספק את מקשר MSVC ו-Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
במהלך ההתקנה (או דרך Visual Studio Installer), בחר את עומס העבודה **"Desktop development with C++"**.
|
||||
|
||||
2. **שרשרת כלים Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
לאחר ההתקנה, פתח טרמינל חדש והרץ `rustup default stable` כדי לוודא ששרשרת הכלים היציבה פעילה.
|
||||
|
||||
3. **אמת** ששניהם עובדים:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### אופציונלי
|
||||
|
||||
- **Docker Desktop** — נדרש רק אם משתמשים ב[סביבת ריצה Docker בארגז חול](#תמיכה-בסביבת-ריצה-נוכחי) (`runtime.kind = "docker"`). התקן דרך `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### נדרש
|
||||
|
||||
1. **כלי בנייה:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** התקן Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **שרשרת כלים Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
ראה [rustup.rs](https://rustup.rs) לפרטים.
|
||||
|
||||
3. **אמת** ששניהם עובדים:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### מתקין בשורה אחת
|
||||
|
||||
או דלג על השלבים למעלה והתקן הכל (תלויות מערכת, Rust, ZeroClaw) בפקודה אחת:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### דרישות משאבי קומפילציה
|
||||
|
||||
בנייה מקוד מקור דורשת יותר משאבים מהרצת הבינארי המתקבל:
|
||||
|
||||
| משאב | מינימום | מומלץ |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **דיסק פנוי** | 6 GB | 10 GB+ |
|
||||
|
||||
אם המארח שלך מתחת למינימום, השתמש בבינאריים מוכנים מראש:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
כדי לדרוש התקנת בינארי בלבד ללא חלופת מקור:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### אופציונלי
|
||||
|
||||
- **Docker** — נדרש רק אם משתמשים ב[סביבת ריצה Docker בארגז חול](#תמיכה-בסביבת-ריצה-נוכחי) (`runtime.kind = "docker"`). התקן דרך מנהל החבילות שלך או [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **הערה:** ברירת המחדל `cargo build --release` משתמשת ב-`codegen-units=1` כדי להפחית לחץ קומפילציה שיא. לבנייות מהירות יותר על מכונות חזקות, השתמש ב-`cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### בינאריים מוכנים מראש
|
||||
|
||||
נכסי שחרור מפורסמים עבור:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
הורד את הנכסים האחרונים מ:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## תיעוד
|
||||
|
||||
השתמש באלה כשעברת את תהליך ההכניסה ורוצה את המדריך המעמיק יותר.
|
||||
|
||||
- התחל עם [אינדקס התיעוד](docs/README.md) לניווט ו"מה נמצא איפה."
|
||||
- קרא את [סקירת הארכיטקטורה](docs/architecture.md) למודל המערכת המלא.
|
||||
- השתמש ב[מדריך ההגדרות](docs/reference/api/config-reference.md) כשאתה צריך כל מפתח ודוגמה.
|
||||
- הפעל את ה-Gateway לפי הספר עם [מדריך התפעול](docs/ops/operations-runbook.md).
|
||||
- עקוב אחרי [ZeroClaw Onboard](#התחלה-מהירה) להגדרה מונחית.
|
||||
- אבחן כשלים נפוצים עם [מדריך פתרון בעיות](docs/ops/troubleshooting.md).
|
||||
- סקור את [הנחיות האבטחה](docs/security/README.md) לפני חשיפת משהו.
|
||||
|
||||
### תיעוד מדריכים
|
||||
|
||||
- מרכז תיעוד: [docs/README.md](docs/README.md)
|
||||
- תוכן עניינים מאוחד: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- מדריך פקודות: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- מדריך הגדרות: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- מדריך ספקים: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- מדריך ערוצים: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- מדריך תפעול: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- פתרון בעיות: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### תיעוד שיתוף פעולה
|
||||
|
||||
- מדריך תרומה: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- מדיניות תהליך PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- מדריך תהליך CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- מדריך סוקר: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- מדיניות חשיפת אבטחה: [SECURITY.md](SECURITY.md)
|
||||
- תבנית תיעוד: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### פריסה + תפעול
|
||||
|
||||
- מדריך פריסת רשת: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- מדריך סוכן פרוקסי: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- מדריכי חומרה: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw נבנה עבור ה-smooth crab 🦀, עוזר AI מהיר ויעיל. נבנה על ידי Argenis De La Rosa והקהילה.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## תמוך ב-ZeroClaw
|
||||
|
||||
אם ZeroClaw עוזר לעבודה שלך ואתה רוצה לתמוך בפיתוח המתמשך, אתה יכול לתרום כאן:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 תודה מיוחדת
|
||||
|
||||
תודה מכל הלב לקהילות ולמוסדות שמעוררים השראה ומניעים את עבודת הקוד הפתוח הזו:
|
||||
|
||||
- **Harvard University** — על טיפוח סקרנות אינטלקטואלית ודחיפת גבולות האפשרי.
|
||||
- **MIT** — על קידום ידע פתוח, קוד פתוח והאמונה שטכנולוגיה צריכה להיות נגישה לכולם.
|
||||
- **Sundai Club** — על הקהילה, האנרגיה והמאמץ הבלתי פוסק לבנות דברים שחשובים.
|
||||
- **העולם ומעבר** 🌍✨ — לכל תורם, חולם ובונה שם שהופך קוד פתוח לכוח לטובה. זה בשבילכם.
|
||||
|
||||
אנחנו בונים בגלוי כי הרעיונות הטובים ביותר מגיעים מכל מקום. אם אתה קורא את זה, אתה חלק מזה. ברוך הבא. 🦀❤️
|
||||
|
||||
## תרומה
|
||||
|
||||
חדש ב-ZeroClaw? חפש בעיות עם התווית [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — ראה את [מדריך התרומה](CONTRIBUTING.md#first-time-contributors) שלנו כדי להתחיל. PR של AI/vibe-coded מתקבלים בברכה! 🤖
|
||||
|
||||
ראה [CONTRIBUTING.md](CONTRIBUTING.md) ו-[CLA.md](docs/contributing/cla.md). ממש trait, שלח PR:
|
||||
|
||||
- מדריך תהליך CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- `Provider` חדש → `src/providers/`
|
||||
- `Channel` חדש → `src/channels/`
|
||||
- `Observer` חדש → `src/observability/`
|
||||
- `Tool` חדש → `src/tools/`
|
||||
- `Memory` חדש → `src/memory/`
|
||||
- `Tunnel` חדש → `src/tunnel/`
|
||||
- `Peripheral` חדש → `src/peripherals/`
|
||||
- `Skill` חדש → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ מאגר רשמי ואזהרת התחזות
|
||||
|
||||
**זהו מאגר ZeroClaw הרשמי היחיד:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
כל מאגר, ארגון, דומיין או חבילה אחרים הטוענים להיות "ZeroClaw" או מרמזים על שיוך ל-ZeroClaw Labs הם **לא מורשים ולא מזוהים עם פרויקט זה**. פורקים לא מורשים ידועים ירשמו ב-[TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
אם אתה נתקל בהתחזות או שימוש לרעה בסימן מסחרי, אנא [פתח issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## רישיון
|
||||
|
||||
ZeroClaw מורשה ברישיון כפול לפתיחות מקסימלית והגנה על תורמים:
|
||||
|
||||
| רישיון | מקרה שימוש |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | קוד פתוח, מחקר, אקדמי, שימוש אישי |
|
||||
| [Apache 2.0](LICENSE-APACHE) | הגנת פטנטים, מוסדי, פריסה מסחרית |
|
||||
|
||||
אתה יכול לבחור כל רישיון. **תורמים מעניקים זכויות באופן אוטומטי תחת שניהם** — ראה [CLA.md](docs/contributing/cla.md) להסכם התורם המלא.
|
||||
|
||||
### סימן מסחרי
|
||||
|
||||
השם והלוגו של **ZeroClaw** הם סימנים מסחריים של ZeroClaw Labs. רישיון זה אינו מעניק הרשאה להשתמש בהם כדי לרמוז על תמיכה או שיוך. ראה [TRADEMARK.md](docs/maintainers/trademark.md) לשימושים מותרים ואסורים.
|
||||
|
||||
### הגנות על תורמים
|
||||
|
||||
- אתה **שומר על זכויות יוצרים** על תרומותיך
|
||||
- **הענקת פטנט** (Apache 2.0) מגנה עליך מתביעות פטנט של תורמים אחרים
|
||||
- תרומותיך **מיוחסות באופן קבוע** בהיסטוריית הקומיטים וב-[NOTICE](NOTICE)
|
||||
- לא מועברות זכויות סימן מסחרי על ידי תרומה
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — אפס תקורה. אפס פשרות. פרוס בכל מקום. החלף הכל. 🦀
|
||||
|
||||
## תורמים
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
רשימה זו נוצרת מגרף התורמים של GitHub ומתעדכנת אוטומטית.
|
||||
|
||||
## היסטוריית כוכבים
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.hi.md
755
README.hi.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — व्यक्तिगत AI सहायक</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>शून्य ओवरहेड। शून्य समझौता। 100% Rust। 100% अज्ञेयवादी।</strong><br>
|
||||
⚡️ <strong>$10 के हार्डवेयर पर <5MB RAM के साथ चलता है: यह OpenClaw से 99% कम मेमोरी और Mac mini से 98% सस्ता है!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Harvard, MIT, और Sundai.Club समुदायों के छात्रों और सदस्यों द्वारा निर्मित।
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>भाषाएँ:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw एक व्यक्तिगत AI सहायक है जिसे आप अपने उपकरणों पर चलाते हैं। यह आपको उन चैनलों पर जवाब देता है जो आप पहले से उपयोग करते हैं (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, और अन्य)। इसमें रियल-टाइम नियंत्रण के लिए एक वेब डैशबोर्ड है और यह हार्डवेयर पेरीफेरल (ESP32, STM32, Arduino, Raspberry Pi) से जुड़ सकता है। Gateway केवल कंट्रोल प्लेन है — उत्पाद सहायक है।
|
||||
|
||||
यदि आप एक व्यक्तिगत, एकल-उपयोगकर्ता सहायक चाहते हैं जो स्थानीय, तेज़ और हमेशा चालू महसूस हो, तो यह है।
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">वेबसाइट</a> ·
|
||||
<a href="docs/README.md">दस्तावेज़</a> ·
|
||||
<a href="docs/architecture.md">आर्किटेक्चर</a> ·
|
||||
<a href="#त्वरित-शुरुआत">शुरू करें</a> ·
|
||||
<a href="#openclaw-से-माइग्रेशन">OpenClaw से माइग्रेशन</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">समस्या निवारण</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **पसंदीदा सेटअप:** अपने टर्मिनल में `zeroclaw onboard` चलाएँ। ZeroClaw Onboard आपको gateway, workspace, channels, और provider सेट करने में कदम-दर-कदम मार्गदर्शन करता है। यह अनुशंसित सेटअप पथ है और macOS, Linux, और Windows (WSL2 के माध्यम से) पर काम करता है। नया इंस्टॉल? यहाँ से शुरू करें: [शुरू करें](#त्वरित-शुरुआत)
|
||||
|
||||
### सब्सक्रिप्शन ऑथ (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT सब्सक्रिप्शन)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API key या auth token)
|
||||
|
||||
मॉडल नोट: जबकि कई प्रदाताओं/मॉडलों का समर्थन किया जाता है, सर्वोत्तम अनुभव के लिए अपने पास उपलब्ध सबसे मजबूत नवीनतम पीढ़ी के मॉडल का उपयोग करें। देखें [ऑनबोर्डिंग](#त्वरित-शुरुआत)।
|
||||
|
||||
मॉडल कॉन्फ़िग + CLI: [प्रदाता संदर्भ](docs/reference/api/providers-reference.md)
|
||||
ऑथ प्रोफ़ाइल रोटेशन (OAuth बनाम API keys) + फ़ेलओवर: [मॉडल फ़ेलओवर](docs/reference/api/providers-reference.md)
|
||||
|
||||
## इंस्टॉल (अनुशंसित)
|
||||
|
||||
रनटाइम: Rust स्थिर टूलचेन। एकल बाइनरी, कोई रनटाइम निर्भरता नहीं।
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### एक-क्लिक बूटस्ट्रैप
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` इंस्टॉल के बाद स्वचालित रूप से चलता है ताकि आपका workspace और provider कॉन्फ़िगर हो सके।
|
||||
|
||||
## त्वरित शुरुआत (TL;DR)
|
||||
|
||||
पूर्ण शुरुआती गाइड (ऑथ, पेयरिंग, चैनल): [शुरू करें](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Install + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start the gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Talk to the assistant
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonomous runtime (gateway + channels + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
zeroclaw status
|
||||
|
||||
# Run diagnostics
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
अपग्रेड कर रहे हैं? अपडेट के बाद `zeroclaw doctor` चलाएँ।
|
||||
|
||||
### स्रोत से (विकास)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **विकास फ़ॉलबैक (कोई ग्लोबल इंस्टॉल नहीं):** कमांड के आगे `cargo run --release --` लगाएँ (उदाहरण: `cargo run --release -- status`)।
|
||||
|
||||
## OpenClaw से माइग्रेशन
|
||||
|
||||
ZeroClaw आपके OpenClaw workspace, मेमोरी, और कॉन्फ़िगरेशन आयात कर सकता है:
|
||||
|
||||
```bash
|
||||
# Preview what will be migrated (safe, read-only)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Run the migration
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
यह आपकी मेमोरी प्रविष्टियों, workspace फ़ाइलों, और कॉन्फ़िगरेशन को `~/.openclaw/` से `~/.zeroclaw/` में माइग्रेट करता है। कॉन्फ़िग स्वचालित रूप से JSON से TOML में परिवर्तित हो जाता है।
|
||||
|
||||
## सुरक्षा डिफ़ॉल्ट (DM एक्सेस)
|
||||
|
||||
ZeroClaw वास्तविक मैसेजिंग सतहों से जुड़ता है। इनबाउंड DMs को अविश्वसनीय इनपुट के रूप में मानें।
|
||||
|
||||
पूर्ण सुरक्षा गाइड: [SECURITY.md](SECURITY.md)
|
||||
|
||||
सभी चैनलों पर डिफ़ॉल्ट व्यवहार:
|
||||
|
||||
- **DM पेयरिंग** (डिफ़ॉल्ट): अज्ञात प्रेषकों को एक छोटा पेयरिंग कोड मिलता है और बॉट उनका संदेश प्रोसेस नहीं करता।
|
||||
- इससे स्वीकृति दें: `zeroclaw pairing approve <channel> <code>` (फिर प्रेषक स्थानीय अनुमति सूची में जोड़ा जाता है)।
|
||||
- सार्वजनिक इनबाउंड DMs के लिए `config.toml` में स्पष्ट ऑप्ट-इन आवश्यक है।
|
||||
- जोखिमपूर्ण या गलत कॉन्फ़िगर DM नीतियों को सामने लाने के लिए `zeroclaw doctor` चलाएँ।
|
||||
|
||||
**स्वायत्तता स्तर:**
|
||||
|
||||
| स्तर | व्यवहार |
|
||||
|-------|----------|
|
||||
| `ReadOnly` | एजेंट देख सकता है लेकिन कार्य नहीं कर सकता |
|
||||
| `Supervised` (डिफ़ॉल्ट) | एजेंट मध्यम/उच्च जोखिम संचालन के लिए स्वीकृति के साथ कार्य करता है |
|
||||
| `Full` | एजेंट नीति सीमाओं के भीतर स्वायत्त रूप से कार्य करता है |
|
||||
|
||||
**सैंडबॉक्सिंग परतें:** workspace आइसोलेशन, पथ ट्रैवर्सल ब्लॉकिंग, कमांड अनुमति सूची, प्रतिबंधित पथ (`/etc`, `/root`, `~/.ssh`), दर सीमित करना (अधिकतम कार्य/घंटा, लागत/दिन सीमा)।
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 घोषणाएँ
|
||||
|
||||
महत्वपूर्ण सूचनाओं (ब्रेकिंग बदलाव, सुरक्षा सलाह, रखरखाव विंडो, और रिलीज़ ब्लॉकर) के लिए इस बोर्ड का उपयोग करें।
|
||||
|
||||
| तिथि (UTC) | स्तर | सूचना | कार्रवाई |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _गंभीर_ | हम `openagen/zeroclaw`, `zeroclaw.org` या `zeroclaw.net` से **संबद्ध नहीं** हैं। `zeroclaw.org` और `zeroclaw.net` डोमेन वर्तमान में `openagen/zeroclaw` फ़ोर्क की ओर इशारा करते हैं, और वह डोमेन/रिपॉजिटरी हमारी आधिकारिक वेबसाइट/प्रोजेक्ट का रूप धारण कर रहे हैं। | उन स्रोतों से जानकारी, बाइनरी, फंडरेजिंग, या घोषणाओं पर भरोसा न करें। केवल [यह रिपॉजिटरी](https://github.com/zeroclaw-labs/zeroclaw) और हमारे सत्यापित सोशल अकाउंट्स का उपयोग करें। |
|
||||
| 2026-02-21 | _महत्वपूर्ण_ | हमारी आधिकारिक वेबसाइट अब लाइव है: [zeroclawlabs.ai](https://zeroclawlabs.ai)। लॉन्च की तैयारी करते समय आपके धैर्य के लिए धन्यवाद। हम अभी भी प्रतिरूपण प्रयास देख रहे हैं, इसलिए किसी भी निवेश या फंडरेजिंग गतिविधि में **शामिल न हों** जो ZeroClaw नाम का दावा करती है जब तक कि यह हमारे आधिकारिक चैनलों के माध्यम से प्रकाशित न हो। | [यह रिपॉजिटरी](https://github.com/zeroclaw-labs/zeroclaw) को सत्य के एकमात्र स्रोत के रूप में उपयोग करें। आधिकारिक अपडेट के लिए [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs), और [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) को फ़ॉलो करें। |
|
||||
| 2026-02-19 | _महत्वपूर्ण_ | Anthropic ने 2026-02-19 को Authentication and Credential Use शर्तें अपडेट कीं। Claude Code OAuth टोकन (Free, Pro, Max) विशेष रूप से Claude Code और Claude.ai के लिए हैं; Claude Free/Pro/Max से OAuth टोकन का किसी अन्य उत्पाद, उपकरण, या सेवा (Agent SDK सहित) में उपयोग अनुमत नहीं है और उपभोक्ता सेवा की शर्तों का उल्लंघन हो सकता है। | संभावित नुकसान को रोकने के लिए कृपया Claude Code OAuth एकीकरण से अस्थायी रूप से बचें। मूल खंड: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)। |
|
||||
|
||||
## मुख्य विशेषताएँ
|
||||
|
||||
- **डिफ़ॉल्ट रूप से हल्का रनटाइम** — सामान्य CLI और स्थिति वर्कफ़्लो रिलीज़ बिल्ड पर कुछ-मेगाबाइट मेमोरी एन्वेलप में चलते हैं।
|
||||
- **लागत-कुशल डिप्लॉयमेंट** — $10 बोर्ड और छोटे क्लाउड इंस्टेंस के लिए डिज़ाइन किया गया, कोई भारी रनटाइम निर्भरता नहीं।
|
||||
- **तेज़ कोल्ड स्टार्ट** — एकल-बाइनरी Rust रनटाइम कमांड और डेमन स्टार्टअप को लगभग तत्काल रखता है।
|
||||
- **पोर्टेबल आर्किटेक्चर** — ARM, x86, और RISC-V पर एक बाइनरी जिसमें स्वैपेबल प्रदाता/चैनल/उपकरण हैं।
|
||||
- **लोकल-फर्स्ट Gateway** — सेशन, चैनल, टूल, cron, SOPs, और इवेंट के लिए एकल कंट्रोल प्लेन।
|
||||
- **मल्टी-चैनल इनबॉक्स** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket, और अन्य।
|
||||
- **मल्टी-एजेंट ऑर्केस्ट्रेशन (Hands)** — स्वायत्त एजेंट स्वार्म जो शेड्यूल पर चलते हैं और समय के साथ स्मार्ट होते जाते हैं।
|
||||
- **मानक संचालन प्रक्रियाएँ (SOPs)** — MQTT, webhook, cron, और पेरीफेरल ट्रिगर के साथ इवेंट-ड्रिवन वर्कफ़्लो ऑटोमेशन।
|
||||
- **वेब डैशबोर्ड** — React 19 + Vite वेब UI जिसमें रियल-टाइम चैट, मेमोरी ब्राउज़र, कॉन्फ़िग एडिटर, cron मैनेजर, और टूल इंस्पेक्टर है।
|
||||
- **हार्डवेयर पेरीफेरल** — `Peripheral` trait के माध्यम से ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO।
|
||||
- **प्रथम-श्रेणी उपकरण** — shell, फ़ाइल I/O, browser, git, वेब fetch/search, MCP, Jira, Notion, Google Workspace, और 70+ अन्य।
|
||||
- **लाइफसाइकल हुक** — हर चरण पर LLM कॉल, टूल निष्पादन, और संदेशों को इंटरसेप्ट और संशोधित करें।
|
||||
- **स्किल प्लेटफ़ॉर्म** — बंडल, समुदाय, और workspace स्किल जिनमें सुरक्षा ऑडिटिंग है।
|
||||
- **टनल सपोर्ट** — रिमोट एक्सेस के लिए Cloudflare, Tailscale, ngrok, OpenVPN, और कस्टम टनल।
|
||||
|
||||
### टीमें ZeroClaw क्यों चुनती हैं
|
||||
|
||||
- **डिफ़ॉल्ट रूप से हल्का:** छोटी Rust बाइनरी, तेज़ स्टार्टअप, कम मेमोरी फुटप्रिंट।
|
||||
- **डिज़ाइन से सुरक्षित:** पेयरिंग, सख्त सैंडबॉक्सिंग, स्पष्ट अनुमति सूचियाँ, workspace स्कोपिंग।
|
||||
- **पूरी तरह से स्वैपेबल:** कोर सिस्टम traits हैं (providers, channels, tools, memory, tunnels)।
|
||||
- **कोई लॉक-इन नहीं:** OpenAI-संगत प्रदाता समर्थन + प्लगेबल कस्टम एंडपॉइंट।
|
||||
|
||||
## बेंचमार्क स्नैपशॉट (ZeroClaw बनाम OpenClaw, प्रतिलिपि योग्य)
|
||||
|
||||
स्थानीय मशीन त्वरित बेंचमार्क (macOS arm64, फ़रवरी 2026) 0.8GHz एज हार्डवेयर के लिए सामान्यीकृत।
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **भाषा** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **स्टार्टअप (0.8GHz कोर)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **बाइनरी आकार** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **लागत** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **कोई भी हार्डवेयर $10** |
|
||||
|
||||
> नोट: ZeroClaw परिणाम `/usr/bin/time -l` का उपयोग करके रिलीज़ बिल्ड पर मापे गए हैं। OpenClaw को Node.js रनटाइम की आवश्यकता है (आमतौर पर ~390MB अतिरिक्त मेमोरी ओवरहेड), जबकि NanoBot को Python रनटाइम की आवश्यकता है। PicoClaw और ZeroClaw स्टैटिक बाइनरी हैं। ऊपर दिए गए RAM आँकड़े रनटाइम मेमोरी हैं; बिल्ड-टाइम कंपाइलेशन आवश्यकताएँ अधिक हैं।
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### प्रतिलिपि योग्य स्थानीय माप
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## अब तक हमने जो कुछ बनाया है
|
||||
|
||||
### कोर प्लेटफ़ॉर्म
|
||||
|
||||
- Gateway HTTP/WS/SSE कंट्रोल प्लेन जिसमें सेशन, प्रेज़ेंस, कॉन्फ़िग, cron, webhooks, वेब डैशबोर्ड, और पेयरिंग है।
|
||||
- CLI सरफेस: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`।
|
||||
- एजेंट ऑर्केस्ट्रेशन लूप जिसमें टूल डिस्पैच, प्रॉम्प्ट निर्माण, संदेश वर्गीकरण, और मेमोरी लोडिंग है।
|
||||
- सुरक्षा नीति प्रवर्तन, स्वायत्तता स्तर, और अनुमोदन गेटिंग के साथ सेशन मॉडल।
|
||||
- 20+ LLM बैकएंड पर फ़ेलओवर, रिट्राई, और मॉडल रूटिंग के साथ रेज़िलिएंट प्रदाता रैपर।
|
||||
|
||||
### चैनल
|
||||
|
||||
चैनल: WhatsApp (नेटिव), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk।
|
||||
|
||||
फ़ीचर-गेटेड: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`)।
|
||||
|
||||
### वेब डैशबोर्ड
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 वेब डैशबोर्ड सीधे Gateway से सर्व किया जाता है:
|
||||
|
||||
- **डैशबोर्ड** — सिस्टम अवलोकन, स्वास्थ्य स्थिति, अपटाइम, लागत ट्रैकिंग
|
||||
- **एजेंट चैट** — एजेंट के साथ इंटरैक्टिव चैट
|
||||
- **मेमोरी** — मेमोरी प्रविष्टियाँ ब्राउज़ और प्रबंधित करें
|
||||
- **कॉन्फ़िग** — कॉन्फ़िगरेशन देखें और संपादित करें
|
||||
- **Cron** — शेड्यूल किए गए कार्य प्रबंधित करें
|
||||
- **टूल्स** — उपलब्ध उपकरण ब्राउज़ करें
|
||||
- **लॉग्स** — एजेंट गतिविधि लॉग देखें
|
||||
- **लागत** — टोकन उपयोग और लागत ट्रैकिंग
|
||||
- **डॉक्टर** — सिस्टम स्वास्थ्य डायग्नोस्टिक्स
|
||||
- **इंटीग्रेशन** — इंटीग्रेशन स्थिति और सेटअप
|
||||
- **पेयरिंग** — डिवाइस पेयरिंग प्रबंधन
|
||||
|
||||
### फ़र्मवेयर लक्ष्य
|
||||
|
||||
| लक्ष्य | प्लेटफ़ॉर्म | उद्देश्य |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | वायरलेस पेरीफेरल एजेंट |
|
||||
| ESP32-UI | ESP32 + Display | विज़ुअल इंटरफ़ेस वाला एजेंट |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | औद्योगिक पेरीफेरल |
|
||||
| Arduino | Arduino | बेसिक सेंसर/एक्चुएटर ब्रिज |
|
||||
| Uno Q Bridge | Arduino Uno | एजेंट के लिए सीरियल ब्रिज |
|
||||
|
||||
### उपकरण + ऑटोमेशन
|
||||
|
||||
- **कोर:** shell, फ़ाइल read/write/edit, git ऑपरेशन, glob search, content search
|
||||
- **वेब:** ब्राउज़र नियंत्रण, web fetch, web search, screenshot, image info, PDF read
|
||||
- **इंटीग्रेशन:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol टूल रैपर + डिफ़र्ड टूल सेट
|
||||
- **शेड्यूलिंग:** cron add/remove/update/run, schedule tool
|
||||
- **मेमोरी:** recall, store, forget, knowledge, project intel
|
||||
- **उन्नत:** delegate (एजेंट-टू-एजेंट), swarm, model switch/routing, security ops, cloud ops
|
||||
- **हार्डवेयर:** board info, memory map, memory read (फ़ीचर-गेटेड)
|
||||
|
||||
### रनटाइम + सुरक्षा
|
||||
|
||||
- **स्वायत्तता स्तर:** ReadOnly, Supervised (डिफ़ॉल्ट), Full।
|
||||
- **सैंडबॉक्सिंग:** workspace आइसोलेशन, पथ ट्रैवर्सल ब्लॉकिंग, कमांड अनुमति सूचियाँ, प्रतिबंधित पथ, Landlock (Linux), Bubblewrap।
|
||||
- **दर सीमित:** प्रति घंटे अधिकतम कार्य, प्रति दिन अधिकतम लागत (कॉन्फ़िगर योग्य)।
|
||||
- **अनुमोदन गेटिंग:** मध्यम/उच्च जोखिम संचालन के लिए इंटरैक्टिव अनुमोदन।
|
||||
- **आपातकालीन रोक:** आपातकालीन शटडाउन क्षमता।
|
||||
- **129+ सुरक्षा परीक्षण** स्वचालित CI में।
|
||||
|
||||
### ऑप्स + पैकेजिंग
|
||||
|
||||
- वेब डैशबोर्ड सीधे Gateway से सर्व किया जाता है।
|
||||
- टनल सपोर्ट: Cloudflare, Tailscale, ngrok, OpenVPN, कस्टम कमांड।
|
||||
- कंटेनराइज़्ड निष्पादन के लिए Docker रनटाइम एडेप्टर।
|
||||
- CI/CD: बीटा (पुश पर ऑटो) → स्टेबल (मैनुअल डिस्पैच) → Docker, crates.io, Scoop, AUR, Homebrew, ट्वीट।
|
||||
- Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64) के लिए प्री-बिल्ट बाइनरी।
|
||||
|
||||
|
||||
## कॉन्फ़िगरेशन
|
||||
|
||||
न्यूनतम `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
पूर्ण कॉन्फ़िगरेशन संदर्भ: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)।
|
||||
|
||||
### चैनल कॉन्फ़िगरेशन
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### टनल कॉन्फ़िगरेशन
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
विवरण: [चैनल संदर्भ](docs/reference/api/channels-reference.md) · [कॉन्फ़िग संदर्भ](docs/reference/api/config-reference.md)
|
||||
|
||||
### रनटाइम सपोर्ट (वर्तमान)
|
||||
|
||||
- **`native`** (डिफ़ॉल्ट) — सीधा प्रोसेस निष्पादन, सबसे तेज़ पथ, विश्वसनीय वातावरण के लिए आदर्श।
|
||||
- **`docker`** — पूर्ण कंटेनर आइसोलेशन, लागू सुरक्षा नीतियाँ, Docker आवश्यक।
|
||||
|
||||
सख्त सैंडबॉक्सिंग या नेटवर्क आइसोलेशन के लिए `runtime.kind = "docker"` सेट करें।
|
||||
|
||||
## सब्सक्रिप्शन ऑथ (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw सब्सक्रिप्शन-नेटिव ऑथ प्रोफ़ाइल का समर्थन करता है (मल्टी-अकाउंट, रेस्ट पर एन्क्रिप्टेड)।
|
||||
|
||||
- स्टोर फ़ाइल: `~/.zeroclaw/auth-profiles.json`
|
||||
- एन्क्रिप्शन कुंजी: `~/.zeroclaw/.secret_key`
|
||||
- प्रोफ़ाइल id फ़ॉर्मेट: `<provider>:<profile_name>` (उदाहरण: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## एजेंट workspace + स्किल
|
||||
|
||||
Workspace रूट: `~/.zeroclaw/workspace/` (कॉन्फ़िग के माध्यम से कॉन्फ़िगर करने योग्य)।
|
||||
|
||||
इंजेक्ट किए गए प्रॉम्प्ट फ़ाइलें:
|
||||
- `IDENTITY.md` — एजेंट का व्यक्तित्व और भूमिका
|
||||
- `USER.md` — उपयोगकर्ता संदर्भ और प्राथमिकताएँ
|
||||
- `MEMORY.md` — दीर्घकालिक तथ्य और सबक
|
||||
- `AGENTS.md` — सेशन सम्मेलन और इनिशियलाइज़ेशन नियम
|
||||
- `SOUL.md` — कोर पहचान और संचालन सिद्धांत
|
||||
|
||||
स्किल: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` या `SKILL.toml`।
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI कमांड
|
||||
|
||||
```bash
|
||||
# Workspace management
|
||||
zeroclaw onboard # Guided setup wizard
|
||||
zeroclaw status # Show daemon/agent status
|
||||
zeroclaw doctor # Run system diagnostics
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonomous runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactive chat mode
|
||||
zeroclaw agent -m "message" # Single message mode
|
||||
|
||||
# Service management
|
||||
zeroclaw service install # Install as OS service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Channels
|
||||
zeroclaw channel list # List configured channels
|
||||
zeroclaw channel doctor # Check channel health
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + scheduling
|
||||
zeroclaw cron list # List scheduled jobs
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memory
|
||||
zeroclaw memory list # List memory entries
|
||||
zeroclaw memory get <key> # Retrieve a memory
|
||||
zeroclaw memory stats # Memory statistics
|
||||
|
||||
# Auth profiles
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware peripherals
|
||||
zeroclaw hardware discover # Scan for connected devices
|
||||
zeroclaw peripheral list # List connected peripherals
|
||||
zeroclaw peripheral flash # Flash firmware to device
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell completions
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
पूर्ण कमांड संदर्भ: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## पूर्वापेक्षाएँ
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### आवश्यक
|
||||
|
||||
1. **Visual Studio Build Tools** (MSVC लिंकर और Windows SDK प्रदान करता है):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
इंस्टॉलेशन के दौरान (या Visual Studio Installer के माध्यम से), **"Desktop development with C++"** वर्कलोड चुनें।
|
||||
|
||||
2. **Rust टूलचेन:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
इंस्टॉलेशन के बाद, एक नया टर्मिनल खोलें और `rustup default stable` चलाएँ ताकि स्थिर टूलचेन सक्रिय हो।
|
||||
|
||||
3. **सत्यापित करें** कि दोनों काम कर रहे हैं:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### वैकल्पिक
|
||||
|
||||
- **Docker Desktop** — केवल तभी आवश्यक जब [Docker सैंडबॉक्स्ड रनटाइम](#रनटाइम-सपोर्ट-वर्तमान) (`runtime.kind = "docker"`) का उपयोग कर रहे हों। `winget install Docker.DockerDesktop` से इंस्टॉल करें।
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### आवश्यक
|
||||
|
||||
1. **बिल्ड एसेंशियल:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Xcode Command Line Tools इंस्टॉल करें: `xcode-select --install`
|
||||
|
||||
2. **Rust टूलचेन:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
विवरण के लिए [rustup.rs](https://rustup.rs) देखें।
|
||||
|
||||
3. **सत्यापित करें** कि दोनों काम कर रहे हैं:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### एक-पंक्ति इंस्टॉलर
|
||||
|
||||
या ऊपर के चरणों को छोड़ें और एक ही कमांड में सब कुछ (सिस्टम deps, Rust, ZeroClaw) इंस्टॉल करें:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### कंपाइलेशन संसाधन आवश्यकताएँ
|
||||
|
||||
स्रोत से बिल्ड करने के लिए परिणामी बाइनरी चलाने से अधिक संसाधनों की आवश्यकता होती है:
|
||||
|
||||
| संसाधन | न्यूनतम | अनुशंसित |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **खाली डिस्क** | 6 GB | 10 GB+ |
|
||||
|
||||
यदि आपका होस्ट न्यूनतम से नीचे है, तो प्री-बिल्ट बाइनरी का उपयोग करें:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
बिना सोर्स फ़ॉलबैक के केवल बाइनरी इंस्टॉल की आवश्यकता के लिए:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### वैकल्पिक
|
||||
|
||||
- **Docker** — केवल तभी आवश्यक जब [Docker सैंडबॉक्स्ड रनटाइम](#रनटाइम-सपोर्ट-वर्तमान) (`runtime.kind = "docker"`) का उपयोग कर रहे हों। अपने पैकेज मैनेजर या [docker.com](https://docs.docker.com/engine/install/) से इंस्टॉल करें।
|
||||
|
||||
> **नोट:** डिफ़ॉल्ट `cargo build --release` पीक कंपाइल प्रेशर कम करने के लिए `codegen-units=1` का उपयोग करता है। शक्तिशाली मशीनों पर तेज़ बिल्ड के लिए, `cargo build --profile release-fast` का उपयोग करें।
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### प्री-बिल्ट बाइनरी
|
||||
|
||||
रिलीज़ एसेट इसके लिए प्रकाशित किए जाते हैं:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
नवीनतम एसेट यहाँ से डाउनलोड करें:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## दस्तावेज़
|
||||
|
||||
इनका उपयोग तब करें जब आप ऑनबोर्डिंग प्रवाह से आगे हों और गहरा संदर्भ चाहें।
|
||||
|
||||
- नेविगेशन और "क्या कहाँ है" के लिए [दस्तावेज़ सूचकांक](docs/README.md) से शुरू करें।
|
||||
- पूर्ण सिस्टम मॉडल के लिए [आर्किटेक्चर अवलोकन](docs/architecture.md) पढ़ें।
|
||||
- जब आपको हर कुंजी और उदाहरण चाहिए तो [कॉन्फ़िगरेशन संदर्भ](docs/reference/api/config-reference.md) का उपयोग करें।
|
||||
- [संचालन रनबुक](docs/ops/operations-runbook.md) के अनुसार Gateway चलाएँ।
|
||||
- मार्गदर्शित सेटअप के लिए [ZeroClaw Onboard](#त्वरित-शुरुआत) का पालन करें।
|
||||
- [समस्या निवारण गाइड](docs/ops/troubleshooting.md) से सामान्य विफलताओं का निदान करें।
|
||||
- कुछ भी एक्सपोज़ करने से पहले [सुरक्षा मार्गदर्शन](docs/security/README.md) की समीक्षा करें।
|
||||
|
||||
### संदर्भ दस्तावेज़
|
||||
|
||||
- दस्तावेज़ हब: [docs/README.md](docs/README.md)
|
||||
- एकीकृत दस्तावेज़ TOC: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- कमांड संदर्भ: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- कॉन्फ़िग संदर्भ: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- प्रदाता संदर्भ: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- चैनल संदर्भ: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- संचालन रनबुक: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- समस्या निवारण: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### सहयोग दस्तावेज़
|
||||
|
||||
- योगदान गाइड: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR वर्कफ़्लो नीति: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI वर्कफ़्लो गाइड: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- समीक्षक प्लेबुक: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- सुरक्षा प्रकटीकरण नीति: [SECURITY.md](SECURITY.md)
|
||||
- दस्तावेज़ टेम्पलेट: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### डिप्लॉयमेंट + संचालन
|
||||
|
||||
- नेटवर्क डिप्लॉयमेंट गाइड: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- प्रॉक्सी एजेंट प्लेबुक: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- हार्डवेयर गाइड: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw को smooth crab 🦀 के लिए बनाया गया था, एक तेज़ और कुशल AI सहायक। Argenis De La Rosa और समुदाय द्वारा निर्मित।
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ZeroClaw का समर्थन करें
|
||||
|
||||
यदि ZeroClaw आपके काम में मदद करता है और आप चल रहे विकास का समर्थन करना चाहते हैं, तो आप यहाँ दान कर सकते हैं:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 विशेष धन्यवाद
|
||||
|
||||
उन समुदायों और संस्थानों को हृदय से धन्यवाद जो इस ओपन-सोर्स कार्य को प्रेरित और ईंधन देते हैं:
|
||||
|
||||
- **Harvard University** — बौद्धिक जिज्ञासा को बढ़ावा देने और संभावनाओं की सीमाओं को आगे बढ़ाने के लिए।
|
||||
- **MIT** — खुले ज्ञान, ओपन सोर्स, और इस विश्वास का समर्थन करने के लिए कि तकनीक सभी के लिए सुलभ होनी चाहिए।
|
||||
- **Sundai Club** — समुदाय, ऊर्जा, और महत्वपूर्ण चीज़ें बनाने के अथक प्रयास के लिए।
|
||||
- **दुनिया और उससे परे** 🌍✨ — हर योगदानकर्ता, सपने देखने वाले, और बिल्डर के लिए जो ओपन सोर्स को भलाई की शक्ति बना रहे हैं। यह आपके लिए है।
|
||||
|
||||
हम खुले में बना रहे हैं क्योंकि सबसे अच्छे विचार हर जगह से आते हैं। यदि आप यह पढ़ रहे हैं, तो आप इसका हिस्सा हैं। स्वागत है। 🦀❤️
|
||||
|
||||
## योगदान
|
||||
|
||||
ZeroClaw में नए हैं? [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) लेबल वाले मुद्दों की तलाश करें — शुरू करने का तरीका जानने के लिए हमारा [योगदान गाइड](CONTRIBUTING.md#first-time-contributors) देखें। AI/vibe-coded PRs का स्वागत है! 🤖
|
||||
|
||||
[CONTRIBUTING.md](CONTRIBUTING.md) और [CLA.md](docs/contributing/cla.md) देखें। एक trait लागू करें, PR सबमिट करें:
|
||||
|
||||
- CI वर्कफ़्लो गाइड: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- नया `Provider` → `src/providers/`
|
||||
- नया `Channel` → `src/channels/`
|
||||
- नया `Observer` → `src/observability/`
|
||||
- नया `Tool` → `src/tools/`
|
||||
- नया `Memory` → `src/memory/`
|
||||
- नया `Tunnel` → `src/tunnel/`
|
||||
- नया `Peripheral` → `src/peripherals/`
|
||||
- नया `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ आधिकारिक रिपॉजिटरी और प्रतिरूपण चेतावनी
|
||||
|
||||
**यह एकमात्र आधिकारिक ZeroClaw रिपॉजिटरी है:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
कोई भी अन्य रिपॉजिटरी, संगठन, डोमेन, या पैकेज जो "ZeroClaw" होने का दावा करता है या ZeroClaw Labs से संबद्धता का संकेत देता है, **अनधिकृत है और इस प्रोजेक्ट से संबद्ध नहीं है**। ज्ञात अनधिकृत फ़ोर्क [TRADEMARK.md](docs/maintainers/trademark.md) में सूचीबद्ध किए जाएँगे।
|
||||
|
||||
यदि आप प्रतिरूपण या ट्रेडमार्क दुरुपयोग का सामना करते हैं, तो कृपया [एक इश्यू खोलें](https://github.com/zeroclaw-labs/zeroclaw/issues)।
|
||||
|
||||
---
|
||||
|
||||
## लाइसेंस
|
||||
|
||||
ZeroClaw अधिकतम खुलेपन और योगदानकर्ता सुरक्षा के लिए दोहरे-लाइसेंस प्राप्त है:
|
||||
|
||||
| लाइसेंस | उपयोग का मामला |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | ओपन-सोर्स, अनुसंधान, अकादमिक, व्यक्तिगत उपयोग |
|
||||
| [Apache 2.0](LICENSE-APACHE) | पेटेंट सुरक्षा, संस्थागत, वाणिज्यिक डिप्लॉयमेंट |
|
||||
|
||||
आप कोई भी लाइसेंस चुन सकते हैं। **योगदानकर्ता स्वचालित रूप से दोनों के तहत अधिकार प्रदान करते हैं** — पूर्ण योगदानकर्ता समझौते के लिए [CLA.md](docs/contributing/cla.md) देखें।
|
||||
|
||||
### ट्रेडमार्क
|
||||
|
||||
**ZeroClaw** नाम और लोगो ZeroClaw Labs के ट्रेडमार्क हैं। यह लाइसेंस समर्थन या संबद्धता का संकेत देने के लिए इनका उपयोग करने की अनुमति नहीं देता। अनुमत और निषिद्ध उपयोग के लिए [TRADEMARK.md](docs/maintainers/trademark.md) देखें।
|
||||
|
||||
### योगदानकर्ता सुरक्षा
|
||||
|
||||
- आप अपने योगदान का **कॉपीराइट बनाए रखते हैं**
|
||||
- **पेटेंट अनुदान** (Apache 2.0) आपको अन्य योगदानकर्ताओं द्वारा पेटेंट दावों से बचाता है
|
||||
- आपके योगदान कमिट इतिहास और [NOTICE](NOTICE) में **स्थायी रूप से श्रेयित** हैं
|
||||
- योगदान करने से कोई ट्रेडमार्क अधिकार स्थानांतरित नहीं होते
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — शून्य ओवरहेड। शून्य समझौता। कहीं भी डिप्लॉय करें। कुछ भी स्वैप करें। 🦀
|
||||
|
||||
## योगदानकर्ता
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
यह सूची GitHub योगदानकर्ता ग्राफ़ से उत्पन्न होती है और स्वचालित रूप से अपडेट होती है।
|
||||
|
||||
## स्टार इतिहास
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.hu.md
755
README.hu.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Szemelyes MI Asszisztens</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nulla terheles. Nulla kompromisszum. 100% Rust. 100% Agnosztikus.</strong><br>
|
||||
⚡️ <strong>$10-os hardveren fut <5MB RAM-mal: Ez 99%-kal kevesebb memoria, mint az OpenClaw es 98%-kal olcsobb, mint egy Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
A Harvard, MIT es Sundai.Club kozossegek diakjai es tagjai epitettek.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Nyelvek:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
A ZeroClaw egy szemelyes MI asszisztens, amelyet a sajat eszkozeiden futtathatsz. Valaszol a mar hasznalt csatornaidon (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work es meg tobb). Rendelkezik webes vezerlopulttal valos ideju iranyitashoz, es csatlakoztathat hardver periferiakhoz (ESP32, STM32, Arduino, Raspberry Pi). A Gateway csupan a vezerlesi sik — a termek maga az asszisztens.
|
||||
|
||||
Ha szemelyes, egyfelhasznalos asszisztenst szeretnel, ami lokalis, gyors es mindig elerheto, ez az.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Weboldal</a> ·
|
||||
<a href="docs/README.md">Dokumentacio</a> ·
|
||||
<a href="docs/architecture.md">Architektura</a> ·
|
||||
<a href="#gyors-inditas-tldr">Kezdes</a> ·
|
||||
<a href="#atallas-openclawrol">Atallas OpenClawrol</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Hibaelharitas</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Ajanlott beallitas:** futtasd a `zeroclaw onboard` parancsot a terminalban. A ZeroClaw Onboard lepesrol lepesre vegigvezet a gateway, munkater, csatornak es szolgaltato beallitasan. Ez az ajanlott beallitasi ut, es mukodik macOS-en, Linuxon es Windowson (WSL2-n keresztul). Uj telepites? Kezdd itt: [Kezdes](#gyors-inditas-tldr)
|
||||
|
||||
### Elofizetes hitelesites (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT elofizetes)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API kulcs vagy hitelesitesi token)
|
||||
|
||||
Modell megjegyzes: bar sok szolgaltato/modell tamogatott, a legjobb elmeny erdekeben hasznald a legerosebb, legujabb generacios modellt. Lasd [Onboarding](#gyors-inditas-tldr).
|
||||
|
||||
Modellek konfiguracio + CLI: [Szolgaltatoi referencia](docs/reference/api/providers-reference.md)
|
||||
Auth profil rotacio (OAuth vs API kulcsok) + failover: [Modell failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Telepites (ajanlott)
|
||||
|
||||
Futtato kornyezet: Rust stable toolchain. Egyetlen binaris, nincs futtatasi ideju fuggoseg.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Egy kattintasos telepites
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
A `zeroclaw onboard` automatikusan lefut a telepites utan a munkater es szolgaltato konfiguralasakor.
|
||||
|
||||
## Gyors inditas (TL;DR)
|
||||
|
||||
Teljes kezdo utmutato (hitelesites, parositas, csatornak): [Kezdes](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Telepites + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Gateway inditasa (webhook szerver + webes vezerlopult)
|
||||
zeroclaw gateway # alapertelmezett: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # veletlenszeru port (biztonsagi szilarditas)
|
||||
|
||||
# Beszelgess az asszisztenssel
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktiv mod
|
||||
zeroclaw agent
|
||||
|
||||
# Teljes autonom futtatas inditasa (gateway + csatornak + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Allapot ellenorzes
|
||||
zeroclaw status
|
||||
|
||||
# Diagnosztika futtatasa
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Frissites? Futtasd a `zeroclaw doctor` parancsot a frissites utan.
|
||||
|
||||
### Forrasbol (fejlesztes)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Fejlesztoi alternativa (globalis telepites nelkul):** a parancsokat prefixeld `cargo run --release --`-vel (pelda: `cargo run --release -- status`).
|
||||
|
||||
## Atallas OpenClawrol
|
||||
|
||||
A ZeroClaw importalhatja az OpenClaw munkateret, memoriat es konfiguraciot:
|
||||
|
||||
```bash
|
||||
# Elonezet az attelepitendo adatokrol (biztonsagos, csak olvasható)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Migracio futtatasa
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Ez migralja a memoriabejegyzeseket, munkater fajlokat es konfiguraciot a `~/.openclaw/` konyvtarbol a `~/.zeroclaw/` konyvtarba. A konfiguracio automatikusan JSON-bol TOML-ra konvertalodik.
|
||||
|
||||
## Biztonsagi alapertelmezesek (DM hozzaferes)
|
||||
|
||||
A ZeroClaw valos uzenetfeluletekkez csatlakozik. Kezeld a bejovo DM-eket nem megbizhato bemenetekkent.
|
||||
|
||||
Teljes biztonsagi utmutato: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Alapertelmezett viselkedes minden csatornan:
|
||||
|
||||
- **DM parositas** (alapertelmezett): az ismeretlen feladok rovid parosito kodot kapnak, es a bot nem dolgozza fel az uzenetuket.
|
||||
- Jovahagy paranccsal: `zeroclaw pairing approve <channel> <code>` (ezutan a felado felkerul egy lokalis engedelyezesi listara).
|
||||
- A nyilvanos bejovo DM-ek kifejezett opt-in-t igenyelnek a `config.toml`-ban.
|
||||
- Futtasd a `zeroclaw doctor` parancsot a kockazatos vagy rosszul konfiguralt DM szabalyzatok feltarasahoz.
|
||||
|
||||
**Autonomia szintek:**
|
||||
|
||||
| Szint | Viselkedes |
|
||||
|-------|------------|
|
||||
| `ReadOnly` | Az agens megfigyel, de nem cselekszik |
|
||||
| `Supervised` (alapertelmezett) | Az agens jovahagyassal cselekszik kozepes/magas kockazatu muveletenel |
|
||||
| `Full` | Az agens autonoman cselekszik a szabalyzat hataran belul |
|
||||
|
||||
**Sandboxing retegek:** munkater izolalas, utvonal-atjaras blokkolas, parancs engedelyezesi listak, tiltott utvonalak (`/etc`, `/root`, `~/.ssh`), sebessegkorlatozas (max muveletek/ora, koltseg/nap korlatok).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Kozlemenyek
|
||||
|
||||
Hasznald ezt a tablat fontos ertesitesekhez (torekenyen kompatibilis valtozasok, biztonsagi tanacsadok, karbantartasi idosavok es kiadasi blokkolok).
|
||||
|
||||
| Datum (UTC) | Szint | Ertesites | Teendo |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritikus_ | **Nem** allunk kapcsolatban az `openagen/zeroclaw`, `zeroclaw.org` vagy `zeroclaw.net` oldalakkal. A `zeroclaw.org` es `zeroclaw.net` domainek jelenleg az `openagen/zeroclaw` fork-ra mutatnak, es az a domain/tarolo megszemelyesiti a hivatalos weboldalunkat/projektunket. | Ne bizz meg az ezekbol a forrasokbol szarmazo informaciokban, binarisokban, adomanygyujtesekben vagy kozlemenyekben. Kizarolag [ezt a tarolot](https://github.com/zeroclaw-labs/zeroclaw) es az ellenorzott kozossegi media fiokjainkat hasznald. |
|
||||
| 2026-02-21 | _Fontos_ | A hivatalos weboldalunk most mar el: [zeroclawlabs.ai](https://zeroclawlabs.ai). Koszonjuk turelmuket, amig elokeszitettuk az inditast. Meg mindig latunk megszemelyesitesi kiserleteket, ezert **ne** csatlakozz semmilyen befektetesi vagy adomanygyujtesi tevekenyseghez, amely a ZeroClaw nevet hasznalja, hacsak nem a hivatalos csatornainkon keresztul jelenik meg. | Hasznald [ezt a tarolot](https://github.com/zeroclaw-labs/zeroclaw) egyetlen igazsagforraskent. Kovesd az [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) es [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) oldalakat a hivatalos frissitesekert. |
|
||||
| 2026-02-19 | _Fontos_ | Az Anthropic frissitette a Hitelesitesi es Hitellevelek Hasznalara vonatkozo felteteleket 2026-02-19-en. A Claude Code OAuth tokenek (Free, Pro, Max) kizarolag a Claude Code es a Claude.ai szamara keszultek; az OAuth tokenek barmely mas termekben, eszkozben vagy szolgaltatasban valo hasznalata (beleertve az Agent SDK-t) nem megengedett es sertheti a Fogyasztoi Szolgaltatasi Felteteleket. | Kerlek ideiglenesen keruld a Claude Code OAuth integraciokat a potencialis veszteseg megelozese erdekeben. Eredeti kikotes: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Fobb jellemzok
|
||||
|
||||
- **Konnyu futtatokornyezet alapertelmezetten** — a szokasos CLI es allapot munkafolyamatok nehany megabajtos memoria burkban futnak release buildekben.
|
||||
- **Koltseghatekony telepites** — $10-os kartyakhoz es kis cloud peldanyokhoz tervezve, nehez futtatokornyezeti fuggosegek nelkul.
|
||||
- **Gyors hideg inditas** — az egyetlen binarisbol allo Rust futtatokornyezet szinte azonnali parancs- es daemon-inditast biztosit.
|
||||
- **Hordozhato architektura** — egy binaris ARM, x86 es RISC-V rendszereken cserelheto szolgaltatok/csatornak/eszkozokkel.
|
||||
- **Lokalis-eloszor Gateway** — egyetlen vezerlesi sik a munkamenetekhez, csatornakhoz, eszkozokhoz, cron-hoz, SOP-khoz es esemenyekhez.
|
||||
- **Tobbcsatornas beerkeze** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket es meg tobb.
|
||||
- **Tobbagens orkesztracio (Hands)** — autonom agens rajok, amelyek utemezetten futnak es idovel okosabbak lesznek.
|
||||
- **Szabvanyos Muveleti Eljarasok (SOPs)** — esemenyvezeerlt munkafolyamat automatizalas MQTT, webhook, cron es periferia triggerekkel.
|
||||
- **Webes vezerlopult** — React 19 + Vite webes felulet valos ideju csevegeessel, memoriaboongeszevel, konfiguracioszerkesztovel, cron kezelovel es eszkoz vizsgaloval.
|
||||
- **Hardver periferiak** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO a `Peripheral` trait-en keresztul.
|
||||
- **Elso osztalyu eszkozok** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace es 70+ tovabb.
|
||||
- **Eletciklus hookok** — LLM hivasok, eszkozvegrehajtasok es uzenetek elfogasa es modositasa minden szinten.
|
||||
- **Kepesseg platform** — beepitett, kozossegi es munkater kepessegek biztonsagi auditalassal.
|
||||
- **Tunnel tamogatas** — Cloudflare, Tailscale, ngrok, OpenVPN es egyedi tunnelek tavoli hozzafereshez.
|
||||
|
||||
### Miert valasztjak a csapatok a ZeroClaw-t
|
||||
|
||||
- **Konnyu alapertelmezetten:** kis Rust binaris, gyors inditas, alacsony memoriahasznalat.
|
||||
- **Biztonsagos tervezessel:** parositas, szigoru sandboxing, kifejezett engedelyezesi listak, munkater hatarolás.
|
||||
- **Teljesen cserelheto:** az alaprendszerek trait-ek (providers, channels, tools, memory, tunnels).
|
||||
- **Nincs bezartsag:** OpenAI-kompatibilis szolgaltatoi tamogatas + csatlakoztatható egyedi vegpontok.
|
||||
|
||||
## Benchmark pillanatkep (ZeroClaw vs OpenClaw, Reprodukalhato)
|
||||
|
||||
Lokalis gepi gyors benchmark (macOS arm64, 2026 feb.) normalizalva 0.8GHz edge hardverre.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Nyelv** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Inditas (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binaris meret** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Koltseg** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Barmilyen hardver $10** |
|
||||
|
||||
> Megjegyzesek: A ZeroClaw eredmenyek release buildeken merve `/usr/bin/time -l` hasznalataval. Az OpenClaw Node.js futtatokornyezetet igenyel (tipikusan ~390MB memoria terheles), mig a NanoBot Python futtatokornyezetet. A PicoClaw es ZeroClaw statikus binarisok. A fenti RAM adatok futtatasi ideju memoriat mutatnak; a forditasi ideju kovetelmenyek magasabbak.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Reprodukalhato lokalis meres
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Minden, amit eddig epitettunk
|
||||
|
||||
### Alapplatform
|
||||
|
||||
- Gateway HTTP/WS/SSE vezerlesi sik munkamenetekkel, jelenleettel, konfiguracioval, cron-nal, webhookkal, webes vezerlopulttal es parositassal.
|
||||
- CLI felulet: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agens orkesztracios hurk eszkoz-kuldessel, prompt epitessel, uzenet osztalyozassal es memoria betoltessel.
|
||||
- Munkamenet modell biztonsagi szabalyzat ervenyesitessel, autonomia szintekkel es jovahagyasi kapuval.
|
||||
- Ellenallo szolgaltatoi wrapper failover-rel, ujraprobalassal es modell iranyitassal 20+ LLM backend-en.
|
||||
|
||||
### Csatornak
|
||||
|
||||
Csatornak: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Webes vezerlopult
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 webes vezerlopult, amelyet kozvetlenul a Gateway szolgaltat ki:
|
||||
|
||||
- **Dashboard** — rendszer attekintes, egeszsegi allapot, uzemido, koltsegkovetes
|
||||
- **Agent Chat** — interaktiv csevegees az agenssel
|
||||
- **Memory** — memoriabejegyzesek bongeszese es kezelese
|
||||
- **Config** — konfiguracio megtekintese es szerkesztese
|
||||
- **Cron** — utemezett feladatok kezelese
|
||||
- **Tools** — elerheto eszkozok bongeszese
|
||||
- **Logs** — agens tevekenysegnaplo megtekintese
|
||||
- **Cost** — token hasznalat es koltsegkovetes
|
||||
- **Doctor** — rendszer egeszseugyi diagnosztika
|
||||
- **Integrations** — integracios allapot es beallitas
|
||||
- **Pairing** — eszkoz parositas kezeles
|
||||
|
||||
### Firmware celok
|
||||
|
||||
| Cel | Platform | Rendeltetees |
|
||||
|-----|----------|-------------|
|
||||
| ESP32 | Espressif ESP32 | Vezetek nelkuli periferia agens |
|
||||
| ESP32-UI | ESP32 + Display | Agens vizualis feluelettel |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Ipari periferia |
|
||||
| Arduino | Arduino | Alap szenzor/aktualtor hid |
|
||||
| Uno Q Bridge | Arduino Uno | Soros hid az agenshez |
|
||||
|
||||
### Eszkozok + automatizalas
|
||||
|
||||
- **Alap:** shell, file read/write/edit, git operations, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Integraciok:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Utemezes:** cron add/remove/update/run, schedule tool
|
||||
- **Memoria:** recall, store, forget, knowledge, project intel
|
||||
- **Halado:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Hardver:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Futtatokornyezet + biztonsag
|
||||
|
||||
- **Autonomia szintek:** ReadOnly, Supervised (alapertelmezett), Full.
|
||||
- **Sandboxing:** munkater izolalas, utvonal-atjaras blokkolas, parancs engedelyezesi listak, tiltott utvonalak, Landlock (Linux), Bubblewrap.
|
||||
- **Sebessegkorlatozas:** max muveletek orankent, max koltseg naponta (konfiguralhato).
|
||||
- **Jovahagyasi kapu:** interaktiv jovahagy kozepes/magas kockazatu mueveletekhez.
|
||||
- **E-stop:** veszleallitasi kepesseg.
|
||||
- **129+ biztonsagi teszt** automatizalt CI-ben.
|
||||
|
||||
### Muveletek + csomagolas
|
||||
|
||||
- Webes vezerlopult kozvetlenul a Gateway-bol kiszolgalva.
|
||||
- Tunnel tamogatas: Cloudflare, Tailscale, ngrok, OpenVPN, egyedi parancs.
|
||||
- Docker runtime adapter konterizalt vegrehajtashoz.
|
||||
- CI/CD: beta (auto on push) → stable (manual dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Elore elkeszitett binarisok Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64) rendszerekhez.
|
||||
|
||||
|
||||
## Konfiguracio
|
||||
|
||||
Minimalis `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Teljes konfiguracios referencia: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Csatorna konfiguracio
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnel konfiguracio
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Reszletek: [Csatorna referencia](docs/reference/api/channels-reference.md) · [Konfiguracios referencia](docs/reference/api/config-reference.md)
|
||||
|
||||
### Futtatokornyezet tamogatas (aktualis)
|
||||
|
||||
- **`native`** (alapertelmezett) — kozvetlen folyamat vegrehajtas, leggyorsabb ut, idealis megbizhato kornyezetekhez.
|
||||
- **`docker`** — teljes kontener izolalas, ervenyesitett biztonsagi szabalyzatok, Docker szukseges.
|
||||
|
||||
Allitsd be a `runtime.kind = "docker"` erteket a szigoru sandboxinghoz vagy halozati izolaciohoz.
|
||||
|
||||
## Elofizetes hitelesites (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
A ZeroClaw tamogatja az elofizetes-nativ hitelesitesi profilokat (tobb fiok, titkositva tarolva).
|
||||
|
||||
- Tarolo fajl: `~/.zeroclaw/auth-profiles.json`
|
||||
- Titkositasi kulcs: `~/.zeroclaw/.secret_key`
|
||||
- Profil azonosito formatum: `<provider>:<profile_name>` (pelda: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Run the agent with subscription auth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agens munkater + kepessegek
|
||||
|
||||
Munkater gyoker: `~/.zeroclaw/workspace/` (konfiguralhato a config-on keresztul).
|
||||
|
||||
Beinjektalt prompt fajlok:
|
||||
- `IDENTITY.md` — agens szemelyiseg es szerep
|
||||
- `USER.md` — felhasznaloi kontextus es prefernciak
|
||||
- `MEMORY.md` — hosszu tavu tenyek es tanulsagok
|
||||
- `AGENTS.md` — munkamenet konvenciok es inicializalasi szabalyok
|
||||
- `SOUL.md` — alapveto identitas es mukodesi elvek
|
||||
|
||||
Kepessegek: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` vagy `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI parancsok
|
||||
|
||||
```bash
|
||||
# Munkater kezeles
|
||||
zeroclaw onboard # Vezerelt beallitasi varazslo
|
||||
zeroclaw status # Daemon/agent allapot megjelenites
|
||||
zeroclaw doctor # Rendszer diagnosztika futtatasa
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Gateway szerver inditasa (127.0.0.1:42617)
|
||||
zeroclaw daemon # Teljes autonom futtatas inditasa
|
||||
|
||||
# Agens
|
||||
zeroclaw agent # Interaktiv csevegesi mod
|
||||
zeroclaw agent -m "message" # Egyszeri uzenet mod
|
||||
|
||||
# Szolgaltatas kezeles
|
||||
zeroclaw service install # Telepites OS szolgaltataskent (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Csatornak
|
||||
zeroclaw channel list # Konfiguralt csatornak listazasa
|
||||
zeroclaw channel doctor # Csatorna egeszseg ellenorzes
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + utemezes
|
||||
zeroclaw cron list # Utemezett feladatok listazasa
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memoria
|
||||
zeroclaw memory list # Memoriabejegyzesek listazasa
|
||||
zeroclaw memory get <key> # Memoria lekerese
|
||||
zeroclaw memory stats # Memoria statisztikak
|
||||
|
||||
# Hitelesitesi profilok
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardver periferiak
|
||||
zeroclaw hardware discover # Csatlakoztatott eszkozok keresese
|
||||
zeroclaw peripheral list # Csatlakoztatott periferiak listazasa
|
||||
zeroclaw peripheral flash # Firmware felirasa eszkozre
|
||||
|
||||
# Migracio
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell kiegeszitesek
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Teljes parancs referencia: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Elofeltetelek
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Szukseges
|
||||
|
||||
1. **Visual Studio Build Tools** (biztositja az MSVC linkert es a Windows SDK-t):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
A telepites soran (vagy a Visual Studio Installer-en keresztul) valaszd a **"Desktop development with C++"** munkafolyamatot.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
A telepites utan nyiss egy uj terminalt es futtasd a `rustup default stable` parancsot a stabil toolchain aktivalasahoz.
|
||||
|
||||
3. **Ellenorzes**, hogy mindketto mukodik:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opcionalis
|
||||
|
||||
- **Docker Desktop** — csak a [Docker sandboxed runtime](#futtatokornyezet-tamogatas-aktualis) hasznalatahoz szukseges (`runtime.kind = "docker"`). Telepites: `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Szukseges
|
||||
|
||||
1. **Epitesi alapeszkozok:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Telepitsd az Xcode Command Line Tools-t: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Reszletekert lasd [rustup.rs](https://rustup.rs).
|
||||
|
||||
3. **Ellenorzes**, hogy mindketto mukodik:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Egyvonalas telepito
|
||||
|
||||
Vagy hagyd ki a fenti lepeseket es telepits mindent (rendszer fuggosegek, Rust, ZeroClaw) egyetlen paranccsal:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Forditasi eroforrasigeny
|
||||
|
||||
A forrasbol valo epites tobb eroforras igenyel, mint az eredmeny binaris futtatasa:
|
||||
|
||||
| Eroforras | Minimum | Ajanlott |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Szabad lemez** | 6 GB | 10 GB+ |
|
||||
|
||||
Ha a gazdageped a minimum alatt van, hasznalj elore elkeszitett binarisokat:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Kizarolag binaris telepiteshez forras alternativa nelkul:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opcionalis
|
||||
|
||||
- **Docker** — csak a [Docker sandboxed runtime](#futtatokornyezet-tamogatas-aktualis) hasznalatahoz szukseges (`runtime.kind = "docker"`). Telepites a csomagkezelodon keresztul vagy [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Megjegyzes:** Az alapertelmezett `cargo build --release` `codegen-units=1` erteket hasznal a csucs forditasi terheles csokkenteseere. Gyorsabb epitesekhez eros gepeken hasznald a `cargo build --profile release-fast` parancsot.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Elore elkeszitett binarisok
|
||||
|
||||
Kiadas eszkozok az alabbi platformokra kerulnek kozetetelre:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Toltsd le a legujabb eszkozoket innen:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentacio
|
||||
|
||||
Hasznald ezeket, ha tuljutottal az onboarding folyamaton es melyebb referenciara van szukseged.
|
||||
|
||||
- Kezdd a [dokumentacios indexszel](docs/README.md) a navigaciohoz es a "mi hol talalhato" informaciohoz.
|
||||
- Olvasd el az [architektura attekintest](docs/architecture.md) a teljes rendszermodellhez.
|
||||
- Hasznald a [konfiguracios referenciat](docs/reference/api/config-reference.md), ha minden kulcsra es peldara szukseged van.
|
||||
- Futtasd a Gateway-t a konyv szerint az [uzemeltetesi kezikonyvvel](docs/ops/operations-runbook.md).
|
||||
- Kovesd a [ZeroClaw Onboard](#gyors-inditas-tldr) szolgaltatast a vezerelt beallitashoz.
|
||||
- Hibakeress a gyakori problemakat a [hibaelharitasi utmutatoval](docs/ops/troubleshooting.md).
|
||||
- Tekintsd at a [biztonsagi utmutatast](docs/security/README.md) mielott barmit is kiteszel.
|
||||
|
||||
### Referencia dokumentaciok
|
||||
|
||||
- Dokumentacios kozpont: [docs/README.md](docs/README.md)
|
||||
- Egysegesitett tartalomjegyzek: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Parancs referencia: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Konfiguracios referencia: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Szolgaltatoi referencia: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Csatorna referencia: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Uzemeltetesi kezikonyv: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Hibaelharitas: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Egyuttmukodesi dokumentaciok
|
||||
|
||||
- Hozzajarulasi utmutato: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR munkafolyamat szabalyzat: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI munkafolyamat utmutato: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Biraloi kezikonyv: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Biztonsagi kozzeteeteli szabalyzat: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentacios sablon: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Telepites + muveletek
|
||||
|
||||
- Halozati telepitesi utmutato: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy agens kezikonyv: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hardver utmutatok: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
A ZeroClaw a smooth crab 🦀 szamara keszult, egy gyors es hatekony MI asszisztens. Epitette Argenis De La Rosa es a kozosseg.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Tamogasd a ZeroClaw-t
|
||||
|
||||
Ha a ZeroClaw segiti a munkadat es tamogatni szeretned a folyamatos fejlesztest, itt adomanyozhatsz:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Kulonos koszonet
|
||||
|
||||
Szivbol jovo koszonet a kozossegeknek es intezmenyeknek, amelyek inspiraljak es taplaljak ezt a nyilt forrasu munkat:
|
||||
|
||||
- **Harvard University** — az intellektualis kivancsiság apolasaert es a lehetosegek hatarainak tolásáert.
|
||||
- **MIT** — a nyilt tudas, nyilt forras es azon hit bajnokakent, hogy a technologianak mindenki szamara elerheto kell lennie.
|
||||
- **Sundai Club** — a kozossegert, az energiaert es a szuntelen torekveseert, hogy fontos dolgokat epitsenek.
|
||||
- **A Vilag es Azon Tul** 🌍✨ — minden hozzajarulonak, almodonak es epitonek, aki a nyilt forrast a jo erdekeben mukodo erove teszi. Ez neked szol.
|
||||
|
||||
Nyiltan epitunk, mert a legjobb otletek mindenhonnan jonnek. Ha ezt olvasod, a resze vagy. Udvozlunk. 🦀❤️
|
||||
|
||||
## Hozzajarulas
|
||||
|
||||
Uj vagy a ZeroClaw-ban? Keresd a [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) cimkevel ellatott issue-kat — lasd a [Hozzajarulasi utmutatot](CONTRIBUTING.md#first-time-contributors) a kezdeshez. AI/vibe-coded PR-ok szivesen latottak! 🤖
|
||||
|
||||
Lasd [CONTRIBUTING.md](CONTRIBUTING.md) es [CLA.md](docs/contributing/cla.md). Implementalj egy trait-et, kuuldj be egy PR-t:
|
||||
|
||||
- CI munkafolyamat utmutato: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Uj `Provider` → `src/providers/`
|
||||
- Uj `Channel` → `src/channels/`
|
||||
- Uj `Observer` → `src/observability/`
|
||||
- Uj `Tool` → `src/tools/`
|
||||
- Uj `Memory` → `src/memory/`
|
||||
- Uj `Tunnel` → `src/tunnel/`
|
||||
- Uj `Peripheral` → `src/peripherals/`
|
||||
- Uj `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Hivatalos tarolo es megszemelyesitesi figyelmeztetes
|
||||
|
||||
**Ez az egyetlen hivatalos ZeroClaw tarolo:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Barmely mas tarolo, szervezet, domain vagy csomag, amely azt allitja, hogy "ZeroClaw" vagy kapcsolatot sugall a ZeroClaw Labs-szal, **jogosulatlan es nem all kapcsolatban ezzel a projekttel**. Az ismert jogosulatlan forkok a [TRADEMARK.md](docs/maintainers/trademark.md) fajlban lesznek felsorolva.
|
||||
|
||||
Ha megszemelyesitessel vagy vedjeggyel valo visszaelessel talalkozol, kerlek [nyiss egy issue-t](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licenc
|
||||
|
||||
A ZeroClaw kettos licenccel rendelkezik a maximalis nyitottsag es hozzajaruloi vedelem erdekeben:
|
||||
|
||||
| Licenc | Felhasznalasi eset |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Nyilt forras, kutatas, akademiai, szemelyes haszanalat |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Szabadalmi vedelem, intezmenyi, kereskedelmi telepites |
|
||||
|
||||
Barmely licencet valaszthatod. **A hozzajarulok automatikusan mindketto alatt jogot biztositanak** — lasd [CLA.md](docs/contributing/cla.md) a teljes hozzajarulasi megallapodasert.
|
||||
|
||||
### Vedjegy
|
||||
|
||||
A **ZeroClaw** nev es logo a ZeroClaw Labs vedjegyei. Ez a licenc nem ad engedelyt arra, hogy tamogatast vagy kapcsolatot sugalljanak. Lasd [TRADEMARK.md](docs/maintainers/trademark.md) a megengedett es tiltott hasznalati modokert.
|
||||
|
||||
### Hozzajaruloi vedelmek
|
||||
|
||||
- **Megtartod a szerzoi jogot** a hozzajarulasaidon
|
||||
- **Szabadalmi engedely** (Apache 2.0) vedi meg mas hozzajarulok szabadalmi igenyeitol
|
||||
- A hozzajarulasaid **veglegesen attribulaltak** a commit tortenelben es a [NOTICE](NOTICE) fajlban
|
||||
- Nem kerulnek at vedjegyjogok a hozzajarulassal
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nulla terheles. Nulla kompromisszum. Telepites barhova. Csere barmire. 🦀
|
||||
|
||||
## Hozzajarulok
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Ez a lista a GitHub hozzajaruloi grafikonjabol keszul es automatikusan frissul.
|
||||
|
||||
## Csillag tortenelem
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.id.md
755
README.id.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Asisten AI Pribadi</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nol overhead. Nol kompromi. 100% Rust. 100% Agnostik.</strong><br>
|
||||
⚡️ <strong>Berjalan di perangkat keras $10 dengan RAM <5MB: Itu 99% lebih hemat memori dari OpenClaw dan 98% lebih murah dari Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Dibangun oleh mahasiswa dan anggota komunitas Harvard, MIT, dan Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Bahasa:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw adalah asisten AI pribadi yang Anda jalankan di perangkat sendiri. Ia menjawab Anda melalui saluran yang sudah Anda gunakan (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, dan lainnya). Ia memiliki dasbor web untuk kontrol real-time dan dapat terhubung ke periferal perangkat keras (ESP32, STM32, Arduino, Raspberry Pi). Gateway hanyalah bidang kendali — produknya adalah asisten.
|
||||
|
||||
Jika Anda menginginkan asisten pribadi, pengguna tunggal, yang terasa lokal, cepat, dan selalu aktif, inilah solusinya.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Situs Web</a> ·
|
||||
<a href="docs/README.md">Dokumentasi</a> ·
|
||||
<a href="docs/architecture.md">Arsitektur</a> ·
|
||||
<a href="#mulai-cepat">Memulai</a> ·
|
||||
<a href="#migrasi-dari-openclaw">Migrasi dari OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Pemecahan Masalah</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Pengaturan yang disarankan:** jalankan `zeroclaw onboard` di terminal Anda. ZeroClaw Onboard memandu Anda langkah demi langkah dalam menyiapkan gateway, workspace, saluran, dan provider. Ini adalah jalur pengaturan yang disarankan dan berfungsi di macOS, Linux, dan Windows (melalui WSL2). Instalasi baru? Mulai di sini: [Memulai](#mulai-cepat)
|
||||
|
||||
### Autentikasi Berlangganan (OAuth)
|
||||
|
||||
- **OpenAI Codex** (langganan ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (kunci API atau token autentikasi)
|
||||
|
||||
Catatan model: meskipun banyak provider/model didukung, untuk pengalaman terbaik gunakan model generasi terbaru terkuat yang tersedia untuk Anda. Lihat [Onboarding](#mulai-cepat).
|
||||
|
||||
Konfigurasi model + CLI: [Referensi Provider](docs/reference/api/providers-reference.md)
|
||||
Rotasi profil autentikasi (OAuth vs kunci API) + failover: [Failover Model](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instal (disarankan)
|
||||
|
||||
Runtime: Rust stable toolchain. Biner tunggal, tanpa dependensi runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Bootstrap sekali klik
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` berjalan otomatis setelah instalasi untuk mengonfigurasi workspace dan provider Anda.
|
||||
|
||||
## Mulai cepat (TL;DR)
|
||||
|
||||
Panduan lengkap pemula (autentikasi, pairing, saluran): [Memulai](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instal + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Mulai gateway (server webhook + dasbor web)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # port acak (keamanan ditingkatkan)
|
||||
|
||||
# Bicara ke asisten
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Mode interaktif
|
||||
zeroclaw agent
|
||||
|
||||
# Mulai runtime otonom penuh (gateway + saluran + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Periksa status
|
||||
zeroclaw status
|
||||
|
||||
# Jalankan diagnostik
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Memperbarui? Jalankan `zeroclaw doctor` setelah pembaruan.
|
||||
|
||||
### Dari sumber (pengembangan)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Alternatif dev (tanpa instalasi global):** awali perintah dengan `cargo run --release --` (contoh: `cargo run --release -- status`).
|
||||
|
||||
## Migrasi dari OpenClaw
|
||||
|
||||
ZeroClaw dapat mengimpor workspace, memori, dan konfigurasi OpenClaw Anda:
|
||||
|
||||
```bash
|
||||
# Pratinjau apa yang akan dimigrasikan (aman, hanya-baca)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Jalankan migrasi
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Ini memigrasikan entri memori, file workspace, dan konfigurasi Anda dari `~/.openclaw/` ke `~/.zeroclaw/`. Konfigurasi dikonversi dari JSON ke TOML secara otomatis.
|
||||
|
||||
## Default keamanan (akses DM)
|
||||
|
||||
ZeroClaw terhubung ke permukaan pesan nyata. Perlakukan DM masuk sebagai input tidak tepercaya.
|
||||
|
||||
Panduan keamanan lengkap: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Perilaku default di semua saluran:
|
||||
|
||||
- **Pairing DM** (default): pengirim yang tidak dikenal menerima kode pairing singkat dan bot tidak memproses pesan mereka.
|
||||
- Setujui dengan: `zeroclaw pairing approve <channel> <code>` (kemudian pengirim ditambahkan ke daftar izin lokal).
|
||||
- DM masuk publik memerlukan opt-in eksplisit di `config.toml`.
|
||||
- Jalankan `zeroclaw doctor` untuk menemukan kebijakan DM yang berisiko atau salah konfigurasi.
|
||||
|
||||
**Level otonomi:**
|
||||
|
||||
| Level | Perilaku |
|
||||
|-------|----------|
|
||||
| `ReadOnly` | Agen dapat mengamati tetapi tidak bertindak |
|
||||
| `Supervised` (default) | Agen bertindak dengan persetujuan untuk operasi risiko menengah/tinggi |
|
||||
| `Full` | Agen bertindak secara otonom dalam batas kebijakan |
|
||||
|
||||
**Lapisan sandboxing:** isolasi workspace, pemblokiran traversal jalur, daftar izin perintah, jalur terlarang (`/etc`, `/root`, `~/.ssh`), pembatasan laju (maksimum tindakan/jam, batas biaya/hari).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Pengumuman
|
||||
|
||||
Gunakan papan ini untuk pemberitahuan penting (perubahan yang merusak, saran keamanan, jendela pemeliharaan, dan pemblokir rilis).
|
||||
|
||||
| Tanggal (UTC) | Level | Pemberitahuan | Tindakan |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritis_ | Kami **tidak berafiliasi** dengan `openagen/zeroclaw`, `zeroclaw.org` atau `zeroclaw.net`. Domain `zeroclaw.org` dan `zeroclaw.net` saat ini mengarah ke fork `openagen/zeroclaw`, dan domain/repositori tersebut menyamar sebagai situs web/proyek resmi kami. | Jangan percaya informasi, biner, penggalangan dana, atau pengumuman dari sumber tersebut. Gunakan hanya [repositori ini](https://github.com/zeroclaw-labs/zeroclaw) dan akun sosial terverifikasi kami. |
|
||||
| 2026-02-21 | _Penting_ | Situs web resmi kami sekarang aktif: [zeroclawlabs.ai](https://zeroclawlabs.ai). Terima kasih atas kesabaran Anda selama kami mempersiapkan peluncuran. Kami masih melihat upaya peniruan, jadi **jangan** bergabung dengan aktivitas investasi atau penggalangan dana yang mengklaim nama ZeroClaw kecuali dipublikasikan melalui saluran resmi kami. | Gunakan [repositori ini](https://github.com/zeroclaw-labs/zeroclaw) sebagai satu-satunya sumber kebenaran. Ikuti [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs), dan [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) untuk pembaruan resmi. |
|
||||
| 2026-02-19 | _Penting_ | Anthropic memperbarui ketentuan Autentikasi dan Penggunaan Kredensial pada 2026-02-19. Token OAuth Claude Code (Free, Pro, Max) ditujukan secara eksklusif untuk Claude Code dan Claude.ai; menggunakan token OAuth dari Claude Free/Pro/Max di produk, alat, atau layanan lain (termasuk Agent SDK) tidak diizinkan dan dapat melanggar Ketentuan Layanan Konsumen. | Harap sementara hindari integrasi OAuth Claude Code untuk mencegah potensi kerugian. Klausul asli: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Sorotan
|
||||
|
||||
- **Runtime Ringan secara Default** — alur kerja CLI dan status umum berjalan dalam amplop memori beberapa megabyte pada build rilis.
|
||||
- **Deployment Hemat Biaya** — dirancang untuk board $10 dan instans cloud kecil, tanpa dependensi runtime berat.
|
||||
- **Cold Start Cepat** — runtime Rust biner tunggal menjaga startup perintah dan daemon hampir instan.
|
||||
- **Arsitektur Portabel** — satu biner di ARM, x86, dan RISC-V dengan provider/saluran/alat yang dapat ditukar.
|
||||
- **Gateway Lokal-Pertama** — bidang kendali tunggal untuk sesi, saluran, alat, cron, SOP, dan peristiwa.
|
||||
- **Inbox multi-saluran** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket, dan lainnya.
|
||||
- **Orkestrasi multi-agen (Hands)** — swarm agen otonom yang berjalan sesuai jadwal dan semakin pintar seiring waktu.
|
||||
- **Standard Operating Procedures (SOP)** — otomasi alur kerja berbasis peristiwa dengan MQTT, webhook, cron, dan pemicu periferal.
|
||||
- **Dasbor Web** — UI web React 19 + Vite dengan obrolan real-time, browser memori, editor konfigurasi, manajer cron, dan inspektor alat.
|
||||
- **Periferal perangkat keras** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO melalui trait `Peripheral`.
|
||||
- **Alat kelas satu** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace, dan 70+ lainnya.
|
||||
- **Hook siklus hidup** — intersep dan modifikasi panggilan LLM, eksekusi alat, dan pesan di setiap tahap.
|
||||
- **Platform skill** — skill bawaan, komunitas, dan workspace dengan audit keamanan.
|
||||
- **Dukungan tunnel** — Cloudflare, Tailscale, ngrok, OpenVPN, dan tunnel kustom untuk akses jarak jauh.
|
||||
|
||||
### Mengapa tim memilih ZeroClaw
|
||||
|
||||
- **Ringan secara default:** biner Rust kecil, startup cepat, jejak memori rendah.
|
||||
- **Aman secara desain:** pairing, sandboxing ketat, daftar izin eksplisit, pelingkupan workspace.
|
||||
- **Sepenuhnya dapat ditukar:** sistem inti adalah trait (provider, saluran, alat, memori, tunnel).
|
||||
- **Tanpa lock-in:** dukungan provider kompatibel OpenAI + endpoint kustom pluggable.
|
||||
|
||||
## Cuplikan Benchmark (ZeroClaw vs OpenClaw, Dapat Direproduksi)
|
||||
|
||||
Benchmark cepat mesin lokal (macOS arm64, Feb 2026) dinormalisasi untuk perangkat keras edge 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Bahasa** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Startup (inti 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Ukuran Biner** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Biaya** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Perangkat keras apa pun $10** |
|
||||
|
||||
> Catatan: Hasil ZeroClaw diukur pada build rilis menggunakan `/usr/bin/time -l`. OpenClaw memerlukan runtime Node.js (biasanya ~390MB overhead memori tambahan), sedangkan NanoBot memerlukan runtime Python. PicoClaw dan ZeroClaw adalah biner statis. Angka RAM di atas adalah memori runtime; kebutuhan kompilasi saat build lebih tinggi.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Pengukuran lokal yang dapat direproduksi
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Semua yang telah kami bangun sejauh ini
|
||||
|
||||
### Platform inti
|
||||
|
||||
- Bidang kendali HTTP/WS/SSE Gateway dengan sesi, presence, konfigurasi, cron, webhook, dasbor web, dan pairing.
|
||||
- Permukaan CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Loop orkestrasi agen dengan dispatch alat, konstruksi prompt, klasifikasi pesan, dan pemuatan memori.
|
||||
- Model sesi dengan penegakan kebijakan keamanan, level otonomi, dan gating persetujuan.
|
||||
- Wrapper provider resilient dengan failover, retry, dan routing model di 20+ backend LLM.
|
||||
|
||||
### Saluran
|
||||
|
||||
Saluran: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Dasbor web
|
||||
|
||||
Dasbor web React 19 + Vite 6 + Tailwind CSS 4 yang disajikan langsung dari Gateway:
|
||||
|
||||
- **Dashboard** — ikhtisar sistem, status kesehatan, uptime, pelacakan biaya
|
||||
- **Agent Chat** — obrolan interaktif dengan agen
|
||||
- **Memory** — jelajahi dan kelola entri memori
|
||||
- **Config** — lihat dan edit konfigurasi
|
||||
- **Cron** — kelola tugas terjadwal
|
||||
- **Tools** — jelajahi alat yang tersedia
|
||||
- **Logs** — lihat log aktivitas agen
|
||||
- **Cost** — penggunaan token dan pelacakan biaya
|
||||
- **Doctor** — diagnostik kesehatan sistem
|
||||
- **Integrations** — status integrasi dan pengaturan
|
||||
- **Pairing** — manajemen pairing perangkat
|
||||
|
||||
### Target firmware
|
||||
|
||||
| Target | Platform | Tujuan |
|
||||
|--------|----------|--------|
|
||||
| ESP32 | Espressif ESP32 | Agen periferal nirkabel |
|
||||
| ESP32-UI | ESP32 + Display | Agen dengan antarmuka visual |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periferal industri |
|
||||
| Arduino | Arduino | Jembatan sensor/aktuator dasar |
|
||||
| Uno Q Bridge | Arduino Uno | Jembatan serial ke agen |
|
||||
|
||||
### Alat + otomasi
|
||||
|
||||
- **Inti:** shell, file read/write/edit, operasi git, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Integrasi:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Penjadwalan:** cron add/remove/update/run, schedule tool
|
||||
- **Memori:** recall, store, forget, knowledge, project intel
|
||||
- **Lanjutan:** delegate (agen-ke-agen), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Perangkat keras:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Runtime + keamanan
|
||||
|
||||
- **Level otonomi:** ReadOnly, Supervised (default), Full.
|
||||
- **Sandboxing:** isolasi workspace, pemblokiran traversal jalur, daftar izin perintah, jalur terlarang, Landlock (Linux), Bubblewrap.
|
||||
- **Pembatasan laju:** maksimum tindakan per jam, maksimum biaya per hari (dapat dikonfigurasi).
|
||||
- **Gating persetujuan:** persetujuan interaktif untuk operasi risiko menengah/tinggi.
|
||||
- **E-stop:** kemampuan shutdown darurat.
|
||||
- **129+ tes keamanan** dalam CI otomatis.
|
||||
|
||||
### Ops + pengemasan
|
||||
|
||||
- Dasbor web disajikan langsung dari Gateway.
|
||||
- Dukungan tunnel: Cloudflare, Tailscale, ngrok, OpenVPN, perintah kustom.
|
||||
- Adapter runtime Docker untuk eksekusi terkontainerisasi.
|
||||
- CI/CD: beta (otomatis saat push) → stable (dispatch manual) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Biner pre-built untuk Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfigurasi
|
||||
|
||||
Minimal `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Referensi konfigurasi lengkap: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Konfigurasi saluran
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Konfigurasi tunnel
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # atau "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detail: [Referensi Saluran](docs/reference/api/channels-reference.md) · [Referensi Konfigurasi](docs/reference/api/config-reference.md)
|
||||
|
||||
### Dukungan runtime (saat ini)
|
||||
|
||||
- **`native`** (default) — eksekusi proses langsung, jalur tercepat, ideal untuk lingkungan tepercaya.
|
||||
- **`docker`** — isolasi kontainer penuh, kebijakan keamanan ditegakkan, memerlukan Docker.
|
||||
|
||||
Atur `runtime.kind = "docker"` untuk sandboxing ketat atau isolasi jaringan.
|
||||
|
||||
## Autentikasi Berlangganan (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw mendukung profil autentikasi native berlangganan (multi-akun, terenkripsi saat istirahat).
|
||||
|
||||
- File penyimpanan: `~/.zeroclaw/auth-profiles.json`
|
||||
- Kunci enkripsi: `~/.zeroclaw/.secret_key`
|
||||
- Format id profil: `<provider>:<profile_name>` (contoh: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (langganan ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Periksa / refresh / ganti profil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Jalankan agen dengan auth berlangganan
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace agen + skill
|
||||
|
||||
Root workspace: `~/.zeroclaw/workspace/` (dapat dikonfigurasi melalui config).
|
||||
|
||||
File prompt yang diinjeksi:
|
||||
- `IDENTITY.md` — kepribadian dan peran agen
|
||||
- `USER.md` — konteks dan preferensi pengguna
|
||||
- `MEMORY.md` — fakta dan pelajaran jangka panjang
|
||||
- `AGENTS.md` — konvensi sesi dan aturan inisialisasi
|
||||
- `SOUL.md` — identitas inti dan prinsip operasi
|
||||
|
||||
Skill: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` atau `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Daftar skill yang terinstal
|
||||
zeroclaw skills list
|
||||
|
||||
# Instal dari git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Audit keamanan sebelum instalasi
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Hapus skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Perintah CLI
|
||||
|
||||
```bash
|
||||
# Manajemen workspace
|
||||
zeroclaw onboard # Wizard pengaturan terpandu
|
||||
zeroclaw status # Tampilkan status daemon/agen
|
||||
zeroclaw doctor # Jalankan diagnostik sistem
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Mulai server gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Mulai runtime otonom penuh
|
||||
|
||||
# Agen
|
||||
zeroclaw agent # Mode obrolan interaktif
|
||||
zeroclaw agent -m "message" # Mode pesan tunggal
|
||||
|
||||
# Manajemen layanan
|
||||
zeroclaw service install # Instal sebagai layanan OS (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Saluran
|
||||
zeroclaw channel list # Daftar saluran yang dikonfigurasi
|
||||
zeroclaw channel doctor # Periksa kesehatan saluran
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + penjadwalan
|
||||
zeroclaw cron list # Daftar tugas terjadwal
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memori
|
||||
zeroclaw memory list # Daftar entri memori
|
||||
zeroclaw memory get <key> # Ambil memori
|
||||
zeroclaw memory stats # Statistik memori
|
||||
|
||||
# Profil autentikasi
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Periferal perangkat keras
|
||||
zeroclaw hardware discover # Pindai perangkat yang terhubung
|
||||
zeroclaw peripheral list # Daftar periferal yang terhubung
|
||||
zeroclaw peripheral flash # Flash firmware ke perangkat
|
||||
|
||||
# Migrasi
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Pelengkapan shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Referensi perintah lengkap: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Prasyarat
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Diperlukan
|
||||
|
||||
1. **Visual Studio Build Tools** (menyediakan linker MSVC dan Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Selama instalasi (atau melalui Visual Studio Installer), pilih beban kerja **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Setelah instalasi, buka terminal baru dan jalankan `rustup default stable` untuk memastikan toolchain stabil aktif.
|
||||
|
||||
3. **Verifikasi** keduanya berfungsi:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opsional
|
||||
|
||||
- **Docker Desktop** — diperlukan hanya jika menggunakan [runtime Docker sandboxed](#dukungan-runtime-saat-ini) (`runtime.kind = "docker"`). Instal melalui `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Diperlukan
|
||||
|
||||
1. **Build essentials:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Instal Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Lihat [rustup.rs](https://rustup.rs) untuk detail.
|
||||
|
||||
3. **Verifikasi** keduanya berfungsi:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Installer Satu Baris
|
||||
|
||||
Atau lewati langkah di atas dan instal semuanya (dependensi sistem, Rust, ZeroClaw) dalam satu perintah:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Kebutuhan sumber daya kompilasi
|
||||
|
||||
Membangun dari sumber memerlukan lebih banyak sumber daya daripada menjalankan biner yang dihasilkan:
|
||||
|
||||
| Sumber Daya | Minimum | Disarankan |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Disk kosong**| 6 GB | 10 GB+ |
|
||||
|
||||
Jika host Anda di bawah minimum, gunakan biner pre-built:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Untuk memerlukan instalasi hanya-biner tanpa fallback sumber:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opsional
|
||||
|
||||
- **Docker** — diperlukan hanya jika menggunakan [runtime Docker sandboxed](#dukungan-runtime-saat-ini) (`runtime.kind = "docker"`). Instal melalui manajer paket Anda atau [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Catatan:** Default `cargo build --release` menggunakan `codegen-units=1` untuk menurunkan tekanan kompilasi puncak. Untuk build lebih cepat di mesin yang kuat, gunakan `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Biner pre-built
|
||||
|
||||
Aset rilis dipublikasikan untuk:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Unduh aset terbaru dari:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentasi
|
||||
|
||||
Gunakan ini ketika Anda sudah melewati alur onboarding dan menginginkan referensi yang lebih mendalam.
|
||||
|
||||
- Mulai dengan [indeks dokumentasi](docs/README.md) untuk navigasi dan "apa di mana."
|
||||
- Baca [ikhtisar arsitektur](docs/architecture.md) untuk model sistem lengkap.
|
||||
- Gunakan [referensi konfigurasi](docs/reference/api/config-reference.md) ketika Anda memerlukan setiap kunci dan contoh.
|
||||
- Jalankan Gateway sesuai buku dengan [runbook operasional](docs/ops/operations-runbook.md).
|
||||
- Ikuti [ZeroClaw Onboard](#mulai-cepat) untuk pengaturan terpandu.
|
||||
- Debug kegagalan umum dengan [panduan pemecahan masalah](docs/ops/troubleshooting.md).
|
||||
- Tinjau [panduan keamanan](docs/security/README.md) sebelum mengekspos apa pun.
|
||||
|
||||
### Dokumentasi referensi
|
||||
|
||||
- Hub dokumentasi: [docs/README.md](docs/README.md)
|
||||
- TOC dokumentasi terpadu: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Referensi perintah: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Referensi konfigurasi: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Referensi provider: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Referensi saluran: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Runbook operasional: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Pemecahan masalah: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Dokumentasi kolaborasi
|
||||
|
||||
- Panduan kontribusi: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Kebijakan alur kerja PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Panduan alur kerja CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Playbook reviewer: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Kebijakan pengungkapan keamanan: [SECURITY.md](SECURITY.md)
|
||||
- Template dokumentasi: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Deployment + operasi
|
||||
|
||||
- Panduan deployment jaringan: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Playbook proxy agent: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Panduan perangkat keras: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw dibangun untuk smooth crab 🦀, asisten AI yang cepat dan efisien. Dibangun oleh Argenis De La Rosa dan komunitas.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Dukung ZeroClaw
|
||||
|
||||
Jika ZeroClaw membantu pekerjaan Anda dan Anda ingin mendukung pengembangan berkelanjutan, Anda dapat berdonasi di sini:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Terima Kasih Khusus
|
||||
|
||||
Terima kasih yang tulus kepada komunitas dan institusi yang menginspirasi dan mendorong pekerjaan open-source ini:
|
||||
|
||||
- **Harvard University** — untuk memupuk rasa ingin tahu intelektual dan mendorong batas dari apa yang mungkin.
|
||||
- **MIT** — untuk memperjuangkan pengetahuan terbuka, open source, dan keyakinan bahwa teknologi harus dapat diakses oleh semua orang.
|
||||
- **Sundai Club** — untuk komunitas, energi, dan dorongan tanpa henti untuk membangun hal-hal yang penting.
|
||||
- **Dunia & Seterusnya** 🌍✨ — kepada setiap kontributor, pemimpi, dan pembangun di luar sana yang menjadikan open source sebagai kekuatan untuk kebaikan. Ini untuk kalian.
|
||||
|
||||
Kami membangun secara terbuka karena ide terbaik datang dari mana saja. Jika Anda membaca ini, Anda adalah bagian darinya. Selamat datang. 🦀❤️
|
||||
|
||||
## Berkontribusi
|
||||
|
||||
Baru di ZeroClaw? Cari isu berlabel [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — lihat [Panduan Kontribusi](CONTRIBUTING.md#first-time-contributors) untuk cara memulai. PR yang dibuat dengan AI/vibe-coded dipersilakan! 🤖
|
||||
|
||||
Lihat [CONTRIBUTING.md](CONTRIBUTING.md) dan [CLA.md](docs/contributing/cla.md). Implementasikan trait, kirimkan PR:
|
||||
|
||||
- Panduan alur kerja CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- `Provider` baru → `src/providers/`
|
||||
- `Channel` baru → `src/channels/`
|
||||
- `Observer` baru → `src/observability/`
|
||||
- `Tool` baru → `src/tools/`
|
||||
- `Memory` baru → `src/memory/`
|
||||
- `Tunnel` baru → `src/tunnel/`
|
||||
- `Peripheral` baru → `src/peripherals/`
|
||||
- `Skill` baru → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Repositori Resmi & Peringatan Peniruan
|
||||
|
||||
**Ini adalah satu-satunya repositori resmi ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Repositori, organisasi, domain, atau paket lain yang mengklaim sebagai "ZeroClaw" atau menyiratkan afiliasi dengan ZeroClaw Labs adalah **tidak sah dan tidak berafiliasi dengan proyek ini**. Fork tidak sah yang diketahui akan terdaftar di [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Jika Anda menemukan peniruan atau penyalahgunaan merek dagang, silakan [buka isu](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Lisensi
|
||||
|
||||
ZeroClaw memiliki dual-license untuk keterbukaan maksimum dan perlindungan kontributor:
|
||||
|
||||
| Lisensi | Kasus penggunaan |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open-source, riset, akademik, penggunaan pribadi |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Perlindungan paten, institusional, deployment komersial |
|
||||
|
||||
Anda dapat memilih salah satu lisensi. **Kontributor secara otomatis memberikan hak di bawah keduanya** — lihat [CLA.md](docs/contributing/cla.md) untuk perjanjian kontributor lengkap.
|
||||
|
||||
### Merek Dagang
|
||||
|
||||
Nama dan logo **ZeroClaw** adalah merek dagang dari ZeroClaw Labs. Lisensi ini tidak memberikan izin untuk menggunakannya untuk menyiratkan dukungan atau afiliasi. Lihat [TRADEMARK.md](docs/maintainers/trademark.md) untuk penggunaan yang diizinkan dan dilarang.
|
||||
|
||||
### Perlindungan Kontributor
|
||||
|
||||
- Anda **mempertahankan hak cipta** atas kontribusi Anda
|
||||
- **Hibah paten** (Apache 2.0) melindungi Anda dari klaim paten oleh kontributor lain
|
||||
- Kontribusi Anda **secara permanen diatribusikan** dalam riwayat commit dan [NOTICE](NOTICE)
|
||||
- Tidak ada hak merek dagang yang dialihkan dengan berkontribusi
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nol overhead. Nol kompromi. Deploy di mana saja. Tukar apa saja. 🦀
|
||||
|
||||
## Kontributor
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Daftar ini dihasilkan dari grafik kontributor GitHub dan diperbarui secara otomatis.
|
||||
|
||||
## Riwayat Bintang
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.it.md
755
README.it.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Assistente Personale IA</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Zero overhead. Zero compromessi. 100% Rust. 100% Agnostico.</strong><br>
|
||||
⚡️ <strong>Funziona su hardware da $10 con <5MB di RAM: il 99% in meno di memoria rispetto a OpenClaw e il 98% più economico di un Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Costruito da studenti e membri delle comunità di Harvard, MIT e Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Lingue:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw è un assistente personale IA che esegui sui tuoi dispositivi. Ti risponde sui canali che già usi (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work e altri). Ha una dashboard web per il controllo in tempo reale e può connettersi a periferiche hardware (ESP32, STM32, Arduino, Raspberry Pi). Il Gateway è solo il piano di controllo — il prodotto è l'assistente.
|
||||
|
||||
Se vuoi un assistente personale, per un singolo utente, che sia locale, veloce e sempre attivo, questo fa per te.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Sito web</a> ·
|
||||
<a href="docs/README.md">Documentazione</a> ·
|
||||
<a href="docs/architecture.md">Architettura</a> ·
|
||||
<a href="#avvio-rapido">Per iniziare</a> ·
|
||||
<a href="#migrazione-da-openclaw">Migrazione da OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Risoluzione problemi</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Configurazione consigliata:** esegui `zeroclaw onboard` nel tuo terminale. ZeroClaw Onboard ti guida passo dopo passo nella configurazione del gateway, workspace, canali e provider. È il percorso di configurazione consigliato e funziona su macOS, Linux e Windows (tramite WSL2). Nuova installazione? Inizia qui: [Per iniziare](#avvio-rapido)
|
||||
|
||||
### Autenticazione tramite abbonamento (OAuth)
|
||||
|
||||
- **OpenAI Codex** (abbonamento ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (chiave API o token di autenticazione)
|
||||
|
||||
Nota sui modelli: sebbene siano supportati molti provider/modelli, per la migliore esperienza usa il modello di ultima generazione più potente a tua disposizione. Vedi [Onboarding](#avvio-rapido).
|
||||
|
||||
Configurazione modelli + CLI: [Riferimento provider](docs/reference/api/providers-reference.md)
|
||||
Rotazione profili di autenticazione (OAuth vs chiavi API) + failover: [Failover modelli](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installazione (consigliata)
|
||||
|
||||
Requisito: toolchain stabile di Rust. Un singolo binario, nessuna dipendenza di runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Bootstrap con un clic
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` viene eseguito automaticamente dopo l'installazione per configurare il tuo workspace e provider.
|
||||
|
||||
## Avvio rapido (TL;DR)
|
||||
|
||||
Guida completa per principianti (autenticazione, accoppiamento, canali): [Per iniziare](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installa + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Avvia il gateway (server webhook + dashboard web)
|
||||
zeroclaw gateway # predefinito: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # porta casuale (sicurezza rafforzata)
|
||||
|
||||
# Parla con l'assistente
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Modalità interattiva
|
||||
zeroclaw agent
|
||||
|
||||
# Avvia il runtime autonomo completo (gateway + canali + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Controlla lo stato
|
||||
zeroclaw status
|
||||
|
||||
# Esegui diagnostica
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Aggiornamento? Esegui `zeroclaw doctor` dopo l'aggiornamento.
|
||||
|
||||
### Dal codice sorgente (sviluppo)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Alternativa per lo sviluppo (senza installazione globale):** anteponi `cargo run --release --` ai comandi (esempio: `cargo run --release -- status`).
|
||||
|
||||
## Migrazione da OpenClaw
|
||||
|
||||
ZeroClaw può importare il tuo workspace, memoria e configurazione da OpenClaw:
|
||||
|
||||
```bash
|
||||
# Anteprima di ciò che verrà migrato (sicuro, sola lettura)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Esegui la migrazione
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Questo migra le tue voci di memoria, i file del workspace e la configurazione da `~/.openclaw/` a `~/.zeroclaw/`. La configurazione viene convertita da JSON a TOML automaticamente.
|
||||
|
||||
## Impostazioni di sicurezza predefinite (accesso DM)
|
||||
|
||||
ZeroClaw si connette a superfici di messaggistica reali. Tratta i DM in arrivo come input non attendibile.
|
||||
|
||||
Guida completa alla sicurezza: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Comportamento predefinito su tutti i canali:
|
||||
|
||||
- **Accoppiamento DM** (predefinito): i mittenti sconosciuti ricevono un breve codice di accoppiamento e il bot non elabora il loro messaggio.
|
||||
- Approva con: `zeroclaw pairing approve <channel> <code>` (il mittente viene quindi aggiunto a una allowlist locale).
|
||||
- I DM pubblici in arrivo richiedono un'attivazione esplicita in `config.toml`.
|
||||
- Esegui `zeroclaw doctor` per individuare politiche DM rischiose o mal configurate.
|
||||
|
||||
**Livelli di autonomia:**
|
||||
|
||||
| Livello | Comportamento |
|
||||
|---------|---------------|
|
||||
| `ReadOnly` | L'agente può osservare ma non agire |
|
||||
| `Supervised` (predefinito) | L'agente agisce con approvazione per operazioni a rischio medio/alto |
|
||||
| `Full` | L'agente agisce autonomamente entro i limiti della policy |
|
||||
|
||||
**Livelli di sandboxing:** isolamento del workspace, blocco del traversal dei percorsi, allowlist dei comandi, percorsi proibiti (`/etc`, `/root`, `~/.ssh`), limitazione della velocità (max azioni/ora, tetti di costo/giorno).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Annunci
|
||||
|
||||
Usa questa bacheca per avvisi importanti (breaking change, avvisi di sicurezza, finestre di manutenzione e bloccanti del rilascio).
|
||||
|
||||
| Data (UTC) | Livello | Avviso | Azione |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Critico_ | **Non siamo affiliati** con `openagen/zeroclaw`, `zeroclaw.org` o `zeroclaw.net`. I domini `zeroclaw.org` e `zeroclaw.net` attualmente puntano al fork `openagen/zeroclaw`, e quel dominio/repository stanno impersonando il nostro sito web/progetto ufficiale. | Non fidarti di informazioni, binari, raccolte fondi o annunci da quelle fonti. Usa solo [questo repository](https://github.com/zeroclaw-labs/zeroclaw) e i nostri account social verificati. |
|
||||
| 2026-02-21 | _Importante_ | Il nostro sito web ufficiale è ora online: [zeroclawlabs.ai](https://zeroclawlabs.ai). Grazie per la pazienza mentre preparavamo il lancio. Continuiamo a vedere tentativi di impersonificazione, quindi **non** partecipare ad attività di investimento o raccolta fondi che usano il nome ZeroClaw a meno che non siano pubblicate attraverso i nostri canali ufficiali. | Usa [questo repository](https://github.com/zeroclaw-labs/zeroclaw) come unica fonte di verità. Segui [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Gruppo)](https://www.facebook.com/groups/zeroclawlabs) e [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) per aggiornamenti ufficiali. |
|
||||
| 2026-02-19 | _Importante_ | Anthropic ha aggiornato i termini di Autenticazione e Uso delle Credenziali il 2026-02-19. I token OAuth di Claude Code (Free, Pro, Max) sono destinati esclusivamente a Claude Code e Claude.ai; usare token OAuth di Claude Free/Pro/Max in qualsiasi altro prodotto, strumento o servizio (incluso Agent SDK) non è consentito e può violare i Termini di Servizio del Consumatore. | Per favore, evita temporaneamente le integrazioni OAuth di Claude Code per prevenire potenziali perdite. Clausola originale: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Punti di forza
|
||||
|
||||
- **Runtime leggero per impostazione predefinita** — i flussi di lavoro comuni di CLI e stato funzionano in pochi megabyte di memoria nelle build release.
|
||||
- **Distribuzione economica** — progettato per schede da $10 e piccole istanze cloud, nessuna dipendenza di runtime pesante.
|
||||
- **Avvio a freddo rapido** — il runtime Rust a binario singolo mantiene l'avvio dei comandi e del daemon quasi istantaneo.
|
||||
- **Architettura portabile** — un binario per ARM, x86 e RISC-V con provider/canali/strumenti intercambiabili.
|
||||
- **Gateway local-first** — piano di controllo unico per sessioni, canali, strumenti, cron, SOP ed eventi.
|
||||
- **Casella di posta multicanale** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket e altri.
|
||||
- **Orchestrazione multi-agente (Hands)** — sciami di agenti autonomi che funzionano secondo programma e diventano più intelligenti nel tempo.
|
||||
- **Procedure Operative Standard (SOP)** — automazione dei flussi di lavoro guidata da eventi con MQTT, webhook, cron e trigger dei periferici.
|
||||
- **Dashboard web** — interfaccia web React 19 + Vite con chat in tempo reale, browser della memoria, editor di configurazione, gestore cron e ispettore degli strumenti.
|
||||
- **Periferiche hardware** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO tramite il trait `Peripheral`.
|
||||
- **Strumenti di prima classe** — shell, I/O file, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace e oltre 70 altri.
|
||||
- **Hook del ciclo di vita** — intercetta e modifica chiamate LLM, esecuzioni di strumenti e messaggi in ogni fase.
|
||||
- **Piattaforma skill** — skill incluse, della community e del workspace con audit di sicurezza.
|
||||
- **Supporto tunnel** — Cloudflare, Tailscale, ngrok, OpenVPN e tunnel personalizzati per l'accesso remoto.
|
||||
|
||||
### Perché i team scelgono ZeroClaw
|
||||
|
||||
- **Leggero per impostazione predefinita:** binario Rust piccolo, avvio rapido, basso consumo di memoria.
|
||||
- **Sicuro per design:** accoppiamento, sandboxing rigoroso, allowlist esplicite, scoping del workspace.
|
||||
- **Completamente intercambiabile:** i sistemi centrali sono trait (provider, canali, strumenti, memoria, tunnel).
|
||||
- **Nessun vendor lock-in:** supporto provider compatibili con OpenAI + endpoint personalizzati collegabili.
|
||||
|
||||
## Riepilogo benchmark (ZeroClaw vs OpenClaw, riproducibile)
|
||||
|
||||
Benchmark rapido su macchina locale (macOS arm64, feb 2026) normalizzato per hardware edge a 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Linguaggio** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Avvio (core 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Dimensione binario** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Costo** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Qualsiasi hardware $10** |
|
||||
|
||||
> Note: I risultati di ZeroClaw sono misurati su build release usando `/usr/bin/time -l`. OpenClaw richiede il runtime Node.js (tipicamente ~390MB di overhead di memoria aggiuntivo), mentre NanoBot richiede il runtime Python. PicoClaw e ZeroClaw sono binari statici. I valori di RAM sopra sono memoria a runtime; i requisiti di compilazione sono superiori.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Misurazione locale riproducibile
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Tutto ciò che abbiamo costruito finora
|
||||
|
||||
### Piattaforma centrale
|
||||
|
||||
- Piano di controllo Gateway HTTP/WS/SSE con sessioni, presenza, configurazione, cron, webhook, dashboard web e accoppiamento.
|
||||
- Superficie CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Loop di orchestrazione dell'agente con dispatch degli strumenti, costruzione dei prompt, classificazione dei messaggi e caricamento della memoria.
|
||||
- Modello di sessione con applicazione delle policy di sicurezza, livelli di autonomia e approvazione condizionale.
|
||||
- Wrapper provider resiliente con failover, retry e routing dei modelli su oltre 20 backend LLM.
|
||||
|
||||
### Canali
|
||||
|
||||
Canali: WhatsApp (nativo), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Abilitati tramite feature gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Dashboard web
|
||||
|
||||
Dashboard web React 19 + Vite 6 + Tailwind CSS 4 servita direttamente dal Gateway:
|
||||
|
||||
- **Dashboard** — panoramica del sistema, stato di salute, uptime, tracciamento dei costi
|
||||
- **Chat dell'agente** — chat interattiva con l'agente
|
||||
- **Memoria** — esplora e gestisci le voci di memoria
|
||||
- **Configurazione** — visualizza e modifica la configurazione
|
||||
- **Cron** — gestisci attività programmate
|
||||
- **Strumenti** — esplora gli strumenti disponibili
|
||||
- **Log** — visualizza i log di attività dell'agente
|
||||
- **Costi** — utilizzo dei token e tracciamento dei costi
|
||||
- **Doctor** — diagnostica della salute del sistema
|
||||
- **Integrazioni** — stato e configurazione delle integrazioni
|
||||
- **Accoppiamento** — gestione dell'accoppiamento dei dispositivi
|
||||
|
||||
### Obiettivi firmware
|
||||
|
||||
| Obiettivo | Piattaforma | Scopo |
|
||||
|-----------|-------------|-------|
|
||||
| ESP32 | Espressif ESP32 | Agente periferico wireless |
|
||||
| ESP32-UI | ESP32 + Display | Agente con interfaccia visiva |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periferico industriale |
|
||||
| Arduino | Arduino | Ponte base sensori/attuatori |
|
||||
| Uno Q Bridge | Arduino Uno | Ponte seriale verso l'agente |
|
||||
|
||||
### Strumenti + automazione
|
||||
|
||||
- **Core:** shell, lettura/scrittura/modifica file, operazioni git, ricerca glob, ricerca contenuti
|
||||
- **Web:** controllo browser, web fetch, web search, screenshot, informazioni immagine, lettura PDF
|
||||
- **Integrazioni:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + set di strumenti differiti
|
||||
- **Programmazione:** cron add/remove/update/run, strumento di programmazione
|
||||
- **Memoria:** recall, store, forget, knowledge, project intel
|
||||
- **Avanzato:** delegate (agente-a-agente), swarm, cambio/routing modelli, operazioni di sicurezza, operazioni cloud
|
||||
- **Hardware:** board info, memory map, memory read (abilitato tramite feature gate)
|
||||
|
||||
### Runtime + sicurezza
|
||||
|
||||
- **Livelli di autonomia:** ReadOnly, Supervised (predefinito), Full.
|
||||
- **Sandboxing:** isolamento del workspace, blocco del traversal dei percorsi, allowlist dei comandi, percorsi proibiti, Landlock (Linux), Bubblewrap.
|
||||
- **Limitazione della velocità:** max azioni per ora, max costo per giorno (configurabile).
|
||||
- **Approvazione condizionale:** approvazione interattiva per operazioni a rischio medio/alto.
|
||||
- **Arresto di emergenza:** capacità di spegnimento di emergenza.
|
||||
- **129+ test di sicurezza** in CI automatizzato.
|
||||
|
||||
### Operazioni + packaging
|
||||
|
||||
- Dashboard web servita direttamente dal Gateway.
|
||||
- Supporto tunnel: Cloudflare, Tailscale, ngrok, OpenVPN, comando personalizzato.
|
||||
- Adattatore runtime Docker per esecuzione in container.
|
||||
- CI/CD: beta (automatico al push) → stable (dispatch manuale) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Binari precompilati per Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Configurazione
|
||||
|
||||
`~/.zeroclaw/config.toml` minimo:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Riferimento completo della configurazione: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Configurazione dei canali
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Configurazione dei tunnel
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # o "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Dettagli: [Riferimento canali](docs/reference/api/channels-reference.md) · [Riferimento configurazione](docs/reference/api/config-reference.md)
|
||||
|
||||
### Supporto runtime (attuale)
|
||||
|
||||
- **`native`** (predefinito) — esecuzione diretta dei processi, percorso più veloce, ideale per ambienti fidati.
|
||||
- **`docker`** — isolamento completo in container, policy di sicurezza forzate, richiede Docker.
|
||||
|
||||
Imposta `runtime.kind = "docker"` per sandboxing rigoroso o isolamento di rete.
|
||||
|
||||
## Autenticazione tramite abbonamento (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw supporta profili di autenticazione nativi tramite abbonamento (multi-account, crittografati a riposo).
|
||||
|
||||
- File di archiviazione: `~/.zeroclaw/auth-profiles.json`
|
||||
- Chiave di crittografia: `~/.zeroclaw/.secret_key`
|
||||
- Formato id profilo: `<provider>:<profile_name>` (esempio: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (abbonamento ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Controlla / aggiorna / cambia profilo
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Esegui l'agente con autenticazione tramite abbonamento
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace dell'agente + skill
|
||||
|
||||
Root del workspace: `~/.zeroclaw/workspace/` (configurabile tramite config).
|
||||
|
||||
File di prompt iniettati:
|
||||
- `IDENTITY.md` — personalità e ruolo dell'agente
|
||||
- `USER.md` — contesto e preferenze dell'utente
|
||||
- `MEMORY.md` — fatti e lezioni a lungo termine
|
||||
- `AGENTS.md` — convenzioni di sessione e regole di inizializzazione
|
||||
- `SOUL.md` — identità centrale e principi operativi
|
||||
|
||||
Skill: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` o `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Elenca le skill installate
|
||||
zeroclaw skills list
|
||||
|
||||
# Installa da git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Audit di sicurezza prima dell'installazione
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Rimuovi una skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Comandi CLI
|
||||
|
||||
```bash
|
||||
# Gestione del workspace
|
||||
zeroclaw onboard # Procedura guidata di configurazione
|
||||
zeroclaw status # Mostra stato del daemon/agente
|
||||
zeroclaw doctor # Esegui diagnostica del sistema
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Avvia server gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Avvia runtime autonomo completo
|
||||
|
||||
# Agente
|
||||
zeroclaw agent # Modalità chat interattiva
|
||||
zeroclaw agent -m "message" # Modalità messaggio singolo
|
||||
|
||||
# Gestione servizi
|
||||
zeroclaw service install # Installa come servizio del SO (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Canali
|
||||
zeroclaw channel list # Elenca i canali configurati
|
||||
zeroclaw channel doctor # Controlla la salute dei canali
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + programmazione
|
||||
zeroclaw cron list # Elenca i lavori programmati
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memoria
|
||||
zeroclaw memory list # Elenca le voci di memoria
|
||||
zeroclaw memory get <key> # Recupera una memoria
|
||||
zeroclaw memory stats # Statistiche della memoria
|
||||
|
||||
# Profili di autenticazione
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Periferiche hardware
|
||||
zeroclaw hardware discover # Scansiona i dispositivi connessi
|
||||
zeroclaw peripheral list # Elenca le periferiche connesse
|
||||
zeroclaw peripheral flash # Flash del firmware sul dispositivo
|
||||
|
||||
# Migrazione
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Completamento shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Riferimento completo dei comandi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Prerequisiti
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Richiesto
|
||||
|
||||
1. **Visual Studio Build Tools** (fornisce il linker MSVC e il Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Durante l'installazione (o tramite il Visual Studio Installer), seleziona il carico di lavoro **"Sviluppo desktop con C++"**.
|
||||
|
||||
2. **Toolchain di Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Dopo l'installazione, apri un nuovo terminale ed esegui `rustup default stable` per assicurarti che la toolchain stabile sia attiva.
|
||||
|
||||
3. **Verifica** che entrambi funzionino:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opzionale
|
||||
|
||||
- **Docker Desktop** — necessario solo se usi il [runtime sandbox con Docker](#supporto-runtime-attuale) (`runtime.kind = "docker"`). Installa tramite `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Richiesto
|
||||
|
||||
1. **Strumenti di compilazione essenziali:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Installa Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Toolchain di Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Vedi [rustup.rs](https://rustup.rs) per i dettagli.
|
||||
|
||||
3. **Verifica** che entrambi funzionino:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Installatore in una riga
|
||||
|
||||
Oppure salta i passaggi precedenti e installa tutto (dipendenze di sistema, Rust, ZeroClaw) con un solo comando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Requisiti di risorse per la compilazione
|
||||
|
||||
Compilare dal codice sorgente richiede più risorse rispetto all'esecuzione del binario risultante:
|
||||
|
||||
| Risorsa | Minimo | Consigliato |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Disco libero**| 6 GB | 10 GB+ |
|
||||
|
||||
Se il tuo host è al di sotto del minimo, usa i binari precompilati:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Per richiedere l'installazione solo da binari senza compilazione di fallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opzionale
|
||||
|
||||
- **Docker** — necessario solo se usi il [runtime sandbox con Docker](#supporto-runtime-attuale) (`runtime.kind = "docker"`). Installa tramite il tuo gestore di pacchetti o [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Nota:** Il `cargo build --release` predefinito usa `codegen-units=1` per ridurre la pressione massima di compilazione. Per build più veloci su macchine potenti, usa `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Binari precompilati
|
||||
|
||||
Gli asset di release sono pubblicati per:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Scarica gli ultimi asset da:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Documentazione
|
||||
|
||||
Usa queste risorse quando hai superato il flusso di onboarding e vuoi il riferimento più approfondito.
|
||||
|
||||
- Inizia con l'[indice della documentazione](docs/README.md) per la navigazione e "cosa c'è dove."
|
||||
- Leggi la [panoramica dell'architettura](docs/architecture.md) per il modello completo del sistema.
|
||||
- Usa il [riferimento della configurazione](docs/reference/api/config-reference.md) quando hai bisogno di ogni chiave ed esempio.
|
||||
- Esegui il Gateway secondo il libro con il [runbook operativo](docs/ops/operations-runbook.md).
|
||||
- Segui [ZeroClaw Onboard](#avvio-rapido) per una configurazione guidata.
|
||||
- Risolvi errori comuni con la [guida alla risoluzione dei problemi](docs/ops/troubleshooting.md).
|
||||
- Rivedi la [guida alla sicurezza](docs/security/README.md) prima di esporre qualsiasi cosa.
|
||||
|
||||
### Documentazione di riferimento
|
||||
|
||||
- Hub della documentazione: [docs/README.md](docs/README.md)
|
||||
- TOC unificato dei docs: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Riferimento comandi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Riferimento configurazione: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Riferimento provider: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Riferimento canali: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Runbook operativo: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Risoluzione problemi: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Documentazione di collaborazione
|
||||
|
||||
- Guida alla contribuzione: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Politica del flusso di lavoro PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Guida al flusso di lavoro CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Manuale del revisore: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Politica di divulgazione della sicurezza: [SECURITY.md](SECURITY.md)
|
||||
- Template della documentazione: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Distribuzione + operazioni
|
||||
|
||||
- Guida alla distribuzione in rete: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Manuale dell'agente proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Guide hardware: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw è stato costruito per il granchio liscio 🦀, un assistente IA veloce ed efficiente. Costruito da Argenis De La Rosa e la comunità.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Supporta ZeroClaw
|
||||
|
||||
Se ZeroClaw ti aiuta nel lavoro e vuoi supportare lo sviluppo continuo, puoi donare qui:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Ringraziamenti speciali
|
||||
|
||||
Un sentito ringraziamento alle comunità e alle istituzioni che ispirano e alimentano questo lavoro open source:
|
||||
|
||||
- **Harvard University** — per alimentare la curiosità intellettuale e spingere i confini del possibile.
|
||||
- **MIT** — per difendere la conoscenza aperta, l'open source e la convinzione che la tecnologia debba essere accessibile a tutti.
|
||||
- **Sundai Club** — per la comunità, l'energia e la spinta instancabile a costruire cose che contano.
|
||||
- **Il Mondo e Oltre** 🌍✨ — a ogni contributore, sognatore e costruttore che rende l'open source una forza per il bene. Questo è per te.
|
||||
|
||||
Stiamo costruendo apertamente perché le migliori idee vengono da ovunque. Se stai leggendo questo, ne fai parte. Benvenuto. 🦀❤️
|
||||
|
||||
## Contribuire
|
||||
|
||||
Nuovo su ZeroClaw? Cerca le issue etichettate [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — consulta la nostra [Guida alla contribuzione](CONTRIBUTING.md#first-time-contributors) per sapere come iniziare. PR con IA/vibe-coded sono benvenuti! 🤖
|
||||
|
||||
Vedi [CONTRIBUTING.md](CONTRIBUTING.md) e [CLA.md](docs/contributing/cla.md). Implementa un trait, invia un PR:
|
||||
|
||||
- Guida al flusso di lavoro CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Nuovo `Provider` → `src/providers/`
|
||||
- Nuovo `Channel` → `src/channels/`
|
||||
- Nuovo `Observer` → `src/observability/`
|
||||
- Nuovo `Tool` → `src/tools/`
|
||||
- Nuovo `Memory` → `src/memory/`
|
||||
- Nuovo `Tunnel` → `src/tunnel/`
|
||||
- Nuovo `Peripheral` → `src/peripherals/`
|
||||
- Nuovo `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Repository ufficiale e avviso di impersonificazione
|
||||
|
||||
**Questo è l'unico repository ufficiale di ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Qualsiasi altro repository, organizzazione, dominio o pacchetto che affermi di essere "ZeroClaw" o implichi un'affiliazione con ZeroClaw Labs **non è autorizzato e non è affiliato a questo progetto**. I fork non autorizzati conosciuti saranno elencati in [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Se incontri impersonificazione o uso improprio del marchio, per favore [apri una issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licenza
|
||||
|
||||
ZeroClaw ha doppia licenza per massima apertura e protezione dei contributori:
|
||||
|
||||
| Licenza | Caso d'uso |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open source, ricerca, accademico, uso personale |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Protezione brevetti, istituzionale, distribuzione commerciale |
|
||||
|
||||
Puoi scegliere una delle due licenze. **I contributori concedono automaticamente diritti sotto entrambe** — vedi [CLA.md](docs/contributing/cla.md) per l'accordo completo dei contributori.
|
||||
|
||||
### Marchio
|
||||
|
||||
Il nome e il logo di **ZeroClaw** sono marchi di ZeroClaw Labs. Questa licenza non concede il permesso di usarli per implicare approvazione o affiliazione. Vedi [TRADEMARK.md](docs/maintainers/trademark.md) per gli usi consentiti e proibiti.
|
||||
|
||||
### Protezioni per i contributori
|
||||
|
||||
- **Mantieni il copyright** delle tue contribuzioni
|
||||
- **Concessione di brevetti** (Apache 2.0) ti protegge da rivendicazioni di brevetti di altri contributori
|
||||
- Le tue contribuzioni sono **permanentemente attribuite** nella cronologia dei commit e [NOTICE](NOTICE)
|
||||
- Nessun diritto di marchio viene trasferito contribuendo
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Zero overhead. Zero compromessi. Distribuisci ovunque. Scambia qualsiasi cosa. 🦀
|
||||
|
||||
## Contributori
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Questa lista è generata dal grafico dei contributori di GitHub e si aggiorna automaticamente.
|
||||
|
||||
## Cronologia delle stelle
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
919
README.ja.md
919
README.ja.md
@ -1,250 +1,98 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — パーソナルAIアシスタント</h1>
|
||||
<h1 align="center">ZeroClaw 🦀（日本語）</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>ゼロオーバーヘッド。ゼロ妥協。100% Rust。100% 非依存。</strong><br>
|
||||
⚡️ <strong>10ドルのハードウェアで5MB未満のRAMで動作：OpenClawより99%少ないメモリ、Mac miniより98%安い！</strong>
|
||||
<strong>Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
|
||||
<a href="https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search"><img src="https://img.shields.io/badge/Xiaohongshu-Official-FF2442?style=flat" alt="Xiaohongshu: Official" /></a>
|
||||
<a href="https://t.me/zeroclawlabs"><img src="https://img.shields.io/badge/Telegram-%40zeroclawlabs-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclaw"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
ハーバード大学、MIT、Sundai.Clubコミュニティの学生とメンバーにより構築。
|
||||
🌐 言語: <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a> · <a href="README.fr.md">Français</a> · <a href="README.vi.md">Tiếng Việt</a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Languages:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
<a href="bootstrap.sh">ワンクリック導入</a> |
|
||||
<a href="docs/getting-started/README.md">導入ガイド</a> |
|
||||
<a href="docs/README.ja.md">ドキュメントハブ</a> |
|
||||
<a href="docs/SUMMARY.md">Docs TOC</a>
|
||||
</p>
|
||||
|
||||
ZeroClawは、あなた自身のデバイスで実行するパーソナルAIアシスタントです。既に使用しているチャンネル（WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、Nostr、Mattermost、Nextcloud Talk、DingTalk、Lark、QQ、Reddit、LinkedIn、Twitter、MQTT、WeChat Workなど）で応答します。リアルタイム制御用のウェブダッシュボードを備え、ハードウェア周辺機器（ESP32、STM32、Arduino、Raspberry Pi）に接続できます。Gatewayはコントロールプレーンに過ぎず、製品はアシスタントそのものです。
|
||||
|
||||
ローカルで高速、常時稼働のパーソナルなシングルユーザーアシスタントが必要なら、これがその答えです。
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">ウェブサイト</a> ·
|
||||
<a href="docs/README.md">ドキュメント</a> ·
|
||||
<a href="docs/architecture.md">アーキテクチャ</a> ·
|
||||
<a href="#クイックスタートtldr">はじめに</a> ·
|
||||
<a href="#openclawからの移行">OpenClawからの移行</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">トラブルシューティング</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
<strong>クイック分流：</strong>
|
||||
<a href="docs/reference/README.md">参照</a> ·
|
||||
<a href="docs/operations/README.md">運用</a> ·
|
||||
<a href="docs/troubleshooting.md">障害対応</a> ·
|
||||
<a href="docs/security/README.md">セキュリティ</a> ·
|
||||
<a href="docs/hardware/README.md">ハードウェア</a> ·
|
||||
<a href="docs/contributing/README.md">貢献・CI</a>
|
||||
</p>
|
||||
|
||||
> **推奨セットアップ：** ターミナルで `zeroclaw onboard` を実行してください。ZeroClaw Onboardがゲートウェイ、ワークスペース、チャンネル、プロバイダーのセットアップをステップバイステップでガイドします。これは推奨されるセットアップパスで、macOS、Linux、Windows（WSL2経由）で動作します。新規インストール？ここから開始：[はじめに](#クイックスタートtldr)
|
||||
> この文書は `README.md` の内容を、正確性と可読性を重視して日本語に整えた版です（逐語訳ではありません）。
|
||||
>
|
||||
> コマンド名、設定キー、API パス、Trait 名などの技術識別子は英語のまま維持しています。
|
||||
>
|
||||
> 最終同期日: **2026-02-19**。
|
||||
|
||||
### サブスクリプション認証（OAuth）
|
||||
## 📢 お知らせボード
|
||||
|
||||
- **OpenAI Codex**（ChatGPTサブスクリプション）
|
||||
- **Gemini**（Google OAuth）
|
||||
- **Anthropic**（APIキーまたは認証トークン）
|
||||
重要なお知らせ（互換性破壊変更、セキュリティ告知、メンテナンス時間、リリース阻害事項など）をここに掲載します。
|
||||
|
||||
モデルに関する注意：多くのプロバイダー/モデルがサポートされていますが、最良のエクスペリエンスのために、利用可能な最新世代の最も強力なモデルを使用してください。[オンボーディング](#クイックスタートtldr)を参照。
|
||||
| 日付 (UTC) | レベル | お知らせ | 対応 |
|
||||
|---|---|---|---|
|
||||
| 2026-02-19 | _緊急_ | 私たちは `openagen/zeroclaw` および `zeroclaw.org` とは**一切関係ありません**。`zeroclaw.org` は現在 `openagen/zeroclaw` の fork を指しており、そのドメイン/リポジトリは当プロジェクトの公式サイト・公式プロジェクトを装っています。 | これらの情報源による案内、バイナリ、資金調達情報、公式発表は信頼しないでください。必ず[本リポジトリ](https://github.com/zeroclaw-labs/zeroclaw)と認証済み公式SNSのみを参照してください。 |
|
||||
| 2026-02-21 | _重要_ | 公式サイトを公開しました: [zeroclawlabs.ai](https://zeroclawlabs.ai)。公開までお待ちいただきありがとうございました。引き続きなりすましの試みを確認しているため、ZeroClaw 名義の投資・資金調達などの案内は、公式チャネルで確認できない限り参加しないでください。 | 情報は[本リポジトリ](https://github.com/zeroclaw-labs/zeroclaw)を最優先で確認し、[X（@zeroclawlabs）](https://x.com/zeroclawlabs?s=21)、[Telegram（@zeroclawlabs）](https://t.me/zeroclawlabs)、[Facebook（グループ）](https://www.facebook.com/groups/zeroclaw)、[Reddit（r/zeroclawlabs）](https://www.reddit.com/r/zeroclawlabs/) と [小紅書アカウント](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search) で公式更新を確認してください。 |
|
||||
| 2026-02-19 | _重要_ | Anthropic は 2026-02-19 に Authentication and Credential Use を更新しました。条文では、OAuth authentication（Free/Pro/Max）は Claude Code と Claude.ai 専用であり、Claude Free/Pro/Max で取得した OAuth トークンを他の製品・ツール・サービス（Agent SDK を含む）で使用することは許可されず、Consumer Terms of Service 違反に該当すると明記されています。 | 損失回避のため、当面は Claude Code OAuth 連携を試さないでください。原文: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)。 |
|
||||
|
||||
モデル設定 + CLI：[プロバイダーリファレンス](docs/reference/api/providers-reference.md)
|
||||
認証プロファイルローテーション（OAuth vs APIキー）+ フェイルオーバー：[モデルフェイルオーバー](docs/reference/api/providers-reference.md)
|
||||
## 概要
|
||||
|
||||
## インストール（推奨）
|
||||
ZeroClaw は、高速・省リソース・高拡張性を重視した自律エージェント実行基盤です。ZeroClawはエージェントワークフローのための**ランタイムオペレーティングシステム**です — モデル、ツール、メモリ、実行を抽象化し、エージェントを一度構築すればどこでも実行できるインフラストラクチャです。
|
||||
|
||||
ランタイム：Rust stable ツールチェーン。単一バイナリ、ランタイム依存なし。
|
||||
- Rust ネイティブ実装、単一バイナリで配布可能
|
||||
- Trait ベース設計（`Provider` / `Channel` / `Tool` / `Memory` など）
|
||||
- セキュアデフォルト（ペアリング、明示 allowlist、サンドボックス、スコープ制御）
|
||||
|
||||
### Homebrew（macOS/Linuxbrew）
|
||||
## ZeroClaw が選ばれる理由
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### ワンクリックブートストラップ
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` はインストール後に自動的に実行され、ワークスペースとプロバイダーを設定します。
|
||||
|
||||
## クイックスタート（TL;DR）
|
||||
|
||||
完全な初心者ガイド（認証、ペアリング、チャンネル）：[はじめに](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# インストール + オンボード
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# ゲートウェイを起動（webhookサーバー + ウェブダッシュボード）
|
||||
zeroclaw gateway # デフォルト：127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # ランダムポート（セキュリティ強化）
|
||||
|
||||
# アシスタントと会話
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# インタラクティブモード
|
||||
zeroclaw agent
|
||||
|
||||
# フル自律ランタイムを起動（ゲートウェイ + チャンネル + cron + hands）
|
||||
zeroclaw daemon
|
||||
|
||||
# ステータス確認
|
||||
zeroclaw status
|
||||
|
||||
# 診断を実行
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
アップグレード？更新後に `zeroclaw doctor` を実行してください。
|
||||
|
||||
### ソースからビルド（開発）
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **開発用代替手段（グローバルインストールなし）：** コマンドの前に `cargo run --release --` を付けてください（例：`cargo run --release -- status`）。
|
||||
|
||||
## OpenClawからの移行
|
||||
|
||||
ZeroClawはOpenClawのワークスペース、メモリ、設定をインポートできます：
|
||||
|
||||
```bash
|
||||
# 移行内容のプレビュー（安全、読み取り専用）
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# 移行を実行
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
これにより、メモリエントリ、ワークスペースファイル、設定が `~/.openclaw/` から `~/.zeroclaw/` に移行されます。設定はJSONからTOMLに自動変換されます。
|
||||
|
||||
## セキュリティデフォルト（DMアクセス）
|
||||
|
||||
ZeroClawは実際のメッセージングサービスに接続します。着信DMを信頼できない入力として扱ってください。
|
||||
|
||||
完全なセキュリティガイド：[SECURITY.md](SECURITY.md)
|
||||
|
||||
すべてのチャンネルのデフォルト動作：
|
||||
|
||||
- **DMペアリング**（デフォルト）：不明な送信者には短いペアリングコードが送信され、ボットはメッセージを処理しません。
|
||||
- 承認方法：`zeroclaw pairing approve <channel> <code>`（送信者がローカル許可リストに追加されます）。
|
||||
- パブリック着信DMには `config.toml` での明示的なオプトインが必要です。
|
||||
- `zeroclaw doctor` を実行してリスクのある、または設定ミスのあるDMポリシーを検出します。
|
||||
|
||||
**自律レベル：**
|
||||
|
||||
| レベル | 動作 |
|
||||
|--------|------|
|
||||
| `ReadOnly` | エージェントは観察のみで操作不可 |
|
||||
| `Supervised`（デフォルト） | エージェントは中/高リスク操作時に承認が必要 |
|
||||
| `Full` | エージェントはポリシー範囲内で自律的に操作 |
|
||||
|
||||
**サンドボックス層：** ワークスペース分離、パストラバーサルブロック、コマンド許可リスト、禁止パス（`/etc`、`/root`、`~/.ssh`）、レート制限（時間あたり最大アクション数、日あたりコスト上限）。
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 お知らせ
|
||||
|
||||
このボードは重要な通知（破壊的変更、セキュリティアドバイザリ、メンテナンスウィンドウ、リリースブロッカー）に使用します。
|
||||
|
||||
| 日付 (UTC) | レベル | 通知 | 対応 |
|
||||
| ---------- | ------ | ---- | ---- |
|
||||
| 2026-02-19 | _重大_ | 当プロジェクトは `openagen/zeroclaw`、`zeroclaw.org`、`zeroclaw.net` とは**一切関係ありません**。`zeroclaw.org` と `zeroclaw.net` ドメインは現在 `openagen/zeroclaw` フォークを指しており、そのドメイン/リポジトリは当プロジェクトの公式ウェブサイト/プロジェクトを偽装しています。 | それらのソースからの情報、バイナリ、資金調達、告知を信頼しないでください。[このリポジトリ](https://github.com/zeroclaw-labs/zeroclaw)と認証済みのソーシャルアカウントのみを使用してください。 |
|
||||
| 2026-02-21 | _重要_ | 公式ウェブサイトが公開されました：[zeroclawlabs.ai](https://zeroclawlabs.ai)。ローンチ準備中のお待ちいただき、ありがとうございます。引き続き偽装行為が確認されていますので、公式チャンネルを通じて公開されない限り、ZeroClawの名前を使った投資や資金調達活動には**参加しないでください**。 | [このリポジトリ](https://github.com/zeroclaw-labs/zeroclaw)を唯一の信頼できる情報源として使用してください。公式アップデートは [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21)、[Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs)、[Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) をフォローしてください。 |
|
||||
| 2026-02-19 | _重要_ | Anthropicは2026-02-19に認証と資格情報の使用に関する規約を更新しました。Claude Code OAuthトークン（Free、Pro、Max）はClaude CodeおよびClaude.ai専用です。Claude Free/Pro/MaxのOAuthトークンを他の製品、ツール、サービス（Agent SDKを含む）で使用することは許可されておらず、消費者利用規約に違反する可能性があります。 | 潜在的な損失を防ぐため、一時的にClaude Code OAuth統合を避けてください。元の条項：[Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use)。 |
|
||||
|
||||
## ハイライト
|
||||
|
||||
- **デフォルトでリーンなランタイム** — 一般的なCLIとステータスワークフローは、リリースビルドで数メガバイトのメモリエンベロープで実行されます。
|
||||
- **コスト効率の良いデプロイ** — 10ドルボードや小規模クラウドインスタンス向けに設計、重量級ランタイム依存なし。
|
||||
- **高速コールドスタート** — シングルバイナリRustランタイムにより、コマンドとデーモンの起動がほぼ瞬時。
|
||||
- **ポータブルアーキテクチャ** — ARM、x86、RISC-Vにまたがる単一バイナリで、プロバイダー/チャンネル/ツールが交換可能。
|
||||
- **ローカルファーストゲートウェイ** — セッション、チャンネル、ツール、cron、SOP、イベントの単一コントロールプレーン。
|
||||
- **マルチチャンネル受信箱** — WhatsApp、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、Nostr、Mattermost、Nextcloud Talk、DingTalk、Lark、QQ、Reddit、LinkedIn、Twitter、MQTT、WeChat Work、WebSocketなど。
|
||||
- **マルチエージェントオーケストレーション（Hands）** — スケジュールに基づいて実行され、時間とともにスマートになる自律エージェントスウォーム。
|
||||
- **標準運用手順（SOPs）** — MQTT、webhook、cron、周辺機器トリガーによるイベント駆動ワークフロー自動化。
|
||||
- **ウェブダッシュボード** — React 19 + Viteウェブ UIで、リアルタイムチャット、メモリブラウザ、設定エディタ、cronマネージャー、ツールインスペクター。
|
||||
- **ハードウェア周辺機器** — `Peripheral` traitを通じてESP32、STM32 Nucleo、Arduino、Raspberry Pi GPIOをサポート。
|
||||
- **ファーストクラスツール** — shell、ファイルI/O、ブラウザ、git、ウェブフェッチ/検索、MCP、Jira、Notion、Google Workspaceなど70以上。
|
||||
- **ライフサイクルフック** — あらゆる段階でLLM呼び出し、ツール実行、メッセージをインターセプトおよび変更。
|
||||
- **スキルプラットフォーム** — バンドル、コミュニティ、ワークスペーススキルとセキュリティ監査。
|
||||
- **トンネルサポート** — Cloudflare、Tailscale、ngrok、OpenVPN、カスタムトンネルによるリモートアクセス。
|
||||
|
||||
### チームがZeroClawを選ぶ理由
|
||||
|
||||
- **デフォルトでリーン：** 小型Rustバイナリ、高速起動、低メモリフットプリント。
|
||||
- **設計によるセキュリティ：** ペアリング、厳格なサンドボックス、明示的な許可リスト、ワークスペーススコーピング。
|
||||
- **完全に交換可能：** コアシステムはすべてtrait（プロバイダー、チャンネル、ツール、メモリ、トンネル）。
|
||||
- **ロックインなし：** OpenAI互換プロバイダーサポート + プラガブルなカスタムエンドポイント。
|
||||
- **軽量ランタイムを標準化**: CLI や `status` などの常用操作は数MB級メモリで動作。
|
||||
- **低コスト環境に適合**: 低価格ボードや小規模クラウドでも、重い実行基盤なしで運用可能。
|
||||
- **高速コールドスタート**: Rust 単一バイナリにより、主要コマンドと daemon 起動が非常に速い。
|
||||
- **高い移植性**: ARM / x86 / RISC-V を同じ運用モデルで扱え、provider/channel/tool を差し替え可能。
|
||||
|
||||
## ベンチマークスナップショット（ZeroClaw vs OpenClaw、再現可能）
|
||||
|
||||
ローカルマシンクイックベンチマーク（macOS arm64、2026年2月）、0.8GHzエッジハードウェア向けに正規化。
|
||||
以下はローカルのクイック比較（macOS arm64、2026年2月）を、0.8GHz エッジ CPU 基準で正規化したものです。
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **言語** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **起動時間（0.8GHzコア）** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **バイナリサイズ** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **コスト** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **任意のハードウェア $10** |
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
|---|---|---|---|---|
|
||||
| **言語** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **起動時間（0.8GHz コア）** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **バイナリサイズ** | ~28MB（dist） | N/A（スクリプト） | ~8MB | **~8.8 MB** |
|
||||
| **コスト** | Mac Mini $599 | Linux SBC ~$50 | Linux ボード $10 | **任意の $10 ハードウェア** |
|
||||
|
||||
> 注意：ZeroClawの結果はリリースビルドで `/usr/bin/time -l` を使用して測定されています。OpenClawにはNode.jsランタイム（通常約390MBの追加メモリオーバーヘッド）が必要で、NanoBotにはPythonランタイムが必要です。PicoClawとZeroClawは静的バイナリです。上記のRAM数値はランタイムメモリです。ビルド時のコンパイル要件はより高くなります。
|
||||
> 注記: ZeroClaw の結果は release ビルドを `/usr/bin/time -l` で計測したものです。OpenClaw は Node.js ランタイムが必要で、ランタイム由来だけで通常は約390MBの追加メモリを要します。NanoBot は Python ランタイムが必要です。PicoClaw と ZeroClaw は静的バイナリです。
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
<img src="zero-claw.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### 再現可能なローカル測定
|
||||
### ローカルで再現可能な測定
|
||||
|
||||
ベンチマーク値はコードやツールチェーン更新で変わるため、必ず自身の環境で再測定してください。
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
@ -254,502 +102,199 @@ ls -lh target/release/zeroclaw
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## これまでに構築したすべて
|
||||
README のサンプル値（macOS arm64, 2026-02-18）:
|
||||
|
||||
### コアプラットフォーム
|
||||
- Release バイナリ: `8.8M`
|
||||
- `zeroclaw --help`: 約 `0.02s`、ピークメモリ 約 `3.9MB`
|
||||
- `zeroclaw status`: 約 `0.01s`、ピークメモリ 約 `4.1MB`
|
||||
|
||||
- Gateway HTTP/WS/SSEコントロールプレーン：セッション、プレゼンス、設定、cron、webhook、ウェブダッシュボード、ペアリング。
|
||||
- CLIサーフェス：`gateway`、`agent`、`onboard`、`doctor`、`status`、`service`、`migrate`、`auth`、`cron`、`channel`、`skills`。
|
||||
- エージェントオーケストレーションループ：ツールディスパッチ、プロンプト構築、メッセージ分類、メモリロード。
|
||||
- セッションモデル：セキュリティポリシー実行、自律レベル、承認ゲーティング。
|
||||
- レジリエントプロバイダーラッパー：20以上のLLMバックエンドにわたるフェイルオーバー、リトライ、モデルルーティング。
|
||||
|
||||
### チャンネル
|
||||
|
||||
チャンネル：WhatsApp（ネイティブ）、Telegram、Slack、Discord、Signal、iMessage、Matrix、IRC、Email、Bluesky、DingTalk、Lark、Mattermost、Nextcloud Talk、Nostr、QQ、Reddit、LinkedIn、Twitter、MQTT、WeChat Work、WATI、Mochat、Linq、Notion、WebSocket、ClawdTalk。
|
||||
|
||||
フィーチャーゲート：Matrix（`channel-matrix`）、Lark（`channel-lark`）、Nostr（`channel-nostr`）。
|
||||
|
||||
### ウェブダッシュボード
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 ウェブダッシュボード、Gatewayから直接提供：
|
||||
|
||||
- **ダッシュボード** — システム概要、ヘルスステータス、アップタイム、コストトラッキング
|
||||
- **エージェントチャット** — エージェントとのインタラクティブチャット
|
||||
- **メモリ** — メモリエントリの閲覧と管理
|
||||
- **設定** — 設定の表示と編集
|
||||
- **Cron** — スケジュールタスクの管理
|
||||
- **ツール** — 利用可能なツールの閲覧
|
||||
- **ログ** — エージェントアクティビティログの表示
|
||||
- **コスト** — トークン使用量とコストトラッキング
|
||||
- **Doctor** — システムヘルス診断
|
||||
- **インテグレーション** — インテグレーションステータスとセットアップ
|
||||
- **ペアリング** — デバイスペアリング管理
|
||||
|
||||
### ファームウェアターゲット
|
||||
|
||||
| ターゲット | プラットフォーム | 用途 |
|
||||
|------------|------------------|------|
|
||||
| ESP32 | Espressif ESP32 | ワイヤレス周辺機器エージェント |
|
||||
| ESP32-UI | ESP32 + Display | ビジュアルインターフェース付きエージェント |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | 産業用周辺機器 |
|
||||
| Arduino | Arduino | 基本センサー/アクチュエーターブリッジ |
|
||||
| Uno Q Bridge | Arduino Uno | エージェントへのシリアルブリッジ |
|
||||
|
||||
### ツール + 自動化
|
||||
|
||||
- **コア：** shell、ファイル読み書き/編集、git操作、glob検索、コンテンツ検索
|
||||
- **ウェブ：** ブラウザ制御、ウェブフェッチ、ウェブ検索、スクリーンショット、画像情報、PDF読み取り
|
||||
- **インテグレーション：** Jira、Notion、Google Workspace、Microsoft 365、LinkedIn、Composio、Pushover
|
||||
- **MCP：** Model Context Protocolツールラッパー + 遅延ツールセット
|
||||
- **スケジューリング：** cron追加/削除/更新/実行、スケジュールツール
|
||||
- **メモリ：** 想起、保存、忘却、知識、プロジェクトインテル
|
||||
- **高度：** 委譲（エージェント間）、スウォーム、モデル切り替え/ルーティング、セキュリティオプス、クラウドオプス
|
||||
- **ハードウェア：** ボード情報、メモリマップ、メモリ読み取り（フィーチャーゲート）
|
||||
|
||||
### ランタイム + 安全性
|
||||
|
||||
- **自律レベル：** ReadOnly、Supervised（デフォルト）、Full。
|
||||
- **サンドボックス：** ワークスペース分離、パストラバーサルブロック、コマンド許可リスト、禁止パス、Landlock（Linux）、Bubblewrap。
|
||||
- **レート制限：** 時間あたり最大アクション数、日あたり最大コスト（設定可能）。
|
||||
- **承認ゲーティング：** 中/高リスク操作のインタラクティブ承認。
|
||||
- **緊急停止：** 緊急シャットダウン機能。
|
||||
- **129以上のセキュリティテスト** が自動化CIに含まれています。
|
||||
|
||||
### 運用 + パッケージング
|
||||
|
||||
- ウェブダッシュボードはGatewayから直接提供。
|
||||
- トンネルサポート：Cloudflare、Tailscale、ngrok、OpenVPN、カスタムコマンド。
|
||||
- Dockerランタイムアダプターによるコンテナ化実行。
|
||||
- CI/CD：beta（プッシュ時自動）→ stable（手動ディスパッチ）→ Docker、crates.io、Scoop、AUR、Homebrew、tweet。
|
||||
- プリビルドバイナリ：Linux（x86_64、aarch64、armv7）、macOS（x86_64、aarch64）、Windows（x86_64）。
|
||||
|
||||
|
||||
## 設定
|
||||
|
||||
最小 `~/.zeroclaw/config.toml`：
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
完全な設定リファレンス：[docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)。
|
||||
|
||||
### チャンネル設定
|
||||
|
||||
**Telegram：**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord：**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack：**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp：**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix：**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal：**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### トンネル設定
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
詳細：[チャンネルリファレンス](docs/reference/api/channels-reference.md) · [設定リファレンス](docs/reference/api/config-reference.md)
|
||||
|
||||
### ランタイムサポート（現在）
|
||||
|
||||
- **`native`**（デフォルト）— 直接プロセス実行、最速パス、信頼できる環境に最適。
|
||||
- **`docker`** — 完全なコンテナ分離、強制セキュリティポリシー、Docker必要。
|
||||
|
||||
厳格なサンドボックスまたはネットワーク分離には `runtime.kind = "docker"` を設定してください。
|
||||
|
||||
## サブスクリプション認証（OpenAI Codex / Claude Code / Gemini）
|
||||
|
||||
ZeroClawはサブスクリプションネイティブ認証プロファイル（マルチアカウント、保存時暗号化）をサポートしています。
|
||||
|
||||
- ストアファイル：`~/.zeroclaw/auth-profiles.json`
|
||||
- 暗号化キー：`~/.zeroclaw/.secret_key`
|
||||
- プロファイルIDフォーマット：`<provider>:<profile_name>`（例：`openai-codex:work`）
|
||||
## ワンクリック導入
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth（ChatGPTサブスクリプション）
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./bootstrap.sh
|
||||
```
|
||||
|
||||
環境ごと初期化する場合: `./bootstrap.sh --install-system-deps --install-rust`（システムパッケージで `sudo` が必要な場合があります）。
|
||||
|
||||
詳細は [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md) を参照してください。
|
||||
|
||||
## クイックスタート
|
||||
|
||||
### Homebrew（macOS/Linuxbrew）
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard --api-key sk-... --provider openrouter
|
||||
zeroclaw onboard --interactive
|
||||
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# default: 127.0.0.1:42617
|
||||
zeroclaw gateway
|
||||
|
||||
zeroclaw daemon
|
||||
```
|
||||
|
||||
## Subscription Auth（OpenAI Codex / Claude Code）
|
||||
|
||||
ZeroClaw はサブスクリプションベースのネイティブ認証プロファイルをサポートしています（マルチアカウント対応、保存時暗号化）。
|
||||
|
||||
- 保存先: `~/.zeroclaw/auth-profiles.json`
|
||||
- 暗号化キー: `~/.zeroclaw/.secret_key`
|
||||
- Profile ID 形式: `<provider>:<profile_name>`（例: `openai-codex:work`）
|
||||
|
||||
OpenAI Codex OAuth（ChatGPT サブスクリプション）:
|
||||
|
||||
```bash
|
||||
# サーバー/ヘッドレス環境向け推奨
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
# ブラウザ/コールバックフロー（ペーストフォールバック付き）
|
||||
zeroclaw auth login --provider openai-codex --profile default
|
||||
zeroclaw auth paste-redirect --provider openai-codex --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# チェック / リフレッシュ / プロファイル切り替え
|
||||
# 確認 / リフレッシュ / プロファイル切替
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
```
|
||||
|
||||
# サブスクリプション認証でエージェントを実行
|
||||
Claude Code / Anthropic setup-token:
|
||||
|
||||
```bash
|
||||
# サブスクリプション/setup token の貼り付け（Authorization header モード）
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# エイリアスコマンド
|
||||
zeroclaw auth setup-token --provider anthropic --profile default
|
||||
```
|
||||
|
||||
Subscription auth で agent を実行:
|
||||
|
||||
```bash
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider openai-codex --auth-profile openai-codex:work -m "hello"
|
||||
|
||||
# Anthropic は API key と auth token の両方の環境変数をサポート:
|
||||
# ANTHROPIC_AUTH_TOKEN, ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## エージェントワークスペース + スキル
|
||||
## アーキテクチャ
|
||||
|
||||
ワークスペースルート：`~/.zeroclaw/workspace/`（設定で変更可能）。
|
||||
|
||||
注入されるプロンプトファイル：
|
||||
- `IDENTITY.md` — エージェントの人格と役割
|
||||
- `USER.md` — ユーザーコンテキストと好み
|
||||
- `MEMORY.md` — 長期的な事実と教訓
|
||||
- `AGENTS.md` — セッション規約と初期化ルール
|
||||
- `SOUL.md` — コアアイデンティティと運用原則
|
||||
|
||||
スキル：`~/.zeroclaw/workspace/skills/<skill>/SKILL.md` または `SKILL.toml`。
|
||||
|
||||
```bash
|
||||
# インストール済みスキルの一覧
|
||||
zeroclaw skills list
|
||||
|
||||
# gitからインストール
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# インストール前のセキュリティ監査
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# スキルの削除
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLIコマンド
|
||||
|
||||
```bash
|
||||
# ワークスペース管理
|
||||
zeroclaw onboard # ガイド付きセットアップウィザード
|
||||
zeroclaw status # デーモン/エージェントのステータス表示
|
||||
zeroclaw doctor # システム診断を実行
|
||||
|
||||
# ゲートウェイ + デーモン
|
||||
zeroclaw gateway # ゲートウェイサーバーを起動（127.0.0.1:42617）
|
||||
zeroclaw daemon # フル自律ランタイムを起動
|
||||
|
||||
# エージェント
|
||||
zeroclaw agent # インタラクティブチャットモード
|
||||
zeroclaw agent -m "message" # 単一メッセージモード
|
||||
|
||||
# サービス管理
|
||||
zeroclaw service install # OSサービスとしてインストール（launchd/systemd）
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# チャンネル
|
||||
zeroclaw channel list # 設定済みチャンネルの一覧
|
||||
zeroclaw channel doctor # チャンネルヘルスの確認
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + スケジューリング
|
||||
zeroclaw cron list # スケジュールタスクの一覧
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# メモリ
|
||||
zeroclaw memory list # メモリエントリの一覧
|
||||
zeroclaw memory get <key> # メモリの取得
|
||||
zeroclaw memory stats # メモリ統計
|
||||
|
||||
# 認証プロファイル
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# ハードウェア周辺機器
|
||||
zeroclaw hardware discover # 接続デバイスのスキャン
|
||||
zeroclaw peripheral list # 接続周辺機器の一覧
|
||||
zeroclaw peripheral flash # デバイスへのファームウェア書き込み
|
||||
|
||||
# 移行
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# シェル補完
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
完全なコマンドリファレンス：[docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## 前提条件
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### 必須
|
||||
|
||||
1. **Visual Studio Build Tools**（MSVCリンカーとWindows SDKを提供）：
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
インストール時（またはVisual Studioインストーラーで）、**"Desktop development with C++"** ワークロードを選択してください。
|
||||
|
||||
2. **Rustツールチェーン：**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
インストール後、新しいターミナルを開いて `rustup default stable` を実行し、stableツールチェーンがアクティブであることを確認してください。
|
||||
|
||||
3. 両方が動作していることを**確認**：
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### オプション
|
||||
|
||||
- **Docker Desktop** — [Dockerサンドボックスランタイム](#ランタイムサポート現在)（`runtime.kind = "docker"`）を使用する場合のみ必要。`winget install Docker.DockerDesktop` でインストール。
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### 必須
|
||||
|
||||
1. **ビルドツール：**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Xcodeコマンドラインツールをインストール：`xcode-select --install`
|
||||
|
||||
2. **Rustツールチェーン：**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
詳細は [rustup.rs](https://rustup.rs) を参照。
|
||||
|
||||
3. 両方が動作していることを**確認**：
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### ワンラインインストーラー
|
||||
|
||||
または、上記のステップをスキップして、単一コマンドですべてをインストール（システム依存、Rust、ZeroClaw）：
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### コンパイルリソース要件
|
||||
|
||||
ソースからのビルドは、結果のバイナリを実行するよりも多くのリソースが必要です：
|
||||
|
||||
| リソース | 最小 | 推奨 |
|
||||
| -------- | ---- | ---- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **空きディスク** | 6 GB | 10 GB+ |
|
||||
|
||||
ホストが最小要件を下回る場合、プリビルドバイナリを使用してください：
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
ソースフォールバックなしのバイナリのみインストール：
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### オプション
|
||||
|
||||
- **Docker** — [Dockerサンドボックスランタイム](#ランタイムサポート現在)（`runtime.kind = "docker"`）を使用する場合のみ必要。パッケージマネージャーまたは [docker.com](https://docs.docker.com/engine/install/) からインストール。
|
||||
|
||||
> **注意：** デフォルトの `cargo build --release` は `codegen-units=1` を使用してコンパイルのピーク圧力を低減します。強力なマシンでのビルド高速化には `cargo build --profile release-fast` を使用してください。
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### プリビルドバイナリ
|
||||
|
||||
リリースアセットは以下で公開されています：
|
||||
|
||||
- Linux: `x86_64`、`aarch64`、`armv7`
|
||||
- macOS: `x86_64`、`aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
最新アセットはこちらからダウンロード：
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## ドキュメント
|
||||
|
||||
オンボーディングフローを終えて、より深いリファレンスが必要な場合に使用してください。
|
||||
|
||||
- ナビゲーションと「どこに何があるか」は[ドキュメントインデックス](docs/README.md)から。
|
||||
- [アーキテクチャ概要](docs/architecture.md)で完全なシステムモデルを確認。
|
||||
- すべてのキーと例は[設定リファレンス](docs/reference/api/config-reference.md)で。
|
||||
- [運用ランブック](docs/ops/operations-runbook.md)に従ってGatewayを実行。
|
||||
- [ZeroClaw Onboard](#クイックスタートtldr)でガイド付きセットアップ。
|
||||
- [トラブルシューティングガイド](docs/ops/troubleshooting.md)で一般的な障害をデバッグ。
|
||||
- 何かを公開する前に[セキュリティガイダンス](docs/security/README.md)を確認。
|
||||
|
||||
### リファレンスドキュメント
|
||||
|
||||
- ドキュメントハブ：[docs/README.md](docs/README.md)
|
||||
- 統一ドキュメント目次：[docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- コマンドリファレンス：[docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- 設定リファレンス：[docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- プロバイダーリファレンス：[docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- チャンネルリファレンス：[docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- 運用ランブック：[docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- トラブルシューティング：[docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### コラボレーションドキュメント
|
||||
|
||||
- 貢献ガイド：[CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PRワークフローポリシー：[docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CIワークフローガイド：[docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- レビューアープレイブック：[docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- セキュリティ開示ポリシー：[SECURITY.md](SECURITY.md)
|
||||
- ドキュメントテンプレート：[docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### デプロイ + 運用
|
||||
|
||||
- ネットワークデプロイガイド：[docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- プロキシエージェントプレイブック：[docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- ハードウェアガイド：[docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClawはsmooth crab 🦀のために構築されました。高速で効率的なAIアシスタント。Argenis De La Rosaとコミュニティによって構築されました。
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ZeroClawを支援
|
||||
|
||||
ZeroClawがあなたの仕事に役立ち、継続的な開発を支援したい場合は、こちらから寄付できます：
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 特別な感謝
|
||||
|
||||
このオープンソースの取り組みにインスピレーションと活力を与えてくれたコミュニティと機関に心からの感謝を：
|
||||
|
||||
- **ハーバード大学** — 知的好奇心を育み、可能性の限界を押し広げてくれたことに感謝。
|
||||
- **MIT** — オープンな知識、オープンソース、そしてテクノロジーは誰もがアクセスできるべきという信念を擁護してくれたことに感謝。
|
||||
- **Sundai Club** — コミュニティ、エネルギー、そして意味のあるものを構築するための弛まぬ努力に感謝。
|
||||
- **世界とその先** 🌍✨ — オープンソースを良い力にしているすべての貢献者、夢想家、構築者へ。これはあなたのためのものです。
|
||||
|
||||
最高のアイデアはあらゆるところから生まれるため、私たちはオープンに構築しています。これを読んでいるなら、あなたはその一部です。ようこそ。🦀❤️
|
||||
|
||||
## 貢献
|
||||
|
||||
ZeroClaw初心者ですか？[`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) ラベルの付いた課題を探してください — 始め方は[貢献ガイド](CONTRIBUTING.md#first-time-contributors)を参照。AI/vibe-coded PRも歓迎します！🤖
|
||||
|
||||
[CONTRIBUTING.md](CONTRIBUTING.md) と [CLA.md](docs/contributing/cla.md) を参照。traitを実装してPRを提出してください：
|
||||
|
||||
- CIワークフローガイド：[docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- 新 `Provider` → `src/providers/`
|
||||
- 新 `Channel` → `src/channels/`
|
||||
- 新 `Observer` → `src/observability/`
|
||||
- 新 `Tool` → `src/tools/`
|
||||
- 新 `Memory` → `src/memory/`
|
||||
- 新 `Tunnel` → `src/tunnel/`
|
||||
- 新 `Peripheral` → `src/peripherals/`
|
||||
- 新 `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ 公式リポジトリと偽装警告
|
||||
|
||||
**これがZeroClawの唯一の公式リポジトリです：**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
「ZeroClaw」を名乗る、またはZeroClaw Labsとの提携を示唆する他のリポジトリ、組織、ドメイン、パッケージは**無許可であり、本プロジェクトとは無関係です**。既知の無許可フォークは [TRADEMARK.md](docs/maintainers/trademark.md) に記載されます。
|
||||
|
||||
偽装や商標の悪用を見つけた場合は、[issueを作成](https://github.com/zeroclaw-labs/zeroclaw/issues)してください。
|
||||
|
||||
---
|
||||
|
||||
## ライセンス
|
||||
|
||||
ZeroClawは最大限のオープン性と貢献者保護のためにデュアルライセンスです：
|
||||
|
||||
| ライセンス | 用途 |
|
||||
|------------|------|
|
||||
| [MIT](LICENSE-MIT) | オープンソース、研究、学術、個人使用 |
|
||||
| [Apache 2.0](LICENSE-APACHE) | 特許保護、機関、商用デプロイ |
|
||||
|
||||
どちらのライセンスでも選択できます。**貢献者は両方のライセンスの権利を自動的に付与します** — 完全な貢献者契約については [CLA.md](docs/contributing/cla.md) を参照してください。
|
||||
|
||||
### 商標
|
||||
|
||||
**ZeroClaw** の名称とロゴはZeroClaw Labsの商標です。このライセンスは、推薦や提携を暗示するための使用許可を付与しません。許可された使用と禁止された使用については [TRADEMARK.md](docs/maintainers/trademark.md) を参照してください。
|
||||
|
||||
### 貢献者の保護
|
||||
|
||||
- あなたは貢献の**著作権を保持**します
|
||||
- **特許付与**（Apache 2.0）により、他の貢献者からの特許請求から保護されます
|
||||
- あなたの貢献はコミット履歴と [NOTICE](NOTICE) に**永続的に帰属**されます
|
||||
- 貢献により商標権は移転されません
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — ゼロオーバーヘッド。ゼロ妥協。どこでもデプロイ。何でも交換。🦀
|
||||
|
||||
## 貢献者
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
このリストはGitHub貢献者グラフから生成され、自動的に更新されます。
|
||||
|
||||
## Star履歴
|
||||
すべてのサブシステムは **Trait** — 設定変更だけで実装を差し替え可能、コード変更不要。
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
<img src="docs/architecture.svg" alt="ZeroClaw アーキテクチャ" width="900" />
|
||||
</p>
|
||||
|
||||
| サブシステム | Trait | 内蔵実装 | 拡張方法 |
|
||||
|-------------|-------|----------|----------|
|
||||
| **AI モデル** | `Provider` | `zeroclaw providers` で確認（現在 28 個の組み込み + エイリアス、カスタムエンドポイント対応） | `custom:https://your-api.com`（OpenAI 互換）または `anthropic-custom:https://your-api.com` |
|
||||
| **チャネル** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Linq, Email, IRC, Lark, DingTalk, QQ, Webhook | 任意のメッセージ API |
|
||||
| **メモリ** | `Memory` | SQLite ハイブリッド検索, PostgreSQL バックエンド, Lucid ブリッジ, Markdown ファイル, 明示的 `none` バックエンド, スナップショット/復元, オプション応答キャッシュ | 任意の永続化バックエンド |
|
||||
| **ツール** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, ハードウェアツール | 任意の機能 |
|
||||
| **オブザーバビリティ** | `Observer` | Noop, Log, Multi | Prometheus, OTel |
|
||||
| **ランタイム** | `RuntimeAdapter` | Native, Docker（サンドボックス） | adapter 経由で追加可能；未対応の kind は即座にエラー |
|
||||
| **セキュリティ** | `SecurityPolicy` | Gateway ペアリング, サンドボックス, allowlist, レート制限, ファイルシステムスコープ, 暗号化シークレット | — |
|
||||
| **アイデンティティ** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | 任意の ID フォーマット |
|
||||
| **トンネル** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | 任意のトンネルバイナリ |
|
||||
| **ハートビート** | Engine | HEARTBEAT.md 定期タスク | — |
|
||||
| **スキル** | Loader | TOML マニフェスト + SKILL.md インストラクション | コミュニティスキルパック |
|
||||
| **インテグレーション** | Registry | 9 カテゴリ、70 件以上の連携 | プラグインシステム |
|
||||
|
||||
### ランタイムサポート（現状）
|
||||
|
||||
- ✅ 現在サポート: `runtime.kind = "native"` または `runtime.kind = "docker"`
|
||||
- 🚧 計画中（未実装）: WASM / エッジランタイム
|
||||
|
||||
未対応の `runtime.kind` が設定された場合、ZeroClaw は native へのサイレントフォールバックではなく、明確なエラーで終了します。
|
||||
|
||||
### メモリシステム（フルスタック検索エンジン）
|
||||
|
||||
すべて自社実装、外部依存ゼロ — Pinecone、Elasticsearch、LangChain 不要:
|
||||
|
||||
| レイヤー | 実装 |
|
||||
|---------|------|
|
||||
| **ベクトル DB** | Embeddings を SQLite に BLOB として保存、コサイン類似度検索 |
|
||||
| **キーワード検索** | FTS5 仮想テーブル、BM25 スコアリング |
|
||||
| **ハイブリッドマージ** | カスタム重み付きマージ関数（`vector.rs`） |
|
||||
| **Embeddings** | `EmbeddingProvider` trait — OpenAI、カスタム URL、または noop |
|
||||
| **チャンキング** | 行ベースの Markdown チャンカー（見出し構造保持） |
|
||||
| **キャッシュ** | SQLite `embedding_cache` テーブル、LRU エビクション |
|
||||
| **安全な再インデックス** | FTS5 再構築 + 欠落ベクトルの再埋め込みをアトミックに実行 |
|
||||
|
||||
Agent はツール経由でメモリの呼び出し・保存・管理を自動的に行います。
|
||||
|
||||
```toml
|
||||
[memory]
|
||||
backend = "sqlite" # "sqlite", "lucid", "postgres", "markdown", "none"
|
||||
auto_save = true
|
||||
embedding_provider = "none" # "none", "openai", "custom:https://..."
|
||||
vector_weight = 0.7
|
||||
keyword_weight = 0.3
|
||||
```
|
||||
|
||||
## セキュリティのデフォルト
|
||||
|
||||
- Gateway の既定バインド: `127.0.0.1:42617`
|
||||
- 既定でペアリング必須: `require_pairing = true`
|
||||
- 既定で公開バインド禁止: `allow_public_bind = false`
|
||||
- Channel allowlist:
|
||||
- `[]` は deny-by-default
|
||||
- `["*"]` は allow all（意図的に使う場合のみ）
|
||||
|
||||
## 設定例
|
||||
|
||||
```toml
|
||||
api_key = "sk-..."
|
||||
default_provider = "openrouter"
|
||||
default_model = "anthropic/claude-sonnet-4-6"
|
||||
default_temperature = 0.7
|
||||
|
||||
[memory]
|
||||
backend = "sqlite"
|
||||
auto_save = true
|
||||
embedding_provider = "none"
|
||||
|
||||
[gateway]
|
||||
host = "127.0.0.1"
|
||||
port = 42617
|
||||
require_pairing = true
|
||||
allow_public_bind = false
|
||||
```
|
||||
|
||||
## ドキュメント入口
|
||||
|
||||
- ドキュメントハブ（英語）: [`docs/README.md`](docs/README.md)
|
||||
- 統合 TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md)
|
||||
- ドキュメントハブ（日本語）: [`docs/README.ja.md`](docs/README.ja.md)
|
||||
- コマンドリファレンス: [`docs/commands-reference.md`](docs/commands-reference.md)
|
||||
- 設定リファレンス: [`docs/config-reference.md`](docs/config-reference.md)
|
||||
- Provider リファレンス: [`docs/providers-reference.md`](docs/providers-reference.md)
|
||||
- Channel リファレンス: [`docs/channels-reference.md`](docs/channels-reference.md)
|
||||
- 運用ガイド（Runbook）: [`docs/operations-runbook.md`](docs/operations-runbook.md)
|
||||
- トラブルシューティング: [`docs/troubleshooting.md`](docs/troubleshooting.md)
|
||||
- ドキュメント一覧 / 分類: [`docs/docs-inventory.md`](docs/docs-inventory.md)
|
||||
- プロジェクト triage スナップショット: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
|
||||
|
||||
## コントリビュート / ライセンス
|
||||
|
||||
- Contributing: [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
||||
- PR Workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md)
|
||||
- Reviewer Playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
|
||||
- License: MIT or Apache 2.0（[`LICENSE-MIT`](LICENSE-MIT), [`LICENSE-APACHE`](LICENSE-APACHE), [`NOTICE`](NOTICE)）
|
||||
|
||||
---
|
||||
|
||||
詳細仕様（全コマンド、アーキテクチャ、API 仕様、開発フロー）は英語版の [`README.md`](README.md) を参照してください。
|
||||
|
||||
755
README.ko.md
755
README.ko.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — 개인 AI 어시스턴트</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>오버헤드 없음. 타협 없음. 100% Rust. 100% 독립적.</strong><br>
|
||||
⚡️ <strong>$10 하드웨어에서 <5MB RAM으로 실행: OpenClaw보다 99% 적은 메모리, Mac mini보다 98% 저렴!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Harvard, MIT, 그리고 Sundai.Club 커뮤니티의 학생들과 멤버들이 만들었습니다.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>언어:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw는 자신의 기기에서 실행하는 개인 AI 어시스턴트입니다. 이미 사용하고 있는 채널(WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work 등)에서 응답합니다. 실시간 제어를 위한 웹 대시보드가 있으며 하드웨어 주변기기(ESP32, STM32, Arduino, Raspberry Pi)에 연결할 수 있습니다. Gateway는 단순한 제어 평면이며, 제품은 어시스턴트 자체입니다.
|
||||
|
||||
로컬에서 빠르고 항상 켜져 있는 개인 단일 사용자 어시스턴트를 원한다면 바로 이것입니다.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">웹사이트</a> ·
|
||||
<a href="docs/README.md">문서</a> ·
|
||||
<a href="docs/architecture.md">아키텍처</a> ·
|
||||
<a href="#빠른-시작-tldr">시작하기</a> ·
|
||||
<a href="#openclaw에서-마이그레이션">OpenClaw에서 마이그레이션</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">문제 해결</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **권장 설정:** 터미널에서 `zeroclaw onboard`를 실행하세요. ZeroClaw Onboard가 gateway, workspace, 채널, 제공자 설정을 단계별로 안내합니다. macOS, Linux, Windows(WSL2)에서 작동하는 권장 설정 경로입니다. 새로 설치하시나요? 여기서 시작하세요: [시작하기](#빠른-시작-tldr)
|
||||
|
||||
### Subscription Auth (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT 구독)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API 키 또는 인증 토큰)
|
||||
|
||||
모델 참고: 많은 제공자/모델이 지원되지만, 최상의 경험을 위해 사용 가능한 최신 세대의 가장 강력한 모델을 사용하세요. [온보딩](#빠른-시작-tldr)을 참조하세요.
|
||||
|
||||
모델 구성 + CLI: [Providers reference](docs/reference/api/providers-reference.md)
|
||||
인증 프로필 교체(OAuth vs API 키) + 장애 조치: [Model failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## 설치 (권장)
|
||||
|
||||
런타임: Rust stable 툴체인. 단일 바이너리, 런타임 의존성 없음.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### 원클릭 부트스트랩
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard`는 설치 후 자동으로 실행되어 workspace와 제공자를 구성합니다.
|
||||
|
||||
## 빠른 시작 (TL;DR)
|
||||
|
||||
전체 초보자 가이드(인증, 페어링, 채널): [시작하기](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# 설치 + 온보드
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Gateway 시작 (webhook 서버 + 웹 대시보드)
|
||||
zeroclaw gateway # 기본값: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # 랜덤 포트 (보안 강화)
|
||||
|
||||
# 어시스턴트와 대화
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# 대화형 모드
|
||||
zeroclaw agent
|
||||
|
||||
# 완전 자율 런타임 시작 (gateway + 채널 + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# 상태 확인
|
||||
zeroclaw status
|
||||
|
||||
# 진단 실행
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
업그레이드 하셨나요? 업데이트 후 `zeroclaw doctor`를 실행하세요.
|
||||
|
||||
### 소스에서 빌드 (개발용)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **개발 폴백 (글로벌 설치 없이):** 명령 앞에 `cargo run --release --`를 붙이세요 (예: `cargo run --release -- status`).
|
||||
|
||||
## OpenClaw에서 마이그레이션
|
||||
|
||||
ZeroClaw는 OpenClaw workspace, 메모리, 구성을 가져올 수 있습니다:
|
||||
|
||||
```bash
|
||||
# 마이그레이션 대상 미리보기 (안전, 읽기 전용)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# 마이그레이션 실행
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
이것은 메모리 항목, workspace 파일, 구성을 `~/.openclaw/`에서 `~/.zeroclaw/`로 마이그레이션합니다. 구성은 JSON에서 TOML로 자동 변환됩니다.
|
||||
|
||||
## 보안 기본값 (DM 접근)
|
||||
|
||||
ZeroClaw는 실제 메시징 서비스에 연결됩니다. 수신 DM을 신뢰할 수 없는 입력으로 취급하세요.
|
||||
|
||||
전체 보안 가이드: [SECURITY.md](SECURITY.md)
|
||||
|
||||
모든 채널의 기본 동작:
|
||||
|
||||
- **DM 페어링** (기본값): 알 수 없는 발신자는 짧은 페어링 코드를 받으며 봇은 메시지를 처리하지 않습니다.
|
||||
- 승인: `zeroclaw pairing approve <channel> <code>` (발신자가 로컬 허용 목록에 추가됩니다).
|
||||
- 공개 수신 DM은 `config.toml`에서 명시적 옵트인이 필요합니다.
|
||||
- `zeroclaw doctor`를 실행하여 위험하거나 잘못 구성된 DM 정책을 확인하세요.
|
||||
|
||||
**자율성 수준:**
|
||||
|
||||
| 수준 | 동작 |
|
||||
|-------|----------|
|
||||
| `ReadOnly` | 에이전트가 관찰만 할 수 있고 행동하지 않음 |
|
||||
| `Supervised` (기본값) | 에이전트가 중/고위험 작업에 대해 승인을 받고 행동 |
|
||||
| `Full` | 에이전트가 정책 범위 내에서 자율적으로 행동 |
|
||||
|
||||
**샌드박싱 계층:** workspace 격리, 경로 탐색 차단, 명령 허용 목록, 금지 경로 (`/etc`, `/root`, `~/.ssh`), 속도 제한 (시간당 최대 작업 수, 일일 비용 상한).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 공지사항
|
||||
|
||||
이 표를 사용하여 중요한 공지사항(호환성 변경, 보안 권고, 유지보수 기간, 릴리스 차단)을 확인하세요.
|
||||
|
||||
| 날짜 (UTC) | 수준 | 공지 | 조치 |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _치명적_ | 우리는 `openagen/zeroclaw`, `zeroclaw.org` 또는 `zeroclaw.net`과 **관련이 없습니다**. `zeroclaw.org`과 `zeroclaw.net` 도메인은 현재 `openagen/zeroclaw` 포크를 가리키고 있으며, 해당 도메인/저장소는 우리의 공식 웹사이트/프로젝트를 사칭하고 있습니다. | 해당 소스의 정보, 바이너리, 모금, 공지를 신뢰하지 마세요. [이 저장소](https://github.com/zeroclaw-labs/zeroclaw)와 검증된 소셜 계정만 사용하세요. |
|
||||
| 2026-02-21 | _중요_ | 공식 웹사이트가 이제 온라인입니다: [zeroclawlabs.ai](https://zeroclawlabs.ai). 기다려주셔서 감사합니다. 사칭 시도가 여전히 감지되고 있으므로, 공식 채널을 통해 게시되지 않은 ZeroClaw 이름의 투자나 모금 활동에 참여하지 **마세요**. | [이 저장소](https://github.com/zeroclaw-labs/zeroclaw)를 유일한 진실의 원천으로 사용하세요. [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (그룹)](https://www.facebook.com/groups/zeroclawlabs), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/)을 팔로우하여 공식 업데이트를 받으세요. |
|
||||
| 2026-02-19 | _중요_ | Anthropic이 2026-02-19에 인증 및 자격증명 사용 약관을 업데이트했습니다. Claude Code OAuth 토큰(Free, Pro, Max)은 Claude Code와 Claude.ai 전용입니다. 다른 제품, 도구 또는 서비스(Agent SDK 포함)에서 Claude Free/Pro/Max OAuth 토큰을 사용하는 것은 허용되지 않으며 소비자 이용약관을 위반할 수 있습니다. | 잠재적 손실을 방지하기 위해 일시적으로 Claude Code OAuth 통합을 피하세요. 원본 조항: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## 주요 특징
|
||||
|
||||
- **기본 경량 런타임** — 일반적인 CLI 및 상태 워크플로우가 릴리스 빌드에서 몇 메가바이트의 메모리 범위 내에서 실행됩니다.
|
||||
- **비용 효율적인 배포** — $10 보드와 소규모 클라우드 인스턴스를 위해 설계되었으며, 무거운 런타임 의존성이 없습니다.
|
||||
- **빠른 콜드 스타트** — 단일 바이너리 Rust 런타임으로 명령 및 데몬 시작이 거의 즉각적입니다.
|
||||
- **이식 가능한 아키텍처** — 교체 가능한 제공자/채널/도구로 ARM, x86, RISC-V에서 하나의 바이너리.
|
||||
- **로컬 우선 Gateway** — 세션, 채널, 도구, cron, SOP, 이벤트를 위한 단일 제어 평면.
|
||||
- **멀티 채널 수신함** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket 등.
|
||||
- **멀티 에이전트 오케스트레이션 (Hands)** — 스케줄에 따라 실행되고 시간이 지남에 따라 더 똑똑해지는 자율 에이전트 스웜.
|
||||
- **표준 운영 절차 (SOPs)** — MQTT, webhook, cron, 주변기기 트리거를 통한 이벤트 기반 워크플로우 자동화.
|
||||
- **웹 대시보드** — 실시간 채팅, 메모리 브라우저, 구성 편집기, cron 관리자, 도구 검사기를 갖춘 React 19 + Vite 웹 UI.
|
||||
- **하드웨어 주변기기** — `Peripheral` 트레이트를 통한 ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO.
|
||||
- **일급 도구** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace 등 70개 이상.
|
||||
- **라이프사이클 훅** — 모든 단계에서 LLM 호출, 도구 실행, 메시지를 가로채고 수정.
|
||||
- **스킬 플랫폼** — 번들, 커뮤니티, workspace 스킬과 보안 감사.
|
||||
- **터널 지원** — 원격 접속을 위한 Cloudflare, Tailscale, ngrok, OpenVPN, 사용자 정의 터널.
|
||||
|
||||
### 팀이 ZeroClaw를 선택하는 이유
|
||||
|
||||
- **기본 경량:** 작은 Rust 바이너리, 빠른 시작, 낮은 메모리 사용.
|
||||
- **기본 보안:** 페어링, 엄격한 샌드박싱, 명시적 허용 목록, workspace 범위 지정.
|
||||
- **완전히 교체 가능:** 핵심 시스템이 트레이트(제공자, 채널, 도구, 메모리, 터널).
|
||||
- **벤더 락인 없음:** OpenAI 호환 제공자 지원 + 플러그 가능한 사용자 정의 엔드포인트.
|
||||
|
||||
## 벤치마크 스냅샷 (ZeroClaw vs OpenClaw, 재현 가능)
|
||||
|
||||
로컬 머신 빠른 벤치마크 (macOS arm64, 2026년 2월) 0.8GHz 엣지 하드웨어로 정규화.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **언어** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **시작 (0.8GHz 코어)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **바이너리 크기** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **비용** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **모든 하드웨어 $10** |
|
||||
|
||||
> 참고: ZeroClaw 결과는 `/usr/bin/time -l`을 사용한 릴리스 빌드에서 측정되었습니다. OpenClaw는 Node.js 런타임이 필요하며(일반적으로 ~390MB 추가 메모리 오버헤드), NanoBot은 Python 런타임이 필요합니다. PicoClaw와 ZeroClaw는 정적 바이너리입니다. 위 RAM 수치는 런타임 메모리이며, 빌드 시 컴파일 요구사항은 더 높습니다.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### 재현 가능한 로컬 측정
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## 지금까지 구축한 모든 것
|
||||
|
||||
### 핵심 플랫폼
|
||||
|
||||
- 세션, 프레즌스, 구성, cron, webhook, 웹 대시보드, 페어링을 갖춘 Gateway HTTP/WS/SSE 제어 평면.
|
||||
- CLI 표면: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- 도구 디스패치, 프롬프트 구성, 메시지 분류, 메모리 로딩을 갖춘 에이전트 오케스트레이션 루프.
|
||||
- 보안 정책 적용, 자율성 수준, 승인 게이팅을 갖춘 세션 모델.
|
||||
- 20개 이상의 LLM 백엔드에 걸쳐 장애 조치, 재시도, 모델 라우팅을 갖춘 탄력적 제공자 래퍼.
|
||||
|
||||
### 채널
|
||||
|
||||
채널: WhatsApp (네이티브), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
기능 게이트: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### 웹 대시보드
|
||||
|
||||
Gateway에서 직접 제공하는 React 19 + Vite 6 + Tailwind CSS 4 웹 대시보드:
|
||||
|
||||
- **대시보드** — 시스템 개요, 상태, 가동 시간, 비용 추적
|
||||
- **에이전트 채팅** — 에이전트와의 대화형 채팅
|
||||
- **메모리** — 메모리 항목 탐색 및 관리
|
||||
- **구성** — 구성 보기 및 편집
|
||||
- **Cron** — 예약된 작업 관리
|
||||
- **도구** — 사용 가능한 도구 탐색
|
||||
- **로그** — 에이전트 활동 로그 보기
|
||||
- **비용** — 토큰 사용량 및 비용 추적
|
||||
- **Doctor** — 시스템 상태 진단
|
||||
- **통합** — 통합 상태 및 설정
|
||||
- **페어링** — 기기 페어링 관리
|
||||
|
||||
### 펌웨어 대상
|
||||
|
||||
| 대상 | 플랫폼 | 용도 |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | 무선 주변기기 에이전트 |
|
||||
| ESP32-UI | ESP32 + Display | 시각적 인터페이스를 갖춘 에이전트 |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | 산업용 주변기기 |
|
||||
| Arduino | Arduino | 기본 센서/액추에이터 브릿지 |
|
||||
| Uno Q Bridge | Arduino Uno | 에이전트와의 시리얼 브릿지 |
|
||||
|
||||
### 도구 + 자동화
|
||||
|
||||
- **코어:** shell, file read/write/edit, git operations, glob search, content search
|
||||
- **웹:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **통합:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **스케줄링:** cron add/remove/update/run, schedule tool
|
||||
- **메모리:** recall, store, forget, knowledge, project intel
|
||||
- **고급:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **하드웨어:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### 런타임 + 안전
|
||||
|
||||
- **자율성 수준:** ReadOnly, Supervised (기본값), Full.
|
||||
- **샌드박싱:** workspace 격리, 경로 탐색 차단, 명령 허용 목록, 금지 경로, Landlock (Linux), Bubblewrap.
|
||||
- **속도 제한:** 시간당 최대 작업 수, 일일 최대 비용 (구성 가능).
|
||||
- **승인 게이팅:** 중/고위험 작업에 대한 대화형 승인.
|
||||
- **긴급 정지:** 긴급 종료 기능.
|
||||
- **129개 이상의 보안 테스트** 자동화된 CI에서.
|
||||
|
||||
### 운영 + 패키징
|
||||
|
||||
- Gateway에서 직접 제공하는 웹 대시보드.
|
||||
- 터널 지원: Cloudflare, Tailscale, ngrok, OpenVPN, custom command.
|
||||
- 컨테이너화된 실행을 위한 Docker 런타임 어댑터.
|
||||
- CI/CD: beta (push 시 자동) → stable (수동 디스패치) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64)용 사전 빌드 바이너리.
|
||||
|
||||
|
||||
## 구성
|
||||
|
||||
최소 `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
전체 구성 참조: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### 채널 구성
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### 터널 구성
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # 또는 "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
상세 정보: [Channel reference](docs/reference/api/channels-reference.md) · [Config reference](docs/reference/api/config-reference.md)
|
||||
|
||||
### 현재 런타임 지원
|
||||
|
||||
- **`native`** (기본값) — 직접 프로세스 실행, 가장 빠른 경로, 신뢰할 수 있는 환경에 적합.
|
||||
- **`docker`** — 완전한 컨테이너 격리, 강화된 보안 정책, Docker 필요.
|
||||
|
||||
엄격한 샌드박싱이나 네트워크 격리를 위해 `runtime.kind = "docker"`를 설정하세요.
|
||||
|
||||
## Subscription Auth (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw는 구독 기반 인증 프로필(다중 계정, 저장 시 암호화)을 지원합니다.
|
||||
|
||||
- 저장 파일: `~/.zeroclaw/auth-profiles.json`
|
||||
- 암호화 키: `~/.zeroclaw/.secret_key`
|
||||
- 프로필 id 형식: `<provider>:<profile_name>` (예: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT 구독)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# 확인 / 갱신 / 프로필 전환
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# 구독 인증으로 에이전트 실행
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## 에이전트 workspace + 스킬
|
||||
|
||||
Workspace 루트: `~/.zeroclaw/workspace/` (구성을 통해 변경 가능).
|
||||
|
||||
주입되는 프롬프트 파일:
|
||||
- `IDENTITY.md` — 에이전트 성격과 역할
|
||||
- `USER.md` — 사용자 컨텍스트와 선호도
|
||||
- `MEMORY.md` — 장기 사실과 교훈
|
||||
- `AGENTS.md` — 세션 규칙과 초기화 규칙
|
||||
- `SOUL.md` — 핵심 정체성과 운영 원칙
|
||||
|
||||
스킬: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` 또는 `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# 설치된 스킬 목록
|
||||
zeroclaw skills list
|
||||
|
||||
# git에서 설치
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# 설치 전 보안 감사
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# 스킬 제거
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI 명령어
|
||||
|
||||
```bash
|
||||
# Workspace 관리
|
||||
zeroclaw onboard # 안내된 설정 마법사
|
||||
zeroclaw status # 데몬/에이전트 상태 표시
|
||||
zeroclaw doctor # 시스템 진단 실행
|
||||
|
||||
# Gateway + 데몬
|
||||
zeroclaw gateway # Gateway 서버 시작 (127.0.0.1:42617)
|
||||
zeroclaw daemon # 완전 자율 런타임 시작
|
||||
|
||||
# 에이전트
|
||||
zeroclaw agent # 대화형 채팅 모드
|
||||
zeroclaw agent -m "message" # 단일 메시지 모드
|
||||
|
||||
# 서비스 관리
|
||||
zeroclaw service install # OS 서비스로 설치 (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# 채널
|
||||
zeroclaw channel list # 구성된 채널 목록
|
||||
zeroclaw channel doctor # 채널 상태 확인
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + 스케줄링
|
||||
zeroclaw cron list # 예약된 작업 목록
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# 메모리
|
||||
zeroclaw memory list # 메모리 항목 목록
|
||||
zeroclaw memory get <key> # 메모리 조회
|
||||
zeroclaw memory stats # 메모리 통계
|
||||
|
||||
# 인증 프로필
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# 하드웨어 주변기기
|
||||
zeroclaw hardware discover # 연결된 기기 스캔
|
||||
zeroclaw peripheral list # 연결된 주변기기 목록
|
||||
zeroclaw peripheral flash # 기기에 펌웨어 플래시
|
||||
|
||||
# 마이그레이션
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# 셸 자동완성
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
전체 명령어 참조: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## 사전 요구사항
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### 필수
|
||||
|
||||
1. **Visual Studio Build Tools** (MSVC 링커와 Windows SDK 제공):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
설치 중(또는 Visual Studio Installer를 통해) **"C++를 사용한 데스크톱 개발"** 워크로드를 선택하세요.
|
||||
|
||||
2. **Rust 툴체인:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
설치 후 새 터미널을 열고 `rustup default stable`을 실행하여 stable 툴체인이 활성화되었는지 확인하세요.
|
||||
|
||||
3. **확인:** 둘 다 작동하는지 확인:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### 선택사항
|
||||
|
||||
- **Docker Desktop** — [Docker 샌드박스 런타임](#현재-런타임-지원)을 사용하는 경우에만 필요 (`runtime.kind = "docker"`). `winget install Docker.DockerDesktop`으로 설치.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### 필수
|
||||
|
||||
1. **빌드 필수 도구:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Xcode Command Line Tools 설치: `xcode-select --install`
|
||||
|
||||
2. **Rust 툴체인:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
자세한 내용은 [rustup.rs](https://rustup.rs)를 참조하세요.
|
||||
|
||||
3. **확인:** 둘 다 작동하는지 확인:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### 한 줄 설치
|
||||
|
||||
위 단계를 건너뛰고 모든 것(시스템 의존성, Rust, ZeroClaw)을 한 번에 설치:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### 컴파일 리소스 요구사항
|
||||
|
||||
소스에서 빌드하려면 결과 바이너리를 실행하는 것보다 더 많은 리소스가 필요합니다:
|
||||
|
||||
| 리소스 | 최소 | 권장 |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **여유 디스크** | 6 GB | 10 GB+ |
|
||||
|
||||
호스트가 최소 사양 미만인 경우 사전 빌드 바이너리를 사용하세요:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
소스 빌드 폴백 없이 바이너리만 설치:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### 선택사항
|
||||
|
||||
- **Docker** — [Docker 샌드박스 런타임](#현재-런타임-지원)을 사용하는 경우에만 필요 (`runtime.kind = "docker"`). 패키지 관리자 또는 [docker.com](https://docs.docker.com/engine/install/)을 통해 설치.
|
||||
|
||||
> **참고:** 기본 `cargo build --release`는 `codegen-units=1`을 사용하여 피크 컴파일 압력을 낮춥니다. 성능이 좋은 머신에서 더 빠른 빌드를 위해 `cargo build --profile release-fast`를 사용하세요.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### 사전 빌드 바이너리
|
||||
|
||||
릴리스 에셋은 다음 플랫폼에 게시됩니다:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
최신 에셋 다운로드:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## 문서
|
||||
|
||||
온보딩을 마친 후 더 깊은 참조가 필요할 때 사용하세요.
|
||||
|
||||
- [문서 인덱스](docs/README.md)에서 탐색과 "무엇이 어디에 있는지"를 확인하세요.
|
||||
- [아키텍처 개요](docs/architecture.md)에서 전체 시스템 모델을 확인하세요.
|
||||
- [구성 참조](docs/reference/api/config-reference.md)에서 모든 키와 예제를 확인하세요.
|
||||
- [운영 런북](docs/ops/operations-runbook.md)으로 Gateway를 운영하세요.
|
||||
- [ZeroClaw Onboard](#빠른-시작-tldr)를 따라 안내된 설정을 진행하세요.
|
||||
- [문제 해결 가이드](docs/ops/troubleshooting.md)로 일반적인 오류를 디버그하세요.
|
||||
- 노출하기 전에 [보안 가이드](docs/security/README.md)를 검토하세요.
|
||||
|
||||
### 참조 문서
|
||||
|
||||
- 문서 허브: [docs/README.md](docs/README.md)
|
||||
- 통합 문서 목차: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- 명령어 참조: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- 구성 참조: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- 제공자 참조: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- 채널 참조: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- 운영 런북: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- 문제 해결: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### 협업 문서
|
||||
|
||||
- 기여 가이드: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR 워크플로 정책: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI 워크플로 가이드: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- 리뷰어 플레이북: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- 보안 공개 정책: [SECURITY.md](SECURITY.md)
|
||||
- 문서 템플릿: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### 배포 + 운영
|
||||
|
||||
- 네트워크 배포 가이드: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- 프록시 에이전트 플레이북: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- 하드웨어 가이드: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw는 빠르고 효율적인 AI 어시스턴트인 smooth crab 🦀을 위해 만들어졌습니다. Argenis De La Rosa와 커뮤니티가 만들었습니다.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## ZeroClaw 지원하기
|
||||
|
||||
ZeroClaw가 여러분의 작업에 도움이 되었고 지속적인 개발을 지원하고 싶다면 여기에서 기부할 수 있습니다:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 특별 감사
|
||||
|
||||
이 오픈소스 작업에 영감을 주고 힘을 실어주는 커뮤니티와 기관에 진심으로 감사드립니다:
|
||||
|
||||
- **Harvard University** — 지적 호기심을 키우고 가능성의 한계를 넓혀 주셔서.
|
||||
- **MIT** — 열린 지식, 오픈소스, 그리고 기술이 모두에게 접근 가능해야 한다는 신념을 옹호해 주셔서.
|
||||
- **Sundai Club** — 커뮤니티, 에너지, 그리고 의미 있는 것을 만들고자 하는 끊임없는 열정.
|
||||
- **세계 그리고 그 너머** 🌍✨ — 오픈소스를 선한 힘으로 만드는 모든 기여자, 꿈꾸는 이, 그리고 빌더에게. 이것은 여러분을 위한 것입니다.
|
||||
|
||||
우리는 최고의 아이디어가 모든 곳에서 나오기 때문에 오픈소스로 구축합니다. 이것을 읽고 있다면 여러분도 그 일부입니다. 환영합니다. 🦀❤️
|
||||
|
||||
## 기여하기
|
||||
|
||||
ZeroClaw가 처음이신가요? [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) 레이블이 붙은 이슈를 찾아보세요 — 시작하는 방법은 [기여 가이드](CONTRIBUTING.md#first-time-contributors)를 참조하세요. AI/vibe-coded PR도 환영합니다! 🤖
|
||||
|
||||
[CONTRIBUTING.md](CONTRIBUTING.md)와 [CLA.md](docs/contributing/cla.md)를 참조하세요. 트레이트를 구현하고 PR을 제출하세요:
|
||||
|
||||
- CI 워크플로 가이드: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- 새 `Provider` → `src/providers/`
|
||||
- 새 `Channel` → `src/channels/`
|
||||
- 새 `Observer` → `src/observability/`
|
||||
- 새 `Tool` → `src/tools/`
|
||||
- 새 `Memory` → `src/memory/`
|
||||
- 새 `Tunnel` → `src/tunnel/`
|
||||
- 새 `Peripheral` → `src/peripherals/`
|
||||
- 새 `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ 공식 저장소 및 사칭 경고
|
||||
|
||||
**이것이 유일한 공식 ZeroClaw 저장소입니다:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
"ZeroClaw"라고 주장하거나 ZeroClaw Labs와의 제휴를 암시하는 다른 저장소, 조직, 도메인 또는 패키지는 **승인되지 않았으며 이 프로젝트와 관련이 없습니다**. 알려진 비인가 포크는 [TRADEMARK.md](docs/maintainers/trademark.md)에 나열됩니다.
|
||||
|
||||
사칭이나 상표 오용을 발견하면 [이슈를 열어](https://github.com/zeroclaw-labs/zeroclaw/issues) 신고해 주세요.
|
||||
|
||||
---
|
||||
|
||||
## 라이선스
|
||||
|
||||
ZeroClaw는 최대한의 개방성과 기여자 보호를 위해 듀얼 라이선스가 적용됩니다:
|
||||
|
||||
| 라이선스 | 사용 사례 |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | 오픈소스, 연구, 학술, 개인 사용 |
|
||||
| [Apache 2.0](LICENSE-APACHE) | 특허 보호, 기관, 상업 배포 |
|
||||
|
||||
두 라이선스 중 하나를 선택할 수 있습니다. **기여자는 자동으로 두 가지 모두에 대한 권한을 부여합니다** — 전체 기여자 계약은 [CLA.md](docs/contributing/cla.md)를 참조하세요.
|
||||
|
||||
### 상표
|
||||
|
||||
**ZeroClaw** 이름과 로고는 ZeroClaw Labs의 상표입니다. 이 라이선스는 승인이나 제휴를 암시하기 위해 사용할 권한을 부여하지 않습니다. 허용 및 금지 사용은 [TRADEMARK.md](docs/maintainers/trademark.md)를 참조하세요.
|
||||
|
||||
### 기여자 보호
|
||||
|
||||
- 기여의 **저작권을 유지**합니다
|
||||
- **특허 부여** (Apache 2.0)가 다른 기여자의 특허 청구로부터 보호합니다
|
||||
- 기여는 커밋 기록과 [NOTICE](NOTICE)에 **영구적으로 귀속**됩니다
|
||||
- 기여함으로써 상표권이 이전되지 않습니다
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — 오버헤드 없음. 타협 없음. 어디서나 배포. 무엇이든 교체. 🦀
|
||||
|
||||
## 기여자
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
이 목록은 GitHub 기여자 그래프에서 생성되며 자동으로 업데이트됩니다.
|
||||
|
||||
## 스타 히스토리
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.nb.md
755
README.nb.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Personlig AI-assistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Null overhead. Null kompromiss. 100% Rust. 100% Agnostisk.</strong><br>
|
||||
⚡️ <strong>Kjorer pa $10 maskinvare med <5MB RAM: Det er 99% mindre minne enn OpenClaw og 98% billigere enn en Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Bygget av studenter og medlemmer av Harvard-, MIT- og Sundai.Club-miljoene.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Sprak:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw er en personlig AI-assistent du kjorer pa dine egne enheter. Den svarer deg pa kanalene du allerede bruker (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work og flere). Den har et nettbasert dashbord for sanntidskontroll og kan kobles til maskinvareperiferiutstyr (ESP32, STM32, Arduino, Raspberry Pi). Gateway er bare kontrollplanet — produktet er assistenten.
|
||||
|
||||
Hvis du onsker en personlig, enkeltbruker-assistent som foler seg lokal, rask og alltid tilgjengelig, er dette den.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Nettsted</a> ·
|
||||
<a href="docs/README.md">Dokumentasjon</a> ·
|
||||
<a href="docs/architecture.md">Arkitektur</a> ·
|
||||
<a href="#hurtigstart">Kom i gang</a> ·
|
||||
<a href="#migrering-fra-openclaw">Migrering fra OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Feilsoking</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Anbefalt oppsett:** kjor `zeroclaw onboard` i terminalen din. ZeroClaw Onboard guider deg steg for steg gjennom oppsett av gateway, arbeidsomrade, kanaler og leverandor. Det er den anbefalte oppsettsveien og fungerer pa macOS, Linux og Windows (via WSL2). Ny installasjon? Start her: [Kom i gang](#hurtigstart)
|
||||
|
||||
### Abonnementsautentisering (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-abonnement)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-nokkel eller autentiseringstoken)
|
||||
|
||||
Modellmerknad: selv om mange leverandorer/modeller stotter, for best opplevelse bruk den sterkeste siste-generasjons modellen tilgjengelig for deg. Se [Onboarding](#hurtigstart).
|
||||
|
||||
Modellkonfigurasjon + CLI: [Leverandorreferanse](docs/reference/api/providers-reference.md)
|
||||
Autentiseringsprofil-rotasjon (OAuth vs API-nokler) + failover: [Modell-failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installasjon (anbefalt)
|
||||
|
||||
Kjoretidemiljo: Rust stabil verktoyskjede. Enkel binarfil, ingen kjoretidesavhengigheter.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Ett-klikks oppstart
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` kjorer automatisk etter installasjon for a konfigurere arbeidsomradet og leverandoren din.
|
||||
|
||||
## Hurtigstart (TL;DR)
|
||||
|
||||
Full nybegynnerguide (autentisering, paring, kanaler): [Kom i gang](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installer + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start gateway (webhook-server + nettbasert dashbord)
|
||||
zeroclaw gateway # standard: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # tilfeldig port (sikkerhetsskarmet)
|
||||
|
||||
# Snakk med assistenten
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktiv modus
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonom kjoretidemiljo (gateway + kanaler + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Sjekk status
|
||||
zeroclaw status
|
||||
|
||||
# Kjor diagnostikk
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Oppgraderer? Kjor `zeroclaw doctor` etter oppdatering.
|
||||
|
||||
### Fra kildekode (utvikling)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Utvikler-fallback (ingen global installasjon):** prefiks kommandoer med `cargo run --release --` (eksempel: `cargo run --release -- status`).
|
||||
|
||||
## Migrering fra OpenClaw
|
||||
|
||||
ZeroClaw kan importere ditt OpenClaw-arbeidsomrade, minne og konfigurasjon:
|
||||
|
||||
```bash
|
||||
# Forhandsvis hva som vil bli migrert (trygt, skrivebeskyttet)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Kjor migreringen
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Dette migrerer minneoppforinger, arbeidsomradefiler og konfigurasjon fra `~/.openclaw/` til `~/.zeroclaw/`. Konfigurasjon konverteres automatisk fra JSON til TOML.
|
||||
|
||||
## Sikkerhetsstandarder (DM-tilgang)
|
||||
|
||||
ZeroClaw kobler til ekte meldingsflater. Behandle innkommende DM-er som upalitelig inndata.
|
||||
|
||||
Full sikkerhetsguide: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Standardoppforsel pa alle kanaler:
|
||||
|
||||
- **DM-paring** (standard): ukjente avsendere mottar en kort paringskode og boten behandler ikke meldingen deres.
|
||||
- Godkjenn med: `zeroclaw pairing approve <channel> <code>` (deretter legges avsenderen til en lokal tillatelesliste).
|
||||
- Offentlige innkommende DM-er krever en eksplisitt opt-in i `config.toml`.
|
||||
- Kjor `zeroclaw doctor` for a avdekke risikable eller feilkonfigurerte DM-policyer.
|
||||
|
||||
**Autonominiva:**
|
||||
|
||||
| Niva | Oppforsel |
|
||||
|------|-----------|
|
||||
| `ReadOnly` | Agenten kan observere men ikke handle |
|
||||
| `Supervised` (standard) | Agenten handler med godkjenning for medium/hoy-risiko operasjoner |
|
||||
| `Full` | Agenten handler autonomt innenfor policygrenser |
|
||||
|
||||
**Sandkasselag:** arbeidsomradeisolasjon, stiblokkering, kommandotillatelselister, forbudte stier (`/etc`, `/root`, `~/.ssh`), hastighetsbegrensning (maks handlinger/time, kostnad/dag-tak).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### Kunngoringer
|
||||
|
||||
Bruk denne tavlen for viktige meldinger (brytende endringer, sikkerhetsrad, vedlikeholdsvinduer og utgivelsesblokkeringer).
|
||||
|
||||
| Dato (UTC) | Niva | Merknad | Handling |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritisk_ | Vi er **ikke tilknyttet** `openagen/zeroclaw`, `zeroclaw.org` eller `zeroclaw.net`. Domenene `zeroclaw.org` og `zeroclaw.net` peker for oyeblikket til `openagen/zeroclaw`-forken, og dette domenet/repositoriet utgir seg for a vaere vart offisielle nettsted/prosjekt. | Ikke stol pa informasjon, binarfiler, innsamlinger eller kunngoringer fra disse kildene. Bruk kun [dette repositoriet](https://github.com/zeroclaw-labs/zeroclaw) og vare verifiserte sosiale kontoer. |
|
||||
| 2026-02-21 | _Viktig_ | Vart offisielle nettsted er na live: [zeroclawlabs.ai](https://zeroclawlabs.ai). Takk for talmodigheten mens vi forberedte lanseringen. Vi ser fortsatt etterligningsforsok, sa **ikke** bli med pa noen investerings- eller innsamlingsaktivitet som hevder ZeroClaw-navnet med mindre det er publisert gjennom vare offisielle kanaler. | Bruk [dette repositoriet](https://github.com/zeroclaw-labs/zeroclaw) som eneste sannhetskilde. Folg [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Gruppe)](https://www.facebook.com/groups/zeroclawlabs) og [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) for offisielle oppdateringer. |
|
||||
| 2026-02-19 | _Viktig_ | Anthropic oppdaterte vilkarene for autentisering og legitimasjonsbruk 2026-02-19. Claude Code OAuth-tokens (Free, Pro, Max) er utelukkende ment for Claude Code og Claude.ai; bruk av OAuth-tokens fra Claude Free/Pro/Max i andre produkter, verktoy eller tjenester (inkludert Agent SDK) er ikke tillatt og kan bryte forbruksvilkarene. | Vennligst unnga Claude Code OAuth-integrasjoner midlertidig for a forhindre potensielt tap. Opprinnelig klausul: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Hoydepunkter
|
||||
|
||||
- **Slank kjoretidemiljo som standard** — vanlige CLI- og statusarbeidsflyter kjorer i en fa-megabyte minneramme pa release-bygg.
|
||||
- **Kostnadseffektiv distribusjon** — designet for $10-kort og sma skyinstanser, ingen tunge kjoretidesavhengigheter.
|
||||
- **Raske kaldstarter** — enkel-binar Rust-kjoretidemiljo holder kommando- og daemonoppstart naer oydblikkelig.
|
||||
- **Portabel arkitektur** — en binarfil pa tvers av ARM, x86 og RISC-V med byttbare leverandorer/kanaler/verktoy.
|
||||
- **Lokal-forst Gateway** — enkelt kontrollplan for sesjoner, kanaler, verktoy, cron, SOP-er og hendelser.
|
||||
- **Multikanal-innboks** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket og flere.
|
||||
- **Multi-agent-orkestrering (Hands)** — autonome agentsverm som kjorer etter tidsplan og blir smartere over tid.
|
||||
- **Standard Operating Procedures (SOPs)** — hendelsesdrevet arbeidsflytautomatisering med MQTT, webhook, cron og periferielle utlosere.
|
||||
- **Nettbasert dashbord** — React 19 + Vite nettgrensesnitt med sanntidschat, minneleser, konfigurasjonsredigeringsverktoy, cron-behandler og verktoyinspektoring.
|
||||
- **Maskinvareperiferiutstyr** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via `Peripheral`-traitet.
|
||||
- **Forsterangs verktoy** — shell, fil-I/O, nettleser, git, web fetch/search, MCP, Jira, Notion, Google Workspace og 70+ flere.
|
||||
- **Livssyklus-hooks** — fang opp og modifiser LLM-kall, verktoyutforelser og meldinger pa hvert trinn.
|
||||
- **Ferdighetsplattform** — medfoldgende, fellesskaps- og arbeidsomrade-ferdigheter med sikkerhetsgransking.
|
||||
- **Tunnelstotte** — Cloudflare, Tailscale, ngrok, OpenVPN og egendefinerte tunneler for fjerntilgang.
|
||||
|
||||
### Hvorfor team velger ZeroClaw
|
||||
|
||||
- **Slank som standard:** liten Rust-binarfil, rask oppstart, lavt minneforbruk.
|
||||
- **Sikker fra grunnen:** paring, streng sandkassing, eksplisitte tillateleslister, arbeidsomradeomfang.
|
||||
- **Fullt byttbart:** kjernesystemer er traits (leverandorer, kanaler, verktoy, minne, tunneler).
|
||||
- **Ingen innlasing:** OpenAI-kompatibel leverandorstotte + pluggbare egendefinerte endepunkter.
|
||||
|
||||
## Ytelsessammenligning (ZeroClaw vs OpenClaw, reproduserbar)
|
||||
|
||||
Lokal maskin hurtigtest (macOS arm64, feb 2026) normalisert for 0.8GHz kantmaskinvare.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Sprak** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Oppstart (0.8GHz-kjerne)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binarstorrelse** | ~28MB (dist) | N/A (Skript) | ~8MB | **~8.8 MB** |
|
||||
| **Kostnad** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Enhver maskinvare $10** |
|
||||
|
||||
> Merknader: ZeroClaw-resultater er malt pa release-bygg med `/usr/bin/time -l`. OpenClaw krever Node.js-kjoretidemiljo (typisk ~390MB ekstra minneoverhead), mens NanoBot krever Python-kjoretidemiljo. PicoClaw og ZeroClaw er statiske binarfiler. RAM-tallene ovenfor er kjoretidesminne; byggetidskompileringskrav er hoyere.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw-sammenligning" width="800" />
|
||||
</p>
|
||||
|
||||
### Reproduserbar lokal maling
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Alt vi har bygget sa langt
|
||||
|
||||
### Kjerneplattform
|
||||
|
||||
- Gateway HTTP/WS/SSE-kontrollplan med sesjoner, tilstedevaerelse, konfigurasjon, cron, webhooks, nettbasert dashbord og paring.
|
||||
- CLI-overflate: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agentorkestreringssloyfe med verktoyutsendelse, prompt-konstruksjon, meldingsklassifisering og minnelasting.
|
||||
- Sesjonsmodell med sikkerhetspolicy-handhevelse, autonominiva og godkjenningsstyring.
|
||||
- Robust leverandorwrapper med failover, retry og modellruting pa tvers av 20+ LLM-backends.
|
||||
|
||||
### Kanaler
|
||||
|
||||
Kanaler: WhatsApp (native), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Funksjonsbaserte: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Nettbasert dashbord
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 nettbasert dashbord servert direkte fra Gateway:
|
||||
|
||||
- **Dashbord** — systemoversikt, helsestatus, oppetid, kostnadssporing
|
||||
- **Agentchat** — interaktiv chat med agenten
|
||||
- **Minne** — bla gjennom og administrer minneoppforinger
|
||||
- **Konfigurasjon** — vis og rediger konfigurasjon
|
||||
- **Cron** — administrer planlagte oppgaver
|
||||
- **Verktoy** — bla gjennom tilgjengelige verktoy
|
||||
- **Logger** — vis agentaktivitetslogger
|
||||
- **Kostnad** — tokenbruk og kostnadssporing
|
||||
- **Doktor** — systemhelsediagnostikk
|
||||
- **Integrasjoner** — integrasjonsstatus og oppsett
|
||||
- **Paring** — enhetsparingsadministrasjon
|
||||
|
||||
### Firmwaremal
|
||||
|
||||
| Mal | Plattform | Formal |
|
||||
|-----|-----------|--------|
|
||||
| ESP32 | Espressif ESP32 | Tradlos periferiagent |
|
||||
| ESP32-UI | ESP32 + Skjerm | Agent med visuelt grensesnitt |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Industriell periferi |
|
||||
| Arduino | Arduino | Grunnleggende sensor/aktuatorbro |
|
||||
| Uno Q Bridge | Arduino Uno | Seriell bro til agent |
|
||||
|
||||
### Verktoy + automatisering
|
||||
|
||||
- **Kjerne:** shell, fillesing/skriving/redigering, git-operasjoner, glob-sok, innholdssok
|
||||
- **Nett:** nettleserkontroll, web fetch, web search, skjermbilde, bildeinformasjon, PDF-lesing
|
||||
- **Integrasjoner:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol verktoy-wrapper + utsatte verktoysamlinger
|
||||
- **Planlegging:** cron legg til/fjern/oppdater/kjor, planleggingsverktoy
|
||||
- **Minne:** recall, store, forget, knowledge, project intel
|
||||
- **Avansert:** delegate (agent-til-agent), swarm, modellbytte/-ruting, sikkerhetsoperasjoner, skyoperasjoner
|
||||
- **Maskinvare:** board info, memory map, memory read (funksjonsbasert)
|
||||
|
||||
### Kjoretidemiljo + sikkerhet
|
||||
|
||||
- **Autonominiva:** ReadOnly, Supervised (standard), Full.
|
||||
- **Sandkassing:** arbeidsomradeisolasjon, stiblokkering, kommandotillatelselister, forbudte stier, Landlock (Linux), Bubblewrap.
|
||||
- **Hastighetsbegrensning:** maks handlinger per time, maks kostnad per dag (konfigurerbart).
|
||||
- **Godkjenningsstyring:** interaktiv godkjenning for medium/hoy-risiko operasjoner.
|
||||
- **Nodstopp:** mulighet for nodavslutning.
|
||||
- **129+ sikkerhetstester** i automatisert CI.
|
||||
|
||||
### Drift + pakking
|
||||
|
||||
- Nettbasert dashbord servert direkte fra Gateway.
|
||||
- Tunnelstotte: Cloudflare, Tailscale, ngrok, OpenVPN, egendefinert kommando.
|
||||
- Docker kjoretidemiljoadapter for kontainerisert utforelse.
|
||||
- CI/CD: beta (auto pa push) -> stabil (manuell utsendelse) -> Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Forhandsbygde binarfiler for Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfigurasjon
|
||||
|
||||
Minimal `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Full konfigurasjonsreferanse: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanalkonfigurasjon
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnelkonfigurasjon
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # eller "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detaljer: [Kanalreferanse](docs/reference/api/channels-reference.md) · [Konfigurasjonsreferanse](docs/reference/api/config-reference.md)
|
||||
|
||||
### Kjoretidestotte (gjeldende)
|
||||
|
||||
- **`native`** (standard) — direkte prosessutforelse, raskeste sti, ideell for palitelige miljoer.
|
||||
- **`docker`** — full kontainerisolasjon, handhevede sikkerhetspolicyer, krever Docker.
|
||||
|
||||
Sett `runtime.kind = "docker"` for streng sandkassing eller nettverksisolasjon.
|
||||
|
||||
## Abonnementsautentisering (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw stotter abonnements-native autentiseringsprofiler (multi-konto, kryptert i hvile).
|
||||
|
||||
- Lagringsfil: `~/.zeroclaw/auth-profiles.json`
|
||||
- Krypteringsnokkel: `~/.zeroclaw/.secret_key`
|
||||
- Profil-ID-format: `<provider>:<profile_name>` (eksempel: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT-abonnement)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Sjekk / oppdater / bytt profil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Kjor agenten med abonnementsautentisering
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agentarbeidsomrade + ferdigheter
|
||||
|
||||
Arbeidsomraderot: `~/.zeroclaw/workspace/` (konfigurerbar via konfigurasjon).
|
||||
|
||||
Injiserte prompt-filer:
|
||||
- `IDENTITY.md` — agentpersonlighet og rolle
|
||||
- `USER.md` — brukerkontekst og preferanser
|
||||
- `MEMORY.md` — langtidsfakta og laerdommer
|
||||
- `AGENTS.md` — sesjonskonvensjoner og initialiseringsregler
|
||||
- `SOUL.md` — kjerneidentitet og driftsprinsipper
|
||||
|
||||
Ferdigheter: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` eller `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installerte ferdigheter
|
||||
zeroclaw skills list
|
||||
|
||||
# Installer fra git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Sikkerhetsgransking for installasjon
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Fjern en ferdighet
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-kommandoer
|
||||
|
||||
```bash
|
||||
# Arbeidsomradeadministrasjon
|
||||
zeroclaw onboard # Veiledet oppsettveiviser
|
||||
zeroclaw status # Vis daemon/agentstatus
|
||||
zeroclaw doctor # Kjor systemdiagnostikk
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway-server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonom kjoretidemiljo
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interaktiv chatmodus
|
||||
zeroclaw agent -m "melding" # Enkeltmeldingsmodus
|
||||
|
||||
# Tjenesteadministrasjon
|
||||
zeroclaw service install # Installer som OS-tjeneste (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanaler
|
||||
zeroclaw channel list # List konfigurerte kanaler
|
||||
zeroclaw channel doctor # Sjekk kanalhelse
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + planlegging
|
||||
zeroclaw cron list # List planlagte jobber
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Sjekk systemhelse"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Minne
|
||||
zeroclaw memory list # List minneoppforinger
|
||||
zeroclaw memory get <key> # Hent et minne
|
||||
zeroclaw memory stats # Minnestatistikk
|
||||
|
||||
# Autentiseringsprofiler
|
||||
zeroclaw auth login --provider <navn>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <navn> --profile <profil>
|
||||
|
||||
# Maskinvareperiferiutstyr
|
||||
zeroclaw hardware discover # Sok etter tilkoblede enheter
|
||||
zeroclaw peripheral list # List tilkoblede periferienheter
|
||||
zeroclaw peripheral flash # Flash firmware til enhet
|
||||
|
||||
# Migrering
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-fullforinger
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Full kommandoreferanse: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Forutsetninger
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Pakrevd
|
||||
|
||||
1. **Visual Studio Build Tools** (gir MSVC-linker og Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Under installasjon (eller via Visual Studio Installer), velg arbeidsbelastningen **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust-verktoyskjede:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Etter installasjon, apne en ny terminal og kjor `rustup default stable` for a sikre at den stabile verktoyskjeden er aktiv.
|
||||
|
||||
3. **Verifiser** at begge fungerer:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Valgfritt
|
||||
|
||||
- **Docker Desktop** — kun pakrevd ved bruk av [Docker-sandkassekjoretidemiljo](#kjoretidestotte-gjeldende) (`runtime.kind = "docker"`). Installer via `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Pakrevd
|
||||
|
||||
1. **Byggeverktoyer:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Installer Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust-verktoyskjede:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Se [rustup.rs](https://rustup.rs) for detaljer.
|
||||
|
||||
3. **Verifiser** at begge fungerer:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### En-linje installasjon
|
||||
|
||||
Eller hopp over stegene ovenfor og installer alt (systemavhengigheter, Rust, ZeroClaw) med en enkelt kommando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Kompileringsressurskrav
|
||||
|
||||
Bygging fra kildekode krever mer ressurser enn a kjore den resulterende binarfilen:
|
||||
|
||||
| Ressurs | Minimum | Anbefalt |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Ledig disk** | 6 GB | 10 GB+ |
|
||||
|
||||
Hvis verten din er under minimum, bruk forhandsbygde binarfiler:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
For a kreve kun binarinstallasjon uten kildekodefallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Valgfritt
|
||||
|
||||
- **Docker** — kun pakrevd ved bruk av [Docker-sandkassekjoretidemiljo](#kjoretidestotte-gjeldende) (`runtime.kind = "docker"`). Installer via pakkebehandleren din eller [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Merk:** Standard `cargo build --release` bruker `codegen-units=1` for a senke topp-kompileringstrykk. For raskere bygg pa kraftige maskiner, bruk `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Forhandsbygde binarfiler
|
||||
|
||||
Utgivelsesfiler publiseres for:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Last ned de nyeste filene fra:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentasjon
|
||||
|
||||
Bruk disse nar du er forbi onboarding-flyten og onsker dypere referanse.
|
||||
|
||||
- Start med [dokumentasjonsindeksen](docs/README.md) for navigasjon og "hva er hvor."
|
||||
- Les [arkitekturoversikten](docs/architecture.md) for den fullstendige systemmodellen.
|
||||
- Bruk [konfigurasjonsreferansen](docs/reference/api/config-reference.md) nar du trenger hver nokkel og eksempel.
|
||||
- Kjor Gateway etter boken med [driftshandboken](docs/ops/operations-runbook.md).
|
||||
- Folg [ZeroClaw Onboard](#hurtigstart) for et veiledet oppsett.
|
||||
- Feilsok vanlige problemer med [feilsokingsguiden](docs/ops/troubleshooting.md).
|
||||
- Gjennga [sikkerhetsveiledning](docs/security/README.md) for du eksponerer noe.
|
||||
|
||||
### Referansedokumentasjon
|
||||
|
||||
- Dokumentasjonshub: [docs/README.md](docs/README.md)
|
||||
- Samlet innholdsfortegnelse: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Kommandoreferanse: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Konfigurasjonsreferanse: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Leverandorreferanse: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanalreferanse: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Driftshandbok: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Feilsoking: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Samarbeidsdokumentasjon
|
||||
|
||||
- Bidragsguide: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-arbeidsflyts-policy: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-arbeidsflytguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Anmelderhandbok: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Sikkerhetsavsloring: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentasjonsmal: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Distribusjon + drift
|
||||
|
||||
- Nettverksdistribusjonsguide: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-agenthandbok: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Maskinvareguider: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw ble bygget for den smidige krabben 🦀, en rask og effektiv AI-assistent. Bygget av Argenis De La Rosa og fellesskapet.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Stott ZeroClaw
|
||||
|
||||
Hvis ZeroClaw hjelper arbeidet ditt og du onsker a stotte pagaende utvikling, kan du donere her:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### Spesiell takk
|
||||
|
||||
En hjertelig takk til miljoene og institusjonene som inspirerer og driver dette open source-arbeidet:
|
||||
|
||||
- **Harvard University** — for a fremme intellektuell nysgjerrighet og flytte grensene for hva som er mulig.
|
||||
- **MIT** — for a fremme apen kunnskap, apen kildekode og troen pa at teknologi bor vaere tilgjengelig for alle.
|
||||
- **Sundai Club** — for fellesskapet, energien og den uboyelige driven til a bygge ting som betyr noe.
|
||||
- **Verden og videre** 🌍✨ — til hver bidragsyter, drommer og bygger der ute som gjor open source til en kraft for det gode. Dette er for dere.
|
||||
|
||||
Vi bygger i det apne fordi de beste ideene kommer fra overalt. Hvis du leser dette, er du en del av det. Velkommen. 🦀❤️
|
||||
|
||||
## Bidra
|
||||
|
||||
Ny til ZeroClaw? Se etter issues merket [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — se var [Bidragsguide](CONTRIBUTING.md#first-time-contributors) for hvordan du kommer i gang. AI/vibe-kodede PR-er er velkomne! 🤖
|
||||
|
||||
Se [CONTRIBUTING.md](CONTRIBUTING.md) og [CLA.md](docs/contributing/cla.md). Implementer et trait, send inn en PR:
|
||||
|
||||
- CI-arbeidsflytguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Ny `Provider` -> `src/providers/`
|
||||
- Ny `Channel` -> `src/channels/`
|
||||
- Ny `Observer` -> `src/observability/`
|
||||
- Nytt `Tool` -> `src/tools/`
|
||||
- Nytt `Memory` -> `src/memory/`
|
||||
- Ny `Tunnel` -> `src/tunnel/`
|
||||
- Ny `Peripheral` -> `src/peripherals/`
|
||||
- Ny `Skill` -> `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## Offisielt repository og etterligningsadvarsel
|
||||
|
||||
**Dette er det eneste offisielle ZeroClaw-repositoriet:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Ethvert annet repository, organisasjon, domene eller pakke som hevder a vaere "ZeroClaw" eller antyder tilknytning til ZeroClaw Labs er **uautorisert og ikke tilknyttet dette prosjektet**. Kjente uautoriserte forker vil bli listet i [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Hvis du stoter pa etterligning eller varemerkemisbruk, vennligst [opprett en issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Lisens
|
||||
|
||||
ZeroClaw er dobbelt-lisensiert for maksimal apenhet og bidragsyterbeskyttelse:
|
||||
|
||||
| Lisens | Bruksomrade |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open source, forskning, akademisk, personlig bruk |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patentbeskyttelse, institusjonell, kommersiell distribusjon |
|
||||
|
||||
Du kan velge begge lisenser. **Bidragsytere gir automatisk rettigheter under begge** — se [CLA.md](docs/contributing/cla.md) for den fullstendige bidragsyteravtalen.
|
||||
|
||||
### Varemerke
|
||||
|
||||
**ZeroClaw**-navnet og logoen er varemerker for ZeroClaw Labs. Denne lisensen gir ikke tillatelse til a bruke dem for a antyde stotte eller tilknytning. Se [TRADEMARK.md](docs/maintainers/trademark.md) for tillatt og forbudt bruk.
|
||||
|
||||
### Bidragsyterbeskyttelse
|
||||
|
||||
- Du **beholder opphavsretten** til dine bidrag
|
||||
- **Patentbevilgning** (Apache 2.0) beskytter deg mot patentkrav fra andre bidragsytere
|
||||
- Dine bidrag er **permanent attribuert** i commit-historikk og [NOTICE](NOTICE)
|
||||
- Ingen varemerkerettigheter overdrages ved a bidra
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Null overhead. Null kompromiss. Distribuer overalt. Bytt hva som helst. 🦀
|
||||
|
||||
## Bidragsytere
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw-bidragsytere" />
|
||||
</a>
|
||||
|
||||
Denne listen genereres fra GitHub-bidragsytergrafen og oppdateres automatisk.
|
||||
|
||||
## Stjernehistorikk
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Stjernehistorikk-diagram" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.nl.md
755
README.nl.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Persoonlijke AI-Assistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Nul overhead. Nul compromis. 100% Rust. 100% Agnostisch.</strong><br>
|
||||
⚡️ <strong>Draait op $10 hardware met <5MB RAM: Dat is 99% minder geheugen dan OpenClaw en 98% goedkoper dan een Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Gebouwd door studenten en leden van de Harvard-, MIT- en Sundai.Club-gemeenschappen.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Talen:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw is een persoonlijke AI-assistent die je op je eigen apparaten draait. Hij beantwoordt je op de kanalen die je al gebruikt (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work en meer). Het heeft een webdashboard voor realtime controle en kan verbinding maken met hardware-randapparatuur (ESP32, STM32, Arduino, Raspberry Pi). De Gateway is slechts het besturingsvlak — het product is de assistent.
|
||||
|
||||
Als je een persoonlijke, single-user assistent wilt die lokaal, snel en altijd beschikbaar aanvoelt — dit is het.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Website</a> ·
|
||||
<a href="docs/README.md">Documentatie</a> ·
|
||||
<a href="docs/architecture.md">Architectuur</a> ·
|
||||
<a href="#snelle-start">Aan de slag</a> ·
|
||||
<a href="#migreren-van-openclaw">Migreren van OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Probleemoplossing</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Aanbevolen setup:** voer `zeroclaw onboard` uit in je terminal. ZeroClaw Onboard begeleidt je stap voor stap door het instellen van de gateway, workspace, kanalen en provider. Het is het aanbevolen installatiepad en werkt op macOS, Linux en Windows (via WSL2). Nieuwe installatie? Begin hier: [Aan de slag](#snelle-start)
|
||||
|
||||
### Abonnementsauthenticatie (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-abonnement)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-sleutel of autorisatietoken)
|
||||
|
||||
Modelopmerking: hoewel veel providers/modellen worden ondersteund, gebruik voor de beste ervaring het sterkste beschikbare model van de nieuwste generatie. Zie [Onboarding](#snelle-start).
|
||||
|
||||
Modelconfiguratie + CLI: [Providers-referentie](docs/reference/api/providers-reference.md)
|
||||
Autorisatieprofiel-rotatie (OAuth vs API-sleutels) + failover: [Model-failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installatie (aanbevolen)
|
||||
|
||||
Runtime: stabiele Rust-toolchain. Enkel binair bestand, geen runtime-afhankelijkheden.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Installatie met één klik
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` wordt automatisch uitgevoerd na installatie om je workspace en provider te configureren.
|
||||
|
||||
## Snelle start (TL;DR)
|
||||
|
||||
Volledige beginnersgids (authenticatie, koppeling, kanalen): [Aan de slag](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installatie + onboarding
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start de gateway (webhook-server + webdashboard)
|
||||
zeroclaw gateway # standaard: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # willekeurige poort (beveiligingsversterkt)
|
||||
|
||||
# Praat met de assistent
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactieve modus
|
||||
zeroclaw agent
|
||||
|
||||
# Start volledige autonome runtime (gateway + kanalen + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Controleer status
|
||||
zeroclaw status
|
||||
|
||||
# Voer diagnostiek uit
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Bijwerken? Voer `zeroclaw doctor` uit na het updaten.
|
||||
|
||||
### Vanuit broncode (ontwikkeling)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Dev-fallback (geen globale installatie):** voeg `cargo run --release --` voor commando's toe (voorbeeld: `cargo run --release -- status`).
|
||||
|
||||
## Migreren van OpenClaw
|
||||
|
||||
ZeroClaw kan je OpenClaw-workspace, geheugen en configuratie importeren:
|
||||
|
||||
```bash
|
||||
# Voorbeeld van wat gemigreerd wordt (veilig, alleen-lezen)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Voer de migratie uit
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Dit migreert je geheugenregistraties, workspace-bestanden en configuratie van `~/.openclaw/` naar `~/.zeroclaw/`. Configuratie wordt automatisch geconverteerd van JSON naar TOML.
|
||||
|
||||
## Standaard beveiligingsinstellingen (DM-toegang)
|
||||
|
||||
ZeroClaw verbindt met echte berichtenplatforms. Behandel inkomende DM's als onbetrouwbare invoer.
|
||||
|
||||
Volledige beveiligingsgids: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Standaardgedrag op alle kanalen:
|
||||
|
||||
- **DM-koppeling** (standaard): onbekende afzenders ontvangen een korte koppelingscode en de bot verwerkt hun bericht niet.
|
||||
- Goedkeuren met: `zeroclaw pairing approve <channel> <code>` (vervolgens wordt de afzender toegevoegd aan een lokale allowlist).
|
||||
- Publieke inkomende DM's vereisen een expliciete opt-in in `config.toml`.
|
||||
- Voer `zeroclaw doctor` uit om riskante of verkeerd geconfigureerde DM-beleidsregels te detecteren.
|
||||
|
||||
**Autonomieniveaus:**
|
||||
|
||||
| Niveau | Gedrag |
|
||||
|--------|--------|
|
||||
| `ReadOnly` | Agent kan observeren maar niet handelen |
|
||||
| `Supervised` (standaard) | Agent handelt met goedkeuring voor medium/hoog risico-operaties |
|
||||
| `Full` | Agent handelt autonoom binnen beleidsgrenzen |
|
||||
|
||||
**Sandboxing-lagen:** workspace-isolatie, padtraversatieblokkering, commando-allowlisting, verboden paden (`/etc`, `/root`, `~/.ssh`), snelheidsbeperking (max acties/uur, kosten/dag-limieten).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Aankondigingen
|
||||
|
||||
Gebruik dit bord voor belangrijke mededelingen (breaking changes, beveiligingsadviezen, onderhoudsvensters en release-blokkers).
|
||||
|
||||
| Datum (UTC) | Niveau | Mededeling | Actie |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritiek_ | We zijn **niet gelieerd** aan `openagen/zeroclaw`, `zeroclaw.org` of `zeroclaw.net`. De domeinen `zeroclaw.org` en `zeroclaw.net` verwijzen momenteel naar de `openagen/zeroclaw`-fork, en dat domein/repository doet zich voor als onze officiële website/project. | Vertrouw geen informatie, binaire bestanden, fondswerving of aankondigingen van die bronnen. Gebruik alleen [dit repository](https://github.com/zeroclaw-labs/zeroclaw) en onze geverifieerde sociale accounts. |
|
||||
| 2026-02-21 | _Belangrijk_ | Onze officiële website is nu live: [zeroclawlabs.ai](https://zeroclawlabs.ai). Bedankt voor je geduld terwijl we de lancering voorbereidden. We zien nog steeds imitatiepogingen, dus **doe niet** mee aan investeringen of fondsenwerving die de ZeroClaw-naam claimt, tenzij deze gepubliceerd is via onze officiële kanalen. | Gebruik [dit repository](https://github.com/zeroclaw-labs/zeroclaw) als de enige bron van waarheid. Volg [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Groep)](https://www.facebook.com/groups/zeroclawlabs) en [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) voor officiële updates. |
|
||||
| 2026-02-19 | _Belangrijk_ | Anthropic heeft de voorwaarden voor authenticatie en gebruik van inloggegevens bijgewerkt op 2026-02-19. Claude Code OAuth-tokens (Free, Pro, Max) zijn uitsluitend bedoeld voor Claude Code en Claude.ai; het gebruik van OAuth-tokens van Claude Free/Pro/Max in elk ander product, tool of service (inclusief Agent SDK) is niet toegestaan en kan de Consumentenvoorwaarden schenden. | Vermijd tijdelijk Claude Code OAuth-integraties om potentieel verlies te voorkomen. Originele clausule: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Hoogtepunten
|
||||
|
||||
- **Lichte runtime standaard** — veelvoorkomende CLI- en statusworkflows draaien in een geheugenomvang van enkele megabytes op release-builds.
|
||||
- **Kostenefficiënte implementatie** — ontworpen voor $10-borden en kleine cloud-instances, geen zware runtime-afhankelijkheden.
|
||||
- **Snelle koude starts** — single-binary Rust-runtime houdt het opstarten van commando's en daemon vrijwel instant.
|
||||
- **Draagbare architectuur** — één binair bestand voor ARM, x86 en RISC-V met verwisselbare providers/kanalen/tools.
|
||||
- **Lokale gateway** — enkel besturingsvlak voor sessies, kanalen, tools, cron, SOP's en events.
|
||||
- **Multi-channel inbox** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket en meer.
|
||||
- **Multi-agent-orkestratie (Hands)** — autonome agentenzwermen die op schema draaien en na verloop van tijd slimmer worden.
|
||||
- **Standaard Operationele Procedures (SOP's)** — event-gedreven workflowautomatisering met MQTT-, webhook-, cron- en periferie-triggers.
|
||||
- **Webdashboard** — React 19 + Vite web-UI met realtime chat, geheugenbrowser, configuratie-editor, cron-manager en tool-inspector.
|
||||
- **Hardware-randapparatuur** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via de `Peripheral`-trait.
|
||||
- **Eersteklas tools** — shell, bestands-I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace en 70+ meer.
|
||||
- **Lifecycle-hooks** — onderschep en wijzig LLM-aanroepen, tool-uitvoeringen en berichten in elke fase.
|
||||
- **Skills-platform** — ingebouwde, community- en workspace-skills met beveiligingsaudit.
|
||||
- **Tunnelondersteuning** — Cloudflare, Tailscale, ngrok, OpenVPN en aangepaste tunnels voor externe toegang.
|
||||
|
||||
### Waarom teams kiezen voor ZeroClaw
|
||||
|
||||
- **Licht standaard:** klein Rust-binair bestand, snelle opstart, laag geheugengebruik.
|
||||
- **Veilig by design:** koppeling, strikte sandboxing, expliciete allowlists, workspace-scoping.
|
||||
- **Volledig verwisselbaar:** kernsystemen zijn traits (providers, kanalen, tools, geheugen, tunnels).
|
||||
- **Geen vendor lock-in:** OpenAI-compatibele provider-ondersteuning + inplugbare aangepaste endpoints.
|
||||
|
||||
## Benchmark-overzicht (ZeroClaw vs OpenClaw, reproduceerbaar)
|
||||
|
||||
Snelle lokale benchmark (macOS arm64, feb 2026) genormaliseerd voor 0.8GHz edge-hardware.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Taal** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Opstart (0.8GHz core)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binaire grootte** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Kosten** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Elke hardware $10** |
|
||||
|
||||
> Opmerkingen: ZeroClaw-resultaten zijn gemeten op release-builds met `/usr/bin/time -l`. OpenClaw vereist Node.js-runtime (typisch ~390MB extra geheugenoverhead), terwijl NanoBot Python-runtime vereist. PicoClaw en ZeroClaw zijn statische binaries. De RAM-cijfers hierboven zijn runtime-geheugen; compilatievereisten zijn hoger.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Reproduceerbare lokale meting
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Alles wat we tot nu toe hebben gebouwd
|
||||
|
||||
### Kernplatform
|
||||
|
||||
- Gateway HTTP/WS/SSE besturingsvlak met sessies, aanwezigheid, configuratie, cron, webhooks, webdashboard en koppeling.
|
||||
- CLI-oppervlak: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agent-orkestratielus met tool-dispatch, promptconstructie, berichtclassificatie en geheugen laden.
|
||||
- Sessiemodel met beveiligingsbeleid-handhaving, autonomieniveaus en goedkeuringspoorten.
|
||||
- Veerkrachtige provider-wrapper met failover, retry en modelrouting over 20+ LLM-backends.
|
||||
|
||||
### Kanalen
|
||||
|
||||
Kanalen: WhatsApp (natief), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Webdashboard
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 webdashboard geserveerd direct vanuit de Gateway:
|
||||
|
||||
- **Dashboard** — systeemoverzicht, gezondheidsstatus, uptime, kostentracking
|
||||
- **Agent Chat** — interactieve chat met de agent
|
||||
- **Geheugen** — bladeren en beheren van geheugenregistraties
|
||||
- **Configuratie** — bekijken en bewerken van configuratie
|
||||
- **Cron** — beheer van geplande taken
|
||||
- **Tools** — bladeren door beschikbare tools
|
||||
- **Logs** — bekijken van agent-activiteitslogs
|
||||
- **Kosten** — tokengebruik en kostentracking
|
||||
- **Doctor** — systeemgezondheidsdiagnostiek
|
||||
- **Integraties** — integratiestatus en setup
|
||||
- **Koppeling** — apparaatkoppelingsbeheer
|
||||
|
||||
### Firmware-doelen
|
||||
|
||||
| Doel | Platform | Doel |
|
||||
|------|----------|------|
|
||||
| ESP32 | Espressif ESP32 | Draadloze perifere agent |
|
||||
| ESP32-UI | ESP32 + Display | Agent met visuele interface |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Industriële periferie |
|
||||
| Arduino | Arduino | Basis sensor/actuator-brug |
|
||||
| Uno Q Bridge | Arduino Uno | Seriële brug naar agent |
|
||||
|
||||
### Tools + automatisering
|
||||
|
||||
- **Kern:** shell, bestand lezen/schrijven/bewerken, git-operaties, glob-zoekopdracht, inhoudszoekopdracht
|
||||
- **Web:** browserbediening, web fetch, webzoekopdracht, screenshot, afbeeldingsinfo, PDF lezen
|
||||
- **Integraties:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool-wrapper + uitgestelde toolsets
|
||||
- **Planning:** cron add/remove/update/run, planningstool
|
||||
- **Geheugen:** recall, store, forget, knowledge, project intel
|
||||
- **Geavanceerd:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Hardware:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Runtime + veiligheid
|
||||
|
||||
- **Autonomieniveaus:** ReadOnly, Supervised (standaard), Full.
|
||||
- **Sandboxing:** workspace-isolatie, padtraversatieblokkering, commando-allowlists, verboden paden, Landlock (Linux), Bubblewrap.
|
||||
- **Snelheidsbeperking:** max acties per uur, max kosten per dag (configureerbaar).
|
||||
- **Goedkeuringspoort:** interactieve goedkeuring voor medium/hoog risico-operaties.
|
||||
- **E-stop:** noodstopfunctionaliteit.
|
||||
- **129+ beveiligingstests** in geautomatiseerd CI.
|
||||
|
||||
### Ops + verpakking
|
||||
|
||||
- Webdashboard geserveerd direct vanuit de Gateway.
|
||||
- Tunnelondersteuning: Cloudflare, Tailscale, ngrok, OpenVPN, aangepast commando.
|
||||
- Docker runtime-adapter voor gecontaineriseerde uitvoering.
|
||||
- CI/CD: beta (auto bij push) → stable (handmatige dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Voorgebouwde binaries voor Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Configuratie
|
||||
|
||||
Minimale `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Volledige configuratiereferentie: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanaalconfiguratie
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnelconfiguratie
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # of "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Details: [Kanaalreferentie](docs/reference/api/channels-reference.md) · [Configuratiereferentie](docs/reference/api/config-reference.md)
|
||||
|
||||
### Runtime-ondersteuning (huidig)
|
||||
|
||||
- **`native`** (standaard) — directe procesuitvoering, snelste pad, ideaal voor vertrouwde omgevingen.
|
||||
- **`docker`** — volledige containerisolatie, afgedwongen beveiligingsbeleid, vereist Docker.
|
||||
|
||||
Stel `runtime.kind = "docker"` in voor strikte sandboxing of netwerkisolatie.
|
||||
|
||||
## Abonnementsauthenticatie (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw ondersteunt native abonnementsautorisatieprofielen (meerdere accounts, versleuteld in rust).
|
||||
|
||||
- Opslagbestand: `~/.zeroclaw/auth-profiles.json`
|
||||
- Versleutelingssleutel: `~/.zeroclaw/.secret_key`
|
||||
- Profiel-ID-formaat: `<provider>:<profile_name>` (voorbeeld: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT-abonnement)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Controleer / ververs / wissel profiel
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Agent draaien met abonnementsauth
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agent-workspace + skills
|
||||
|
||||
Workspace-root: `~/.zeroclaw/workspace/` (configureerbaar via config).
|
||||
|
||||
Geïnjecteerde promptbestanden:
|
||||
- `IDENTITY.md` — persoonlijkheid en rol van de agent
|
||||
- `USER.md` — gebruikerscontext en voorkeuren
|
||||
- `MEMORY.md` — langetermijnfeiten en lessen
|
||||
- `AGENTS.md` — sessieconventies en initialisatieregels
|
||||
- `SOUL.md` — kernidentiteit en operationele principes
|
||||
|
||||
Skills: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` of `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Lijst geïnstalleerde skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Installeer vanuit git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Beveiligingsaudit voor installatie
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Verwijder een skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-commando's
|
||||
|
||||
```bash
|
||||
# Workspace-beheer
|
||||
zeroclaw onboard # Begeleide installatiewizard
|
||||
zeroclaw status # Toon daemon/agent-status
|
||||
zeroclaw doctor # Voer systeemdiagnostiek uit
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway-server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start volledige autonome runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactieve chatmodus
|
||||
zeroclaw agent -m "message" # Enkele berichtmodus
|
||||
|
||||
# Servicebeheer
|
||||
zeroclaw service install # Installeer als OS-service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanalen
|
||||
zeroclaw channel list # Lijst geconfigureerde kanalen
|
||||
zeroclaw channel doctor # Controleer kanaalgezondheid
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + planning
|
||||
zeroclaw cron list # Lijst geplande taken
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Geheugen
|
||||
zeroclaw memory list # Lijst geheugenregistraties
|
||||
zeroclaw memory get <key> # Haal een geheugenitem op
|
||||
zeroclaw memory stats # Geheugenstatistieken
|
||||
|
||||
# Autorisatieprofielen
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware-randapparatuur
|
||||
zeroclaw hardware discover # Scan verbonden apparaten
|
||||
zeroclaw peripheral list # Lijst verbonden randapparatuur
|
||||
zeroclaw peripheral flash # Flash firmware naar apparaat
|
||||
|
||||
# Migratie
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-aanvullingen
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Volledige commandoreferentie: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Vereisten
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Vereist
|
||||
|
||||
1. **Visual Studio Build Tools** (biedt de MSVC-linker en Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Selecteer tijdens de installatie (of via de Visual Studio Installer) de **"Desktop development with C++"** workload.
|
||||
|
||||
2. **Rust-toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Open na installatie een nieuwe terminal en voer `rustup default stable` uit om te verzekeren dat de stabiele toolchain actief is.
|
||||
|
||||
3. **Controleer** of beide werken:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Optioneel
|
||||
|
||||
- **Docker Desktop** — alleen vereist bij gebruik van de [Docker-sandboxed runtime](#runtime-ondersteuning-huidig) (`runtime.kind = "docker"`). Installeer via `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Vereist
|
||||
|
||||
1. **Bouwtools:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Installeer Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust-toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Zie [rustup.rs](https://rustup.rs) voor details.
|
||||
|
||||
3. **Controleer** of beide werken:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Eenregelige installer
|
||||
|
||||
Of sla bovenstaande stappen over en installeer alles (systeemafhankelijkheden, Rust, ZeroClaw) in één commando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Compilatieresource-vereisten
|
||||
|
||||
Bouwen vanuit broncode heeft meer resources nodig dan het draaien van het resulterende binaire bestand:
|
||||
|
||||
| Resource | Minimum | Aanbevolen |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Vrije schijf** | 6 GB | 10 GB+ |
|
||||
|
||||
Als je host onder het minimum zit, gebruik dan voorgebouwde binaries:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Om alleen binaire installatie te forceren zonder broncode-fallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Optioneel
|
||||
|
||||
- **Docker** — alleen vereist bij gebruik van de [Docker-sandboxed runtime](#runtime-ondersteuning-huidig) (`runtime.kind = "docker"`). Installeer via je pakketbeheerder of [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Opmerking:** De standaard `cargo build --release` gebruikt `codegen-units=1` om piekcompiledruk te verlagen. Voor snellere builds op krachtige machines, gebruik `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Voorgebouwde binaries
|
||||
|
||||
Release-assets worden gepubliceerd voor:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Download de nieuwste assets van:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Documentatie
|
||||
|
||||
Gebruik deze wanneer je voorbij de onboarding bent en diepere referentie wilt.
|
||||
|
||||
- Begin met de [documentatie-index](docs/README.md) voor navigatie en "wat staat waar."
|
||||
- Lees het [architectuuroverzicht](docs/architecture.md) voor het volledige systeemmodel.
|
||||
- Gebruik de [configuratiereferentie](docs/reference/api/config-reference.md) wanneer je elke sleutel en elk voorbeeld nodig hebt.
|
||||
- Draai de Gateway volgens het [operationele draaiboek](docs/ops/operations-runbook.md).
|
||||
- Volg [ZeroClaw Onboard](#snelle-start) voor een begeleide setup.
|
||||
- Debug veelvoorkomende fouten met de [probleemoplossingsgids](docs/ops/troubleshooting.md).
|
||||
- Bekijk de [beveiligingsrichtlijnen](docs/security/README.md) voordat je iets blootstelt.
|
||||
|
||||
### Referentiedocumentatie
|
||||
|
||||
- Documentatiehub: [docs/README.md](docs/README.md)
|
||||
- Uniforme inhoudsopgave: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Commandoreferentie: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Configuratiereferentie: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Providerreferentie: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanaalreferentie: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Operationeel draaiboek: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Probleemoplossing: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Samenwerkingsdocumentatie
|
||||
|
||||
- Bijdragegids: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-workflowbeleid: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-workflowgids: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Reviewer-draaiboek: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Beveiligingsonthullingsbeleid: [SECURITY.md](SECURITY.md)
|
||||
- Documentatiesjabloon: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Implementatie + operaties
|
||||
|
||||
- Netwerkimplementatiegids: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-agent-draaiboek: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hardwaregidsen: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw is gebouwd voor de smooth crab 🦀, een snelle en efficiënte AI-assistent. Gebouwd door Argenis De La Rosa en de gemeenschap.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Steun ZeroClaw
|
||||
|
||||
Als ZeroClaw je werk helpt en je de voortdurende ontwikkeling wilt steunen, kun je hier doneren:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Speciale dank
|
||||
|
||||
Een hartelijk dankjewel aan de gemeenschappen en instellingen die dit open-source werk inspireren en voeden:
|
||||
|
||||
- **Harvard University** — voor het bevorderen van intellectuele nieuwsgierigheid en het verleggen van de grenzen van het mogelijke.
|
||||
- **MIT** — voor het verdedigen van open kennis, open source en het geloof dat technologie voor iedereen toegankelijk moet zijn.
|
||||
- **Sundai Club** — voor de gemeenschap, de energie en de onvermoeibare drang om dingen te bouwen die ertoe doen.
|
||||
- **De wereld en verder** 🌍✨ — aan elke bijdrager, dromer en bouwer die open source een kracht ten goede maakt. Dit is voor jou.
|
||||
|
||||
We bouwen in het open omdat de beste ideeën overal vandaan komen. Als je dit leest, ben je er onderdeel van. Welkom. 🦀❤️
|
||||
|
||||
## Bijdragen
|
||||
|
||||
Nieuw bij ZeroClaw? Zoek naar issues gelabeld [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — zie onze [Bijdragegids](CONTRIBUTING.md#first-time-contributors) om te beginnen. AI/vibe-coded PR's welkom! 🤖
|
||||
|
||||
Zie [CONTRIBUTING.md](CONTRIBUTING.md) en [CLA.md](docs/contributing/cla.md). Implementeer een trait, dien een PR in:
|
||||
|
||||
- CI-workflowgids: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Nieuwe `Provider` → `src/providers/`
|
||||
- Nieuw `Channel` → `src/channels/`
|
||||
- Nieuwe `Observer` → `src/observability/`
|
||||
- Nieuwe `Tool` → `src/tools/`
|
||||
- Nieuw `Memory` → `src/memory/`
|
||||
- Nieuwe `Tunnel` → `src/tunnel/`
|
||||
- Nieuw `Peripheral` → `src/peripherals/`
|
||||
- Nieuwe `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Officieel repository & waarschuwing tegen imitatie
|
||||
|
||||
**Dit is het enige officiële ZeroClaw-repository:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Elk ander repository, organisatie, domein of pakket dat beweert "ZeroClaw" te zijn of een relatie met ZeroClaw Labs impliceert, is **ongeautoriseerd en niet gelieerd aan dit project**. Bekende ongeautoriseerde forks worden vermeld in [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Als je imitatie of merkmisbruik tegenkomt, [open dan een issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licentie
|
||||
|
||||
ZeroClaw heeft een dubbele licentie voor maximale openheid en bescherming van bijdragers:
|
||||
|
||||
| Licentie | Gebruiksscenario |
|
||||
|----------|-------------------|
|
||||
| [MIT](LICENSE-MIT) | Open-source, onderzoek, academisch, persoonlijk gebruik |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Octrooi-bescherming, institutioneel, commerciële implementatie |
|
||||
|
||||
Je kunt een van beide licenties kiezen. **Bijdragers verlenen automatisch rechten onder beide** — zie [CLA.md](docs/contributing/cla.md) voor de volledige bijdrager-overeenkomst.
|
||||
|
||||
### Handelsmerk
|
||||
|
||||
De **ZeroClaw**-naam en het logo zijn handelsmerken van ZeroClaw Labs. Deze licentie verleent geen toestemming om ze te gebruiken om goedkeuring of affiliatie te impliceren. Zie [TRADEMARK.md](docs/maintainers/trademark.md) voor toegestaan en verboden gebruik.
|
||||
|
||||
### Bijdragerbescherming
|
||||
|
||||
- Je **behoudt het auteursrecht** op je bijdragen
|
||||
- **Octrooiverlening** (Apache 2.0) beschermt je tegen octrooiclaims van andere bijdragers
|
||||
- Je bijdragen worden **permanent toegeschreven** in de commitgeschiedenis en [NOTICE](NOTICE)
|
||||
- Er worden geen handelsmerkrechten overgedragen door bij te dragen
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Nul overhead. Nul compromis. Implementeer overal. Wissel alles. 🦀
|
||||
|
||||
## Bijdragers
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Deze lijst wordt gegenereerd vanuit de GitHub-bijdragersgrafiek en wordt automatisch bijgewerkt.
|
||||
|
||||
## Sterrengeschiedenis
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.pl.md
755
README.pl.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Osobisty Asystent AI</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Zero narzutu. Zero kompromisów. 100% Rust. 100% Agnostyczny.</strong><br>
|
||||
⚡️ <strong>Działa na sprzęcie za $10 z <5MB RAM: To 99% mniej pamięci niż OpenClaw i 98% taniej niż Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Stworzone przez studentów i członków społeczności Harvard, MIT i Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Języki:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw to osobisty asystent AI, który uruchamiasz na własnych urządzeniach. Odpowiada na kanałach, których już używasz (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work i więcej). Posiada panel webowy do kontroli w czasie rzeczywistym i może łączyć się z peryferiami sprzętowymi (ESP32, STM32, Arduino, Raspberry Pi). Gateway to tylko warstwa sterowania — produktem jest asystent.
|
||||
|
||||
Jeśli szukasz osobistego, jednoosobowego asystenta, który działa lokalnie, szybko i jest zawsze dostępny — to jest to.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Strona internetowa</a> ·
|
||||
<a href="docs/README.md">Dokumentacja</a> ·
|
||||
<a href="docs/architecture.md">Architektura</a> ·
|
||||
<a href="#szybki-start">Rozpocznij</a> ·
|
||||
<a href="#migracja-z-openclaw">Migracja z OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Rozwiązywanie problemów</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Zalecana konfiguracja:** uruchom `zeroclaw onboard` w terminalu. ZeroClaw Onboard prowadzi Cię krok po kroku przez konfigurację gateway, workspace, kanałów i dostawcy. Jest to zalecana ścieżka konfiguracji i działa na macOS, Linux i Windows (przez WSL2). Nowa instalacja? Zacznij tutaj: [Rozpocznij](#szybki-start)
|
||||
|
||||
### Uwierzytelnianie subskrypcyjne (OAuth)
|
||||
|
||||
- **OpenAI Codex** (subskrypcja ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (klucz API lub token autoryzacyjny)
|
||||
|
||||
Uwaga dotycząca modeli: chociaż obsługiwanych jest wielu dostawców/modeli, dla najlepszego doświadczenia używaj najsilniejszego dostępnego modelu najnowszej generacji. Zobacz [Onboarding](#szybki-start).
|
||||
|
||||
Konfiguracja modeli + CLI: [Dokumentacja dostawców](docs/reference/api/providers-reference.md)
|
||||
Rotacja profili autoryzacyjnych (OAuth vs klucze API) + failover: [Failover modeli](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instalacja (zalecana)
|
||||
|
||||
Środowisko uruchomieniowe: stabilny toolchain Rust. Pojedynczy plik binarny, brak zależności runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Instalacja jednym kliknięciem
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` uruchamia się automatycznie po instalacji, aby skonfigurować workspace i dostawcę.
|
||||
|
||||
## Szybki start (TL;DR)
|
||||
|
||||
Pełny przewodnik dla początkujących (autoryzacja, parowanie, kanały): [Rozpocznij](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instalacja + onboarding
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Uruchom gateway (serwer webhook + panel webowy)
|
||||
zeroclaw gateway # domyślnie: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # losowy port (wzmocnione bezpieczeństwo)
|
||||
|
||||
# Porozmawiaj z asystentem
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Tryb interaktywny
|
||||
zeroclaw agent
|
||||
|
||||
# Uruchom pełne autonomiczne środowisko (gateway + kanały + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Sprawdź status
|
||||
zeroclaw status
|
||||
|
||||
# Uruchom diagnostykę
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Aktualizujesz? Uruchom `zeroclaw doctor` po aktualizacji.
|
||||
|
||||
### Ze źródła (rozwój)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Tryb deweloperski (bez globalnej instalacji):** poprzedź komendy `cargo run --release --` (przykład: `cargo run --release -- status`).
|
||||
|
||||
## Migracja z OpenClaw
|
||||
|
||||
ZeroClaw może zaimportować Twój workspace, pamięć i konfigurację OpenClaw:
|
||||
|
||||
```bash
|
||||
# Podgląd tego, co zostanie zmigrowane (bezpieczne, tylko odczyt)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Uruchom migrację
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Migruje wpisy pamięci, pliki workspace i konfigurację z `~/.openclaw/` do `~/.zeroclaw/`. Konfiguracja jest automatycznie konwertowana z JSON do TOML.
|
||||
|
||||
## Domyślne ustawienia bezpieczeństwa (dostęp DM)
|
||||
|
||||
ZeroClaw łączy się z prawdziwymi platformami komunikacyjnymi. Traktuj przychodzące DM jako niezaufane dane wejściowe.
|
||||
|
||||
Pełny przewodnik bezpieczeństwa: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Domyślne zachowanie na wszystkich kanałach:
|
||||
|
||||
- **Parowanie DM** (domyślne): nieznani nadawcy otrzymują krótki kod parowania i bot nie przetwarza ich wiadomości.
|
||||
- Zatwierdź za pomocą: `zeroclaw pairing approve <channel> <code>` (wtedy nadawca jest dodawany do lokalnej listy dozwolonych).
|
||||
- Publiczne przychodzące DM wymagają jawnej zgody w `config.toml`.
|
||||
- Uruchom `zeroclaw doctor`, aby wykryć ryzykowne lub błędnie skonfigurowane polityki DM.
|
||||
|
||||
**Poziomy autonomii:**
|
||||
|
||||
| Poziom | Zachowanie |
|
||||
|--------|------------|
|
||||
| `ReadOnly` | Agent może obserwować, ale nie działać |
|
||||
| `Supervised` (domyślny) | Agent działa z zatwierdzeniem dla operacji średniego/wysokiego ryzyka |
|
||||
| `Full` | Agent działa autonomicznie w granicach polityki |
|
||||
|
||||
**Warstwy sandboxingu:** izolacja workspace, blokowanie przechodzenia ścieżek, lista dozwolonych poleceń, zabronione ścieżki (`/etc`, `/root`, `~/.ssh`), ograniczenie szybkości (maks. akcji/godzinę, limity kosztów/dzień).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Ogłoszenia
|
||||
|
||||
Użyj tej tablicy do ważnych ogłoszeń (zmiany łamiące, porady bezpieczeństwa, okna serwisowe i blokery wydań).
|
||||
|
||||
| Data (UTC) | Poziom | Ogłoszenie | Działanie |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Krytyczny_ | **Nie jesteśmy powiązani** z `openagen/zeroclaw`, `zeroclaw.org` ani `zeroclaw.net`. Domeny `zeroclaw.org` i `zeroclaw.net` obecnie kierują do forka `openagen/zeroclaw`, a ta domena/repozytorium podszywają się pod naszą oficjalną stronę/projekt. | Nie ufaj informacjom, plikom binarnym, zbiórkom funduszy ani ogłoszeniom z tych źródeł. Używaj wyłącznie [tego repozytorium](https://github.com/zeroclaw-labs/zeroclaw) i naszych zweryfikowanych kont społecznościowych. |
|
||||
| 2026-02-21 | _Ważny_ | Nasza oficjalna strona internetowa jest teraz dostępna: [zeroclawlabs.ai](https://zeroclawlabs.ai). Dziękujemy za cierpliwość podczas przygotowywania premiery. Nadal obserwujemy próby podszywania się, więc **nie** dołączaj do żadnych inwestycji ani zbiórek funduszy pod nazwą ZeroClaw, chyba że zostały opublikowane przez nasze oficjalne kanały. | Używaj [tego repozytorium](https://github.com/zeroclaw-labs/zeroclaw) jako jedynego źródła prawdy. Śledź [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupa)](https://www.facebook.com/groups/zeroclawlabs) i [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) po oficjalne aktualizacje. |
|
||||
| 2026-02-19 | _Ważny_ | Anthropic zaktualizował warunki uwierzytelniania i użytkowania poświadczeń 2026-02-19. Tokeny OAuth Claude Code (Free, Pro, Max) są przeznaczone wyłącznie dla Claude Code i Claude.ai; używanie tokenów OAuth z Claude Free/Pro/Max w jakimkolwiek innym produkcie, narzędziu lub usłudze (w tym Agent SDK) nie jest dozwolone i może naruszać Warunki korzystania z usługi. | Proszę tymczasowo unikać integracji OAuth Claude Code, aby zapobiec potencjalnym stratom. Oryginalna klauzula: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Najważniejsze cechy
|
||||
|
||||
- **Lekkie środowisko uruchomieniowe domyślnie** — typowe workflow CLI i statusu działają w kopercie pamięci kilku megabajtów na buildach release.
|
||||
- **Ekonomiczne wdrożenie** — zaprojektowane dla płytek za $10 i małych instancji chmurowych, bez ciężkich zależności runtime.
|
||||
- **Szybki zimny start** — jednoplikowe środowisko Rust utrzymuje start komend i demona niemal natychmiastowy.
|
||||
- **Przenośna architektura** — jeden plik binarny na ARM, x86 i RISC-V z wymiennymi dostawcami/kanałami/narzędziami.
|
||||
- **Gateway lokalny** — pojedyncza warstwa sterowania dla sesji, kanałów, narzędzi, cron, SOP i zdarzeń.
|
||||
- **Wielokanałowa skrzynka odbiorcza** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket i więcej.
|
||||
- **Orkiestracja wielu agentów (Hands)** — autonomiczne roje agentów, które działają według harmonogramu i stają się inteligentniejsze z czasem.
|
||||
- **Standardowe Procedury Operacyjne (SOP)** — automatyzacja workflow sterowana zdarzeniami z wyzwalaczami MQTT, webhook, cron i peryferiami.
|
||||
- **Panel webowy** — interfejs React 19 + Vite z czatem w czasie rzeczywistym, przeglądarką pamięci, edytorem konfiguracji, menedżerem cron i inspektorem narzędzi.
|
||||
- **Peryferia sprzętowe** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO przez trait `Peripheral`.
|
||||
- **Narzędzia pierwszej klasy** — shell, plik I/O, przeglądarka, git, web fetch/search, MCP, Jira, Notion, Google Workspace i 70+ więcej.
|
||||
- **Hooki cyklu życia** — przechwytuj i modyfikuj wywołania LLM, wykonania narzędzi i wiadomości na każdym etapie.
|
||||
- **Platforma umiejętności** — wbudowane, społecznościowe i workspace skills z audytem bezpieczeństwa.
|
||||
- **Obsługa tuneli** — Cloudflare, Tailscale, ngrok, OpenVPN i niestandardowe tunele do zdalnego dostępu.
|
||||
|
||||
### Dlaczego zespoły wybierają ZeroClaw
|
||||
|
||||
- **Lekki domyślnie:** mały plik binarny Rust, szybki start, niskie zużycie pamięci.
|
||||
- **Bezpieczny z założenia:** parowanie, ścisły sandboxing, jawne listy dozwolonych, izolacja workspace.
|
||||
- **W pełni wymienny:** podstawowe systemy to traity (dostawcy, kanały, narzędzia, pamięć, tunele).
|
||||
- **Brak vendor lock-in:** obsługa dostawców kompatybilnych z OpenAI + podłączalne niestandardowe endpointy.
|
||||
|
||||
## Porównanie wydajności (ZeroClaw vs OpenClaw, odtwarzalne)
|
||||
|
||||
Szybki benchmark na maszynie lokalnej (macOS arm64, luty 2026) znormalizowany dla sprzętu edge 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Język** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Start (rdzeń 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Rozmiar binarki** | ~28MB (dist) | N/A (Skrypty) | ~8MB | **~8.8 MB** |
|
||||
| **Koszt** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Dowolny sprzęt $10** |
|
||||
|
||||
> Uwagi: Wyniki ZeroClaw są mierzone na buildach release przy użyciu `/usr/bin/time -l`. OpenClaw wymaga środowiska Node.js (typowo ~390MB dodatkowego narzutu pamięci), natomiast NanoBot wymaga środowiska Python. PicoClaw i ZeroClaw to statyczne pliki binarne. Powyższe wartości RAM dotyczą pamięci runtime; wymagania kompilacji są wyższe.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Odtwarzalny pomiar lokalny
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Wszystko, co do tej pory zbudowaliśmy
|
||||
|
||||
### Platforma podstawowa
|
||||
|
||||
- Gateway HTTP/WS/SSE warstwa sterowania z sesjami, obecnością, konfiguracją, cron, webhookami, panelem webowym i parowaniem.
|
||||
- Interfejs CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Pętla orkiestracji agenta z dispatchem narzędzi, konstrukcją promptów, klasyfikacją wiadomości i ładowaniem pamięci.
|
||||
- Model sesji z egzekwowaniem polityki bezpieczeństwa, poziomami autonomii i bramkowaniem zatwierdzeń.
|
||||
- Odporny wrapper dostawcy z failoverem, ponawianiem i routingiem modeli na 20+ backendach LLM.
|
||||
|
||||
### Kanały
|
||||
|
||||
Kanały: WhatsApp (natywny), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Za bramkami feature: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Panel webowy
|
||||
|
||||
Panel webowy React 19 + Vite 6 + Tailwind CSS 4 serwowany bezpośrednio z Gateway:
|
||||
|
||||
- **Dashboard** — przegląd systemu, status zdrowia, uptime, śledzenie kosztów
|
||||
- **Czat z agentem** — interaktywny czat z agentem
|
||||
- **Pamięć** — przeglądanie i zarządzanie wpisami pamięci
|
||||
- **Konfiguracja** — podgląd i edycja konfiguracji
|
||||
- **Cron** — zarządzanie zaplanowanymi zadaniami
|
||||
- **Narzędzia** — przeglądanie dostępnych narzędzi
|
||||
- **Logi** — podgląd logów aktywności agenta
|
||||
- **Koszty** — użycie tokenów i śledzenie kosztów
|
||||
- **Doctor** — diagnostyka zdrowia systemu
|
||||
- **Integracje** — status i konfiguracja integracji
|
||||
- **Parowanie** — zarządzanie parowaniem urządzeń
|
||||
|
||||
### Cele firmware
|
||||
|
||||
| Cel | Platforma | Przeznaczenie |
|
||||
|-----|-----------|---------------|
|
||||
| ESP32 | Espressif ESP32 | Bezprzewodowy agent peryferyjny |
|
||||
| ESP32-UI | ESP32 + Wyświetlacz | Agent z interfejsem wizualnym |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Peryferia przemysłowe |
|
||||
| Arduino | Arduino | Podstawowy mostek czujników/aktuatorów |
|
||||
| Uno Q Bridge | Arduino Uno | Mostek szeregowy do agenta |
|
||||
|
||||
### Narzędzia + automatyzacja
|
||||
|
||||
- **Podstawowe:** shell, odczyt/zapis/edycja plików, operacje git, wyszukiwanie glob, wyszukiwanie treści
|
||||
- **Web:** sterowanie przeglądarką, web fetch, wyszukiwanie web, zrzut ekranu, info o obrazie, odczyt PDF
|
||||
- **Integracje:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** wrapper narzędzi Model Context Protocol + odroczone zestawy narzędzi
|
||||
- **Planowanie:** cron add/remove/update/run, narzędzie planowania
|
||||
- **Pamięć:** recall, store, forget, knowledge, project intel
|
||||
- **Zaawansowane:** delegate (agent-to-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Sprzęt:** board info, memory map, memory read (za bramką feature)
|
||||
|
||||
### Środowisko uruchomieniowe + bezpieczeństwo
|
||||
|
||||
- **Poziomy autonomii:** ReadOnly, Supervised (domyślny), Full.
|
||||
- **Sandboxing:** izolacja workspace, blokowanie przechodzenia ścieżek, listy dozwolonych poleceń, zabronione ścieżki, Landlock (Linux), Bubblewrap.
|
||||
- **Ograniczenie szybkości:** maks. akcji na godzinę, maks. koszt na dzień (konfigurowalne).
|
||||
- **Bramkowanie zatwierdzeń:** interaktywne zatwierdzanie operacji średniego/wysokiego ryzyka.
|
||||
- **E-stop:** możliwość awaryjnego wyłączenia.
|
||||
- **129+ testów bezpieczeństwa** w automatycznym CI.
|
||||
|
||||
### Operacje + pakowanie
|
||||
|
||||
- Panel webowy serwowany bezpośrednio z Gateway.
|
||||
- Obsługa tuneli: Cloudflare, Tailscale, ngrok, OpenVPN, niestandardowe polecenie.
|
||||
- Adapter runtime Docker do konteneryzowanego wykonywania.
|
||||
- CI/CD: beta (auto na push) → stable (ręczny dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Gotowe pliki binarne dla Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfiguracja
|
||||
|
||||
Minimalna `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Pełna dokumentacja konfiguracji: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Konfiguracja kanałów
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Konfiguracja tunelu
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # lub "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Szczegóły: [Dokumentacja kanałów](docs/reference/api/channels-reference.md) · [Dokumentacja konfiguracji](docs/reference/api/config-reference.md)
|
||||
|
||||
### Obsługa runtime (aktualnie)
|
||||
|
||||
- **`native`** (domyślny) — bezpośrednie wykonywanie procesów, najszybsza ścieżka, idealne dla zaufanych środowisk.
|
||||
- **`docker`** — pełna izolacja kontenerowa, wymuszone polityki bezpieczeństwa, wymaga Docker.
|
||||
|
||||
Ustaw `runtime.kind = "docker"` dla ścisłego sandboxingu lub izolacji sieciowej.
|
||||
|
||||
## Uwierzytelnianie subskrypcyjne (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw obsługuje natywne profile autoryzacyjne subskrypcji (wiele kont, szyfrowanie w spoczynku).
|
||||
|
||||
- Plik przechowywania: `~/.zeroclaw/auth-profiles.json`
|
||||
- Klucz szyfrowania: `~/.zeroclaw/.secret_key`
|
||||
- Format ID profilu: `<provider>:<profile_name>` (przykład: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (subskrypcja ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Sprawdź / odśwież / przełącz profil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Uruchom agenta z autoryzacją subskrypcji
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace agenta + umiejętności
|
||||
|
||||
Katalog główny workspace: `~/.zeroclaw/workspace/` (konfigurowalne przez config).
|
||||
|
||||
Wstrzykiwane pliki promptów:
|
||||
- `IDENTITY.md` — osobowość i rola agenta
|
||||
- `USER.md` — kontekst i preferencje użytkownika
|
||||
- `MEMORY.md` — długoterminowe fakty i lekcje
|
||||
- `AGENTS.md` — konwencje sesji i reguły inicjalizacji
|
||||
- `SOUL.md` — podstawowa tożsamość i zasady działania
|
||||
|
||||
Umiejętności: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` lub `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Lista zainstalowanych umiejętności
|
||||
zeroclaw skills list
|
||||
|
||||
# Instalacja z git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Audyt bezpieczeństwa przed instalacją
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Usuń umiejętność
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Komendy CLI
|
||||
|
||||
```bash
|
||||
# Zarządzanie workspace
|
||||
zeroclaw onboard # Kreator konfiguracji z przewodnikiem
|
||||
zeroclaw status # Pokaż status demona/agenta
|
||||
zeroclaw doctor # Uruchom diagnostykę systemu
|
||||
|
||||
# Gateway + demon
|
||||
zeroclaw gateway # Uruchom serwer gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Uruchom pełne autonomiczne środowisko
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Tryb interaktywnego czatu
|
||||
zeroclaw agent -m "message" # Tryb pojedynczej wiadomości
|
||||
|
||||
# Zarządzanie usługami
|
||||
zeroclaw service install # Zainstaluj jako usługę OS (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanały
|
||||
zeroclaw channel list # Lista skonfigurowanych kanałów
|
||||
zeroclaw channel doctor # Sprawdź zdrowie kanałów
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + planowanie
|
||||
zeroclaw cron list # Lista zaplanowanych zadań
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Pamięć
|
||||
zeroclaw memory list # Lista wpisów pamięci
|
||||
zeroclaw memory get <key> # Pobierz wspomnienie
|
||||
zeroclaw memory stats # Statystyki pamięci
|
||||
|
||||
# Profile autoryzacyjne
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Peryferia sprzętowe
|
||||
zeroclaw hardware discover # Skanuj podłączone urządzenia
|
||||
zeroclaw peripheral list # Lista podłączonych peryferiów
|
||||
zeroclaw peripheral flash # Flash firmware na urządzenie
|
||||
|
||||
# Migracja
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Uzupełnianie powłoki
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Pełna dokumentacja komend: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Wymagania wstępne
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Wymagane
|
||||
|
||||
1. **Visual Studio Build Tools** (zapewnia linker MSVC i Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Podczas instalacji (lub przez Visual Studio Installer) wybierz workload **"Desktop development with C++"**.
|
||||
|
||||
2. **Toolchain Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Po instalacji otwórz nowy terminal i uruchom `rustup default stable`, aby upewnić się, że aktywny jest stabilny toolchain.
|
||||
|
||||
3. **Sprawdź**, czy oba działają:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opcjonalne
|
||||
|
||||
- **Docker Desktop** — wymagany tylko przy użyciu [runtime Docker z sandboxem](#obsługa-runtime-aktualnie) (`runtime.kind = "docker"`). Zainstaluj przez `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Wymagane
|
||||
|
||||
1. **Narzędzia budowania:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Zainstaluj Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Toolchain Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Zobacz [rustup.rs](https://rustup.rs) po szczegóły.
|
||||
|
||||
3. **Sprawdź**, czy oba działają:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Instalator jednoliniowy
|
||||
|
||||
Lub pomiń powyższe kroki i zainstaluj wszystko (zależności systemowe, Rust, ZeroClaw) jednym poleceniem:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Wymagania zasobów kompilacji
|
||||
|
||||
Budowanie ze źródła wymaga więcej zasobów niż uruchamianie wynikowego pliku binarnego:
|
||||
|
||||
| Zasób | Minimum | Zalecane |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Wolne miejsce** | 6 GB | 10 GB+ |
|
||||
|
||||
Jeśli Twój host jest poniżej minimum, użyj gotowych plików binarnych:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Aby wymusić instalację wyłącznie z pliku binarnego, bez fallbacku na źródło:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opcjonalne
|
||||
|
||||
- **Docker** — wymagany tylko przy użyciu [runtime Docker z sandboxem](#obsługa-runtime-aktualnie) (`runtime.kind = "docker"`). Zainstaluj przez menedżer pakietów lub [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Uwaga:** Domyślny `cargo build --release` używa `codegen-units=1`, aby obniżyć szczytowe obciążenie kompilacji. Dla szybszych buildów na mocnych maszynach użyj `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Gotowe pliki binarne
|
||||
|
||||
Zasoby wydań są publikowane dla:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Pobierz najnowsze zasoby z:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentacja
|
||||
|
||||
Używaj tych, gdy przeszedłeś już przez onboarding i chcesz głębszej dokumentacji.
|
||||
|
||||
- Zacznij od [indeksu dokumentacji](docs/README.md), aby zobaczyć nawigację i „co gdzie jest."
|
||||
- Przeczytaj [przegląd architektury](docs/architecture.md), aby poznać pełny model systemu.
|
||||
- Użyj [dokumentacji konfiguracji](docs/reference/api/config-reference.md), gdy potrzebujesz każdego klucza i przykładu.
|
||||
- Uruchom Gateway zgodnie z [podręcznikiem operacyjnym](docs/ops/operations-runbook.md).
|
||||
- Postępuj zgodnie z [ZeroClaw Onboard](#szybki-start) dla konfiguracji z przewodnikiem.
|
||||
- Debuguj typowe awarie z [przewodnikiem rozwiązywania problemów](docs/ops/troubleshooting.md).
|
||||
- Przejrzyj [wskazówki bezpieczeństwa](docs/security/README.md) przed wystawieniem czegokolwiek.
|
||||
|
||||
### Dokumentacja referencyjna
|
||||
|
||||
- Centrum dokumentacji: [docs/README.md](docs/README.md)
|
||||
- Ujednolicony spis treści: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Dokumentacja komend: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Dokumentacja konfiguracji: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Dokumentacja dostawców: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Dokumentacja kanałów: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Podręcznik operacyjny: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Rozwiązywanie problemów: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Dokumentacja współpracy
|
||||
|
||||
- Przewodnik kontrybutora: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Polityka workflow PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Przewodnik workflow CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Podręcznik recenzenta: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Polityka ujawniania bezpieczeństwa: [SECURITY.md](SECURITY.md)
|
||||
- Szablon dokumentacji: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Wdrożenie + operacje
|
||||
|
||||
- Przewodnik wdrożenia sieciowego: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Podręcznik agenta proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Przewodniki sprzętowe: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw został zbudowany dla smooth crab 🦀, szybkiego i wydajnego asystenta AI. Stworzony przez Argenisa De La Rosę i społeczność.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Wesprzyj ZeroClaw
|
||||
|
||||
Jeśli ZeroClaw pomaga w Twojej pracy i chcesz wesprzeć dalszy rozwój, możesz przekazać darowiznę tutaj:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Specjalne podziękowania
|
||||
|
||||
Serdeczne podziękowania dla społeczności i instytucji, które inspirują i napędzają tę pracę open-source:
|
||||
|
||||
- **Harvard University** — za wspieranie ciekawości intelektualnej i przesuwanie granic tego, co możliwe.
|
||||
- **MIT** — za promowanie otwartej wiedzy, open source i przekonania, że technologia powinna być dostępna dla wszystkich.
|
||||
- **Sundai Club** — za społeczność, energię i nieustanny zapał do budowania rzeczy, które mają znaczenie.
|
||||
- **Świat i dalej** 🌍✨ — dla każdego kontrybutora, marzyciela i twórcy, który sprawia, że open source jest siłą dobra. To dla Ciebie.
|
||||
|
||||
Budujemy w otwartości, ponieważ najlepsze pomysły pochodzą zewsząd. Jeśli to czytasz, jesteś tego częścią. Witaj. 🦀❤️
|
||||
|
||||
## Współtworzenie
|
||||
|
||||
Nowy w ZeroClaw? Szukaj issues oznaczonych [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — zobacz nasz [Przewodnik kontrybutora](CONTRIBUTING.md#first-time-contributors), aby dowiedzieć się jak zacząć. PR-y z AI/vibe-coded mile widziane! 🤖
|
||||
|
||||
Zobacz [CONTRIBUTING.md](CONTRIBUTING.md) i [CLA.md](docs/contributing/cla.md). Zaimplementuj trait, wyślij PR:
|
||||
|
||||
- Przewodnik workflow CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Nowy `Provider` → `src/providers/`
|
||||
- Nowy `Channel` → `src/channels/`
|
||||
- Nowy `Observer` → `src/observability/`
|
||||
- Nowy `Tool` → `src/tools/`
|
||||
- Nowy `Memory` → `src/memory/`
|
||||
- Nowy `Tunnel` → `src/tunnel/`
|
||||
- Nowy `Peripheral` → `src/peripherals/`
|
||||
- Nowy `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Oficjalne repozytorium i ostrzeżenie przed podszywaniem się
|
||||
|
||||
**To jest jedyne oficjalne repozytorium ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Każde inne repozytorium, organizacja, domena lub pakiet twierdzący, że jest "ZeroClaw" lub sugerujący powiązanie z ZeroClaw Labs jest **nieautoryzowany i niepowiązany z tym projektem**. Znane nieautoryzowane forki będą wymienione w [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Jeśli napotkasz podszywanie się lub nadużycie znaku towarowego, proszę [otwórz zgłoszenie](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licencja
|
||||
|
||||
ZeroClaw jest podwójnie licencjonowany dla maksymalnej otwartości i ochrony kontrybutorów:
|
||||
|
||||
| Licencja | Przypadek użycia |
|
||||
|----------|------------------|
|
||||
| [MIT](LICENSE-MIT) | Open-source, badania, akademia, użytek osobisty |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Ochrona patentowa, instytucjonalne, wdrożenia komercyjne |
|
||||
|
||||
Możesz wybrać dowolną licencję. **Kontrybutorzy automatycznie udzielają praw na obie** — zobacz [CLA.md](docs/contributing/cla.md) po pełną umowę kontrybutora.
|
||||
|
||||
### Znak towarowy
|
||||
|
||||
Nazwa **ZeroClaw** i logo są znakami towarowymi ZeroClaw Labs. Ta licencja nie udziela pozwolenia na ich używanie w celu sugerowania poparcia lub powiązania. Zobacz [TRADEMARK.md](docs/maintainers/trademark.md) po dozwolone i zabronione użycia.
|
||||
|
||||
### Ochrona kontrybutorów
|
||||
|
||||
- **Zachowujesz prawa autorskie** do swoich wkładów
|
||||
- **Udzielenie patentu** (Apache 2.0) chroni Cię przed roszczeniami patentowymi innych kontrybutorów
|
||||
- Twoje wkłady są **trwale przypisane** w historii commitów i [NOTICE](NOTICE)
|
||||
- Żadne prawa do znaku towarowego nie są przenoszone przez współtworzenie
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Zero narzutu. Zero kompromisów. Wdrażaj wszędzie. Wymieniaj wszystko. 🦀
|
||||
|
||||
## Kontrybutorzy
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Ta lista jest generowana z grafu kontrybutorów GitHub i aktualizuje się automatycznie.
|
||||
|
||||
## Historia gwiazdek
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.pt.md
755
README.pt.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Assistente Pessoal de IA</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Zero overhead. Zero compromisso. 100% Rust. 100% Agnóstico.</strong><br>
|
||||
⚡️ <strong>Roda em hardware de $10 com <5MB de RAM: 99% menos memória que o OpenClaw e 98% mais barato que um Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Construído por estudantes e membros das comunidades de Harvard, MIT e Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Idiomas:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw é um assistente pessoal de IA que você executa nos seus próprios dispositivos. Ele responde nos canais que você já usa (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work e mais). Tem um painel web para controle em tempo real e pode se conectar a periféricos de hardware (ESP32, STM32, Arduino, Raspberry Pi). O Gateway é apenas o plano de controle — o produto é o assistente.
|
||||
|
||||
Se você quer um assistente pessoal, para um único usuário, que seja local, rápido e sempre ativo, é isso.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Site</a> ·
|
||||
<a href="docs/README.md">Documentação</a> ·
|
||||
<a href="docs/architecture.md">Arquitetura</a> ·
|
||||
<a href="#início-rápido">Primeiros passos</a> ·
|
||||
<a href="#migração-do-openclaw">Migração do OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Solução de problemas</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Configuração preferida:** execute `zeroclaw onboard` no seu terminal. O ZeroClaw Onboard guia você passo a passo na configuração do gateway, workspace, canais e provedor. É o caminho de configuração recomendado e funciona no macOS, Linux e Windows (via WSL2). Nova instalação? Comece aqui: [Primeiros passos](#início-rápido)
|
||||
|
||||
### Autenticação por assinatura (OAuth)
|
||||
|
||||
- **OpenAI Codex** (assinatura ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (chave API ou token de autenticação)
|
||||
|
||||
Nota sobre modelos: embora muitos provedores/modelos sejam suportados, para a melhor experiência use o modelo de última geração mais poderoso disponível para você. Veja [Onboarding](#início-rápido).
|
||||
|
||||
Configuração de modelos + CLI: [Referência de provedores](docs/reference/api/providers-reference.md)
|
||||
Rotação de perfis de autenticação (OAuth vs chaves API) + failover: [Failover de modelos](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instalação (recomendada)
|
||||
|
||||
Requisito: toolchain estável do Rust. Um único binário, sem dependências de runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Bootstrap com um clique
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` executa automaticamente após a instalação para configurar seu workspace e provedor.
|
||||
|
||||
## Início rápido (TL;DR)
|
||||
|
||||
Guia completo para iniciantes (autenticação, pareamento, canais): [Primeiros passos](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instalar + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Iniciar o gateway (servidor webhook + painel web)
|
||||
zeroclaw gateway # padrão: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # porta aleatória (segurança reforçada)
|
||||
|
||||
# Falar com o assistente
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Modo interativo
|
||||
zeroclaw agent
|
||||
|
||||
# Iniciar runtime autônomo completo (gateway + canais + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Verificar status
|
||||
zeroclaw status
|
||||
|
||||
# Executar diagnósticos
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Atualizando? Execute `zeroclaw doctor` após atualizar.
|
||||
|
||||
### A partir do código-fonte (desenvolvimento)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Alternativa para desenvolvimento (sem instalação global):** prefixe comandos com `cargo run --release --` (exemplo: `cargo run --release -- status`).
|
||||
|
||||
## Migração do OpenClaw
|
||||
|
||||
O ZeroClaw pode importar seu workspace, memória e configuração do OpenClaw:
|
||||
|
||||
```bash
|
||||
# Pré-visualizar o que será migrado (seguro, somente leitura)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Executar a migração
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Isso migra suas entradas de memória, arquivos do workspace e configuração de `~/.openclaw/` para `~/.zeroclaw/`. A configuração é convertida de JSON para TOML automaticamente.
|
||||
|
||||
## Padrões de segurança (acesso por DM)
|
||||
|
||||
O ZeroClaw conecta-se a superfícies de mensagens reais. Trate DMs recebidas como entrada não confiável.
|
||||
|
||||
Guia completo de segurança: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Comportamento padrão em todos os canais:
|
||||
|
||||
- **Pareamento por DM** (padrão): remetentes desconhecidos recebem um código de pareamento curto e o bot não processa sua mensagem.
|
||||
- Aprovar com: `zeroclaw pairing approve <channel> <code>` (então o remetente é adicionado a uma lista de permitidos local).
|
||||
- DMs públicas recebidas requerem uma ativação explícita em `config.toml`.
|
||||
- Execute `zeroclaw doctor` para detectar políticas de DM arriscadas ou mal configuradas.
|
||||
|
||||
**Níveis de autonomia:**
|
||||
|
||||
| Nível | Comportamento |
|
||||
|-------|---------------|
|
||||
| `ReadOnly` | O agente pode observar mas não agir |
|
||||
| `Supervised` (padrão) | O agente age com aprovação para operações de risco médio/alto |
|
||||
| `Full` | O agente age autonomamente dentro dos limites da política |
|
||||
|
||||
**Camadas de sandboxing:** isolamento do workspace, bloqueio de traversal de caminhos, listas de comandos permitidos, caminhos proibidos (`/etc`, `/root`, `~/.ssh`), limitação de taxa (máximo de ações/hora, limites de custo/dia).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Anúncios
|
||||
|
||||
Use este quadro para avisos importantes (mudanças incompatíveis, avisos de segurança, janelas de manutenção e bloqueadores de lançamento).
|
||||
|
||||
| Data (UTC) | Nível | Aviso | Ação |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Crítico_ | **Não somos afiliados** a `openagen/zeroclaw`, `zeroclaw.org` ou `zeroclaw.net`. Os domínios `zeroclaw.org` e `zeroclaw.net` atualmente apontam para o fork `openagen/zeroclaw`, e esse domínio/repositório estão se passando pelo nosso site/projeto oficial. | Não confie em informações, binários, arrecadações de fundos ou anúncios dessas fontes. Use apenas [este repositório](https://github.com/zeroclaw-labs/zeroclaw) e nossas contas sociais verificadas. |
|
||||
| 2026-02-21 | _Importante_ | Nosso site oficial agora está no ar: [zeroclawlabs.ai](https://zeroclawlabs.ai). Obrigado pela paciência enquanto preparávamos o lançamento. Continuamos vendo tentativas de falsificação, então **não** participe de atividades de investimento ou arrecadação de fundos usando o nome ZeroClaw, a menos que sejam publicadas através dos nossos canais oficiais. | Use [este repositório](https://github.com/zeroclaw-labs/zeroclaw) como a única fonte de verdade. Siga [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupo)](https://www.facebook.com/groups/zeroclawlabs) e [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) para atualizações oficiais. |
|
||||
| 2026-02-19 | _Importante_ | A Anthropic atualizou os termos de Autenticação e Uso de Credenciais em 2026-02-19. Os tokens OAuth do Claude Code (Free, Pro, Max) são destinados exclusivamente ao Claude Code e Claude.ai; usar tokens OAuth do Claude Free/Pro/Max em qualquer outro produto, ferramenta ou serviço (incluindo Agent SDK) não é permitido e pode violar os Termos de Serviço do Consumidor. | Por favor, evite temporariamente as integrações OAuth do Claude Code para prevenir perdas potenciais. Cláusula original: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Destaques
|
||||
|
||||
- **Runtime leve por padrão** — fluxos de trabalho comuns de CLI e status rodam em poucos megabytes de memória em builds release.
|
||||
- **Implantação econômica** — projetado para placas de $10 e instâncias pequenas na nuvem, sem dependências pesadas de runtime.
|
||||
- **Cold start rápido** — runtime Rust com binário único mantém a inicialização de comandos e do daemon quase instantânea.
|
||||
- **Arquitetura portável** — um binário para ARM, x86 e RISC-V com provedores/canais/ferramentas intercambiáveis.
|
||||
- **Gateway local-first** — plano de controle único para sessões, canais, ferramentas, cron, SOPs e eventos.
|
||||
- **Caixa de entrada multicanal** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket e mais.
|
||||
- **Orquestração multi-agente (Hands)** — enxames de agentes autônomos que rodam por agendamento e ficam mais inteligentes com o tempo.
|
||||
- **Procedimentos Operacionais Padrão (SOPs)** — automação de fluxos de trabalho orientada por eventos com MQTT, webhook, cron e gatilhos de periféricos.
|
||||
- **Painel web** — interface web React 19 + Vite com chat em tempo real, navegador de memória, editor de configuração, gerenciador de cron e inspetor de ferramentas.
|
||||
- **Periféricos de hardware** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via trait `Peripheral`.
|
||||
- **Ferramentas de primeira classe** — shell, E/S de arquivos, navegador, git, web fetch/search, MCP, Jira, Notion, Google Workspace e mais de 70 outras.
|
||||
- **Hooks de ciclo de vida** — intercepte e modifique chamadas LLM, execuções de ferramentas e mensagens em cada estágio.
|
||||
- **Plataforma de skills** — skills incluídos, comunitários e do workspace com auditoria de segurança.
|
||||
- **Suporte a túneis** — Cloudflare, Tailscale, ngrok, OpenVPN e túneis personalizados para acesso remoto.
|
||||
|
||||
### Por que equipes escolhem o ZeroClaw
|
||||
|
||||
- **Leve por padrão:** binário Rust pequeno, inicialização rápida, baixo consumo de memória.
|
||||
- **Seguro por design:** pareamento, sandboxing rigoroso, listas de permissão explícitas, escopo do workspace.
|
||||
- **Totalmente intercambiável:** sistemas centrais são traits (provedores, canais, ferramentas, memória, túneis).
|
||||
- **Sem vendor lock-in:** suporte a provedores compatíveis com OpenAI + endpoints personalizados plugáveis.
|
||||
|
||||
## Resumo de benchmarks (ZeroClaw vs OpenClaw, reproduzível)
|
||||
|
||||
Benchmark rápido em máquina local (macOS arm64, fev 2026) normalizado para hardware edge de 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Linguagem** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Inicialização (core 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Tamanho do binário** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Custo** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Qualquer hardware $10** |
|
||||
|
||||
> Notas: Os resultados do ZeroClaw são medidos em builds release usando `/usr/bin/time -l`. O OpenClaw requer o runtime Node.js (tipicamente ~390MB de overhead adicional de memória), enquanto o NanoBot requer o runtime Python. PicoClaw e ZeroClaw são binários estáticos. Os valores de RAM acima são memória em runtime; os requisitos de compilação são maiores.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Medição local reproduzível
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Tudo o que construímos até agora
|
||||
|
||||
### Plataforma central
|
||||
|
||||
- Plano de controle Gateway HTTP/WS/SSE com sessões, presença, configuração, cron, webhooks, painel web e pareamento.
|
||||
- Superfície CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Loop de orquestração do agente com despacho de ferramentas, construção de prompts, classificação de mensagens e carregamento de memória.
|
||||
- Modelo de sessão com aplicação de políticas de segurança, níveis de autonomia e aprovação condicional.
|
||||
- Wrapper de provedor resiliente com failover, retry e roteamento de modelos em mais de 20 backends LLM.
|
||||
|
||||
### Canais
|
||||
|
||||
Canais: WhatsApp (nativo), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Habilitados por feature gate: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Painel web
|
||||
|
||||
Painel web React 19 + Vite 6 + Tailwind CSS 4 servido diretamente pelo Gateway:
|
||||
|
||||
- **Dashboard** — visão geral do sistema, status de saúde, uptime, rastreamento de custos
|
||||
- **Chat do agente** — chat interativo com o agente
|
||||
- **Memória** — navegar e gerenciar entradas de memória
|
||||
- **Configuração** — visualizar e editar configuração
|
||||
- **Cron** — gerenciar tarefas agendadas
|
||||
- **Ferramentas** — navegar ferramentas disponíveis
|
||||
- **Logs** — visualizar logs de atividade do agente
|
||||
- **Custos** — uso de tokens e rastreamento de custos
|
||||
- **Doctor** — diagnósticos de saúde do sistema
|
||||
- **Integrações** — status e configuração de integrações
|
||||
- **Pareamento** — gerenciamento de pareamento de dispositivos
|
||||
|
||||
### Alvos de firmware
|
||||
|
||||
| Alvo | Plataforma | Propósito |
|
||||
|------|------------|-----------|
|
||||
| ESP32 | Espressif ESP32 | Agente periférico sem fio |
|
||||
| ESP32-UI | ESP32 + Display | Agente com interface visual |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periférico industrial |
|
||||
| Arduino | Arduino | Ponte básica de sensores/atuadores |
|
||||
| Uno Q Bridge | Arduino Uno | Ponte serial para o agente |
|
||||
|
||||
### Ferramentas + automação
|
||||
|
||||
- **Core:** shell, leitura/escrita/edição de arquivos, operações git, busca glob, busca de conteúdo
|
||||
- **Web:** controle de navegador, web fetch, web search, captura de tela, informação de imagem, leitura de PDF
|
||||
- **Integrações:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + conjuntos de ferramentas deferidos
|
||||
- **Agendamento:** cron add/remove/update/run, ferramenta de agendamento
|
||||
- **Memória:** recall, store, forget, knowledge, project intel
|
||||
- **Avançado:** delegate (agente para agente), swarm, troca/roteamento de modelos, operações de segurança, operações na nuvem
|
||||
- **Hardware:** board info, memory map, memory read (habilitado por feature gate)
|
||||
|
||||
### Runtime + segurança
|
||||
|
||||
- **Níveis de autonomia:** ReadOnly, Supervised (padrão), Full.
|
||||
- **Sandboxing:** isolamento do workspace, bloqueio de traversal de caminhos, listas de comandos permitidos, caminhos proibidos, Landlock (Linux), Bubblewrap.
|
||||
- **Limitação de taxa:** máximo de ações por hora, máximo de custo por dia (configurável).
|
||||
- **Aprovação condicional:** aprovação interativa para operações de risco médio/alto.
|
||||
- **Parada de emergência:** capacidade de desligamento de emergência.
|
||||
- **129+ testes de segurança** em CI automatizado.
|
||||
|
||||
### Operações + empacotamento
|
||||
|
||||
- Painel web servido diretamente pelo Gateway.
|
||||
- Suporte a túneis: Cloudflare, Tailscale, ngrok, OpenVPN, comando personalizado.
|
||||
- Adaptador de runtime Docker para execução em contêineres.
|
||||
- CI/CD: beta (automático no push) → stable (dispatch manual) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Binários pré-construídos para Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Configuração
|
||||
|
||||
`~/.zeroclaw/config.toml` mínimo:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Referência completa de configuração: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Configuração de canais
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Configuração de túneis
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # ou "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detalhes: [Referência de canais](docs/reference/api/channels-reference.md) · [Referência de configuração](docs/reference/api/config-reference.md)
|
||||
|
||||
### Suporte de runtime (atual)
|
||||
|
||||
- **`native`** (padrão) — execução direta de processos, caminho mais rápido, ideal para ambientes confiáveis.
|
||||
- **`docker`** — isolamento completo em contêineres, políticas de segurança forçadas, requer Docker.
|
||||
|
||||
Defina `runtime.kind = "docker"` para sandboxing rigoroso ou isolamento de rede.
|
||||
|
||||
## Autenticação por assinatura (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
O ZeroClaw suporta perfis de autenticação nativos de assinatura (multi-conta, criptografados em repouso).
|
||||
|
||||
- Arquivo de armazenamento: `~/.zeroclaw/auth-profiles.json`
|
||||
- Chave de criptografia: `~/.zeroclaw/.secret_key`
|
||||
- Formato de id do perfil: `<provider>:<profile_name>` (exemplo: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (assinatura ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Verificar / atualizar / trocar perfil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Executar o agente com autenticação por assinatura
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace do agente + skills
|
||||
|
||||
Raiz do workspace: `~/.zeroclaw/workspace/` (configurável via config).
|
||||
|
||||
Arquivos de prompt injetados:
|
||||
- `IDENTITY.md` — personalidade e papel do agente
|
||||
- `USER.md` — contexto e preferências do usuário
|
||||
- `MEMORY.md` — fatos e lições de longo prazo
|
||||
- `AGENTS.md` — convenções de sessão e regras de inicialização
|
||||
- `SOUL.md` — identidade central e princípios operacionais
|
||||
|
||||
Skills: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` ou `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Listar skills instalados
|
||||
zeroclaw skills list
|
||||
|
||||
# Instalar do git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Auditoria de segurança antes de instalar
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remover um skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Comandos CLI
|
||||
|
||||
```bash
|
||||
# Gerenciamento do workspace
|
||||
zeroclaw onboard # Assistente de configuração guiada
|
||||
zeroclaw status # Mostrar status do daemon/agente
|
||||
zeroclaw doctor # Executar diagnósticos do sistema
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Iniciar servidor gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Iniciar runtime autônomo completo
|
||||
|
||||
# Agente
|
||||
zeroclaw agent # Modo de chat interativo
|
||||
zeroclaw agent -m "message" # Modo de mensagem única
|
||||
|
||||
# Gerenciamento de serviços
|
||||
zeroclaw service install # Instalar como serviço do SO (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Canais
|
||||
zeroclaw channel list # Listar canais configurados
|
||||
zeroclaw channel doctor # Verificar saúde dos canais
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + agendamento
|
||||
zeroclaw cron list # Listar trabalhos agendados
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memória
|
||||
zeroclaw memory list # Listar entradas de memória
|
||||
zeroclaw memory get <key> # Recuperar uma memória
|
||||
zeroclaw memory stats # Estatísticas de memória
|
||||
|
||||
# Perfis de autenticação
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Periféricos de hardware
|
||||
zeroclaw hardware discover # Escanear dispositivos conectados
|
||||
zeroclaw peripheral list # Listar periféricos conectados
|
||||
zeroclaw peripheral flash # Flashear firmware no dispositivo
|
||||
|
||||
# Migração
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Completação de shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Referência completa de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Pré-requisitos
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Obrigatório
|
||||
|
||||
1. **Visual Studio Build Tools** (fornece o linker MSVC e o SDK do Windows):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Durante a instalação (ou pelo Visual Studio Installer), selecione a carga de trabalho **"Desenvolvimento para desktop com C++"**.
|
||||
|
||||
2. **Toolchain do Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Após a instalação, abra um novo terminal e execute `rustup default stable` para garantir que o toolchain estável esteja ativo.
|
||||
|
||||
3. **Verifique** que ambos estão funcionando:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opcional
|
||||
|
||||
- **Docker Desktop** — necessário apenas se usar o [runtime sandbox com Docker](#suporte-de-runtime-atual) (`runtime.kind = "docker"`). Instale via `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Obrigatório
|
||||
|
||||
1. **Ferramentas de compilação essenciais:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Instale o Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Toolchain do Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Veja [rustup.rs](https://rustup.rs) para detalhes.
|
||||
|
||||
3. **Verifique** que ambos estão funcionando:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Instalador em uma linha
|
||||
|
||||
Ou pule os passos acima e instale tudo (dependências do sistema, Rust, ZeroClaw) em um único comando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Requisitos de recursos para compilação
|
||||
|
||||
Compilar a partir do código-fonte precisa de mais recursos do que executar o binário resultante:
|
||||
|
||||
| Recurso | Mínimo | Recomendado |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Disco livre**| 6 GB | 10 GB+ |
|
||||
|
||||
Se seu host está abaixo do mínimo, use binários pré-construídos:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Para exigir instalação somente de binários sem compilação de fallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opcional
|
||||
|
||||
- **Docker** — necessário apenas se usar o [runtime sandbox com Docker](#suporte-de-runtime-atual) (`runtime.kind = "docker"`). Instale via seu gerenciador de pacotes ou [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Nota:** O `cargo build --release` padrão usa `codegen-units=1` para reduzir a pressão máxima de compilação. Para builds mais rápidos em máquinas potentes, use `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Binários pré-construídos
|
||||
|
||||
Os assets de release são publicados para:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Baixe os últimos assets em:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Documentação
|
||||
|
||||
Use estes recursos quando tiver passado pelo fluxo de onboarding e quiser a referência mais aprofundada.
|
||||
|
||||
- Comece com o [índice de docs](docs/README.md) para navegação e "o que está onde."
|
||||
- Leia a [visão geral da arquitetura](docs/architecture.md) para o modelo completo do sistema.
|
||||
- Use a [referência de configuração](docs/reference/api/config-reference.md) quando precisar de cada chave e exemplo.
|
||||
- Execute o Gateway conforme o livro com o [runbook operacional](docs/ops/operations-runbook.md).
|
||||
- Siga o [ZeroClaw Onboard](#início-rápido) para uma configuração guiada.
|
||||
- Depure falhas comuns com o [guia de solução de problemas](docs/ops/troubleshooting.md).
|
||||
- Revise a [orientação de segurança](docs/security/README.md) antes de expor qualquer coisa.
|
||||
|
||||
### Documentação de referência
|
||||
|
||||
- Hub de documentação: [docs/README.md](docs/README.md)
|
||||
- TOC unificado de docs: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Referência de comandos: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Referência de configuração: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Referência de provedores: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Referência de canais: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Runbook operacional: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Solução de problemas: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Documentação de colaboração
|
||||
|
||||
- Guia de contribuição: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Política de fluxo de trabalho de PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Guia de fluxo de trabalho CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Manual do revisor: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Política de divulgação de segurança: [SECURITY.md](SECURITY.md)
|
||||
- Template de documentação: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Implantação + operações
|
||||
|
||||
- Guia de implantação em rede: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Manual de agente proxy: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Guias de hardware: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
O ZeroClaw foi construído para o caranguejo suave 🦀, um assistente de IA rápido e eficiente. Construído por Argenis De La Rosa e a comunidade.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Apoie o ZeroClaw
|
||||
|
||||
Se o ZeroClaw ajuda no seu trabalho e você quer apoiar o desenvolvimento contínuo, pode doar aqui:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Agradecimentos especiais
|
||||
|
||||
Um sincero agradecimento às comunidades e instituições que inspiram e impulsionam este trabalho de código aberto:
|
||||
|
||||
- **Harvard University** — por fomentar a curiosidade intelectual e empurrar os limites do possível.
|
||||
- **MIT** — por defender o conhecimento aberto, o código aberto e a crença de que a tecnologia deve ser acessível a todos.
|
||||
- **Sundai Club** — pela comunidade, a energia e o impulso incansável de construir coisas que importam.
|
||||
- **O Mundo e Além** 🌍✨ — a cada contribuidor, sonhador e construtor que faz do código aberto uma força para o bem. Isto é para você.
|
||||
|
||||
Estamos construindo abertamente porque as melhores ideias vêm de todos os lugares. Se você está lendo isto, faz parte disso. Bem-vindo. 🦀❤️
|
||||
|
||||
## Contribuir
|
||||
|
||||
Novo no ZeroClaw? Procure issues rotulados como [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — veja nosso [Guia de contribuição](CONTRIBUTING.md#first-time-contributors) para saber como começar. PRs com IA/vibe-coded são bem-vindos! 🤖
|
||||
|
||||
Veja [CONTRIBUTING.md](CONTRIBUTING.md) e [CLA.md](docs/contributing/cla.md). Implemente um trait, envie um PR:
|
||||
|
||||
- Guia de fluxo de trabalho CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Novo `Provider` → `src/providers/`
|
||||
- Novo `Channel` → `src/channels/`
|
||||
- Novo `Observer` → `src/observability/`
|
||||
- Novo `Tool` → `src/tools/`
|
||||
- Novo `Memory` → `src/memory/`
|
||||
- Novo `Tunnel` → `src/tunnel/`
|
||||
- Novo `Peripheral` → `src/peripherals/`
|
||||
- Novo `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Repositório oficial e aviso de falsificação
|
||||
|
||||
**Este é o único repositório oficial do ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Qualquer outro repositório, organização, domínio ou pacote que afirme ser "ZeroClaw" ou implique afiliação com ZeroClaw Labs **não é autorizado e não é afiliado a este projeto**. Forks não autorizados conhecidos serão listados em [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Se encontrar falsificação ou uso indevido de marca, por favor [abra um issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licença
|
||||
|
||||
O ZeroClaw tem licença dupla para máxima abertura e proteção dos contribuidores:
|
||||
|
||||
| Licença | Caso de uso |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Código aberto, pesquisa, acadêmico, uso pessoal |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Proteção de patentes, institucional, implantação comercial |
|
||||
|
||||
Você pode escolher qualquer uma das licenças. **Os contribuidores automaticamente concedem direitos sob ambas** — veja [CLA.md](docs/contributing/cla.md) para o acordo completo de contribuidores.
|
||||
|
||||
### Marca registrada
|
||||
|
||||
O nome e logo do **ZeroClaw** são marcas registradas da ZeroClaw Labs. Esta licença não concede permissão para usá-los para implicar endosso ou afiliação. Veja [TRADEMARK.md](docs/maintainers/trademark.md) para usos permitidos e proibidos.
|
||||
|
||||
### Proteções para contribuidores
|
||||
|
||||
- Você **mantém o copyright** das suas contribuições
|
||||
- **Concessão de patentes** (Apache 2.0) protege você de reclamações de patentes de outros contribuidores
|
||||
- Suas contribuições são **permanentemente atribuídas** no histórico de commits e [NOTICE](NOTICE)
|
||||
- Nenhum direito de marca registrada é transferido ao contribuir
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Zero overhead. Zero compromisso. Implante em qualquer lugar. Troque qualquer coisa. 🦀
|
||||
|
||||
## Contribuidores
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Esta lista é gerada a partir do gráfico de contribuidores do GitHub e é atualizada automaticamente.
|
||||
|
||||
## Histórico de estrelas
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
755
README.ro.md
755
README.ro.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Asistent AI Personal</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Zero overhead. Zero compromisuri. 100% Rust. 100% Agnostic.</strong><br>
|
||||
⚡️ <strong>Rulează pe hardware de $10 cu <5MB RAM: Cu 99% mai puțină memorie decât OpenClaw și cu 98% mai ieftin decât un Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Construit de studenți și membri ai comunităților Harvard, MIT și Sundai.Club.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Limbi:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw este un asistent AI personal pe care îl rulezi pe propriile dispozitive. Îți răspunde pe canalele pe care le folosești deja (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work și altele). Are un panou web pentru control în timp real și se poate conecta la periferice hardware (ESP32, STM32, Arduino, Raspberry Pi). Gateway-ul este doar planul de control — produsul este asistentul.
|
||||
|
||||
Dacă vrei un asistent personal, pentru un singur utilizator, care se simte local, rapid și mereu activ, acesta este.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Site web</a> ·
|
||||
<a href="docs/README.md">Documentație</a> ·
|
||||
<a href="docs/architecture.md">Arhitectură</a> ·
|
||||
<a href="#pornire-rapidă">Începe</a> ·
|
||||
<a href="#migrarea-de-la-openclaw">Migrare de la OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Depanare</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Configurare recomandată:** rulează `zeroclaw onboard` în terminalul tău. ZeroClaw Onboard te ghidează pas cu pas prin configurarea gateway-ului, workspace-ului, canalelor și provider-ului. Este calea de configurare recomandată și funcționează pe macOS, Linux și Windows (prin WSL2). Instalare nouă? Începe aici: [Începe](#pornire-rapidă)
|
||||
|
||||
### Autentificare prin abonament (OAuth)
|
||||
|
||||
- **OpenAI Codex** (abonament ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (cheie API sau token de autentificare)
|
||||
|
||||
Notă despre modele: deși sunt suportate multe provider-e/modele, pentru cea mai bună experiență folosește cel mai puternic model de ultimă generație disponibil. Vezi [Onboarding](#pornire-rapidă).
|
||||
|
||||
Configurare modele + CLI: [Referință Providers](docs/reference/api/providers-reference.md)
|
||||
Rotație profil de autentificare (OAuth vs chei API) + failover: [Failover model](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Instalare (recomandat)
|
||||
|
||||
Runtime: Rust stable toolchain. Binar unic, fără dependențe de runtime.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Bootstrap cu un clic
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` rulează automat după instalare pentru a configura workspace-ul și provider-ul.
|
||||
|
||||
## Pornire rapidă (TL;DR)
|
||||
|
||||
Ghid complet pentru începători (autentificare, asociere, canale): [Începe](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Instalare + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Pornește gateway-ul (server webhook + panou web)
|
||||
zeroclaw gateway # implicit: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # port aleatoriu (securitate îmbunătățită)
|
||||
|
||||
# Vorbește cu asistentul
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Mod interactiv
|
||||
zeroclaw agent
|
||||
|
||||
# Pornește runtime-ul autonom complet (gateway + canale + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Verifică starea
|
||||
zeroclaw status
|
||||
|
||||
# Rulează diagnostice
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Actualizezi? Rulează `zeroclaw doctor` după actualizare.
|
||||
|
||||
### Din sursă (dezvoltare)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Alternativă dev (fără instalare globală):** prefixează comenzile cu `cargo run --release --` (exemplu: `cargo run --release -- status`).
|
||||
|
||||
## Migrarea de la OpenClaw
|
||||
|
||||
ZeroClaw poate importa workspace-ul, memoria și configurația OpenClaw:
|
||||
|
||||
```bash
|
||||
# Previzualizează ce va fi migrat (sigur, doar citire)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Rulează migrarea
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Aceasta migrează intrările de memorie, fișierele workspace și configurația din `~/.openclaw/` în `~/.zeroclaw/`. Configurația este convertită automat din JSON în TOML.
|
||||
|
||||
## Setări implicite de securitate (acces DM)
|
||||
|
||||
ZeroClaw se conectează la suprafețe de mesagerie reale. Tratează DM-urile primite ca intrare neîncredere.
|
||||
|
||||
Ghid complet de securitate: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Comportament implicit pe toate canalele:
|
||||
|
||||
- **Asociere DM** (implicit): expeditorii necunoscuți primesc un cod scurt de asociere și bot-ul nu procesează mesajul lor.
|
||||
- Aprobă cu: `zeroclaw pairing approve <channel> <code>` (apoi expeditorul este adăugat pe o listă de permisiuni locală).
|
||||
- DM-urile publice primite necesită un opt-in explicit în `config.toml`.
|
||||
- Rulează `zeroclaw doctor` pentru a identifica politici DM riscante sau configurate greșit.
|
||||
|
||||
**Niveluri de autonomie:**
|
||||
|
||||
| Nivel | Comportament |
|
||||
|-------|----------|
|
||||
| `ReadOnly` | Agentul poate observa dar nu poate acționa |
|
||||
| `Supervised` (implicit) | Agentul acționează cu aprobare pentru operațiuni de risc mediu/ridicat |
|
||||
| `Full` | Agentul acționează autonom în limitele politicii |
|
||||
|
||||
**Straturi de sandboxing:** izolarea workspace-ului, blocarea traversării căilor, liste de permisiuni pentru comenzi, căi interzise (`/etc`, `/root`, `~/.ssh`), limitare de rată (acțiuni maxime/oră, limite de cost/zi).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Anunțuri
|
||||
|
||||
Folosește acest panou pentru notificări importante (schimbări care rup compatibilitatea, avize de securitate, ferestre de mentenanță și blocaje de lansare).
|
||||
|
||||
| Data (UTC) | Nivel | Notificare | Acțiune |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Critic_ | Nu suntem **afiliați** cu `openagen/zeroclaw`, `zeroclaw.org` sau `zeroclaw.net`. Domeniile `zeroclaw.org` și `zeroclaw.net` indică în prezent fork-ul `openagen/zeroclaw`, iar acel domeniu/depozit se dă drept site-ul/proiectul nostru oficial. | Nu aveți încredere în informații, binare, strângeri de fonduri sau anunțuri din acele surse. Folosiți doar [acest depozit](https://github.com/zeroclaw-labs/zeroclaw) și conturile noastre sociale verificate. |
|
||||
| 2026-02-21 | _Important_ | Site-ul nostru oficial este acum activ: [zeroclawlabs.ai](https://zeroclawlabs.ai). Mulțumim pentru răbdare în timp ce pregăteam lansarea. Încă observăm tentative de uzurpare a identității, așa că **nu** vă alăturați activităților de investiții sau strângere de fonduri care revendică numele ZeroClaw, decât dacă sunt publicate prin canalele noastre oficiale. | Folosiți [acest depozit](https://github.com/zeroclaw-labs/zeroclaw) ca singura sursă de adevăr. Urmăriți [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) și [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) pentru actualizări oficiale. |
|
||||
| 2026-02-19 | _Important_ | Anthropic a actualizat termenii de Autentificare și Utilizare a Credențialelor pe 2026-02-19. Token-urile OAuth Claude Code (Free, Pro, Max) sunt destinate exclusiv Claude Code și Claude.ai; utilizarea token-urilor OAuth din Claude Free/Pro/Max în orice alt produs, instrument sau serviciu (inclusiv Agent SDK) nu este permisă și poate încălca Termenii Serviciului pentru Consumatori. | Vă rugăm să evitați temporar integrările OAuth Claude Code pentru a preveni pierderi potențiale. Clauza originală: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Puncte forte
|
||||
|
||||
- **Runtime ușor implicit** — fluxurile comune CLI și de stare rulează într-un plic de memorie de câțiva megabytes pe build-urile de lansare.
|
||||
- **Implementare eficientă din punct de vedere al costurilor** — proiectat pentru plăci de $10 și instanțe cloud mici, fără dependențe runtime grele.
|
||||
- **Porniri la rece rapide** — runtime-ul Rust cu binar unic menține pornirea comenzilor și daemon-ului aproape instantanee.
|
||||
- **Arhitectură portabilă** — un singur binar pe ARM, x86 și RISC-V cu provider-e/canale/instrumente interschimbabile.
|
||||
- **Gateway local-first** — plan de control unic pentru sesiuni, canale, instrumente, cron, SOP-uri și evenimente.
|
||||
- **Inbox multi-canal** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket și altele.
|
||||
- **Orchestrare multi-agent (Hands)** — roiuri de agenți autonomi care rulează programat și devin mai inteligenți în timp.
|
||||
- **Proceduri Operaționale Standard (SOP-uri)** — automatizare de fluxuri de lucru bazată pe evenimente cu MQTT, webhook, cron și declanșatoare periferice.
|
||||
- **Panou Web** — UI web React 19 + Vite cu chat în timp real, browser de memorie, editor de configurare, manager cron și inspector de instrumente.
|
||||
- **Periferice hardware** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO prin trait-ul `Peripheral`.
|
||||
- **Instrumente de primă clasă** — shell, file I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace și 70+ altele.
|
||||
- **Hook-uri de ciclu de viață** — interceptează și modifică apelurile LLM, execuțiile de instrumente și mesajele la fiecare etapă.
|
||||
- **Platformă de skill-uri** — skill-uri incluse, comunitare și de workspace cu audit de securitate.
|
||||
- **Suport tunnel** — Cloudflare, Tailscale, ngrok, OpenVPN și tuneluri personalizate pentru acces la distanță.
|
||||
|
||||
### De ce echipele aleg ZeroClaw
|
||||
|
||||
- **Ușor implicit:** binar Rust mic, pornire rapidă, amprentă de memorie redusă.
|
||||
- **Sigur prin design:** asociere, sandboxing strict, liste de permisiuni explicite, limitarea workspace-ului.
|
||||
- **Complet interschimbabil:** sistemele de bază sunt trait-uri (provider-e, canale, instrumente, memorie, tuneluri).
|
||||
- **Fără lock-in:** suport provider compatibil OpenAI + endpoint-uri personalizate conectabile.
|
||||
|
||||
## Instantaneu Benchmark (ZeroClaw vs OpenClaw, Reproductibil)
|
||||
|
||||
Benchmark rapid pe mașină locală (macOS arm64, feb 2026) normalizat pentru hardware edge 0.8GHz.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Limbaj** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Pornire (nucleu 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Dimensiune binar** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Cost** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Orice hardware $10** |
|
||||
|
||||
> Note: Rezultatele ZeroClaw sunt măsurate pe build-uri de lansare folosind `/usr/bin/time -l`. OpenClaw necesită runtime Node.js (de obicei ~390MB overhead suplimentar de memorie), în timp ce NanoBot necesită runtime Python. PicoClaw și ZeroClaw sunt binare statice. Cifrele RAM de mai sus sunt memorie runtime; cerințele de compilare în timpul build-ului sunt mai mari.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
</p>
|
||||
|
||||
### Măsurare locală reproductibilă
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Tot ce am construit până acum
|
||||
|
||||
### Platformă de bază
|
||||
|
||||
- Plan de control HTTP/WS/SSE Gateway cu sesiuni, prezență, configurare, cron, webhook-uri, panou web și asociere.
|
||||
- Suprafață CLI: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Buclă de orchestrare agent cu dispatch de instrumente, construcție de prompt, clasificare de mesaje și încărcare de memorie.
|
||||
- Model de sesiune cu aplicarea politicii de securitate, niveluri de autonomie și aprobare condiționată.
|
||||
- Wrapper provider rezilient cu failover, reîncercare și rutare de modele pe 20+ backend-uri LLM.
|
||||
|
||||
### Canale
|
||||
|
||||
Canale: WhatsApp (nativ), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Feature-gated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Panou web
|
||||
|
||||
Panou web React 19 + Vite 6 + Tailwind CSS 4 servit direct din Gateway:
|
||||
|
||||
- **Dashboard** — prezentare generală a sistemului, stare de sănătate, uptime, urmărire costuri
|
||||
- **Agent Chat** — chat interactiv cu agentul
|
||||
- **Memory** — navighează și gestionează intrările de memorie
|
||||
- **Config** — vizualizează și editează configurația
|
||||
- **Cron** — gestionează sarcinile programate
|
||||
- **Tools** — navighează instrumentele disponibile
|
||||
- **Logs** — vizualizează jurnalele de activitate ale agentului
|
||||
- **Cost** — utilizarea token-urilor și urmărirea costurilor
|
||||
- **Doctor** — diagnostice de sănătate a sistemului
|
||||
- **Integrations** — starea integrărilor și configurare
|
||||
- **Pairing** — gestionarea asocierii dispozitivelor
|
||||
|
||||
### Ținte firmware
|
||||
|
||||
| Țintă | Platformă | Scop |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | Agent periferic wireless |
|
||||
| ESP32-UI | ESP32 + Display | Agent cu interfață vizuală |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Periferic industrial |
|
||||
| Arduino | Arduino | Punte senzor/actuator de bază |
|
||||
| Uno Q Bridge | Arduino Uno | Punte serială către agent |
|
||||
|
||||
### Instrumente + automatizare
|
||||
|
||||
- **De bază:** shell, file read/write/edit, operații git, glob search, content search
|
||||
- **Web:** browser control, web fetch, web search, screenshot, image info, PDF read
|
||||
- **Integrări:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol tool wrapper + deferred tool sets
|
||||
- **Programare:** cron add/remove/update/run, schedule tool
|
||||
- **Memorie:** recall, store, forget, knowledge, project intel
|
||||
- **Avansat:** delegate (agent-la-agent), swarm, model switch/routing, security ops, cloud ops
|
||||
- **Hardware:** board info, memory map, memory read (feature-gated)
|
||||
|
||||
### Runtime + siguranță
|
||||
|
||||
- **Niveluri de autonomie:** ReadOnly, Supervised (implicit), Full.
|
||||
- **Sandboxing:** izolarea workspace-ului, blocarea traversării căilor, liste de permisiuni pentru comenzi, căi interzise, Landlock (Linux), Bubblewrap.
|
||||
- **Limitare de rată:** acțiuni maxime pe oră, cost maxim pe zi (configurabil).
|
||||
- **Aprobare condiționată:** aprobare interactivă pentru operațiuni de risc mediu/ridicat.
|
||||
- **E-stop:** capacitate de oprire de urgență.
|
||||
- **129+ teste de securitate** în CI automatizat.
|
||||
|
||||
### Ops + împachetare
|
||||
|
||||
- Panou web servit direct din Gateway.
|
||||
- Suport tunnel: Cloudflare, Tailscale, ngrok, OpenVPN, comandă personalizată.
|
||||
- Adaptor runtime Docker pentru execuție containerizată.
|
||||
- CI/CD: beta (automat la push) → stable (dispatch manual) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Binare pre-construite pentru Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Configurare
|
||||
|
||||
Minimal `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Referință completă de configurare: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Configurare canale
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Configurare tunnel
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # sau "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detalii: [Referință canale](docs/reference/api/channels-reference.md) · [Referință configurare](docs/reference/api/config-reference.md)
|
||||
|
||||
### Suport runtime (curent)
|
||||
|
||||
- **`native`** (implicit) — execuție directă a procesului, cea mai rapidă cale, ideală pentru medii de încredere.
|
||||
- **`docker`** — izolare completă în container, politici de securitate aplicate, necesită Docker.
|
||||
|
||||
Setează `runtime.kind = "docker"` pentru sandboxing strict sau izolare de rețea.
|
||||
|
||||
## Autentificare prin abonament (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw suportă profiluri de autentificare native abonament (multi-cont, criptate în repaus).
|
||||
|
||||
- Fișier de stocare: `~/.zeroclaw/auth-profiles.json`
|
||||
- Cheie de criptare: `~/.zeroclaw/.secret_key`
|
||||
- Format id profil: `<provider>:<profile_name>` (exemplu: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (abonament ChatGPT)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Verifică / reîmprospătează / schimbă profilul
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Rulează agentul cu autentificare prin abonament
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Workspace agent + skill-uri
|
||||
|
||||
Rădăcina workspace: `~/.zeroclaw/workspace/` (configurabilă prin config).
|
||||
|
||||
Fișiere prompt injectate:
|
||||
- `IDENTITY.md` — personalitatea și rolul agentului
|
||||
- `USER.md` — contextul și preferințele utilizatorului
|
||||
- `MEMORY.md` — fapte și lecții pe termen lung
|
||||
- `AGENTS.md` — convenții de sesiune și reguli de inițializare
|
||||
- `SOUL.md` — identitate de bază și principii operaționale
|
||||
|
||||
Skill-uri: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` sau `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Listează skill-urile instalate
|
||||
zeroclaw skills list
|
||||
|
||||
# Instalează din git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Audit de securitate înainte de instalare
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Elimină un skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Comenzi CLI
|
||||
|
||||
```bash
|
||||
# Gestionarea workspace-ului
|
||||
zeroclaw onboard # Asistent de configurare ghidată
|
||||
zeroclaw status # Afișează starea daemon/agent
|
||||
zeroclaw doctor # Rulează diagnostice de sistem
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Pornește serverul gateway (127.0.0.1:42617)
|
||||
zeroclaw daemon # Pornește runtime-ul autonom complet
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Mod chat interactiv
|
||||
zeroclaw agent -m "message" # Mod mesaj unic
|
||||
|
||||
# Gestionarea serviciilor
|
||||
zeroclaw service install # Instalează ca serviciu OS (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Canale
|
||||
zeroclaw channel list # Listează canalele configurate
|
||||
zeroclaw channel doctor # Verifică sănătatea canalelor
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + programare
|
||||
zeroclaw cron list # Listează sarcinile programate
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memorie
|
||||
zeroclaw memory list # Listează intrările de memorie
|
||||
zeroclaw memory get <key> # Recuperează o memorie
|
||||
zeroclaw memory stats # Statistici memorie
|
||||
|
||||
# Profiluri de autentificare
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Periferice hardware
|
||||
zeroclaw hardware discover # Scanează dispozitivele conectate
|
||||
zeroclaw peripheral list # Listează perifericele conectate
|
||||
zeroclaw peripheral flash # Încarcă firmware pe dispozitiv
|
||||
|
||||
# Migrare
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Completări shell
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Referință completă comenzi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Cerințe preliminare
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Necesare
|
||||
|
||||
1. **Visual Studio Build Tools** (furnizează linker-ul MSVC și Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
În timpul instalării (sau prin Visual Studio Installer), selectează sarcina de lucru **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
După instalare, deschide un terminal nou și rulează `rustup default stable` pentru a te asigura că toolchain-ul stabil este activ.
|
||||
|
||||
3. **Verifică** că ambele funcționează:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Opțional
|
||||
|
||||
- **Docker Desktop** — necesar doar dacă folosești [runtime-ul Docker sandboxed](#suport-runtime-curent) (`runtime.kind = "docker"`). Instalează prin `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Necesare
|
||||
|
||||
1. **Build essentials:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Instalează Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Vezi [rustup.rs](https://rustup.rs) pentru detalii.
|
||||
|
||||
3. **Verifică** că ambele funcționează:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Instalator cu o singură linie
|
||||
|
||||
Sau sări peste pașii de mai sus și instalează totul (dependențe sistem, Rust, ZeroClaw) cu o singură comandă:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Cerințe de resurse pentru compilare
|
||||
|
||||
Construirea din sursă necesită mai multe resurse decât rularea binarului rezultat:
|
||||
|
||||
| Resursă | Minimum | Recomandat |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Disc liber** | 6 GB | 10 GB+ |
|
||||
|
||||
Dacă gazda ta este sub minimum, folosește binare pre-construite:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Pentru a impune instalare doar cu binar, fără fallback sursă:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Opțional
|
||||
|
||||
- **Docker** — necesar doar dacă folosești [runtime-ul Docker sandboxed](#suport-runtime-curent) (`runtime.kind = "docker"`). Instalează prin managerul de pachete sau [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Notă:** `cargo build --release` implicit folosește `codegen-units=1` pentru a reduce presiunea maximă de compilare. Pentru build-uri mai rapide pe mașini puternice, folosește `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Binare pre-construite
|
||||
|
||||
Resursele de lansare sunt publicate pentru:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Descarcă cele mai recente resurse de la:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Documentație
|
||||
|
||||
Folosește-le când ai trecut de fluxul de onboarding și vrei referința mai detaliată.
|
||||
|
||||
- Începe cu [indexul documentației](docs/README.md) pentru navigare și „ce este unde."
|
||||
- Citește [prezentarea arhitecturii](docs/architecture.md) pentru modelul complet al sistemului.
|
||||
- Folosește [referința de configurare](docs/reference/api/config-reference.md) când ai nevoie de fiecare cheie și exemplu.
|
||||
- Rulează Gateway-ul conform [runbook-ului operațional](docs/ops/operations-runbook.md).
|
||||
- Urmează [ZeroClaw Onboard](#pornire-rapidă) pentru configurare ghidată.
|
||||
- Depanează eșecurile comune cu [ghidul de depanare](docs/ops/troubleshooting.md).
|
||||
- Revizuiește [ghidul de securitate](docs/security/README.md) înainte de a expune ceva.
|
||||
|
||||
### Documentație de referință
|
||||
|
||||
- Hub documentație: [docs/README.md](docs/README.md)
|
||||
- TOC documentație unificată: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Referință comenzi: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Referință configurare: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Referință providers: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Referință canale: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Runbook operațional: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Depanare: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Documentație de colaborare
|
||||
|
||||
- Ghid de contribuție: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Politica fluxului de lucru PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Ghid flux de lucru CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Playbook recenzent: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Politica de divulgare a securității: [SECURITY.md](SECURITY.md)
|
||||
- Șablon documentație: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Implementare + operațiuni
|
||||
|
||||
- Ghid de implementare în rețea: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Playbook proxy agent: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Ghiduri hardware: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw a fost construit pentru smooth crab 🦀, un asistent AI rapid și eficient. Construit de Argenis De La Rosa și comunitate.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Susține ZeroClaw
|
||||
|
||||
Dacă ZeroClaw te ajută în muncă și vrei să susții dezvoltarea continuă, poți dona aici:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Mulțumiri Speciale
|
||||
|
||||
Mulțumiri sincere comunităților și instituțiilor care inspiră și alimentează această muncă open-source:
|
||||
|
||||
- **Harvard University** — pentru cultivarea curiozității intelectuale și extinderea limitelor posibilului.
|
||||
- **MIT** — pentru promovarea cunoștințelor deschise, open source și credința că tehnologia ar trebui să fie accesibilă tuturor.
|
||||
- **Sundai Club** — pentru comunitate, energie și dorința neîncetată de a construi lucruri care contează.
|
||||
- **Lumea și Dincolo** 🌍✨ — fiecărui contributor, visător și constructor care face din open source o forță a binelui. Aceasta este pentru voi.
|
||||
|
||||
Construim deschis pentru că cele mai bune idei vin de peste tot. Dacă citești asta, faci parte din asta. Bine ai venit. 🦀❤️
|
||||
|
||||
## Contribuție
|
||||
|
||||
Nou la ZeroClaw? Caută probleme etichetate [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — vezi [Ghidul de Contribuție](CONTRIBUTING.md#first-time-contributors) pentru cum să începi. PR-urile create cu AI/vibe-coded sunt binevenite! 🤖
|
||||
|
||||
Vezi [CONTRIBUTING.md](CONTRIBUTING.md) și [CLA.md](docs/contributing/cla.md). Implementează un trait, trimite un PR:
|
||||
|
||||
- Ghid flux de lucru CI: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- `Provider` nou → `src/providers/`
|
||||
- `Channel` nou → `src/channels/`
|
||||
- `Observer` nou → `src/observability/`
|
||||
- `Tool` nou → `src/tools/`
|
||||
- `Memory` nou → `src/memory/`
|
||||
- `Tunnel` nou → `src/tunnel/`
|
||||
- `Peripheral` nou → `src/peripherals/`
|
||||
- `Skill` nou → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Depozit Oficial & Avertisment de Uzurpare
|
||||
|
||||
**Acesta este singurul depozit oficial ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Orice alt depozit, organizație, domeniu sau pachet care pretinde a fi „ZeroClaw" sau implică afiliere cu ZeroClaw Labs este **neautorizat și nu este afiliat cu acest proiect**. Fork-urile neautorizate cunoscute vor fi listate în [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Dacă întâmpini uzurpare de identitate sau utilizare abuzivă a mărcii comerciale, te rugăm [deschide o problemă](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licență
|
||||
|
||||
ZeroClaw este dual-licențiat pentru deschidere maximă și protecția contributorilor:
|
||||
|
||||
| Licență | Caz de utilizare |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Open-source, cercetare, academic, utilizare personală |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Protecție brevete, instituțional, implementare comercială |
|
||||
|
||||
Poți alege oricare licență. **Contributorii acordă automat drepturi sub ambele** — vezi [CLA.md](docs/contributing/cla.md) pentru acordul complet al contributorului.
|
||||
|
||||
### Marcă comercială
|
||||
|
||||
Numele și logo-ul **ZeroClaw** sunt mărci comerciale ale ZeroClaw Labs. Această licență nu acordă permisiunea de a le folosi pentru a implica aprobare sau afiliere. Vezi [TRADEMARK.md](docs/maintainers/trademark.md) pentru utilizări permise și interzise.
|
||||
|
||||
### Protecții pentru contributori
|
||||
|
||||
- **Păstrezi drepturile de autor** ale contribuțiilor tale
|
||||
- **Acordarea de brevete** (Apache 2.0) te protejează de revendicări de brevete ale altor contributori
|
||||
- Contribuțiile tale sunt **atribuite permanent** în istoricul commit-urilor și [NOTICE](NOTICE)
|
||||
- Nu se transferă drepturi de marcă comercială prin contribuție
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Zero overhead. Zero compromisuri. Implementează oriunde. Schimbă orice. 🦀
|
||||
|
||||
## Contributori
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Această listă este generată din graficul contributorilor GitHub și se actualizează automat.
|
||||
|
||||
## Istoricul Stelelor
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
921
README.ru.md
921
README.ru.md
@ -1,250 +1,98 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Персональный ИИ-ассистент</h1>
|
||||
<h1 align="center">ZeroClaw 🦀（Русский）</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Нулевые накладные расходы. Нулевые компромиссы. 100% Rust. 100% Агностик.</strong><br>
|
||||
⚡️ <strong>Работает на оборудовании за $10 с <5МБ ОЗУ: это на 99% меньше памяти, чем OpenClaw, и на 98% дешевле Mac mini!</strong>
|
||||
<strong>Zero overhead. Zero compromise. 100% Rust. 100% Agnostic.</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
|
||||
<a href="https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search"><img src="https://img.shields.io/badge/Xiaohongshu-Official-FF2442?style=flat" alt="Xiaohongshu: Official" /></a>
|
||||
<a href="https://t.me/zeroclawlabs"><img src="https://img.shields.io/badge/Telegram-%40zeroclawlabs-26A5E4?style=flat&logo=telegram&logoColor=white" alt="Telegram: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclaw"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Создано студентами и участниками сообществ Harvard, MIT и Sundai.Club.
|
||||
🌐 Языки: <a href="README.md">English</a> · <a href="README.zh-CN.md">简体中文</a> · <a href="README.ja.md">日本語</a> · <a href="README.ru.md">Русский</a> · <a href="README.fr.md">Français</a> · <a href="README.vi.md">Tiếng Việt</a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Языки:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
<a href="bootstrap.sh">Установка в 1 клик</a> |
|
||||
<a href="docs/getting-started/README.md">Быстрый старт</a> |
|
||||
<a href="docs/README.ru.md">Хаб документации</a> |
|
||||
<a href="docs/SUMMARY.md">TOC docs</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw — это персональный ИИ-ассистент, который вы запускаете на своих устройствах. Он отвечает вам в каналах, которые вы уже используете (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work и другие). У него есть веб-панель для управления в реальном времени, и он может подключаться к аппаратным периферийным устройствам (ESP32, STM32, Arduino, Raspberry Pi). Gateway — это просто панель управления, а продукт — это ассистент.
|
||||
|
||||
Если вам нужен персональный однопользовательский ассистент, который ощущается локальным, быстрым и всегда включённым — это он.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Веб-сайт</a> ·
|
||||
<a href="docs/README.md">Документация</a> ·
|
||||
<a href="docs/architecture.md">Архитектура</a> ·
|
||||
<a href="#быстрый-старт">Начало работы</a> ·
|
||||
<a href="#миграция-с-openclaw">Миграция с OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Устранение неполадок</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
<strong>Быстрые маршруты:</strong>
|
||||
<a href="docs/reference/README.md">Справочники</a> ·
|
||||
<a href="docs/operations/README.md">Операции</a> ·
|
||||
<a href="docs/troubleshooting.md">Диагностика</a> ·
|
||||
<a href="docs/security/README.md">Безопасность</a> ·
|
||||
<a href="docs/hardware/README.md">Аппаратная часть</a> ·
|
||||
<a href="docs/contributing/README.md">Вклад и CI</a>
|
||||
</p>
|
||||
|
||||
> **Рекомендуемая настройка:** выполните `zeroclaw onboard` в терминале. ZeroClaw Onboard пошагово проведёт вас через настройку gateway, рабочего пространства, каналов и провайдера. Это рекомендуемый путь настройки, работающий на macOS, Linux и Windows (через WSL2). Новая установка? Начните здесь: [Начало работы](#быстрый-старт)
|
||||
> Этот файл — выверенный перевод `README.md` с акцентом на точность и читаемость (не дословный перевод).
|
||||
>
|
||||
> Технические идентификаторы (команды, ключи конфигурации, API-пути, имена Trait) сохранены на английском.
|
||||
>
|
||||
> Последняя синхронизация: **2026-02-19**.
|
||||
|
||||
### Аутентификация по подписке (OAuth)
|
||||
## 📢 Доска объявлений
|
||||
|
||||
- **OpenAI Codex** (подписка ChatGPT)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-ключ или токен аутентификации)
|
||||
Публикуйте здесь важные уведомления (breaking changes, security advisories, окна обслуживания и блокеры релиза).
|
||||
|
||||
Примечание о моделях: хотя поддерживается множество провайдеров/моделей, для лучшего опыта используйте самую мощную модель последнего поколения, доступную вам. См. [Онбординг](#быстрый-старт).
|
||||
| Дата (UTC) | Уровень | Объявление | Действие |
|
||||
|---|---|---|---|
|
||||
| 2026-02-19 | _Срочно_ | Мы **не аффилированы** с `openagen/zeroclaw` и `zeroclaw.org`. Домен `zeroclaw.org` сейчас указывает на fork `openagen/zeroclaw`, и этот домен/репозиторий выдают себя за наш официальный сайт и проект. | Не доверяйте информации, бинарникам, сборам средств и «официальным» объявлениям из этих источников. Используйте только [этот репозиторий](https://github.com/zeroclaw-labs/zeroclaw) и наши верифицированные соцсети. |
|
||||
| 2026-02-21 | _Важно_ | Наш официальный сайт уже запущен: [zeroclawlabs.ai](https://zeroclawlabs.ai). Спасибо, что дождались запуска. При этом попытки выдавать себя за ZeroClaw продолжаются, поэтому не участвуйте в инвестициях, сборах средств и похожих активностях, если они не подтверждены через наши официальные каналы. | Ориентируйтесь только на [этот репозиторий](https://github.com/zeroclaw-labs/zeroclaw); также следите за [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Telegram (@zeroclawlabs)](https://t.me/zeroclawlabs), [Facebook (группа)](https://www.facebook.com/groups/zeroclaw), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) и [Xiaohongshu](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search) для официальных обновлений. |
|
||||
| 2026-02-19 | _Важно_ | Anthropic обновил раздел Authentication and Credential Use 2026-02-19. В нем указано, что OAuth authentication (Free/Pro/Max) предназначена только для Claude Code и Claude.ai; использование OAuth-токенов, полученных через Claude Free/Pro/Max, в любых других продуктах, инструментах или сервисах (включая Agent SDK), не допускается и может считаться нарушением Consumer Terms of Service. | Чтобы избежать потерь, временно не используйте Claude Code OAuth-интеграции. Оригинал: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
Конфигурация моделей + CLI: [Справочник провайдеров](docs/reference/api/providers-reference.md)
|
||||
Ротация профилей аутентификации (OAuth vs API-ключи) + переключение при сбое: [Переключение моделей при сбое](docs/reference/api/providers-reference.md)
|
||||
## О проекте
|
||||
|
||||
## Установка (рекомендуется)
|
||||
ZeroClaw — это производительная и расширяемая инфраструктура автономного AI-агента. ZeroClaw — это **операционная система времени выполнения** для агентных рабочих процессов — инфраструктура, абстрагирующая модели, инструменты, память и выполнение, позволяя создавать агентов один раз и запускать где угодно.
|
||||
|
||||
Среда выполнения: стабильный набор инструментов Rust. Один бинарный файл, без зависимостей времени выполнения.
|
||||
- Нативно на Rust, единый бинарник, переносимость между ARM / x86 / RISC-V
|
||||
- Архитектура на Trait (`Provider`, `Channel`, `Tool`, `Memory` и др.)
|
||||
- Безопасные значения по умолчанию: pairing, явные allowlist, sandbox и scope-ограничения
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
## Почему выбирают ZeroClaw
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
- **Лёгкий runtime по умолчанию**: Повседневные CLI-операции и `status` обычно укладываются в несколько МБ памяти.
|
||||
- **Оптимизирован для недорогих сред**: Подходит для бюджетных плат и небольших cloud-инстансов без тяжёлой runtime-обвязки.
|
||||
- **Быстрый cold start**: Архитектура одного Rust-бинарника ускоряет запуск основных команд и daemon-режима.
|
||||
- **Портативная модель деплоя**: Единый подход для ARM / x86 / RISC-V и возможность менять providers/channels/tools.
|
||||
|
||||
### Установка в один клик
|
||||
## Снимок бенчмарка (ZeroClaw vs OpenClaw, воспроизводимо)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
Ниже — быстрый локальный сравнительный срез (macOS arm64, февраль 2026), нормализованный под 0.8GHz edge CPU.
|
||||
|
||||
`zeroclaw onboard` запускается автоматически после установки для настройки рабочего пространства и провайдера.
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
|---|---|---|---|---|
|
||||
| **Язык** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Старт (ядро 0.8GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Размер бинарника** | ~28MB (dist) | N/A (скрипты) | ~8MB | **~8.8 MB** |
|
||||
| **Стоимость** | Mac Mini $599 | Linux SBC ~$50 | Linux-плата $10 | **Любое железо за $10** |
|
||||
|
||||
## Быстрый старт (TL;DR)
|
||||
|
||||
Полное руководство для начинающих (аутентификация, сопряжение, каналы): [Начало работы](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Install + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Start the gateway (webhook server + web dashboard)
|
||||
zeroclaw gateway # default: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # random port (security hardened)
|
||||
|
||||
# Talk to the assistant
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interactive mode
|
||||
zeroclaw agent
|
||||
|
||||
# Start full autonomous runtime (gateway + channels + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Check status
|
||||
zeroclaw status
|
||||
|
||||
# Run diagnostics
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Обновляетесь? Выполните `zeroclaw doctor` после обновления.
|
||||
|
||||
### Из исходного кода (для разработки)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Альтернатива для разработки (без глобальной установки):** добавляйте перед командами `cargo run --release --` (пример: `cargo run --release -- status`).
|
||||
|
||||
## Миграция с OpenClaw
|
||||
|
||||
ZeroClaw может импортировать ваше рабочее пространство, память и конфигурацию OpenClaw:
|
||||
|
||||
```bash
|
||||
# Preview what will be migrated (safe, read-only)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Run the migration
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Это переносит ваши записи памяти, файлы рабочего пространства и конфигурацию из `~/.openclaw/` в `~/.zeroclaw/`. Конфигурация автоматически конвертируется из JSON в TOML.
|
||||
|
||||
## Настройки безопасности по умолчанию (доступ через ЛС)
|
||||
|
||||
ZeroClaw подключается к реальным поверхностям обмена сообщениями. Относитесь к входящим ЛС как к ненадёжному вводу.
|
||||
|
||||
Полное руководство по безопасности: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Поведение по умолчанию на всех каналах:
|
||||
|
||||
- **Сопряжение ЛС** (по умолчанию): неизвестные отправители получают короткий код сопряжения, и бот не обрабатывает их сообщение.
|
||||
- Одобрение через: `zeroclaw pairing approve <channel> <code>` (затем отправитель добавляется в локальный список разрешённых).
|
||||
- Публичные входящие ЛС требуют явного включения в `config.toml`.
|
||||
- Выполните `zeroclaw doctor` для выявления рискованных или неправильно настроенных политик ЛС.
|
||||
|
||||
**Уровни автономности:**
|
||||
|
||||
| Уровень | Поведение |
|
||||
|---------|-----------|
|
||||
| `ReadOnly` | Агент может наблюдать, но не действовать |
|
||||
| `Supervised` (по умолчанию) | Агент действует с одобрением для операций среднего/высокого риска |
|
||||
| `Full` | Агент действует автономно в рамках политики |
|
||||
|
||||
**Слои изоляции:** изоляция рабочего пространства, блокировка обхода путей, списки разрешённых команд, запрещённые пути (`/etc`, `/root`, `~/.ssh`), ограничение частоты (макс. действий/час, лимиты стоимости/день).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Объявления
|
||||
|
||||
Используйте эту доску для важных уведомлений (критические изменения, рекомендации по безопасности, окна обслуживания и блокеры релизов).
|
||||
|
||||
| Дата (UTC) | Уровень | Уведомление | Действие |
|
||||
| ---------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Критический_ | Мы **не связаны** с `openagen/zeroclaw`, `zeroclaw.org` или `zeroclaw.net`. Домены `zeroclaw.org` и `zeroclaw.net` в настоящее время указывают на форк `openagen/zeroclaw`, и этот домен/репозиторий выдают себя за наш официальный сайт/проект. | Не доверяйте информации, бинарным файлам, сбору средств или объявлениям из этих источников. Используйте только [этот репозиторий](https://github.com/zeroclaw-labs/zeroclaw) и наши верифицированные аккаунты в социальных сетях. |
|
||||
| 2026-02-21 | _Важный_ | Наш официальный сайт теперь доступен: [zeroclawlabs.ai](https://zeroclawlabs.ai). Спасибо за терпение, пока мы готовили запуск. Мы по-прежнему видим попытки имитации, поэтому **не** присоединяйтесь к каким-либо инвестиционным или фандрайзинговым активностям, использующим имя ZeroClaw, если они не опубликованы через наши официальные каналы. | Используйте [этот репозиторий](https://github.com/zeroclaw-labs/zeroclaw) как единственный источник истины. Следите за обновлениями в [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Group)](https://www.facebook.com/groups/zeroclawlabs) и [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/). |
|
||||
| 2026-02-19 | _Важный_ | Anthropic обновила условия Authentication and Credential Use 2026-02-19. Токены Claude Code OAuth (Free, Pro, Max) предназначены исключительно для Claude Code и Claude.ai; использование токенов OAuth от Claude Free/Pro/Max в любом другом продукте, инструменте или сервисе (включая Agent SDK) не разрешено и может нарушать Условия обслуживания потребителей. | Пожалуйста, временно избегайте интеграций Claude Code OAuth для предотвращения потенциальных потерь. Оригинальный пункт: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Основные возможности
|
||||
|
||||
- **Лёгкая среда выполнения по умолчанию** — типичные CLI и статусные рабочие процессы выполняются в оболочке памяти в несколько мегабайт на релизных сборках.
|
||||
- **Экономичное развёртывание** — разработан для плат за $10 и небольших облачных инстансов, без тяжёлых зависимостей среды выполнения.
|
||||
- **Быстрый холодный старт** — однобинарная среда выполнения Rust обеспечивает почти мгновенный запуск команд и демона.
|
||||
- **Портативная архитектура** — один бинарный файл для ARM, x86 и RISC-V с заменяемыми провайдерами/каналами/инструментами.
|
||||
- **Локальный Gateway** — единая панель управления для сессий, каналов, инструментов, cron, SOP и событий.
|
||||
- **Многоканальный почтовый ящик** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket и другие.
|
||||
- **Многоагентная оркестрация (Hands)** — автономные рои агентов, работающие по расписанию и становящиеся умнее со временем.
|
||||
- **Стандартные операционные процедуры (SOPs)** — событийная автоматизация рабочих процессов с MQTT, webhook, cron и триггерами периферийных устройств.
|
||||
- **Веб-панель** — веб-интерфейс React 19 + Vite с чатом в реальном времени, браузером памяти, редактором конфигурации, менеджером cron и инспектором инструментов.
|
||||
- **Аппаратные периферийные устройства** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO через трейт `Peripheral`.
|
||||
- **Первоклассные инструменты** — shell, файловый I/O, browser, git, web fetch/search, MCP, Jira, Notion, Google Workspace и 70+ других.
|
||||
- **Хуки жизненного цикла** — перехват и модификация вызовов LLM, выполнения инструментов и сообщений на каждом этапе.
|
||||
- **Платформа навыков** — встроенные, общественные и навыки рабочего пространства с аудитом безопасности.
|
||||
- **Поддержка туннелей** — Cloudflare, Tailscale, ngrok, OpenVPN и пользовательские туннели для удалённого доступа.
|
||||
|
||||
### Почему команды выбирают ZeroClaw
|
||||
|
||||
- **Лёгкий по умолчанию:** маленький бинарный файл Rust, быстрый запуск, малый объём памяти.
|
||||
- **Безопасный по дизайну:** сопряжение, строгая изоляция, явные списки разрешений, области рабочего пространства.
|
||||
- **Полностью заменяемый:** основные системы — это трейты (провайдеры, каналы, инструменты, память, туннели).
|
||||
- **Без привязки к вендору:** поддержка провайдеров, совместимых с OpenAI + подключаемые пользовательские эндпоинты.
|
||||
|
||||
## Снимок бенчмарков (ZeroClaw vs OpenClaw, воспроизводимый)
|
||||
|
||||
Быстрый бенчмарк на локальной машине (macOS arm64, февраль 2026), нормализованный для edge-оборудования на 0.8 ГГц.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Язык** | TypeScript | Python | Go | **Rust** |
|
||||
| **ОЗУ** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Запуск (ядро 0.8 ГГц)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Размер бинарного файла** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Стоимость** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Любое оборудование $10** |
|
||||
|
||||
> Примечания: результаты ZeroClaw измерены на релизных сборках с использованием `/usr/bin/time -l`. OpenClaw требует среду выполнения Node.js (обычно ~390 МБ дополнительных накладных расходов памяти), а NanoBot требует среду выполнения Python. PicoClaw и ZeroClaw — статические бинарные файлы. Показатели ОЗУ выше — это память времени выполнения; требования к компиляции при сборке выше.
|
||||
> Примечание: результаты ZeroClaw получены на release-сборке с помощью `/usr/bin/time -l`. OpenClaw требует Node.js runtime; только этот runtime обычно добавляет около 390MB дополнительного потребления памяти. NanoBot требует Python runtime. PicoClaw и ZeroClaw — статические бинарники.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw Comparison" width="800" />
|
||||
<img src="zero-claw.jpeg" alt="Сравнение ZeroClaw и OpenClaw" width="800" />
|
||||
</p>
|
||||
|
||||
### Воспроизводимое локальное измерение
|
||||
### Локально воспроизводимое измерение
|
||||
|
||||
Метрики могут меняться вместе с кодом и toolchain, поэтому проверяйте результаты в своей среде:
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
@ -254,502 +102,199 @@ ls -lh target/release/zeroclaw
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Всё, что мы построили
|
||||
Текущие примерные значения из README (macOS arm64, 2026-02-18):
|
||||
|
||||
### Основная платформа
|
||||
- Размер release-бинарника: `8.8M`
|
||||
- `zeroclaw --help`: ~`0.02s`, пик памяти ~`3.9MB`
|
||||
- `zeroclaw status`: ~`0.01s`, пик памяти ~`4.1MB`
|
||||
|
||||
- Gateway HTTP/WS/SSE панель управления с сессиями, присутствием, конфигурацией, cron, вебхуками, веб-панелью и сопряжением.
|
||||
- CLI поверхность: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Цикл оркестрации агента с диспетчеризацией инструментов, построением промптов, классификацией сообщений и загрузкой памяти.
|
||||
- Модель сессий с применением политики безопасности, уровнями автономности и шлюзом одобрения.
|
||||
- Устойчивая обёртка провайдера с переключением при сбое, повторными попытками и маршрутизацией моделей через 20+ бэкендов LLM.
|
||||
|
||||
### Каналы
|
||||
|
||||
Каналы: WhatsApp (нативный), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
За feature-флагами: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Веб-панель
|
||||
|
||||
Веб-панель React 19 + Vite 6 + Tailwind CSS 4, подаваемая непосредственно из Gateway:
|
||||
|
||||
- **Панель управления** — обзор системы, состояние здоровья, время безотказной работы, отслеживание стоимости
|
||||
- **Чат с агентом** — интерактивный чат с агентом
|
||||
- **Память** — просмотр и управление записями памяти
|
||||
- **Конфигурация** — просмотр и редактирование конфигурации
|
||||
- **Cron** — управление запланированными задачами
|
||||
- **Инструменты** — просмотр доступных инструментов
|
||||
- **Логи** — просмотр журналов активности агента
|
||||
- **Стоимость** — использование токенов и отслеживание стоимости
|
||||
- **Доктор** — диагностика здоровья системы
|
||||
- **Интеграции** — статус интеграций и настройка
|
||||
- **Сопряжение** — управление сопряжением устройств
|
||||
|
||||
### Целевые прошивки
|
||||
|
||||
| Цель | Платформа | Назначение |
|
||||
|--------|----------|---------|
|
||||
| ESP32 | Espressif ESP32 | Беспроводной периферийный агент |
|
||||
| ESP32-UI | ESP32 + Display | Агент с визуальным интерфейсом |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Промышленное периферийное устройство |
|
||||
| Arduino | Arduino | Базовый мост датчик/актуатор |
|
||||
| Uno Q Bridge | Arduino Uno | Последовательный мост к агенту |
|
||||
|
||||
### Инструменты + автоматизация
|
||||
|
||||
- **Основные:** shell, чтение/запись/редактирование файлов, операции git, поиск glob, поиск по содержимому
|
||||
- **Веб:** управление браузером, web fetch, web search, скриншоты, информация об изображении, чтение PDF
|
||||
- **Интеграции:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** обёртка инструментов Model Context Protocol + отложенные наборы инструментов
|
||||
- **Планирование:** cron add/remove/update/run, инструмент расписания
|
||||
- **Память:** recall, store, forget, knowledge, project intel
|
||||
- **Продвинутые:** delegate (агент-агенту), swarm, переключение/маршрутизация моделей, операции безопасности, облачные операции
|
||||
- **Оборудование:** информация о плате, карта памяти, чтение памяти (за feature-флагом)
|
||||
|
||||
### Среда выполнения + безопасность
|
||||
|
||||
- **Уровни автономности:** ReadOnly, Supervised (по умолчанию), Full.
|
||||
- **Изоляция:** изоляция рабочего пространства, блокировка обхода путей, списки разрешённых команд, запрещённые пути, Landlock (Linux), Bubblewrap.
|
||||
- **Ограничение частоты:** макс. действий в час, макс. стоимость в день (настраиваемые).
|
||||
- **Шлюз одобрения:** интерактивное одобрение для операций среднего/высокого риска.
|
||||
- **Аварийная остановка:** возможность экстренного отключения.
|
||||
- **129+ тестов безопасности** в автоматизированном CI.
|
||||
|
||||
### Операции + упаковка
|
||||
|
||||
- Веб-панель подаётся непосредственно из Gateway.
|
||||
- Поддержка туннелей: Cloudflare, Tailscale, ngrok, OpenVPN, пользовательская команда.
|
||||
- Docker-адаптер среды выполнения для контейнеризованного выполнения.
|
||||
- CI/CD: бета (авто при push) → стабильный (ручной запуск) → Docker, crates.io, Scoop, AUR, Homebrew, твит.
|
||||
- Предсобранные бинарные файлы для Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Конфигурация
|
||||
|
||||
Минимальный `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Полный справочник конфигурации: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Конфигурация каналов
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Конфигурация туннелей
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # or "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Подробности: [Справочник каналов](docs/reference/api/channels-reference.md) · [Справочник конфигурации](docs/reference/api/config-reference.md)
|
||||
|
||||
### Поддержка среды выполнения (текущая)
|
||||
|
||||
- **`native`** (по умолчанию) — прямое выполнение процесса, самый быстрый путь, идеально для доверенных сред.
|
||||
- **`docker`** — полная контейнерная изоляция, принудительные политики безопасности, требуется Docker.
|
||||
|
||||
Установите `runtime.kind = "docker"` для строгой изоляции или сетевой изоляции.
|
||||
|
||||
## Аутентификация по подписке (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw поддерживает нативные профили аутентификации по подписке (мультиаккаунт, шифрование в состоянии покоя).
|
||||
|
||||
- Файл хранилища: `~/.zeroclaw/auth-profiles.json`
|
||||
- Ключ шифрования: `~/.zeroclaw/.secret_key`
|
||||
- Формат id профиля: `<provider>:<profile_name>` (пример: `openai-codex:work`)
|
||||
## Установка в 1 клик
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT subscription)
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./bootstrap.sh
|
||||
```
|
||||
|
||||
Для полной инициализации окружения: `./bootstrap.sh --install-system-deps --install-rust` (для системных пакетов может потребоваться `sudo`).
|
||||
|
||||
Подробности: [`docs/one-click-bootstrap.md`](docs/one-click-bootstrap.md).
|
||||
|
||||
## Быстрый старт
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard --api-key sk-... --provider openrouter
|
||||
zeroclaw onboard --interactive
|
||||
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# default: 127.0.0.1:42617
|
||||
zeroclaw gateway
|
||||
|
||||
zeroclaw daemon
|
||||
```
|
||||
|
||||
## Subscription Auth (OpenAI Codex / Claude Code)
|
||||
|
||||
ZeroClaw поддерживает нативные профили авторизации на основе подписки (мультиаккаунт, шифрование при хранении).
|
||||
|
||||
- Файл хранения: `~/.zeroclaw/auth-profiles.json`
|
||||
- Ключ шифрования: `~/.zeroclaw/.secret_key`
|
||||
- Формат Profile ID: `<provider>:<profile_name>` (пример: `openai-codex:work`)
|
||||
|
||||
OpenAI Codex OAuth (подписка ChatGPT):
|
||||
|
||||
```bash
|
||||
# Рекомендуется для серверов/headless-окружений
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
# Браузерный/callback-поток с paste-фолбэком
|
||||
zeroclaw auth login --provider openai-codex --profile default
|
||||
zeroclaw auth paste-redirect --provider openai-codex --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Check / refresh / switch profile
|
||||
# Проверка / обновление / переключение профиля
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
```
|
||||
|
||||
# Run the agent with subscription auth
|
||||
Claude Code / Anthropic setup-token:
|
||||
|
||||
```bash
|
||||
# Вставка subscription/setup token (режим Authorization header)
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Команда-алиас
|
||||
zeroclaw auth setup-token --provider anthropic --profile default
|
||||
```
|
||||
|
||||
Запуск agent с subscription auth:
|
||||
|
||||
```bash
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider openai-codex --auth-profile openai-codex:work -m "hello"
|
||||
|
||||
# Anthropic поддерживает и API key, и auth token через переменные окружения:
|
||||
# ANTHROPIC_AUTH_TOKEN, ANTHROPIC_OAUTH_TOKEN, ANTHROPIC_API_KEY
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Рабочее пространство агента + навыки
|
||||
## Архитектура
|
||||
|
||||
Корень рабочего пространства: `~/.zeroclaw/workspace/` (настраивается через конфигурацию).
|
||||
|
||||
Внедряемые файлы промптов:
|
||||
- `IDENTITY.md` — личность и роль агента
|
||||
- `USER.md` — контекст и предпочтения пользователя
|
||||
- `MEMORY.md` — долгосрочные факты и уроки
|
||||
- `AGENTS.md` — соглашения сессий и правила инициализации
|
||||
- `SOUL.md` — основная идентичность и принципы работы
|
||||
|
||||
Навыки: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` или `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# List installed skills
|
||||
zeroclaw skills list
|
||||
|
||||
# Install from git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Security audit before install
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Remove a skill
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## Команды CLI
|
||||
|
||||
```bash
|
||||
# Workspace management
|
||||
zeroclaw onboard # Guided setup wizard
|
||||
zeroclaw status # Show daemon/agent status
|
||||
zeroclaw doctor # Run system diagnostics
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Start gateway server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Start full autonomous runtime
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interactive chat mode
|
||||
zeroclaw agent -m "message" # Single message mode
|
||||
|
||||
# Service management
|
||||
zeroclaw service install # Install as OS service (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Channels
|
||||
zeroclaw channel list # List configured channels
|
||||
zeroclaw channel doctor # Check channel health
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + scheduling
|
||||
zeroclaw cron list # List scheduled jobs
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Memory
|
||||
zeroclaw memory list # List memory entries
|
||||
zeroclaw memory get <key> # Retrieve a memory
|
||||
zeroclaw memory stats # Memory statistics
|
||||
|
||||
# Auth profiles
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hardware peripherals
|
||||
zeroclaw hardware discover # Scan for connected devices
|
||||
zeroclaw peripheral list # List connected peripherals
|
||||
zeroclaw peripheral flash # Flash firmware to device
|
||||
|
||||
# Migration
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell completions
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Полный справочник команд: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Предварительные требования
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Обязательные
|
||||
|
||||
1. **Visual Studio Build Tools** (предоставляет линкер MSVC и Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Во время установки (или через Visual Studio Installer) выберите рабочую нагрузку **"Desktop development with C++"**.
|
||||
|
||||
2. **Набор инструментов Rust:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
После установки откройте новый терминал и выполните `rustup default stable`, чтобы убедиться, что стабильный набор инструментов активен.
|
||||
|
||||
3. **Проверьте**, что оба работают:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Необязательные
|
||||
|
||||
- **Docker Desktop** — требуется только при использовании [изолированной среды выполнения Docker](#поддержка-среды-выполнения-текущая) (`runtime.kind = "docker"`). Установите через `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Обязательные
|
||||
|
||||
1. **Средства сборки:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Установите Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Набор инструментов Rust:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Подробности на [rustup.rs](https://rustup.rs).
|
||||
|
||||
3. **Проверьте**, что оба работают:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Однострочный установщик
|
||||
|
||||
Или пропустите шаги выше и установите всё (системные зависимости, Rust, ZeroClaw) одной командой:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Требования к ресурсам для компиляции
|
||||
|
||||
Сборка из исходного кода требует больше ресурсов, чем запуск результирующего бинарного файла:
|
||||
|
||||
| Ресурс | Минимум | Рекомендуемый |
|
||||
| -------------- | ------- | ----------- |
|
||||
| **ОЗУ + swap** | 2 GB | 4 GB+ |
|
||||
| **Свободное место на диске** | 6 GB | 10 GB+ |
|
||||
|
||||
Если ваш хост ниже минимума, используйте предсобранные бинарные файлы:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
Чтобы требовать установку только бинарного файла без сборки из исходников:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Необязательные
|
||||
|
||||
- **Docker** — требуется только при использовании [изолированной среды выполнения Docker](#поддержка-среды-выполнения-текущая) (`runtime.kind = "docker"`). Установите через менеджер пакетов или [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Примечание:** По умолчанию `cargo build --release` использует `codegen-units=1` для снижения пиковой нагрузки при компиляции. Для более быстрой сборки на мощных машинах используйте `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Предсобранные бинарные файлы
|
||||
|
||||
Артефакты релизов публикуются для:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Скачайте последние артефакты:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Документация
|
||||
|
||||
Используйте это, когда вы прошли онбординг и хотите более глубокий справочник.
|
||||
|
||||
- Начните с [индекса документации](docs/README.md) для навигации и «что где».
|
||||
- Прочитайте [обзор архитектуры](docs/architecture.md) для полной модели системы.
|
||||
- Используйте [справочник конфигурации](docs/reference/api/config-reference.md), когда вам нужен каждый ключ и пример.
|
||||
- Управляйте Gateway по инструкции с [операционным руководством](docs/ops/operations-runbook.md).
|
||||
- Следуйте [ZeroClaw Onboard](#быстрый-старт) для управляемой настройки.
|
||||
- Устраняйте типичные сбои с помощью [руководства по устранению неполадок](docs/ops/troubleshooting.md).
|
||||
- Ознакомьтесь с [руководством по безопасности](docs/security/README.md) перед открытием чего-либо.
|
||||
|
||||
### Справочная документация
|
||||
|
||||
- Хаб документации: [docs/README.md](docs/README.md)
|
||||
- Единое оглавление: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Справочник команд: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Справочник конфигурации: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Справочник провайдеров: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Справочник каналов: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Операционное руководство: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Устранение неполадок: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Документация по сотрудничеству
|
||||
|
||||
- Руководство по участию: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- Политика рабочего процесса PR: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- Руководство по CI-процессу: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Руководство рецензента: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Политика раскрытия уязвимостей: [SECURITY.md](SECURITY.md)
|
||||
- Шаблон документации: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Развёртывание + операции
|
||||
|
||||
- Руководство по сетевому развёртыванию: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Руководство по прокси-агенту: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Руководства по оборудованию: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw был создан для smooth crab 🦀 — быстрого и эффективного ИИ-ассистента. Создан Argenis De La Rosa и сообществом.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Поддержите ZeroClaw
|
||||
|
||||
Если ZeroClaw помогает вашей работе и вы хотите поддержать дальнейшую разработку, вы можете пожертвовать здесь:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Особая благодарность
|
||||
|
||||
Сердечная благодарность сообществам и институтам, которые вдохновляют и питают эту работу с открытым исходным кодом:
|
||||
|
||||
- **Harvard University** — за развитие интеллектуального любопытства и расширение границ возможного.
|
||||
- **MIT** — за продвижение открытых знаний, открытого кода и веры в то, что технологии должны быть доступны каждому.
|
||||
- **Sundai Club** — за сообщество, энергию и неустанное стремление создавать вещи, которые имеют значение.
|
||||
- **Мир и далее** 🌍✨ — каждому участнику, мечтателю и создателю, делающему открытый код силой добра. Это для вас.
|
||||
|
||||
Мы строим открыто, потому что лучшие идеи приходят отовсюду. Если вы это читаете, вы часть этого. Добро пожаловать. 🦀❤️
|
||||
|
||||
## Участие
|
||||
|
||||
Новичок в ZeroClaw? Ищите задачи с меткой [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — см. наше [Руководство по участию](CONTRIBUTING.md#first-time-contributors) для начала. AI/vibe-coded PR приветствуются! 🤖
|
||||
|
||||
См. [CONTRIBUTING.md](CONTRIBUTING.md) и [CLA.md](docs/contributing/cla.md). Реализуйте трейт, отправьте PR:
|
||||
|
||||
- Руководство по CI-процессу: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Новый `Provider` → `src/providers/`
|
||||
- Новый `Channel` → `src/channels/`
|
||||
- Новый `Observer` → `src/observability/`
|
||||
- Новый `Tool` → `src/tools/`
|
||||
- Новый `Memory` → `src/memory/`
|
||||
- Новый `Tunnel` → `src/tunnel/`
|
||||
- Новый `Peripheral` → `src/peripherals/`
|
||||
- Новый `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Официальный репозиторий и предупреждение об имитации
|
||||
|
||||
**Это единственный официальный репозиторий ZeroClaw:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Любой другой репозиторий, организация, домен или пакет, претендующий на звание «ZeroClaw» или подразумевающий связь с ZeroClaw Labs, является **неавторизованным и не связанным с этим проектом**. Известные неавторизованные форки будут перечислены в [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Если вы столкнётесь с имитацией или неправомерным использованием товарного знака, пожалуйста, [откройте issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Лицензия
|
||||
|
||||
ZeroClaw распространяется под двойной лицензией для максимальной открытости и защиты участников:
|
||||
|
||||
| Лицензия | Случай использования |
|
||||
|---|---|
|
||||
| [MIT](LICENSE-MIT) | Открытый код, исследования, академическое, личное использование |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Патентная защита, институциональное, коммерческое развёртывание |
|
||||
|
||||
Вы можете выбрать любую лицензию. **Участники автоматически предоставляют права по обеим** — см. [CLA.md](docs/contributing/cla.md) для полного соглашения участника.
|
||||
|
||||
### Товарный знак
|
||||
|
||||
Название и логотип **ZeroClaw** являются товарными знаками ZeroClaw Labs. Эта лицензия не предоставляет разрешения на их использование для подразумевания одобрения или принадлежности. См. [TRADEMARK.md](docs/maintainers/trademark.md) для разрешённых и запрещённых использований.
|
||||
|
||||
### Защита участников
|
||||
|
||||
- Вы **сохраняете авторские права** на свои вклады
|
||||
- **Патентное предоставление** (Apache 2.0) защищает вас от патентных претензий других участников
|
||||
- Ваши вклады **постоянно атрибутированы** в истории коммитов и [NOTICE](NOTICE)
|
||||
- Никакие права на товарный знак не передаются при участии
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Нулевые накладные расходы. Нулевые компромиссы. Развёртывайте где угодно. Заменяйте что угодно. 🦀
|
||||
|
||||
## Участники
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw contributors" />
|
||||
</a>
|
||||
|
||||
Этот список генерируется из графа участников GitHub и обновляется автоматически.
|
||||
|
||||
## История звёзд
|
||||
Каждая подсистема — это **Trait**: меняйте реализации через конфигурацию, без изменения кода.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
<img src="docs/architecture.svg" alt="Архитектура ZeroClaw" width="900" />
|
||||
</p>
|
||||
|
||||
| Подсистема | Trait | Встроенные реализации | Расширение |
|
||||
|-----------|-------|---------------------|------------|
|
||||
| **AI-модели** | `Provider` | Каталог через `zeroclaw providers` (сейчас 28 встроенных + алиасы, плюс пользовательские endpoint) | `custom:https://your-api.com` (OpenAI-совместимый) или `anthropic-custom:https://your-api.com` |
|
||||
| **Каналы** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Linq, Email, IRC, Lark, DingTalk, QQ, Webhook | Любой messaging API |
|
||||
| **Память** | `Memory` | SQLite гибридный поиск, PostgreSQL-бэкенд, Lucid-мост, Markdown-файлы, явный `none`-бэкенд, snapshot/hydrate, опциональный кэш ответов | Любой persistence-бэкенд |
|
||||
| **Инструменты** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, аппаратные инструменты | Любая функциональность |
|
||||
| **Наблюдаемость** | `Observer` | Noop, Log, Multi | Prometheus, OTel |
|
||||
| **Runtime** | `RuntimeAdapter` | Native, Docker (sandbox) | Через adapter; неподдерживаемые kind завершаются с ошибкой |
|
||||
| **Безопасность** | `SecurityPolicy` | Gateway pairing, sandbox, allowlist, rate limits, scoping файловой системы, шифрование секретов | — |
|
||||
| **Идентификация** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | Любой формат идентификации |
|
||||
| **Туннели** | `Tunnel` | None, Cloudflare, Tailscale, ngrok, Custom | Любой tunnel-бинарник |
|
||||
| **Heartbeat** | Engine | HEARTBEAT.md — периодические задачи | — |
|
||||
| **Навыки** | Loader | TOML-манифесты + SKILL.md-инструкции | Пакеты навыков сообщества |
|
||||
| **Интеграции** | Registry | 70+ интеграций в 9 категориях | Плагинная система |
|
||||
|
||||
### Поддержка runtime (текущая)
|
||||
|
||||
- ✅ Поддерживается сейчас: `runtime.kind = "native"` или `runtime.kind = "docker"`
|
||||
- 🚧 Запланировано, но ещё не реализовано: WASM / edge-runtime
|
||||
|
||||
При указании неподдерживаемого `runtime.kind` ZeroClaw завершается с явной ошибкой, а не молча откатывается к native.
|
||||
|
||||
### Система памяти (полнофункциональный поисковый движок)
|
||||
|
||||
Полностью собственная реализация, ноль внешних зависимостей — без Pinecone, Elasticsearch, LangChain:
|
||||
|
||||
| Уровень | Реализация |
|
||||
|---------|-----------|
|
||||
| **Векторная БД** | Embeddings хранятся как BLOB в SQLite, поиск по косинусному сходству |
|
||||
| **Поиск по ключевым словам** | Виртуальные таблицы FTS5 со скорингом BM25 |
|
||||
| **Гибридное слияние** | Пользовательская взвешенная функция слияния (`vector.rs`) |
|
||||
| **Embeddings** | Trait `EmbeddingProvider` — OpenAI, пользовательский URL или noop |
|
||||
| **Чанкинг** | Построчный Markdown-чанкер с сохранением заголовков |
|
||||
| **Кэширование** | Таблица `embedding_cache` в SQLite с LRU-вытеснением |
|
||||
| **Безопасная переиндексация** | Атомарная перестройка FTS5 + повторное встраивание отсутствующих векторов |
|
||||
|
||||
Agent автоматически вспоминает, сохраняет и управляет памятью через инструменты.
|
||||
|
||||
```toml
|
||||
[memory]
|
||||
backend = "sqlite" # "sqlite", "lucid", "postgres", "markdown", "none"
|
||||
auto_save = true
|
||||
embedding_provider = "none" # "none", "openai", "custom:https://..."
|
||||
vector_weight = 0.7
|
||||
keyword_weight = 0.3
|
||||
```
|
||||
|
||||
## Важные security-дефолты
|
||||
|
||||
- Gateway по умолчанию: `127.0.0.1:42617`
|
||||
- Pairing обязателен по умолчанию: `require_pairing = true`
|
||||
- Публичный bind запрещён по умолчанию: `allow_public_bind = false`
|
||||
- Семантика allowlist каналов:
|
||||
- `[]` => deny-by-default
|
||||
- `["*"]` => allow all (используйте осознанно)
|
||||
|
||||
## Пример конфигурации
|
||||
|
||||
```toml
|
||||
api_key = "sk-..."
|
||||
default_provider = "openrouter"
|
||||
default_model = "anthropic/claude-sonnet-4-6"
|
||||
default_temperature = 0.7
|
||||
|
||||
[memory]
|
||||
backend = "sqlite"
|
||||
auto_save = true
|
||||
embedding_provider = "none"
|
||||
|
||||
[gateway]
|
||||
host = "127.0.0.1"
|
||||
port = 42617
|
||||
require_pairing = true
|
||||
allow_public_bind = false
|
||||
```
|
||||
|
||||
## Навигация по документации
|
||||
|
||||
- Хаб документации (English): [`docs/README.md`](docs/README.md)
|
||||
- Единый TOC docs: [`docs/SUMMARY.md`](docs/SUMMARY.md)
|
||||
- Хаб документации (Русский): [`docs/README.ru.md`](docs/README.ru.md)
|
||||
- Справочник команд: [`docs/commands-reference.md`](docs/commands-reference.md)
|
||||
- Справочник конфигурации: [`docs/config-reference.md`](docs/config-reference.md)
|
||||
- Справочник providers: [`docs/providers-reference.md`](docs/providers-reference.md)
|
||||
- Справочник channels: [`docs/channels-reference.md`](docs/channels-reference.md)
|
||||
- Операционный runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md)
|
||||
- Устранение неполадок: [`docs/troubleshooting.md`](docs/troubleshooting.md)
|
||||
- Инвентарь и классификация docs: [`docs/docs-inventory.md`](docs/docs-inventory.md)
|
||||
- Снимок triage проекта: [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
|
||||
|
||||
## Вклад и лицензия
|
||||
|
||||
- Contribution guide: [`CONTRIBUTING.md`](CONTRIBUTING.md)
|
||||
- PR workflow: [`docs/pr-workflow.md`](docs/pr-workflow.md)
|
||||
- Reviewer playbook: [`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
|
||||
- License: MIT or Apache 2.0 ([`LICENSE-MIT`](LICENSE-MIT), [`LICENSE-APACHE`](LICENSE-APACHE), [`NOTICE`](NOTICE))
|
||||
|
||||
---
|
||||
|
||||
Для полной и исчерпывающей информации (архитектура, все команды, API, разработка) используйте основной английский документ: [`README.md`](README.md).
|
||||
|
||||
755
README.sv.md
755
README.sv.md
@ -1,755 +0,0 @@
|
||||
<p align="center">
|
||||
<img src="https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/docs/assets/zeroclaw-banner.png" alt="ZeroClaw" width="600" />
|
||||
</p>
|
||||
|
||||
<h1 align="center">🦀 ZeroClaw — Personlig AI-assistent</h1>
|
||||
|
||||
<p align="center">
|
||||
<strong>Noll overhead. Noll kompromiss. 100% Rust. 100% Agnostisk.</strong><br>
|
||||
⚡️ <strong>Körs på $10-hårdvara med <5MB RAM: Det är 99% mindre minne än OpenClaw och 98% billigare än en Mac mini!</strong>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<a href="LICENSE-APACHE"><img src="https://img.shields.io/badge/license-MIT%20OR%20Apache%202.0-blue.svg" alt="License: MIT OR Apache-2.0" /></a>
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors"><img src="https://img.shields.io/github/contributors/zeroclaw-labs/zeroclaw?color=green" alt="Contributors" /></a>
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=flat&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
<a href="https://x.com/zeroclawlabs?s=21"><img src="https://img.shields.io/badge/X-%40zeroclawlabs-000000?style=flat&logo=x&logoColor=white" alt="X: @zeroclawlabs" /></a>
|
||||
<a href="https://www.facebook.com/groups/zeroclawlabs"><img src="https://img.shields.io/badge/Facebook-Group-1877F2?style=flat&logo=facebook&logoColor=white" alt="Facebook Group" /></a>
|
||||
<a href="https://discord.com/invite/wDshRVqRjx"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat&logo=discord&logoColor=white" alt="Discord" /></a>
|
||||
<a href="https://www.instagram.com/therealzeroclaw"><img src="https://img.shields.io/badge/Instagram-%40therealzeroclaw-E4405F?style=flat&logo=instagram&logoColor=white" alt="Instagram: @therealzeroclaw" /></a>
|
||||
<a href="https://www.tiktok.com/@zeroclawlabs"><img src="https://img.shields.io/badge/TikTok-%40zeroclawlabs-000000?style=flat&logo=tiktok&logoColor=white" alt="TikTok: @zeroclawlabs" /></a>
|
||||
<a href="https://www.rednote.com/user/profile/69b735e6000000002603927e"><img src="https://img.shields.io/badge/RedNote-Official-FF2442?style=flat" alt="RedNote" /></a>
|
||||
<a href="https://www.reddit.com/r/zeroclawlabs/"><img src="https://img.shields.io/badge/Reddit-r%2Fzeroclawlabs-FF4500?style=flat&logo=reddit&logoColor=white" alt="Reddit: r/zeroclawlabs" /></a>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
Byggt av studenter och medlemmar i Harvard-, MIT- och Sundai.Club-gemenskaperna.
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
🌐 <strong>Språk:</strong>
|
||||
<a href="README.md">🇺🇸 English</a> ·
|
||||
<a href="README.zh-CN.md">🇨🇳 简体中文</a> ·
|
||||
<a href="README.ja.md">🇯🇵 日本語</a> ·
|
||||
<a href="README.ko.md">🇰🇷 한국어</a> ·
|
||||
<a href="README.vi.md">🇻🇳 Tiếng Việt</a> ·
|
||||
<a href="README.tl.md">🇵🇭 Tagalog</a> ·
|
||||
<a href="README.es.md">🇪🇸 Español</a> ·
|
||||
<a href="README.pt.md">🇧🇷 Português</a> ·
|
||||
<a href="README.it.md">🇮🇹 Italiano</a> ·
|
||||
<a href="README.de.md">🇩🇪 Deutsch</a> ·
|
||||
<a href="README.fr.md">🇫🇷 Français</a> ·
|
||||
<a href="README.ar.md">🇸🇦 العربية</a> ·
|
||||
<a href="README.hi.md">🇮🇳 हिन्दी</a> ·
|
||||
<a href="README.ru.md">🇷🇺 Русский</a> ·
|
||||
<a href="README.bn.md">🇧🇩 বাংলা</a> ·
|
||||
<a href="README.he.md">🇮🇱 עברית</a> ·
|
||||
<a href="README.pl.md">🇵🇱 Polski</a> ·
|
||||
<a href="README.cs.md">🇨🇿 Čeština</a> ·
|
||||
<a href="README.nl.md">🇳🇱 Nederlands</a> ·
|
||||
<a href="README.tr.md">🇹🇷 Türkçe</a> ·
|
||||
<a href="README.uk.md">🇺🇦 Українська</a> ·
|
||||
<a href="README.id.md">🇮🇩 Bahasa Indonesia</a> ·
|
||||
<a href="README.th.md">🇹🇭 ไทย</a> ·
|
||||
<a href="README.ur.md">🇵🇰 اردو</a> ·
|
||||
<a href="README.ro.md">🇷🇴 Română</a> ·
|
||||
<a href="README.sv.md">🇸🇪 Svenska</a> ·
|
||||
<a href="README.el.md">🇬🇷 Ελληνικά</a> ·
|
||||
<a href="README.hu.md">🇭🇺 Magyar</a> ·
|
||||
<a href="README.fi.md">🇫🇮 Suomi</a> ·
|
||||
<a href="README.da.md">🇩🇰 Dansk</a> ·
|
||||
<a href="README.nb.md">🇳🇴 Norsk</a>
|
||||
</p>
|
||||
|
||||
ZeroClaw är en personlig AI-assistent som du kör på dina egna enheter. Den svarar dig via de kanaler du redan använder (WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work med flera). Den har en webbpanel för realtidskontroll och kan ansluta till hårdvaruperiferienheter (ESP32, STM32, Arduino, Raspberry Pi). Gateway är bara kontrollplanet — produkten är assistenten.
|
||||
|
||||
Om du vill ha en personlig, enanvändarassistent som känns lokal, snabb och alltid tillgänglig, är det här lösningen.
|
||||
|
||||
<p align="center">
|
||||
<a href="https://zeroclawlabs.ai">Webbplats</a> ·
|
||||
<a href="docs/README.md">Dokumentation</a> ·
|
||||
<a href="docs/architecture.md">Arkitektur</a> ·
|
||||
<a href="#snabbstart">Kom igång</a> ·
|
||||
<a href="#migrera-från-openclaw">Migrera från OpenClaw</a> ·
|
||||
<a href="docs/ops/troubleshooting.md">Felsökning</a> ·
|
||||
<a href="https://discord.com/invite/wDshRVqRjx">Discord</a>
|
||||
</p>
|
||||
|
||||
> **Rekommenderad konfiguration:** kör `zeroclaw onboard` i din terminal. ZeroClaw Onboard guidar dig steg för steg genom att konfigurera gateway, arbetsyta, kanaler och leverantör. Det är den rekommenderade installationsvägen och fungerar på macOS, Linux och Windows (via WSL2). Ny installation? Börja här: [Kom igång](#snabbstart)
|
||||
|
||||
### Prenumerationsautentisering (OAuth)
|
||||
|
||||
- **OpenAI Codex** (ChatGPT-prenumeration)
|
||||
- **Gemini** (Google OAuth)
|
||||
- **Anthropic** (API-nyckel eller autentiseringstoken)
|
||||
|
||||
Modellnotering: även om många leverantörer/modeller stöds, använd den starkaste senaste generationens modell som är tillgänglig för dig för bästa upplevelse. Se [Onboarding](#snabbstart).
|
||||
|
||||
Modellkonfiguration + CLI: [Leverantörsreferens](docs/reference/api/providers-reference.md)
|
||||
Autentiseringsprofil-rotation (OAuth vs API-nycklar) + failover: [Modell-failover](docs/reference/api/providers-reference.md)
|
||||
|
||||
## Installation (rekommenderad)
|
||||
|
||||
Körmiljö: Rust stable toolchain. Enda binär, inga körtidsberoenden.
|
||||
|
||||
### Homebrew (macOS/Linuxbrew)
|
||||
|
||||
```bash
|
||||
brew install zeroclaw
|
||||
```
|
||||
|
||||
### Ett-klicks-installation
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`zeroclaw onboard` körs automatiskt efter installationen för att konfigurera din arbetsyta och leverantör.
|
||||
|
||||
## Snabbstart
|
||||
|
||||
Fullständig nybörjarguide (autentisering, parkoppling, kanaler): [Kom igång](docs/setup-guides/one-click-bootstrap.md)
|
||||
|
||||
```bash
|
||||
# Installera + onboard
|
||||
./install.sh --api-key "sk-..." --provider openrouter
|
||||
|
||||
# Starta gateway (webhook-server + webbpanel)
|
||||
zeroclaw gateway # standard: 127.0.0.1:42617
|
||||
zeroclaw gateway --port 0 # slumpmässig port (säkerhetshärdad)
|
||||
|
||||
# Prata med assistenten
|
||||
zeroclaw agent -m "Hello, ZeroClaw!"
|
||||
|
||||
# Interaktivt läge
|
||||
zeroclaw agent
|
||||
|
||||
# Starta full autonom körmiljö (gateway + kanaler + cron + hands)
|
||||
zeroclaw daemon
|
||||
|
||||
# Kontrollera status
|
||||
zeroclaw status
|
||||
|
||||
# Kör diagnostik
|
||||
zeroclaw doctor
|
||||
```
|
||||
|
||||
Uppgraderar du? Kör `zeroclaw doctor` efter uppdatering.
|
||||
|
||||
### Från källkod (utveckling)
|
||||
|
||||
```bash
|
||||
git clone https://github.com/zeroclaw-labs/zeroclaw.git
|
||||
cd zeroclaw
|
||||
|
||||
cargo build --release --locked
|
||||
cargo install --path . --force --locked
|
||||
|
||||
zeroclaw onboard
|
||||
```
|
||||
|
||||
> **Utvecklar-fallback (ingen global installation):** prefixera kommandon med `cargo run --release --` (exempel: `cargo run --release -- status`).
|
||||
|
||||
## Migrera från OpenClaw
|
||||
|
||||
ZeroClaw kan importera din OpenClaw-arbetsyta, minne och konfiguration:
|
||||
|
||||
```bash
|
||||
# Förhandsgranska vad som migreras (säkert, skrivskyddat)
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
|
||||
# Kör migreringen
|
||||
zeroclaw migrate openclaw
|
||||
```
|
||||
|
||||
Detta migrerar dina minnesposter, arbetsytefiler och konfiguration från `~/.openclaw/` till `~/.zeroclaw/`. Konfiguration konverteras automatiskt från JSON till TOML.
|
||||
|
||||
## Säkerhetsstandarder (DM-åtkomst)
|
||||
|
||||
ZeroClaw ansluter till riktiga meddelandeytor. Behandla inkommande DM som opålitlig indata.
|
||||
|
||||
Fullständig säkerhetsguide: [SECURITY.md](SECURITY.md)
|
||||
|
||||
Standardbeteende på alla kanaler:
|
||||
|
||||
- **DM-parkoppling** (standard): okända avsändare får en kort parkopplingskod och boten behandlar inte deras meddelande.
|
||||
- Godkänn med: `zeroclaw pairing approve <channel> <code>` (sedan läggs avsändaren till i en lokal tillåtlista).
|
||||
- Offentliga inkommande DM kräver ett explicit opt-in i `config.toml`.
|
||||
- Kör `zeroclaw doctor` för att hitta riskfyllda eller felkonfigurerade DM-policyer.
|
||||
|
||||
**Autonominivåer:**
|
||||
|
||||
| Nivå | Beteende |
|
||||
|------|----------|
|
||||
| `ReadOnly` | Agenten kan observera men inte agera |
|
||||
| `Supervised` (standard) | Agenten agerar med godkännande för medel-/högriskoperationer |
|
||||
| `Full` | Agenten agerar autonomt inom policygränser |
|
||||
|
||||
**Sandboxlager:** arbetsyteisolering, sökvägstraversblockering, kommandotillåtlistor, förbjudna sökvägar (`/etc`, `/root`, `~/.ssh`), hastighetsbegränsning (max åtgärder/timme, kostnad/dag-gränser).
|
||||
|
||||
<!-- BEGIN:WHATS_NEW -->
|
||||
<!-- END:WHATS_NEW -->
|
||||
|
||||
### 📢 Meddelanden
|
||||
|
||||
Använd denna tavla för viktiga meddelanden (brytande ändringar, säkerhetsrådgivningar, underhållsfönster och releaseblockerare).
|
||||
|
||||
| Datum (UTC) | Nivå | Meddelande | Åtgärd |
|
||||
| ----------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| 2026-02-19 | _Kritisk_ | Vi är **inte affilierade** med `openagen/zeroclaw`, `zeroclaw.org` eller `zeroclaw.net`. Domänerna `zeroclaw.org` och `zeroclaw.net` pekar för närvarande till `openagen/zeroclaw`-forken, och den domänen/repositoryt utger sig för att vara vår officiella webbplats/projekt. | Lita inte på information, binärer, insamlingar eller meddelanden från dessa källor. Använd bara [detta repository](https://github.com/zeroclaw-labs/zeroclaw) och våra verifierade sociala konton. |
|
||||
| 2026-02-21 | _Viktigt_ | Vår officiella webbplats är nu live: [zeroclawlabs.ai](https://zeroclawlabs.ai). Tack för ert tålamod medan vi förberedde lanseringen. Vi ser fortfarande imitationsförsök, så **gå inte** med i några investerings- eller insamlingsaktiviteter som hävdar ZeroClaw-namnet om de inte publicerats via våra officiella kanaler. | Använd [detta repository](https://github.com/zeroclaw-labs/zeroclaw) som enda sanningskälla. Följ [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Facebook (Grupp)](https://www.facebook.com/groups/zeroclawlabs) och [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/) för officiella uppdateringar. |
|
||||
| 2026-02-19 | _Viktigt_ | Anthropic uppdaterade villkoren för autentisering och inloggningsanvändning 2026-02-19. Claude Code OAuth-tokens (Free, Pro, Max) är avsedda uteslutande för Claude Code och Claude.ai; att använda OAuth-tokens från Claude Free/Pro/Max i någon annan produkt, verktyg eller tjänst (inklusive Agent SDK) är inte tillåtet och kan bryta mot Consumer Terms of Service. | Undvik tillfälligt Claude Code OAuth-integrationer för att förhindra potentiell förlust. Originalklausul: [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
|
||||
|
||||
## Höjdpunkter
|
||||
|
||||
- **Lean körmiljö som standard** — vanliga CLI- och statusarbetsflöden körs i ett fåmegabyte-minnesutrymme på release-byggen.
|
||||
- **Kostnadseffektiv distribution** — designad för $10-kort och små molninstanser, inga tunga körtidsberoenden.
|
||||
- **Snabba kallstarter** — enkel binär Rust-körmiljö håller kommando- och daemon-uppstart nära ögonblicklig.
|
||||
- **Portabel arkitektur** — en binär över ARM, x86 och RISC-V med utbytbara providers/channels/tools.
|
||||
- **Lokal-först Gateway** — enda kontrollplan för sessioner, kanaler, verktyg, cron, SOP:er och händelser.
|
||||
- **Multikanalinkorg** — WhatsApp, Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, Nostr, Mattermost, Nextcloud Talk, DingTalk, Lark, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WebSocket med flera.
|
||||
- **Multiagentorkestrering (Hands)** — autonoma agentsvärmar som körs på schema och blir smartare med tiden.
|
||||
- **Standardoperationsprocedurer (SOPs)** — händelsedriven arbetsflödesautomatisering med MQTT, webhook, cron och periferiutlösare.
|
||||
- **Webbpanel** — React 19 + Vite webb-UI med realtidschatt, minnesutforskare, konfigurationsredigerare, cron-hanterare och verktygsinspektor.
|
||||
- **Hårdvaruperiferienheter** — ESP32, STM32 Nucleo, Arduino, Raspberry Pi GPIO via `Peripheral`-traiten.
|
||||
- **Förstklassiga verktyg** — shell, fil-I/O, webbläsare, git, web fetch/search, MCP, Jira, Notion, Google Workspace och 70+ fler.
|
||||
- **Livscykelkrokar** — fånga upp och modifiera LLM-anrop, verktygsexekveringar och meddelanden i varje steg.
|
||||
- **Färdighetsplattform** — medföljande, community- och arbetsytefärdigheter med säkerhetsgranskning.
|
||||
- **Tunnelstöd** — Cloudflare, Tailscale, ngrok, OpenVPN och anpassade tunnlar för fjärråtkomst.
|
||||
|
||||
### Varför team väljer ZeroClaw
|
||||
|
||||
- **Lean som standard:** liten Rust-binär, snabb start, lågt minnesavtryck.
|
||||
- **Säker från grunden:** parkoppling, strikt sandboxning, explicita tillåtlistor, arbetsyteavgränsning.
|
||||
- **Fullt utbytbar:** kärnssystem är traits (providers, channels, tools, memory, tunnels).
|
||||
- **Inget leverantörslås:** OpenAI-kompatibelt leverantörsstöd + pluggbara anpassade endpoints.
|
||||
|
||||
## Benchmarkögonblicksbild (ZeroClaw vs OpenClaw, Reproducerbar)
|
||||
|
||||
Lokal maskin-snabbtest (macOS arm64, feb 2026) normaliserat för 0.8GHz edge-hårdvara.
|
||||
|
||||
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
|
||||
| ------------------------- | ------------- | -------------- | --------------- | -------------------- |
|
||||
| **Språk** | TypeScript | Python | Go | **Rust** |
|
||||
| **RAM** | > 1GB | > 100MB | < 10MB | **< 5MB** |
|
||||
| **Uppstart (0.8GHz kärna)** | > 500s | > 30s | < 1s | **< 10ms** |
|
||||
| **Binärstorlek** | ~28MB (dist) | N/A (Scripts) | ~8MB | **~8.8 MB** |
|
||||
| **Kostnad** | Mac Mini $599 | Linux SBC ~$50 | Linux Board $10 | **Vilken hårdvara som helst $10** |
|
||||
|
||||
> Noteringar: ZeroClaw-resultat mäts på release-byggen med `/usr/bin/time -l`. OpenClaw kräver Node.js-körmiljö (typiskt ~390MB extra minnesoverhead), medan NanoBot kräver Python-körmiljö. PicoClaw och ZeroClaw är statiska binärer. RAM-siffrorna ovan är körtidsminne; kompileringskrav vid byggtid är högre.
|
||||
|
||||
<p align="center">
|
||||
<img src="docs/assets/zeroclaw-comparison.jpeg" alt="ZeroClaw vs OpenClaw jämförelse" width="800" />
|
||||
</p>
|
||||
|
||||
### Reproducerbar lokal mätning
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
ls -lh target/release/zeroclaw
|
||||
|
||||
/usr/bin/time -l target/release/zeroclaw --help
|
||||
/usr/bin/time -l target/release/zeroclaw status
|
||||
```
|
||||
|
||||
## Allt vi byggt hittills
|
||||
|
||||
### Kärnplattform
|
||||
|
||||
- Gateway HTTP/WS/SSE-kontrollplan med sessioner, närvaro, konfiguration, cron, webhooks, webbpanel och parkoppling.
|
||||
- CLI-yta: `gateway`, `agent`, `onboard`, `doctor`, `status`, `service`, `migrate`, `auth`, `cron`, `channel`, `skills`.
|
||||
- Agentorkestreringsloop med verktygsdistribution, promptkonstruktion, meddelandeklassificering och minnesinläsning.
|
||||
- Sessionsmodell med säkerhetspolicyefterlevnad, autonominivåer och godkännandeportar.
|
||||
- Motståndskraftig leverantörswrapper med failover, retry och modellroutning över 20+ LLM-backends.
|
||||
|
||||
### Kanaler
|
||||
|
||||
Kanaler: WhatsApp (nativ), Telegram, Slack, Discord, Signal, iMessage, Matrix, IRC, Email, Bluesky, DingTalk, Lark, Mattermost, Nextcloud Talk, Nostr, QQ, Reddit, LinkedIn, Twitter, MQTT, WeChat Work, WATI, Mochat, Linq, Notion, WebSocket, ClawdTalk.
|
||||
|
||||
Funktionsgated: Matrix (`channel-matrix`), Lark (`channel-lark`), Nostr (`channel-nostr`).
|
||||
|
||||
### Webbpanel
|
||||
|
||||
React 19 + Vite 6 + Tailwind CSS 4 webbpanel serverad direkt från Gateway:
|
||||
|
||||
- **Dashboard** — systemöversikt, hälsostatus, drifttid, kostnadsspårning
|
||||
- **Agentchatt** — interaktiv chatt med agenten
|
||||
- **Minne** — bläddra och hantera minnesposter
|
||||
- **Konfiguration** — visa och redigera konfiguration
|
||||
- **Cron** — hantera schemalagda uppgifter
|
||||
- **Verktyg** — bläddra tillgängliga verktyg
|
||||
- **Loggar** — visa agentaktivitetsloggar
|
||||
- **Kostnad** — tokenanvändning och kostnadsspårning
|
||||
- **Doktor** — systemhälsodiagnostik
|
||||
- **Integrationer** — integrationsstatus och konfiguration
|
||||
- **Parkoppling** — hantering av enhetsparkoppling
|
||||
|
||||
### Firmware-mål
|
||||
|
||||
| Mål | Plattform | Syfte |
|
||||
|-----|-----------|-------|
|
||||
| ESP32 | Espressif ESP32 | Trådlös periferienhetagent |
|
||||
| ESP32-UI | ESP32 + Display | Agent med visuellt gränssnitt |
|
||||
| STM32 Nucleo | STM32 (ARM Cortex-M) | Industriell periferienhet |
|
||||
| Arduino | Arduino | Grundläggande sensor-/aktuatorbrygga |
|
||||
| Uno Q Bridge | Arduino Uno | Seriell brygga till agent |
|
||||
|
||||
### Verktyg + automatisering
|
||||
|
||||
- **Kärna:** shell, filläsning/skrivning/redigering, git-operationer, glob-sökning, innehållssökning
|
||||
- **Webb:** webbläsarkontroll, web fetch, webbsökning, skärmdump, bildinformation, PDF-läsning
|
||||
- **Integrationer:** Jira, Notion, Google Workspace, Microsoft 365, LinkedIn, Composio, Pushover
|
||||
- **MCP:** Model Context Protocol-verktygs-wrapper + uppskjutna verktygsuppsättningar
|
||||
- **Schemaläggning:** cron add/remove/update/run, schemaverktyg
|
||||
- **Minne:** recall, store, forget, knowledge, project intel
|
||||
- **Avancerat:** delegate (agent-till-agent), swarm, modellväxling/routing, säkerhetsoperationer, molnoperationer
|
||||
- **Hårdvara:** board info, memory map, memory read (funktionsgated)
|
||||
|
||||
### Körmiljö + säkerhet
|
||||
|
||||
- **Autonominivåer:** ReadOnly, Supervised (standard), Full.
|
||||
- **Sandboxning:** arbetsyteisolering, sökvägstraversblockering, kommandotillåtlistor, förbjudna sökvägar, Landlock (Linux), Bubblewrap.
|
||||
- **Hastighetsbegränsning:** max åtgärder per timme, max kostnad per dag (konfigurerbart).
|
||||
- **Godkännandeportar:** interaktivt godkännande för medel-/högriskoperationer.
|
||||
- **E-stopp:** nödavstängningskapacitet.
|
||||
- **129+ säkerhetstester** i automatiserad CI.
|
||||
|
||||
### Drift + paketering
|
||||
|
||||
- Webbpanel serverad direkt från Gateway.
|
||||
- Tunnelstöd: Cloudflare, Tailscale, ngrok, OpenVPN, anpassat kommando.
|
||||
- Docker-körmiljöadapter för containeriserad exekvering.
|
||||
- CI/CD: beta (automatiskt vid push) → stable (manuell dispatch) → Docker, crates.io, Scoop, AUR, Homebrew, tweet.
|
||||
- Förbyggda binärer för Linux (x86_64, aarch64, armv7), macOS (x86_64, aarch64), Windows (x86_64).
|
||||
|
||||
|
||||
## Konfiguration
|
||||
|
||||
Minimal `~/.zeroclaw/config.toml`:
|
||||
|
||||
```toml
|
||||
default_provider = "anthropic"
|
||||
api_key = "sk-ant-..."
|
||||
```
|
||||
|
||||
Fullständig konfigurationsreferens: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md).
|
||||
|
||||
### Kanalkonfiguration
|
||||
|
||||
**Telegram:**
|
||||
```toml
|
||||
[channels.telegram]
|
||||
bot_token = "123456:ABC-DEF..."
|
||||
```
|
||||
|
||||
**Discord:**
|
||||
```toml
|
||||
[channels.discord]
|
||||
token = "your-bot-token"
|
||||
```
|
||||
|
||||
**Slack:**
|
||||
```toml
|
||||
[channels.slack]
|
||||
bot_token = "xoxb-..."
|
||||
app_token = "xapp-..."
|
||||
```
|
||||
|
||||
**WhatsApp:**
|
||||
```toml
|
||||
[channels.whatsapp]
|
||||
enabled = true
|
||||
```
|
||||
|
||||
**Matrix:**
|
||||
```toml
|
||||
[channels.matrix]
|
||||
homeserver_url = "https://matrix.org"
|
||||
username = "@bot:matrix.org"
|
||||
password = "..."
|
||||
```
|
||||
|
||||
**Signal:**
|
||||
```toml
|
||||
[channels.signal]
|
||||
phone_number = "+1234567890"
|
||||
```
|
||||
|
||||
### Tunnelkonfiguration
|
||||
|
||||
```toml
|
||||
[tunnel]
|
||||
kind = "cloudflare" # eller "tailscale", "ngrok", "openvpn", "custom", "none"
|
||||
```
|
||||
|
||||
Detaljer: [Kanalreferens](docs/reference/api/channels-reference.md) · [Konfigurationsreferens](docs/reference/api/config-reference.md)
|
||||
|
||||
### Körmiljöstöd (nuvarande)
|
||||
|
||||
- **`native`** (standard) — direkt processexekvering, snabbaste vägen, idealisk för betrodda miljöer.
|
||||
- **`docker`** — full containerisolering, tvingade säkerhetspolicyer, kräver Docker.
|
||||
|
||||
Ställ in `runtime.kind = "docker"` för strikt sandboxning eller nätverksisolering.
|
||||
|
||||
## Prenumerationsautentisering (OpenAI Codex / Claude Code / Gemini)
|
||||
|
||||
ZeroClaw stöder prenumerationsnativa autentiseringsprofiler (multikonto, krypterat i vila).
|
||||
|
||||
- Lagringsfil: `~/.zeroclaw/auth-profiles.json`
|
||||
- Krypteringsnyckel: `~/.zeroclaw/.secret_key`
|
||||
- Profil-ID-format: `<provider>:<profile_name>` (exempel: `openai-codex:work`)
|
||||
|
||||
```bash
|
||||
# OpenAI Codex OAuth (ChatGPT-prenumeration)
|
||||
zeroclaw auth login --provider openai-codex --device-code
|
||||
|
||||
# Gemini OAuth
|
||||
zeroclaw auth login --provider gemini --profile default
|
||||
|
||||
# Anthropic setup-token
|
||||
zeroclaw auth paste-token --provider anthropic --profile default --auth-kind authorization
|
||||
|
||||
# Kontrollera / uppdatera / byt profil
|
||||
zeroclaw auth status
|
||||
zeroclaw auth refresh --provider openai-codex --profile default
|
||||
zeroclaw auth use --provider openai-codex --profile work
|
||||
|
||||
# Kör agenten med prenumerationsautentisering
|
||||
zeroclaw agent --provider openai-codex -m "hello"
|
||||
zeroclaw agent --provider anthropic -m "hello"
|
||||
```
|
||||
|
||||
## Agentarbetsyta + färdigheter
|
||||
|
||||
Arbetsyterot: `~/.zeroclaw/workspace/` (konfigurerbart via config).
|
||||
|
||||
Injicerade promptfiler:
|
||||
- `IDENTITY.md` — agentpersonlighet och roll
|
||||
- `USER.md` — användarkontext och preferenser
|
||||
- `MEMORY.md` — långtidsfakta och lärdomar
|
||||
- `AGENTS.md` — sessionskonventioner och initieringsregler
|
||||
- `SOUL.md` — kärnidentitet och operationsprinciper
|
||||
|
||||
Färdigheter: `~/.zeroclaw/workspace/skills/<skill>/SKILL.md` eller `SKILL.toml`.
|
||||
|
||||
```bash
|
||||
# Lista installerade färdigheter
|
||||
zeroclaw skills list
|
||||
|
||||
# Installera från git
|
||||
zeroclaw skills install https://github.com/user/my-skill.git
|
||||
|
||||
# Säkerhetsgranskning före installation
|
||||
zeroclaw skills audit https://github.com/user/my-skill.git
|
||||
|
||||
# Ta bort en färdighet
|
||||
zeroclaw skills remove my-skill
|
||||
```
|
||||
|
||||
## CLI-kommandon
|
||||
|
||||
```bash
|
||||
# Arbetsytehantering
|
||||
zeroclaw onboard # Guidad installationsguide
|
||||
zeroclaw status # Visa daemon-/agentstatus
|
||||
zeroclaw doctor # Kör systemdiagnostik
|
||||
|
||||
# Gateway + daemon
|
||||
zeroclaw gateway # Starta gateway-server (127.0.0.1:42617)
|
||||
zeroclaw daemon # Starta full autonom körmiljö
|
||||
|
||||
# Agent
|
||||
zeroclaw agent # Interaktivt chattläge
|
||||
zeroclaw agent -m "message" # Enstaka meddelandeläge
|
||||
|
||||
# Tjänstehantering
|
||||
zeroclaw service install # Installera som OS-tjänst (launchd/systemd)
|
||||
zeroclaw service start|stop|restart|status
|
||||
|
||||
# Kanaler
|
||||
zeroclaw channel list # Lista konfigurerade kanaler
|
||||
zeroclaw channel doctor # Kontrollera kanalhälsa
|
||||
zeroclaw channel bind-telegram 123456789
|
||||
|
||||
# Cron + schemaläggning
|
||||
zeroclaw cron list # Lista schemalagda jobb
|
||||
zeroclaw cron add "*/5 * * * *" --prompt "Check system health"
|
||||
zeroclaw cron remove <id>
|
||||
|
||||
# Minne
|
||||
zeroclaw memory list # Lista minnesposter
|
||||
zeroclaw memory get <key> # Hämta ett minne
|
||||
zeroclaw memory stats # Minnesstatistik
|
||||
|
||||
# Autentiseringsprofiler
|
||||
zeroclaw auth login --provider <name>
|
||||
zeroclaw auth status
|
||||
zeroclaw auth use --provider <name> --profile <profile>
|
||||
|
||||
# Hårdvaruperiferienheter
|
||||
zeroclaw hardware discover # Sök efter anslutna enheter
|
||||
zeroclaw peripheral list # Lista anslutna periferienheter
|
||||
zeroclaw peripheral flash # Flasha firmware till enhet
|
||||
|
||||
# Migrering
|
||||
zeroclaw migrate openclaw --dry-run
|
||||
zeroclaw migrate openclaw
|
||||
|
||||
# Shell-kompletteringar
|
||||
source <(zeroclaw completions bash)
|
||||
zeroclaw completions zsh > ~/.zfunc/_zeroclaw
|
||||
```
|
||||
|
||||
Fullständig kommandoreferens: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
|
||||
<!-- markdownlint-disable MD001 MD024 -->
|
||||
|
||||
## Förutsättningar
|
||||
|
||||
<details>
|
||||
<summary><strong>Windows</strong></summary>
|
||||
|
||||
#### Obligatoriskt
|
||||
|
||||
1. **Visual Studio Build Tools** (tillhandahåller MSVC-länkaren och Windows SDK):
|
||||
|
||||
```powershell
|
||||
winget install Microsoft.VisualStudio.2022.BuildTools
|
||||
```
|
||||
|
||||
Under installationen (eller via Visual Studio Installer), välj arbetsbelastningen **"Desktop development with C++"**.
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```powershell
|
||||
winget install Rustlang.Rustup
|
||||
```
|
||||
|
||||
Efter installationen, öppna en ny terminal och kör `rustup default stable` för att säkerställa att stable-toolchainen är aktiv.
|
||||
|
||||
3. **Verifiera** att båda fungerar:
|
||||
```powershell
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Valfritt
|
||||
|
||||
- **Docker Desktop** — krävs bara om du använder [Docker sandboxad körmiljö](#körmiljöstöd-nuvarande) (`runtime.kind = "docker"`). Installera via `winget install Docker.DockerDesktop`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><strong>Linux / macOS</strong></summary>
|
||||
|
||||
#### Obligatoriskt
|
||||
|
||||
1. **Byggverktyg:**
|
||||
- **Linux (Debian/Ubuntu):** `sudo apt install build-essential pkg-config`
|
||||
- **Linux (Fedora/RHEL):** `sudo dnf group install development-tools && sudo dnf install pkg-config`
|
||||
- **macOS:** Installera Xcode Command Line Tools: `xcode-select --install`
|
||||
|
||||
2. **Rust toolchain:**
|
||||
|
||||
```bash
|
||||
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
|
||||
```
|
||||
|
||||
Se [rustup.rs](https://rustup.rs) för detaljer.
|
||||
|
||||
3. **Verifiera** att båda fungerar:
|
||||
```bash
|
||||
rustc --version
|
||||
cargo --version
|
||||
```
|
||||
|
||||
#### Enradsinstallerare
|
||||
|
||||
Eller hoppa över stegen ovan och installera allt (systemberoenden, Rust, ZeroClaw) med ett enda kommando:
|
||||
|
||||
```bash
|
||||
curl -LsSf https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash
|
||||
```
|
||||
|
||||
#### Kompileringsresurskrav
|
||||
|
||||
Att bygga från källkod kräver mer resurser än att köra den resulterande binären:
|
||||
|
||||
| Resurs | Minimum | Rekommenderat |
|
||||
| -------------- | ------- | ------------- |
|
||||
| **RAM + swap** | 2 GB | 4 GB+ |
|
||||
| **Ledigt disk**| 6 GB | 10 GB+ |
|
||||
|
||||
Om din värd ligger under minimum, använd förbyggda binärer:
|
||||
|
||||
```bash
|
||||
./install.sh --prefer-prebuilt
|
||||
```
|
||||
|
||||
För att kräva enbart binärinstallation utan källkods-fallback:
|
||||
|
||||
```bash
|
||||
./install.sh --prebuilt-only
|
||||
```
|
||||
|
||||
#### Valfritt
|
||||
|
||||
- **Docker** — krävs bara om du använder [Docker sandboxad körmiljö](#körmiljöstöd-nuvarande) (`runtime.kind = "docker"`). Installera via din pakethanterare eller [docker.com](https://docs.docker.com/engine/install/).
|
||||
|
||||
> **Notering:** Standard `cargo build --release` använder `codegen-units=1` för att minska toppkompileringstrycket. För snabbare byggen på kraftfulla maskiner, använd `cargo build --profile release-fast`.
|
||||
|
||||
</details>
|
||||
|
||||
<!-- markdownlint-enable MD001 MD024 -->
|
||||
|
||||
### Förbyggda binärer
|
||||
|
||||
Release-tillgångar publiceras för:
|
||||
|
||||
- Linux: `x86_64`, `aarch64`, `armv7`
|
||||
- macOS: `x86_64`, `aarch64`
|
||||
- Windows: `x86_64`
|
||||
|
||||
Ladda ner de senaste tillgångarna från:
|
||||
<https://github.com/zeroclaw-labs/zeroclaw/releases/latest>
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Använd dessa när du är förbi onboarding-flödet och vill ha den djupare referensen.
|
||||
|
||||
- Börja med [dokumentationsindexet](docs/README.md) för navigering och "vad finns var."
|
||||
- Läs [arkitekturöversikten](docs/architecture.md) för den fullständiga systemmodellen.
|
||||
- Använd [konfigurationsreferensen](docs/reference/api/config-reference.md) när du behöver varje nyckel och exempel.
|
||||
- Kör Gateway enligt boken med [operationsrunbook](docs/ops/operations-runbook.md).
|
||||
- Följ [ZeroClaw Onboard](#snabbstart) för en guidad installation.
|
||||
- Felsök vanliga problem med [felsökningsguiden](docs/ops/troubleshooting.md).
|
||||
- Granska [säkerhetsvägledning](docs/security/README.md) innan du exponerar något.
|
||||
|
||||
### Referensdokumentation
|
||||
|
||||
- Dokumentationshubb: [docs/README.md](docs/README.md)
|
||||
- Enhetlig dokumentations-TOC: [docs/SUMMARY.md](docs/SUMMARY.md)
|
||||
- Kommandoreferens: [docs/reference/cli/commands-reference.md](docs/reference/cli/commands-reference.md)
|
||||
- Konfigurationsreferens: [docs/reference/api/config-reference.md](docs/reference/api/config-reference.md)
|
||||
- Leverantörsreferens: [docs/reference/api/providers-reference.md](docs/reference/api/providers-reference.md)
|
||||
- Kanalreferens: [docs/reference/api/channels-reference.md](docs/reference/api/channels-reference.md)
|
||||
- Operationsrunbook: [docs/ops/operations-runbook.md](docs/ops/operations-runbook.md)
|
||||
- Felsökning: [docs/ops/troubleshooting.md](docs/ops/troubleshooting.md)
|
||||
|
||||
### Samarbetsdokumentation
|
||||
|
||||
- Bidragsguide: [CONTRIBUTING.md](CONTRIBUTING.md)
|
||||
- PR-arbetsflödespolicy: [docs/contributing/pr-workflow.md](docs/contributing/pr-workflow.md)
|
||||
- CI-arbetsflödesguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Granskningsplaybook: [docs/contributing/reviewer-playbook.md](docs/contributing/reviewer-playbook.md)
|
||||
- Säkerhetsutlämnandepolicy: [SECURITY.md](SECURITY.md)
|
||||
- Dokumentationsmall: [docs/contributing/doc-template.md](docs/contributing/doc-template.md)
|
||||
|
||||
### Distribution + drift
|
||||
|
||||
- Nätverksdistributionsguide: [docs/ops/network-deployment.md](docs/ops/network-deployment.md)
|
||||
- Proxy-agentplaybook: [docs/ops/proxy-agent-playbook.md](docs/ops/proxy-agent-playbook.md)
|
||||
- Hårdvaruguider: [docs/hardware/README.md](docs/hardware/README.md)
|
||||
|
||||
## Smooth Crab 🦀
|
||||
|
||||
ZeroClaw byggdes för smooth crab 🦀, en snabb och effektiv AI-assistent. Byggd av Argenis De La Rosa och gemenskapen.
|
||||
|
||||
- [zeroclawlabs.ai](https://zeroclawlabs.ai)
|
||||
- [@zeroclawlabs](https://x.com/zeroclawlabs)
|
||||
|
||||
## Stöd ZeroClaw
|
||||
|
||||
Om ZeroClaw hjälper ditt arbete och du vill stödja pågående utveckling kan du donera här:
|
||||
|
||||
<a href="https://buymeacoffee.com/argenistherose"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-Donate-yellow.svg?style=for-the-badge&logo=buy-me-a-coffee" alt="Buy Me a Coffee" /></a>
|
||||
|
||||
### 🙏 Särskilt tack
|
||||
|
||||
Ett hjärtligt tack till de gemenskaper och institutioner som inspirerar och driver detta open source-arbete:
|
||||
|
||||
- **Harvard University** — för att främja intellektuell nyfikenhet och tänja gränserna för vad som är möjligt.
|
||||
- **MIT** — för att försvara öppen kunskap, öppen källkod och tron att teknologi bör vara tillgänglig för alla.
|
||||
- **Sundai Club** — för gemenskapen, energin och den outtröttliga driften att bygga saker som spelar roll.
|
||||
- **Världen & bortom** 🌍✨ — till varje bidragsgivare, drömmare och byggare där ute som gör öppen källkod till en kraft för gott. Det här är för er.
|
||||
|
||||
Vi bygger öppet eftersom de bästa idéerna kommer från överallt. Om du läser detta är du en del av det. Välkommen. 🦀❤️
|
||||
|
||||
## Bidra
|
||||
|
||||
Ny till ZeroClaw? Leta efter ärenden märkta [`good first issue`](https://github.com/zeroclaw-labs/zeroclaw/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) — se vår [Bidragsguide](CONTRIBUTING.md#first-time-contributors) för hur du kommer igång. AI/vibe-kodade PR:er är välkomna! 🤖
|
||||
|
||||
Se [CONTRIBUTING.md](CONTRIBUTING.md) och [CLA.md](docs/contributing/cla.md). Implementera en trait, skicka in en PR:
|
||||
|
||||
- CI-arbetsflödesguide: [docs/contributing/ci-map.md](docs/contributing/ci-map.md)
|
||||
- Ny `Provider` → `src/providers/`
|
||||
- Ny `Channel` → `src/channels/`
|
||||
- Ny `Observer` → `src/observability/`
|
||||
- Nytt `Tool` → `src/tools/`
|
||||
- Nytt `Memory` → `src/memory/`
|
||||
- Ny `Tunnel` → `src/tunnel/`
|
||||
- Ny `Peripheral` → `src/peripherals/`
|
||||
- Ny `Skill` → `~/.zeroclaw/workspace/skills/<name>/`
|
||||
|
||||
<!-- BEGIN:RECENT_CONTRIBUTORS -->
|
||||
<!-- END:RECENT_CONTRIBUTORS -->
|
||||
|
||||
## ⚠️ Officiellt repository & varning för imitation
|
||||
|
||||
**Detta är det enda officiella ZeroClaw-repositoryt:**
|
||||
|
||||
> https://github.com/zeroclaw-labs/zeroclaw
|
||||
|
||||
Alla andra repositorier, organisationer, domäner eller paket som hävdar att vara "ZeroClaw" eller antyder anslutning till ZeroClaw Labs är **obehöriga och inte affilierade med detta projekt**. Kända obehöriga forkar listas i [TRADEMARK.md](docs/maintainers/trademark.md).
|
||||
|
||||
Om du stöter på imitation eller varumärkesmissbruk, vänligen [öppna ett ärende](https://github.com/zeroclaw-labs/zeroclaw/issues).
|
||||
|
||||
---
|
||||
|
||||
## Licens
|
||||
|
||||
ZeroClaw är dubbellicensierat för maximal öppenhet och bidragsgivarskydd:
|
||||
|
||||
| Licens | Användningsfall |
|
||||
|--------|-----------------|
|
||||
| [MIT](LICENSE-MIT) | Öppen källkod, forskning, akademiskt, personligt bruk |
|
||||
| [Apache 2.0](LICENSE-APACHE) | Patentskydd, institutionell, kommersiell distribution |
|
||||
|
||||
Du kan välja endera licens. **Bidragsgivare beviljar automatiskt rättigheter under båda** — se [CLA.md](docs/contributing/cla.md) för det fullständiga bidragsgivaravtalet.
|
||||
|
||||
### Varumärke
|
||||
|
||||
**ZeroClaw**-namnet och logotypen är varumärken som tillhör ZeroClaw Labs. Denna licens beviljar inte tillstånd att använda dem för att antyda stöd eller anslutning. Se [TRADEMARK.md](docs/maintainers/trademark.md) för tillåtna och förbjudna användningar.
|
||||
|
||||
### Bidragsgivarskydd
|
||||
|
||||
- Du **behåller upphovsrätten** till dina bidrag
|
||||
- **Patentbeviljande** (Apache 2.0) skyddar dig från patentkrav från andra bidragsgivare
|
||||
- Dina bidrag är **permanent tillskrivna** i commit-historik och [NOTICE](NOTICE)
|
||||
- Inga varumärkesrättigheter överförs genom att bidra
|
||||
|
||||
---
|
||||
|
||||
**ZeroClaw** — Noll overhead. Noll kompromiss. Distribuera var som helst. Byt ut vad som helst. 🦀
|
||||
|
||||
## Bidragsgivare
|
||||
|
||||
<a href="https://github.com/zeroclaw-labs/zeroclaw/graphs/contributors">
|
||||
<img src="https://contrib.rocks/image?repo=zeroclaw-labs/zeroclaw" alt="ZeroClaw-bidragsgivare" />
|
||||
</a>
|
||||
|
||||
Denna lista genereras från GitHub-bidragsgivargrafen och uppdateras automatiskt.
|
||||
|
||||
## Stjärnhistorik
|
||||
|
||||
<p align="center">
|
||||
<a href="https://www.star-history.com/#zeroclaw-labs/zeroclaw&type=date&legend=top-left">
|
||||
<picture>
|
||||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&theme=dark&legend=top-left" />
|
||||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
<img alt="Star History Chart" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
|
||||
</picture>
|
||||
</a>
|
||||
</p>
|
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in New Issue
Block a user