polymech/zeroclaw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge branch 'main' into supersede-pr-1872-20260226154155-3787543-theirs

Browse Source
This commit is contained in:
Argenis
2026-02-26 23:43:00 -05:00
committed by GitHub
parent e92a976226 e3e4878ade
commit 96de49d57b
199 changed files with 28803 additions and 9401 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.editorconfig
+7
View File
@@ -15,6 +15,9 @@ indent_size = 4
# Trailing whitespace is significant in Markdown (line breaks).
trim_trailing_whitespace = false
[*.go]
indent_style = tab
[*.{yml,yaml}]
indent_size = 2
@@ -23,3 +26,7 @@ indent_size = 2
[Dockerfile]
indent_size = 4
[*.nix]
indent_style = space
indent_size = 2
.github/CODEOWNERS
+16 -16
View File
@@ -1,5 +1,5 @@
# Default owner for all files
* @chumyin
* @theonlyhennygod
# Important functional modules
/src/agent/** @theonlyhennygod
@@ -13,20 +13,20 @@
/Cargo.lock @theonlyhennygod
# Security / tests / CI-CD ownership
/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
/src/security/** @theonlyhennygod
/tests/** @theonlyhennygod
/.github/** @theonlyhennygod
/.github/workflows/** @theonlyhennygod
/.github/codeql/** @theonlyhennygod
/.github/dependabot.yml @theonlyhennygod
/SECURITY.md @theonlyhennygod
/docs/actions-source-policy.md @theonlyhennygod
/docs/ci-map.md @theonlyhennygod
# Docs & governance
/docs/** @chumyin
/AGENTS.md @chumyin
/CLAUDE.md @chumyin
/CONTRIBUTING.md @chumyin
/docs/pr-workflow.md @chumyin
/docs/reviewer-playbook.md @chumyin
/docs/** @theonlyhennygod
/AGENTS.md @theonlyhennygod
/CLAUDE.md @theonlyhennygod
/CONTRIBUTING.md @theonlyhennygod
/docs/pr-workflow.md @theonlyhennygod
/docs/reviewer-playbook.md @theonlyhennygod
.github/actionlint.yaml
+2 -3
View File
@@ -1,5 +1,4 @@
self-hosted-runner:
labels:
- Linux
- X64
- racknerd
- blacksmith-2vcpu-ubuntu-2404
- aws-india
.github/pull_request_template.md
+3 -2
View File
@@ -2,7 +2,7 @@
Describe this PR in 2-5 bullets:
- Base branch target (`main`):
- Base branch target (`dev` for normal contributions; `main` only for `dev` promotion):
- Problem:
- Why it matters:
- What changed:
@@ -28,7 +28,8 @@ Describe this PR in 2-5 bullets:
- Related #
- Depends on # (if stacked)
- Supersedes # (if replacing older PR)
- External tracking link(s) (optional):
- Linear issue key(s) (required, e.g. `RMN-123`):
- Linear issue URL(s):
## Supersede Attribution (required when `Supersedes #` is used)
.github/release/release-artifact-contract.json
+1
View File
@@ -8,6 +8,7 @@
"zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz",
"zeroclaw-armv7-linux-androideabi.tar.gz",
"zeroclaw-aarch64-linux-android.tar.gz",
"zeroclaw-x86_64-unknown-freebsd.tar.gz",
"zeroclaw-x86_64-apple-darwin.tar.gz",
"zeroclaw-aarch64-apple-darwin.tar.gz",
"zeroclaw-x86_64-pc-windows-msvc.zip"
.github/security/deny-ignore-governance.json
+3 -3
View File
@@ -5,21 +5,21 @@
"id": "RUSTSEC-2025-0141",
"owner": "repo-maintainers",
"reason": "Transitive via probe-rs in current release path; tracked for replacement when probe-rs updates.",
"ticket": "SEC-21",
"ticket": "RMN-21",
"expires_on": "2026-12-31"
},
{
"id": "RUSTSEC-2024-0384",
"owner": "repo-maintainers",
"reason": "Upstream rust-nostr advisory mitigation is still in progress; monitor until released fix lands.",
"ticket": "SEC-21",
"ticket": "RMN-21",
"expires_on": "2026-12-31"
},
{
"id": "RUSTSEC-2024-0388",
"owner": "repo-maintainers",
"reason": "Transitive via matrix-sdk indexeddb dependency chain in current matrix release line; track removal when upstream drops derivative.",
"ticket": "SEC-21",
"ticket": "RMN-21",
"expires_on": "2026-12-31"
}
]
.github/security/gitleaks-allowlist-governance.json
+7 -7
View File
@@ -5,35 +5,35 @@
"pattern": "src/security/leak_detector\\.rs",
"owner": "repo-maintainers",
"reason": "Fixture patterns are intentionally embedded for regression tests in leak detector logic.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
},
{
"pattern": "src/agent/loop_\\.rs",
"owner": "repo-maintainers",
"reason": "Contains escaped template snippets used for command orchestration and parser coverage.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
},
{
"pattern": "src/security/secrets\\.rs",
"owner": "repo-maintainers",
"reason": "Contains detector test vectors and redaction examples required for secret scanning tests.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
},
{
"pattern": "docs/(i18n/vi/|vi/)?zai-glm-setup\\.md",
"owner": "repo-maintainers",
"reason": "Documentation contains literal environment variable placeholders for onboarding commands.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
},
{
"pattern": "\\.github/workflows/pub-release\\.yml",
"owner": "repo-maintainers",
"reason": "Release workflow emits masked authorization header examples during registry smoke checks.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
}
],
@@ -42,14 +42,14 @@
"pattern": "Authorization: Bearer \\$\\{[^}]+\\}",
"owner": "repo-maintainers",
"reason": "Intentional placeholder used in docs/workflow snippets for safe header examples.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
},
{
"pattern": "curl -sS -o /tmp/ghcr-release-manifest\\.json -w \"%\\{http_code\\}\"",
"owner": "repo-maintainers",
"reason": "Release smoke command string is non-secret telemetry and should not be flagged as credential leakage.",
"ticket": "SEC-13",
"ticket": "RMN-13",
"expires_on": "2026-12-31"
}
]
.github/workflows/ci-build-fast.yml
+7 -4
View File
@@ -17,12 +17,15 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
changes:
name: Detect Change Scope
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
outputs:
rust_changed: ${{ steps.scope.outputs.rust_changed }}
docs_only: ${{ steps.scope.outputs.docs_only }}
@@ -42,8 +45,8 @@ jobs:
build-fast:
name: Build (Fast)
needs: [changes]
if: needs.changes.outputs.rust_changed == 'true'
runs-on: [self-hosted, Linux, X64]
if: needs.changes.outputs.rust_changed == 'true' || needs.changes.outputs.workflow_changed == 'true'
runs-on: [self-hosted, aws-india]
timeout-minutes: 25
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -52,7 +55,7 @@ jobs:
with:
toolchain: 1.92.0
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: fast-build
cache-targets: true
.github/workflows/ci-canary-gate.yml
+8 -2
View File
@@ -80,10 +80,16 @@ permissions:
contents: read
actions: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
canary-plan:
name: Canary Plan
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
outputs:
mode: ${{ steps.inputs.outputs.mode }}
@@ -231,7 +237,7 @@ jobs:
name: Canary Execute
needs: [canary-plan]
if: github.event_name == 'workflow_dispatch' && needs.canary-plan.outputs.mode == 'execute' && needs.canary-plan.outputs.ready_to_execute == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 10
permissions:
contents: write
.github/workflows/ci-change-audit.yml
+14 -2
View File
@@ -41,10 +41,16 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
audit:
name: CI Change Audit
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 15
steps:
- name: Checkout
@@ -59,7 +65,13 @@ jobs:
set -euo pipefail
head_sha="$(git rev-parse HEAD)"
if [ "${GITHUB_EVENT_NAME}" = "pull_request" ]; then
base_sha="${{ github.event.pull_request.base.sha }}"
# For pull_request events, checkout uses refs/pull/*/merge; HEAD^1 is the
# effective base commit for this synthesized merge and avoids stale base.sha.
if git rev-parse --verify HEAD^1 >/dev/null 2>&1; then
base_sha="$(git rev-parse HEAD^1)"
else
base_sha="${{ github.event.pull_request.base.sha }}"
fi
elif [ "${GITHUB_EVENT_NAME}" = "push" ]; then
base_sha="${{ github.event.before }}"
else
.github/workflows/ci-connectivity-probes.yml
+7 -1
View File
@@ -19,10 +19,16 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
probes:
name: Provider Connectivity Probes
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
.github/workflows/ci-provider-connectivity.yml
+7 -1
View File
@@ -30,10 +30,16 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
probe:
name: Provider Connectivity Probe
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- name: Checkout
.github/workflows/ci-reproducible-build.yml
+4 -1
View File
@@ -42,12 +42,15 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
reproducibility:
name: Reproducible Build Probe
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 45
steps:
- name: Checkout
.github/workflows/ci-rollback.yml
+8 -2
View File
@@ -55,10 +55,16 @@ permissions:
contents: read
actions: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
rollback-plan:
name: Rollback Guard Plan
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
outputs:
branch: ${{ steps.plan.outputs.branch }}
@@ -182,7 +188,7 @@ jobs:
name: Rollback Execute Actions
needs: [rollback-plan]
if: github.event_name == 'workflow_dispatch' && needs.rollback-plan.outputs.mode == 'execute' && needs.rollback-plan.outputs.ready_to_execute == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 15
permissions:
contents: write
.github/workflows/ci-run.yml
+121 -58
View File
@@ -5,6 +5,8 @@ on:
branches: [dev, main]
pull_request:
branches: [dev, main]
merge_group:
branches: [dev, main]
concurrency:
group: ci-${{ github.event.pull_request.number || github.sha }}
@@ -14,12 +16,15 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
changes:
name: Detect Change Scope
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
outputs:
docs_only: ${{ steps.scope.outputs.docs_only }}
docs_changed: ${{ steps.scope.outputs.docs_changed }}
@@ -30,42 +35,21 @@ jobs:
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
with:
fetch-depth: 1
- name: Ensure diff base is available
shell: bash
env:
BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
run: |
set -euo pipefail
if [ -z "${BASE_SHA}" ]; then
echo "BASE_SHA is empty; detect_change_scope will use fallback mode."
exit 0
fi
if git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
echo "BASE_SHA already present: ${BASE_SHA}"
exit 0
fi
echo "Fetching base commit ${BASE_SHA} for scope detection..."
if ! git fetch --no-tags --depth=1 origin "${BASE_SHA}"; then
echo "::warning::Unable to fetch BASE_SHA=${BASE_SHA}; detect_change_scope will use fallback mode."
fi
fetch-depth: 0
- name: Detect docs-only changes
id: scope
shell: bash
env:
EVENT_NAME: ${{ github.event_name }}
BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event.before }}
BASE_SHA: ${{ github.event_name == 'pull_request' && github.event.pull_request.base.sha || github.event_name == 'merge_group' && github.event.merge_group.base_sha || github.event.before }}
run: ./scripts/ci/detect_change_scope.sh
lint:
name: Lint Gate (Format + Clippy + Strict Delta)
needs: [changes]
if: needs.changes.outputs.rust_changed == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 25
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -76,6 +60,8 @@ jobs:
toolchain: 1.92.0
components: rustfmt, clippy
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: ci-run-lint
- name: Run rust quality gate
run: ./scripts/ci/rust_quality_gate.sh
- name: Run strict lint delta gate
@@ -87,7 +73,7 @@ jobs:
name: Test
needs: [changes, lint]
if: needs.changes.outputs.rust_changed == 'true' && needs.lint.result == 'success'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 30
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -95,6 +81,8 @@ jobs:
with:
toolchain: 1.92.0
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: ci-run-test
- name: Run tests
run: cargo test --locked --verbose
@@ -102,7 +90,7 @@ jobs:
name: Build (Smoke)
needs: [changes]
if: needs.changes.outputs.rust_changed == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
@@ -111,16 +99,66 @@ jobs:
with:
toolchain: 1.92.0
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: ci-run-build
cache-targets: true
- name: Build binary (smoke check)
run: cargo build --profile release-fast --locked --verbose
- name: Check binary size
run: bash scripts/ci/check_binary_size.sh target/release-fast/zeroclaw
flake-probe:
name: Test Flake Retry Probe
needs: [changes, lint, test]
if: always() && needs.changes.outputs.rust_changed == 'true' && (github.event_name != 'pull_request' || contains(github.event.pull_request.labels.*.name, 'ci:full'))
runs-on: [self-hosted, aws-india]
timeout-minutes: 25
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- uses: dtolnay/rust-toolchain@631a55b12751854ce901bb631d5902ceb48146f7 # stable
with:
toolchain: 1.92.0
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: ci-run-flake-probe
- name: Probe flaky failure via single retry
shell: bash
env:
INITIAL_TEST_RESULT: ${{ needs.test.result }}
BLOCK_ON_FLAKE: ${{ vars.CI_BLOCK_ON_FLAKE_SUSPECTED || 'false' }}
run: |
set -euo pipefail
mkdir -p artifacts
python3 scripts/ci/flake_retry_probe.py \
--initial-result "${INITIAL_TEST_RESULT}" \
--retry-command "cargo test --locked --verbose" \
--output-json artifacts/flake-probe.json \
--output-md artifacts/flake-probe.md \
--block-on-flake "${BLOCK_ON_FLAKE}"
- name: Publish flake probe summary
if: always()
shell: bash
run: |
set -euo pipefail
if [ -f artifacts/flake-probe.md ]; then
cat artifacts/flake-probe.md >> "$GITHUB_STEP_SUMMARY"
else
echo "Flake probe report missing." >> "$GITHUB_STEP_SUMMARY"
fi
- name: Upload flake probe artifact
if: always()
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: test-flake-probe
path: artifacts/flake-probe.*
if-no-files-found: ignore
retention-days: 14
docs-only:
name: Docs-Only Fast Path
needs: [changes]
if: needs.changes.outputs.docs_only == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Skip heavy jobs for docs-only change
run: echo "Docs-only change detected. Rust lint/test/build skipped."
@@ -129,7 +167,7 @@ jobs:
name: Non-Rust Fast Path
needs: [changes]
if: needs.changes.outputs.docs_only != 'true' && needs.changes.outputs.rust_changed != 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Skip Rust jobs for non-Rust change scope
run: echo "No Rust-impacting files changed. Rust lint/test/build skipped."
@@ -138,34 +176,12 @@ jobs:
name: Docs Quality
needs: [changes]
if: needs.changes.outputs.docs_changed == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 15
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
with:
fetch-depth: 1
- name: Ensure diff base is available
shell: bash
env:
BASE_SHA: ${{ needs.changes.outputs.base_sha }}
run: |
set -euo pipefail
if [ -z "${BASE_SHA}" ]; then
echo "BASE_SHA is empty; docs gate will fallback to full-file lint."
exit 0
fi
if git cat-file -e "${BASE_SHA}^{commit}" 2>/dev/null; then
echo "BASE_SHA already present: ${BASE_SHA}"
exit 0
fi
echo "Fetching base commit ${BASE_SHA} for docs diff..."
if ! git fetch --no-tags --depth=1 origin "${BASE_SHA}"; then
echo "::warning::Unable to fetch BASE_SHA=${BASE_SHA}; docs gate will fallback to full-file lint."
exit 0
fi
fetch-depth: 0
- name: Markdown lint (changed lines only)
env:
@@ -215,7 +231,7 @@ jobs:
name: Lint Feedback
if: github.event_name == 'pull_request'
needs: [changes, lint, docs-quality]
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
pull-requests: write
@@ -241,7 +257,7 @@ jobs:
name: Workflow Owner Approval
needs: [changes]
if: github.event_name == 'pull_request' && needs.changes.outputs.workflow_changed == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
pull-requests: read
@@ -258,11 +274,34 @@ jobs:
const script = require('./.github/workflows/scripts/ci_workflow_owner_approval.js');
await script({ github, context, core });
human-review-approval:
name: Human Review Approval
needs: [changes]
if: github.event_name == 'pull_request'
runs-on: [self-hosted, aws-india]
permissions:
contents: read
pull-requests: read
steps:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
with:
ref: ${{ github.event.pull_request.base.sha }}
- name: Require at least one human approving review
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
env:
HUMAN_REVIEW_BOT_LOGINS: ${{ vars.HUMAN_REVIEW_BOT_LOGINS }}
with:
script: |
const script = require('./.github/workflows/scripts/ci_human_review_guard.js');
await script({ github, context, core });
license-file-owner-guard:
name: License File Owner Guard
needs: [changes]
if: github.event_name == 'pull_request'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
pull-requests: read
@@ -279,8 +318,8 @@ jobs:
ci-required:
name: CI Required Gate
if: always()
needs: [changes, lint, test, build, docs-only, non-rust, docs-quality, lint-feedback, workflow-owner-approval, license-file-owner-guard]
runs-on: [self-hosted, Linux, X64]
needs: [changes, lint, test, build, flake-probe, docs-only, non-rust, docs-quality, lint-feedback, workflow-owner-approval, human-review-approval, license-file-owner-guard]
runs-on: [self-hosted, aws-india]
steps:
- name: Enforce required status
shell: bash
@@ -293,15 +332,21 @@ jobs:
workflow_changed="${{ needs.changes.outputs.workflow_changed }}"
docs_result="${{ needs.docs-quality.result }}"
workflow_owner_result="${{ needs.workflow-owner-approval.result }}"
human_review_result="${{ needs.human-review-approval.result }}"
license_owner_result="${{ needs.license-file-owner-guard.result }}"
if [ "${{ needs.changes.outputs.docs_only }}" = "true" ]; then
echo "workflow_owner_approval=${workflow_owner_result}"
echo "human_review_approval=${human_review_result}"
echo "license_file_owner_guard=${license_owner_result}"
if [ "$event_name" = "pull_request" ] && [ "$workflow_changed" = "true" ] && [ "$workflow_owner_result" != "success" ]; then
echo "Workflow files changed but workflow owner approval gate did not pass."
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$human_review_result" != "success" ]; then
echo "Human review approval guard did not pass."
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$license_owner_result" != "success" ]; then
echo "License file owner guard did not pass."
exit 1
@@ -317,11 +362,16 @@ jobs:
if [ "$rust_changed" != "true" ]; then
echo "rust_changed=false (non-rust fast path)"
echo "workflow_owner_approval=${workflow_owner_result}"
echo "human_review_approval=${human_review_result}"
echo "license_file_owner_guard=${license_owner_result}"
if [ "$event_name" = "pull_request" ] && [ "$workflow_changed" = "true" ] && [ "$workflow_owner_result" != "success" ]; then
echo "Workflow files changed but workflow owner approval gate did not pass."
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$human_review_result" != "success" ]; then
echo "Human review approval guard did not pass."
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$license_owner_result" != "success" ]; then
echo "License file owner guard did not pass."
exit 1
@@ -338,13 +388,16 @@ jobs:
lint_strict_delta_result="${{ needs.lint.result }}"
test_result="${{ needs.test.result }}"
build_result="${{ needs.build.result }}"
flake_result="${{ needs.flake-probe.result }}"
echo "lint=${lint_result}"
echo "lint_strict_delta=${lint_strict_delta_result}"
echo "test=${test_result}"
echo "build=${build_result}"
echo "flake_probe=${flake_result}"
echo "docs=${docs_result}"
echo "workflow_owner_approval=${workflow_owner_result}"
echo "human_review_approval=${human_review_result}"
echo "license_file_owner_guard=${license_owner_result}"
if [ "$event_name" = "pull_request" ] && [ "$workflow_changed" = "true" ] && [ "$workflow_owner_result" != "success" ]; then
@@ -352,6 +405,11 @@ jobs:
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$human_review_result" != "success" ]; then
echo "Human review approval guard did not pass."
exit 1
fi
if [ "$event_name" = "pull_request" ] && [ "$license_owner_result" != "success" ]; then
echo "License file owner guard did not pass."
exit 1
@@ -375,6 +433,11 @@ jobs:
exit 1
fi
if [ "$flake_result" != "success" ]; then
echo "Flake probe did not pass under current blocking policy."
exit 1
fi
if [ "$docs_changed" = "true" ] && [ "$docs_result" != "success" ]; then
echo "Push changed docs, but docs-quality did not pass."
exit 1
.github/workflows/ci-supply-chain-provenance.yml
+4 -1
View File
@@ -23,12 +23,15 @@ permissions:
id-token: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
provenance:
name: Build + Provenance Bundle
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 35
steps:
- name: Checkout
.github/workflows/docs-deploy.yml
+23 -147
View File
@@ -47,10 +47,16 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
docs-quality:
name: Docs Quality Gate
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
outputs:
docs_files: ${{ steps.scope.outputs.docs_files }}
@@ -197,7 +203,7 @@ jobs:
name: Docs Preview Artifact
needs: [docs-quality]
if: github.event_name == 'pull_request' || (github.event_name == 'workflow_dispatch' && github.event.inputs.deploy_target == 'preview')
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 15
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -210,78 +216,13 @@ jobs:
mkdir -p site/docs
cp -R docs/. site/docs/
cp README.md site/README.md
cat > site/index.html <<'EOF'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>ZeroClaw Docs Preview</title>
<style>
:root { color-scheme: light; }
body {
margin: 0;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
background: #f7f8fb;
color: #1f2937;
}
.container {
max-width: 900px;
margin: 48px auto;
padding: 0 20px;
}
.card {
background: #fff;
border: 1px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
}
h1 { margin-top: 0; }
a { color: #2563eb; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { line-height: 1.9; }
.muted { color: #6b7280; font-size: 14px; }
</style>
</head>
<body>
<main class="container">
<section class="card">
<h1>ZeroClaw Docs Preview</h1>
<p class="muted">Generated by <code>.github/workflows/docs-deploy.yml</code>.</p>
<ul>
<li><a href="./README.md">Repository README</a></li>
<li><a href="./docs/index.html">Docs Navigation</a></li>
<li><a href="./docs/README.md">Docs Home (Markdown)</a></li>
<li><a href="./docs/SUMMARY.md">Docs Summary (Markdown)</a></li>
</ul>
</section>
</main>
</body>
</html>
EOF
cat > site/docs/index.html <<'EOF'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>ZeroClaw Docs Navigation</title>
<style>
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 32px; color: #111827; }
a { color: #2563eb; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { line-height: 1.9; }
</style>
</head>
<body>
<h1>ZeroClaw Docs Navigation</h1>
<ul>
<li><a href="../index.html">Back to site home</a></li>
<li><a href="./README.md">Docs Home</a></li>
<li><a href="./SUMMARY.md">Docs Summary</a></li>
</ul>
</body>
</html>
cat > site/index.md <<'EOF'
# ZeroClaw Docs Preview
This preview bundle is produced by `.github/workflows/docs-deploy.yml`.
- [Repository README](./README.md)
- [Docs Home](./docs/README.md)
EOF
- name: Upload preview artifact
@@ -296,7 +237,7 @@ jobs:
name: Deploy Docs to GitHub Pages
needs: [docs-quality]
if: needs.docs-quality.outputs.deploy_target == 'production' && needs.docs-quality.outputs.ready_to_deploy == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
permissions:
contents: read
@@ -318,78 +259,13 @@ jobs:
mkdir -p site/docs
cp -R docs/. site/docs/
cp README.md site/README.md
cat > site/index.html <<'EOF'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>ZeroClaw Documentation</title>
<style>
:root { color-scheme: light; }
body {
margin: 0;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
background: #f7f8fb;
color: #1f2937;
}
.container {
max-width: 960px;
margin: 48px auto;
padding: 0 20px;
}
.card {
background: #fff;
border: 1px solid #e5e7eb;
border-radius: 12px;
padding: 24px;
}
h1 { margin-top: 0; }
a { color: #2563eb; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { line-height: 1.9; }
.muted { color: #6b7280; font-size: 14px; }
</style>
</head>
<body>
<main class="container">
<section class="card">
<h1>ZeroClaw Documentation</h1>
<p class="muted">Automatically deployed from <code>main</code> via <code>.github/workflows/docs-deploy.yml</code>.</p>
<ul>
<li><a href="./README.md">Repository README</a></li>
<li><a href="./docs/index.html">Docs Navigation</a></li>
<li><a href="./docs/README.md">Docs Home (Markdown)</a></li>
<li><a href="./docs/SUMMARY.md">Docs Summary (Markdown)</a></li>
</ul>
</section>
</main>
</body>
</html>
EOF
cat > site/docs/index.html <<'EOF'
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>ZeroClaw Docs Navigation</title>
<style>
body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; margin: 32px; color: #111827; }
a { color: #2563eb; text-decoration: none; }
a:hover { text-decoration: underline; }
ul { line-height: 1.9; }
</style>
</head>
<body>
<h1>ZeroClaw Docs Navigation</h1>
<ul>
<li><a href="../index.html">Back to site home</a></li>
<li><a href="./README.md">Docs Home</a></li>
<li><a href="./SUMMARY.md">Docs Summary</a></li>
</ul>
</body>
</html>
cat > site/index.md <<'EOF'
# ZeroClaw Documentation
This site is deployed automatically from `main` by `.github/workflows/docs-deploy.yml`.
- [Repository README](./README.md)
- [Docs Home](./docs/README.md)
EOF
- name: Publish deploy source summary
.github/workflows/feature-matrix.yml
+30 -7
View File
@@ -52,12 +52,15 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
resolve-profile:
name: Resolve Matrix Profile
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
outputs:
profile: ${{ steps.resolve.outputs.profile }}
lane_job_prefix: ${{ steps.resolve.outputs.lane_job_prefix }}
@@ -129,7 +132,7 @@ jobs:
feature-check:
name: ${{ needs.resolve-profile.outputs.lane_job_prefix }} (${{ matrix.name }})
needs: [resolve-profile]
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: ${{ fromJSON(needs.resolve-profile.outputs.lane_timeout_minutes) }}
strategy:
fail-fast: false
@@ -160,15 +163,35 @@ jobs:
with:
toolchain: 1.92.0
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: feature-matrix-${{ matrix.name }}
- name: Install Linux deps for all-features lane
- name: Ensure Linux deps for all-features lane
if: matrix.install_libudev
shell: bash
run: |
sudo apt-get update -qq
sudo apt-get install -y --no-install-recommends libudev-dev pkg-config
set -euo pipefail
if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists libudev; then
echo "libudev development headers already available; skipping apt install."
exit 0
fi
echo "Installing missing libudev build dependencies..."
for attempt in 1 2 3; do
if sudo apt-get update -qq -o DPkg::Lock::Timeout=300 && \
sudo apt-get install -y --no-install-recommends --no-upgrade -o DPkg::Lock::Timeout=300 libudev-dev pkg-config; then
echo "Dependency installation succeeded on attempt ${attempt}."
exit 0
fi
if [ "$attempt" -eq 3 ]; then
echo "Failed to install libudev-dev/pkg-config after ${attempt} attempts." >&2
exit 1
fi
echo "Dependency installation failed on attempt ${attempt}; retrying in 10s..."
sleep 10
done
- name: Run matrix lane command
id: lane
@@ -262,7 +285,7 @@ jobs:
name: ${{ needs.resolve-profile.outputs.summary_job_name }}
needs: [resolve-profile, feature-check]
if: always()
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
.github/workflows/main-branch-flow.md
+5 -5
View File
@@ -206,7 +206,7 @@ Canary policy lane:
1. Workflow-file changes (`.github/workflows/**`) activate owner-approval gate in `ci-run.yml`.
2. PR lint/test strictness is intentionally controlled by `ci:full` label.
3. `pr-intake-checks.yml` validates PR-template completeness and patch safety hints; no external tracker key is required.
3. `pr-intake-checks.yml` now blocks PRs missing a Linear issue key (`RMN-*`, `CDV-*`, `COM-*`) to keep execution mapped to Linear.
4. `sec-audit.yml` runs on PR/push/merge queue (`merge_group`), plus scheduled weekly.
5. `ci-change-audit.yml` enforces pinned `uses:` references for CI/security workflow changes.
6. `sec-audit.yml` includes deny policy hygiene checks (`deny_policy_guard.py`) before cargo-deny.
@@ -219,11 +219,11 @@ Canary policy lane:
## Mermaid Diagrams
### PR to Main
### PR to Dev
```mermaid
flowchart TD
A["PR opened or updated -> main"] --> B["pull_request_target lane"]
A["PR opened or updated -> dev"] --> B["pull_request_target lane"]
B --> B1["pr-intake-checks.yml"]
B --> B2["pr-labeler.yml"]
B --> B3["pr-auto-response.yml"]
@@ -237,7 +237,7 @@ flowchart TD
D --> E{"Checks + review policy pass?"}
E -->|No| F["PR stays open"]
E -->|Yes| G["Merge PR"]
G --> H["push event on main"]
G --> H["push event on dev"]
```
### Promotion and Release
@@ -246,7 +246,7 @@ flowchart TD
flowchart TD
D0["Commit reaches dev"] --> B0["ci-run.yml"]
D0 --> C0["sec-audit.yml"]
P["PR to main"] --> PG["main-promotion-gate.yml"]
P["Promotion PR dev -> main"] --> PG["main-promotion-gate.yml"]
PG --> M["Merge to main"]
M --> A["Commit reaches main"]
A --> B["ci-run.yml"]
.github/workflows/main-promotion-gate.yml
+35 -5
View File
@@ -11,12 +11,18 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
enforce-dev-promotion:
name: Enforce Dev -> Main Promotion
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Validate main PR metadata
- name: Validate PR source branch
shell: bash
env:
HEAD_REF: ${{ github.head_ref }}
@@ -26,9 +32,33 @@ jobs:
run: |
set -euo pipefail
if [[ -z "${PR_AUTHOR}" || -z "${HEAD_REF}" ]]; then
echo "::error::Missing PR metadata (author/head_ref)."
pr_author_lc="$(echo "${PR_AUTHOR}" | tr '[:upper:]' '[:lower:]')"
allowed_authors=("willsarg" "theonlyhennygod")
if [[ "$HEAD_REPO" != "$BASE_REPO" ]]; then
echo "::error::PRs into main must originate from ${BASE_REPO}:dev or ${BASE_REPO}:release/*. Current head repo: ${HEAD_REPO}."
exit 1
fi
echo "Main PR policy satisfied: author=${PR_AUTHOR}, source=${HEAD_REPO}:${HEAD_REF} -> main"
if [[ "$HEAD_REF" != "dev" && ! "$HEAD_REF" =~ ^release/ ]]; then
echo "::error::PRs into main must use head branch 'dev' or 'release/*'. Current head branch: ${HEAD_REF}."
exit 1
fi
# Keep strict author allowlist for dev -> main, but allow release/* promotion from same repo.
if [[ "$HEAD_REF" == "dev" ]]; then
is_allowed_author=false
for allowed in "${allowed_authors[@]}"; do
if [[ "$pr_author_lc" == "$allowed" ]]; then
is_allowed_author=true
break
fi
done
if [[ "$is_allowed_author" != "true" ]]; then
echo "::error::dev -> main PRs are restricted to: willsarg, theonlyhennygod. PR author: ${PR_AUTHOR}."
exit 1
fi
fi
echo "Promotion policy satisfied: author=${PR_AUTHOR}, source=${HEAD_REPO}:${HEAD_REF} -> main"
.github/workflows/nightly-all-features.yml
+28 -10
View File
@@ -19,12 +19,15 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
nightly-lanes:
name: Nightly Lane (${{ matrix.name }})
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 70
strategy:
fail-fast: false
@@ -51,21 +54,36 @@ jobs:
with:
toolchain: 1.92.0
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: nightly-all-features-${{ matrix.name }}
- name: Install Linux deps for all-features lane
- name: Ensure Linux deps for all-features lane
if: matrix.install_libudev
shell: bash
run: |
if command -v sudo >/dev/null 2>&1; then
sudo apt-get update -qq
sudo apt-get install -y --no-install-recommends libudev-dev pkg-config
else
apt-get update -qq
apt-get install -y --no-install-recommends libudev-dev pkg-config
set -euo pipefail
if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists libudev; then
echo "libudev development headers already available; skipping apt install."
exit 0
fi
echo "Installing missing libudev build dependencies..."
for attempt in 1 2 3; do
if sudo apt-get update -qq -o DPkg::Lock::Timeout=300 && \
sudo apt-get install -y --no-install-recommends --no-upgrade -o DPkg::Lock::Timeout=300 libudev-dev pkg-config; then
echo "Dependency installation succeeded on attempt ${attempt}."
exit 0
fi
if [ "$attempt" -eq 3 ]; then
echo "Failed to install libudev-dev/pkg-config after ${attempt} attempts." >&2
exit 1
fi
echo "Dependency installation failed on attempt ${attempt}; retrying in 10s..."
sleep 10
done
- name: Run nightly lane command
id: lane
shell: bash
@@ -119,7 +137,7 @@ jobs:
name: Nightly Summary & Routing
needs: [nightly-lanes]
if: always()
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
.github/workflows/pr-auto-response.yml
+6 -3
View File
@@ -10,6 +10,9 @@ on:
permissions: {}
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
LABEL_POLICY_PATH: .github/label-policy.json
jobs:
@@ -19,7 +22,7 @@ jobs:
(github.event.action == 'opened' || github.event.action == 'reopened' || github.event.action == 'labeled' || github.event.action == 'unlabeled')) ||
(github.event_name == 'pull_request_target' &&
(github.event.action == 'labeled' || github.event.action == 'unlabeled'))
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
issues: write
@@ -38,7 +41,7 @@ jobs:
await script({ github, context, core });
first-interaction:
if: github.event.action == 'opened'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
issues: write
pull-requests: write
@@ -69,7 +72,7 @@ jobs:
labeled-routes:
if: github.event.action == 'labeled'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
issues: write
.github/workflows/pr-check-stale.yml
+6 -1
View File
@@ -7,12 +7,17 @@ on:
permissions: {}
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
stale:
permissions:
issues: write
pull-requests: write
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Mark stale issues and pull requests
uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
.github/workflows/pr-check-status.yml
+6 -2
View File
@@ -11,9 +11,14 @@ concurrency:
group: pr-check-status
cancel-in-progress: true
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
nudge-stale-prs:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
permissions:
contents: read
pull-requests: write
@@ -23,7 +28,6 @@ jobs:
steps:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Nudge PRs that need rebase or CI refresh
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
with:
.github/workflows/pr-intake-checks.yml
+7 -1
View File
@@ -14,10 +14,16 @@ permissions:
pull-requests: write
issues: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
intake:
name: Intake Checks
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 10
steps:
- name: Checkout repository
.github/workflows/pr-label-policy-check.yml
+7 -1
View File
@@ -19,9 +19,15 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
contributor-tier-consistency:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 10
steps:
- name: Checkout
.github/workflows/pr-labeler.yml
+4 -1
View File
@@ -25,11 +25,14 @@ permissions:
issues: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
LABEL_POLICY_PATH: .github/label-policy.json
jobs:
label:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
.github/workflows/pub-docker-img.yml
+11 -10
View File
@@ -23,6 +23,9 @@ concurrency:
cancel-in-progress: true
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
REGISTRY: ghcr.io
IMAGE_NAME: ${{ github.repository }}
@@ -30,7 +33,7 @@ jobs:
pr-smoke:
name: PR Docker Smoke
if: github.event_name == 'workflow_dispatch' || (github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository)
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 25
permissions:
contents: read
@@ -38,8 +41,8 @@ jobs:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup Buildx Builder
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v1
- name: Setup Buildx
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
- name: Extract metadata (tags, labels)
if: github.event_name == 'pull_request'
@@ -51,7 +54,7 @@ jobs:
type=ref,event=pr
- name: Build smoke image
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v2
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
with:
context: .
push: false
@@ -70,10 +73,8 @@ jobs:
publish:
name: Build and Push Docker Image
if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v') && github.repository == 'zeroclaw-labs/zeroclaw'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 45
environment:
name: release
permissions:
contents: read
packages: write
@@ -82,8 +83,8 @@ jobs:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Setup Buildx Builder
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v1
- name: Setup Buildx
uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
- name: Log in to Container Registry
uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
@@ -119,7 +120,7 @@ jobs:
} >> "$GITHUB_OUTPUT"
- name: Build and push Docker image
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v2
uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6
with:
context: .
push: true
.github/workflows/pub-prerelease.yml
+7 -4
View File
@@ -35,12 +35,15 @@ permissions:
contents: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
prerelease-guard:
name: Pre-release Guard
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
outputs:
release_tag: ${{ steps.vars.outputs.release_tag }}
@@ -172,7 +175,7 @@ jobs:
build-prerelease:
name: Build Pre-release Artifact
needs: [prerelease-guard]
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 45
steps:
- name: Checkout tag
@@ -184,7 +187,7 @@ jobs:
with:
toolchain: 1.92.0
- uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: prerelease-${{ needs.prerelease-guard.outputs.release_tag }}
cache-targets: true
@@ -234,7 +237,7 @@ jobs:
name: Publish GitHub Pre-release
needs: [prerelease-guard, build-prerelease]
if: needs.prerelease-guard.outputs.ready_to_publish == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 15
steps:
- name: Download prerelease artifacts
.github/workflows/pub-release.yml
+249 -87
View File
@@ -39,12 +39,15 @@ permissions:
id-token: write # Required for cosign keyless signing via OIDC
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
prepare:
name: Prepare Release Context
runs-on: self-hosted
runs-on: [self-hosted, aws-india]
outputs:
release_ref: ${{ steps.vars.outputs.release_ref }}
release_tag: ${{ steps.vars.outputs.release_tag }}
@@ -60,7 +63,6 @@ jobs:
event_name="${GITHUB_EVENT_NAME}"
publish_release="false"
draft_release="false"
semver_pattern='^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$'
if [[ "$event_name" == "push" ]]; then
release_ref="${GITHUB_REF_NAME}"
@@ -87,41 +89,6 @@ jobs:
release_tag="verify-${GITHUB_SHA::12}"
fi
if [[ "$publish_release" == "true" ]]; then
if [[ ! "$release_tag" =~ $semver_pattern ]]; then
echo "::error::release_tag must match semver-like format (vX.Y.Z[-suffix])"
exit 1
fi
if ! git ls-remote --exit-code --tags "https://github.com/${GITHUB_REPOSITORY}.git" "refs/tags/${release_tag}" >/dev/null; then
echo "::error::Tag ${release_tag} does not exist on origin. Push the tag first, then rerun manual publish."
exit 1
fi
# Guardrail: release tags must resolve to commits already reachable from main.
tmp_repo="$(mktemp -d)"
trap 'rm -rf "$tmp_repo"' EXIT
git -C "$tmp_repo" init -q
git -C "$tmp_repo" remote add origin "https://github.com/${GITHUB_REPOSITORY}.git"
git -C "$tmp_repo" fetch --quiet --filter=blob:none origin main "refs/tags/${release_tag}:refs/tags/${release_tag}"
if ! git -C "$tmp_repo" merge-base --is-ancestor "refs/tags/${release_tag}" "origin/main"; then
echo "::error::Tag ${release_tag} is not reachable from origin/main. Release tags must be cut from main."
exit 1
fi
# Guardrail: release tag and Cargo package version must stay aligned.
tag_version="${release_tag#v}"
cargo_version="$(git -C "$tmp_repo" show "refs/tags/${release_tag}:Cargo.toml" | sed -n 's/^version = "\([^"]*\)"/\1/p' | head -n1)"
if [[ -z "$cargo_version" ]]; then
echo "::error::Unable to read Cargo package version from ${release_tag}:Cargo.toml"
exit 1
fi
if [[ "$cargo_version" != "$tag_version" ]]; then
echo "::error::Tag ${release_tag} does not match Cargo.toml version (${cargo_version})."
echo "::error::Bump Cargo.toml version first, then create/publish the matching tag."
exit 1
fi
fi
{
echo "release_ref=${release_ref}"
echo "release_tag=${release_tag}"
@@ -138,6 +105,60 @@ jobs:
echo "- draft_release: ${draft_release}"
} >> "$GITHUB_STEP_SUMMARY"
- name: Checkout
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Validate release trigger and authorization guard
shell: bash
run: |
set -euo pipefail
mkdir -p artifacts
python3 scripts/ci/release_trigger_guard.py \
--repo-root . \
--repository "${GITHUB_REPOSITORY}" \
--event-name "${GITHUB_EVENT_NAME}" \
--actor "${GITHUB_ACTOR}" \
--release-ref "${{ steps.vars.outputs.release_ref }}" \
--release-tag "${{ steps.vars.outputs.release_tag }}" \
--publish-release "${{ steps.vars.outputs.publish_release }}" \
--authorized-actors "${{ vars.RELEASE_AUTHORIZED_ACTORS || 'willsarg,theonlyhennygod,chumyin' }}" \
--authorized-tagger-emails "${{ vars.RELEASE_AUTHORIZED_TAGGER_EMAILS || '' }}" \
--require-annotated-tag true \
--output-json artifacts/release-trigger-guard.json \
--output-md artifacts/release-trigger-guard.md \
--fail-on-violation
- name: Emit release trigger audit event
if: always()
shell: bash
run: |
set -euo pipefail
python3 scripts/ci/emit_audit_event.py \
--event-type release_trigger_guard \
--input-json artifacts/release-trigger-guard.json \
--output-json artifacts/audit-event-release-trigger-guard.json \
--artifact-name release-trigger-guard \
--retention-days 30
- name: Publish release trigger guard summary
if: always()
shell: bash
run: |
set -euo pipefail
cat artifacts/release-trigger-guard.md >> "$GITHUB_STEP_SUMMARY"
- name: Upload release trigger guard artifacts
if: always()
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: release-trigger-guard
path: |
artifacts/release-trigger-guard.json
artifacts/release-trigger-guard.md
artifacts/audit-event-release-trigger-guard.json
if-no-files-found: error
retention-days: 30
build-release:
name: Build ${{ matrix.target }}
needs: [prepare]
@@ -147,28 +168,46 @@ jobs:
fail-fast: false
matrix:
include:
- os: ubuntu-latest
# Keep GNU Linux release artifacts on Ubuntu 22.04 to preserve
# a broadly compatible GLIBC baseline for user distributions.
- os: ubuntu-22.04
target: x86_64-unknown-linux-gnu
artifact: zeroclaw
archive_ext: tar.gz
cross_compiler: ""
linker_env: ""
linker: ""
- os: ubuntu-latest
- os: self-hosted
target: x86_64-unknown-linux-musl
artifact: zeroclaw
archive_ext: tar.gz
cross_compiler: ""
linker_env: ""
linker: ""
use_cross: true
- os: ubuntu-22.04
target: aarch64-unknown-linux-gnu
artifact: zeroclaw
archive_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-latest
- os: self-hosted
target: aarch64-unknown-linux-musl
artifact: zeroclaw
archive_ext: tar.gz
cross_compiler: ""
linker_env: ""
linker: ""
use_cross: true
- os: ubuntu-22.04
target: armv7-unknown-linux-gnueabihf
artifact: zeroclaw
archive_ext: tar.gz
cross_compiler: gcc-arm-linux-gnueabihf
linker_env: CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER
linker: arm-linux-gnueabihf-gcc
- os: ubuntu-latest
- os: self-hosted
target: armv7-linux-androideabi
artifact: zeroclaw
archive_ext: tar.gz
@@ -177,7 +216,7 @@ jobs:
linker: ""
android_ndk: true
android_api: 21
- os: ubuntu-latest
- os: self-hosted
target: aarch64-linux-android
artifact: zeroclaw
archive_ext: tar.gz
@@ -186,6 +225,14 @@ jobs:
linker: ""
android_ndk: true
android_api: 21
- os: self-hosted
target: x86_64-unknown-freebsd
artifact: zeroclaw
archive_ext: tar.gz
cross_compiler: ""
linker_env: ""
linker: ""
use_cross: true
- os: macos-15-intel
target: x86_64-apple-darwin
artifact: zeroclaw
@@ -221,16 +268,16 @@ jobs:
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
if: runner.os != 'Windows'
- name: Install cross for cross-built targets
if: matrix.use_cross
run: |
cargo install cross --git https://github.com/cross-rs/cross
- name: Install cross-compilation toolchain (Linux)
if: runner.os == 'Linux' && matrix.cross_compiler != ''
run: |
if command -v sudo >/dev/null 2>&1; then
sudo apt-get update -qq
sudo apt-get install -y ${{ matrix.cross_compiler }}
else
apt-get update -qq
apt-get install -y ${{ matrix.cross_compiler }}
fi
sudo apt-get update -qq
sudo apt-get install -y "${{ matrix.cross_compiler }}"
- name: Setup Android NDK
if: matrix.android_ndk
@@ -243,13 +290,8 @@ jobs:
NDK_ROOT="${RUNNER_TEMP}/android-ndk"
NDK_HOME="${NDK_ROOT}/android-ndk-${NDK_VERSION}"
if command -v sudo >/dev/null 2>&1; then
sudo apt-get update -qq
sudo apt-get install -y unzip
else
apt-get update -qq
apt-get install -y unzip
fi
sudo apt-get update -qq
sudo apt-get install -y unzip
mkdir -p "${NDK_ROOT}"
curl -fsSL "${NDK_URL}" -o "${RUNNER_TEMP}/${NDK_ZIP}"
@@ -305,12 +347,18 @@ jobs:
env:
LINKER_ENV: ${{ matrix.linker_env }}
LINKER: ${{ matrix.linker }}
USE_CROSS: ${{ matrix.use_cross }}
run: |
if [ -n "$LINKER_ENV" ] && [ -n "$LINKER" ]; then
echo "Using linker override: $LINKER_ENV=$LINKER"
export "$LINKER_ENV=$LINKER"
fi
cargo build --profile release-fast --locked --target ${{ matrix.target }}
if [ "$USE_CROSS" = "true" ]; then
echo "Using cross for MUSL target"
cross build --profile release-fast --locked --target ${{ matrix.target }}
else
cargo build --profile release-fast --locked --target ${{ matrix.target }}
fi
- name: Check binary size (Unix)
if: runner.os != 'Windows'
@@ -338,47 +386,68 @@ jobs:
verify-artifacts:
name: Verify Artifact Set
needs: [prepare, build-release]
runs-on: self-hosted
runs-on: [self-hosted, aws-india]
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
with:
ref: ${{ needs.prepare.outputs.release_ref }}
- name: Download all artifacts
uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7.0.0
with:
path: artifacts
- name: Validate expected archives
- name: Validate release archive contract (verify stage)
shell: bash
run: |
set -euo pipefail
expected=(
"zeroclaw-x86_64-unknown-linux-gnu.tar.gz"
"zeroclaw-aarch64-unknown-linux-gnu.tar.gz"
"zeroclaw-armv7-unknown-linux-gnueabihf.tar.gz"
"zeroclaw-armv7-linux-androideabi.tar.gz"
"zeroclaw-aarch64-linux-android.tar.gz"
"zeroclaw-x86_64-apple-darwin.tar.gz"
"zeroclaw-aarch64-apple-darwin.tar.gz"
"zeroclaw-x86_64-pc-windows-msvc.zip"
)
python3 scripts/ci/release_artifact_guard.py \
--artifacts-dir artifacts \
--contract-file .github/release/release-artifact-contract.json \
--output-json artifacts/release-artifact-guard.verify.json \
--output-md artifacts/release-artifact-guard.verify.md \
--allow-extra-archives \
--skip-manifest-files \
--skip-sbom-files \
--skip-notice-files \
--fail-on-violation
missing=0
for file in "${expected[@]}"; do
if ! find artifacts -type f -name "$file" -print -quit | grep -q .; then
echo "::error::Missing release archive: $file"
missing=1
fi
done
- name: Emit verify-stage artifact guard audit event
if: always()
shell: bash
run: |
set -euo pipefail
python3 scripts/ci/emit_audit_event.py \
--event-type release_artifact_guard_verify \
--input-json artifacts/release-artifact-guard.verify.json \
--output-json artifacts/audit-event-release-artifact-guard-verify.json \
--artifact-name release-artifact-guard-verify \
--retention-days 21
if [ "$missing" -ne 0 ]; then
exit 1
fi
- name: Publish verify-stage artifact guard summary
if: always()
shell: bash
run: |
set -euo pipefail
cat artifacts/release-artifact-guard.verify.md >> "$GITHUB_STEP_SUMMARY"
echo "All expected release archives are present."
- name: Upload verify-stage artifact guard reports
if: always()
uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6.0.0
with:
name: release-artifact-guard-verify
path: |
artifacts/release-artifact-guard.verify.json
artifacts/release-artifact-guard.verify.md
artifacts/audit-event-release-artifact-guard-verify.json
if-no-files-found: error
retention-days: 21
publish:
name: Publish Release
if: needs.prepare.outputs.publish_release == 'true'
needs: [prepare, verify-artifacts]
runs-on: self-hosted
runs-on: [self-hosted, aws-india]
timeout-minutes: 45
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -391,8 +460,12 @@ jobs:
path: artifacts
- name: Install syft
shell: bash
run: |
curl -sSfL https://raw.githubusercontent.com/anchore/syft/main/install.sh | sh -s -- -b /usr/local/bin
set -euo pipefail
mkdir -p "${RUNNER_TEMP}/bin"
./scripts/ci/install_syft.sh "${RUNNER_TEMP}/bin"
echo "${RUNNER_TEMP}/bin" >> "$GITHUB_PATH"
- name: Generate SBOM (CycloneDX)
run: |
@@ -409,12 +482,80 @@ jobs:
cp LICENSE-MIT artifacts/LICENSE-MIT
cp NOTICE artifacts/NOTICE
- name: Generate SHA256 checksums
- name: Generate release manifest + checksums
shell: bash
env:
RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
run: |
cd artifacts
find . -type f \( -name '*.tar.gz' -o -name '*.zip' -o -name '*.cdx.json' -o -name '*.spdx.json' -o -name 'LICENSE-APACHE' -o -name 'LICENSE-MIT' -o -name 'NOTICE' \) -exec sha256sum {} + | sed 's| \./[^/]*/| |' > SHA256SUMS
echo "Generated checksums:"
cat SHA256SUMS
set -euo pipefail
python3 scripts/ci/release_manifest.py \
--artifacts-dir artifacts \
--release-tag "${RELEASE_TAG}" \
--output-json artifacts/release-manifest.json \
--output-md artifacts/release-manifest.md \
--checksums-path artifacts/SHA256SUMS \
--fail-empty
- name: Generate SHA256SUMS provenance statement
shell: bash
env:
RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
run: |
set -euo pipefail
python3 scripts/ci/generate_provenance.py \
--artifact artifacts/SHA256SUMS \
--subject-name "zeroclaw-${RELEASE_TAG}-sha256sums" \
--output artifacts/zeroclaw.sha256sums.intoto.json
- name: Emit SHA256SUMS provenance audit event
shell: bash
run: |
set -euo pipefail
python3 scripts/ci/emit_audit_event.py \
--event-type release_sha256sums_provenance \
--input-json artifacts/zeroclaw.sha256sums.intoto.json \
--output-json artifacts/audit-event-release-sha256sums-provenance.json \
--artifact-name release-sha256sums-provenance \
--retention-days 30
- name: Validate release artifact contract (publish stage)
shell: bash
run: |
set -euo pipefail
python3 scripts/ci/release_artifact_guard.py \
--artifacts-dir artifacts \
--contract-file .github/release/release-artifact-contract.json \
--output-json artifacts/release-artifact-guard.publish.json \
--output-md artifacts/release-artifact-guard.publish.md \
--allow-extra-archives \
--allow-extra-manifest-files \
--allow-extra-sbom-files \
--allow-extra-notice-files \
--fail-on-violation
- name: Emit publish-stage artifact guard audit event
if: always()
shell: bash
run: |
set -euo pipefail
python3 scripts/ci/emit_audit_event.py \
--event-type release_artifact_guard_publish \
--input-json artifacts/release-artifact-guard.publish.json \
--output-json artifacts/audit-event-release-artifact-guard-publish.json \
--artifact-name release-artifact-guard-publish \
--retention-days 30
- name: Publish artifact guard summary
shell: bash
run: |
set -euo pipefail
cat artifacts/release-artifact-guard.publish.md >> "$GITHUB_STEP_SUMMARY"
- name: Publish release manifest summary
shell: bash
run: |
set -euo pipefail
cat artifacts/release-manifest.md >> "$GITHUB_STEP_SUMMARY"
- name: Install cosign
uses: sigstore/cosign-installer@faadad0cce49287aee09b3a48701e75088a2c6ad # v4.0.0
@@ -431,6 +572,26 @@ jobs:
"$file"
done < <(find artifacts -type f ! -name '*.sig' ! -name '*.pem' ! -name '*.sigstore.json' -print0)
- name: Compose release-notes supply-chain references
shell: bash
env:
RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
run: |
set -euo pipefail
python3 scripts/ci/release_notes_with_supply_chain_refs.py \
--artifacts-dir artifacts \
--repository "${GITHUB_REPOSITORY}" \
--release-tag "${RELEASE_TAG}" \
--output-json artifacts/release-notes-supply-chain.json \
--output-md artifacts/release-notes-supply-chain.md \
--fail-on-missing
- name: Publish release-notes supply-chain summary
shell: bash
run: |
set -euo pipefail
cat artifacts/release-notes-supply-chain.md >> "$GITHUB_STEP_SUMMARY"
- name: Verify GHCR release tag availability
shell: bash
env:
@@ -476,6 +637,7 @@ jobs:
with:
tag_name: ${{ needs.prepare.outputs.release_tag }}
draft: ${{ needs.prepare.outputs.draft_release == 'true' }}
body_path: artifacts/release-notes-supply-chain.md
generate_release_notes: true
files: |
artifacts/**/*
.github/workflows/scripts/ci_human_review_guard.js
+61
View File
@@ -0,0 +1,61 @@
// Enforce at least one human approval on pull requests.
// Used by .github/workflows/ci-run.yml via actions/github-script.
module.exports = async ({ github, context, core }) => {
const owner = context.repo.owner;
const repo = context.repo.repo;
const prNumber = context.payload.pull_request?.number;
if (!prNumber) {
core.setFailed("Missing pull_request context.");
return;
}
const botAllowlist = new Set(
(process.env.HUMAN_REVIEW_BOT_LOGINS || "github-actions[bot],dependabot[bot],coderabbitai[bot]")
.split(",")
.map((value) => value.trim().toLowerCase())
.filter(Boolean),
);
const isBotAccount = (login, accountType) => {
if (!login) return false;
if ((accountType || "").toLowerCase() === "bot") return true;
if (login.endsWith("[bot]")) return true;
return botAllowlist.has(login);
};
const reviews = await github.paginate(github.rest.pulls.listReviews, {
owner,
repo,
pull_number: prNumber,
per_page: 100,
});
const latestReviewByUser = new Map();
const decisiveStates = new Set(["APPROVED", "CHANGES_REQUESTED", "DISMISSED"]);
for (const review of reviews) {
const login = review.user?.login?.toLowerCase();
if (!login) continue;
if (!decisiveStates.has(review.state)) continue;
latestReviewByUser.set(login, {
state: review.state,
type: review.user?.type || "",
});
}
const humanApprovers = [];
for (const [login, review] of latestReviewByUser.entries()) {
if (review.state !== "APPROVED") continue;
if (isBotAccount(login, review.type)) continue;
humanApprovers.push(login);
}
if (humanApprovers.length === 0) {
core.setFailed(
"No human approving review found. At least one non-bot approval is required before merge.",
);
return;
}
core.info(`Human approval check passed. Approver(s): ${humanApprovers.join(", ")}`);
};
.github/workflows/scripts/pr_intake_checks.js
+30 -2
View File
@@ -6,6 +6,8 @@ module.exports = async ({ github, context, core }) => {
const repo = context.repo.repo;
const pr = context.payload.pull_request;
if (!pr) return;
const prAuthor = (pr.user?.login || "").toLowerCase();
const prBaseRef = pr.base?.ref || "";
const marker = "<!-- pr-intake-checks -->";
const legacyMarker = "<!-- pr-intake-sanity -->";
@@ -17,6 +19,10 @@ module.exports = async ({ github, context, core }) => {
"## Rollback Plan (required)",
];
const body = pr.body || "";
const linearKeyRegex = /\b(?:RMN|CDV|COM)-\d+\b/g;
const linearKeys = Array.from(
new Set([...(pr.title.match(linearKeyRegex) || []), ...(body.match(linearKeyRegex) || [])]),
);
const missingSections = requiredSections.filter((section) => !body.includes(section));
const missingFields = [];
@@ -83,6 +89,22 @@ module.exports = async ({ github, context, core }) => {
if (dangerousProblems.length > 0) {
blockingFindings.push(`Dangerous patch markers found (${dangerousProblems.length})`);
}
const promotionAuthorAllowlist = new Set(["willsarg", "theonlyhennygod"]);
const shouldRetargetToDev =
prBaseRef === "main" && !promotionAuthorAllowlist.has(prAuthor);
if (linearKeys.length === 0) {
blockingFindings.push(
"Missing Linear issue key reference (`RMN-<id>`, `CDV-<id>`, or `COM-<id>`) in PR title/body.",
);
}
if (shouldRetargetToDev) {
advisoryFindings.push(
"This PR targets `main`, but normal contributions must target `dev`. Retarget this PR to `dev` unless this is an authorized promotion PR.",
);
}
const comments = await github.paginate(github.rest.issues.listComments, {
owner,
repo,
@@ -148,11 +170,17 @@ module.exports = async ({ github, context, core }) => {
"",
"Action items:",
"1. Complete required PR template sections/fields.",
"2. Remove tabs, trailing whitespace, and merge conflict markers from added lines.",
"3. Re-run local checks before pushing:",
"2. Link this PR to exactly one active Linear issue key (`RMN-xxx`/`CDV-xxx`/`COM-xxx`).",
"3. Remove tabs, trailing whitespace, and merge conflict markers from added lines.",
"4. Re-run local checks before pushing:",
" - `./scripts/ci/rust_quality_gate.sh`",
" - `./scripts/ci/rust_strict_delta_gate.sh`",
" - `./scripts/ci/docs_quality_gate.sh`",
...(shouldRetargetToDev
? ["5. Retarget this PR base branch from `main` to `dev`."]
: []),
"",
`Detected Linear keys: ${linearKeys.length > 0 ? linearKeys.join(", ") : "none"}`,
"",
`Run logs: ${runUrl}`,
"",
.github/workflows/sec-audit.yml
+11 -59
View File
@@ -78,49 +78,15 @@ permissions:
checks: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
security-scope:
name: Security Scope
runs-on: [self-hosted, Linux, X64]
outputs:
run_heavy: ${{ steps.detect.outputs.run_heavy }}
steps:
- name: Detect heavy security scope
id: detect
uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8
with:
script: |
if (context.eventName !== "pull_request") {
core.setOutput("run_heavy", "true");
return;
}
const files = await github.paginate(
github.rest.pulls.listFiles,
{
owner: context.repo.owner,
repo: context.repo.repo,
pull_number: context.payload.pull_request.number,
per_page: 100,
},
);
const isRustSurface = (path) =>
path === "Cargo.toml" ||
path === "Cargo.lock" ||
path.startsWith("src/") ||
path.startsWith("crates/") ||
path.startsWith("tests/");
const runHeavy = files.some((file) => isRustSurface(file.filename));
core.info(`Heavy security jobs enabled: ${runHeavy}`);
core.setOutput("run_heavy", runHeavy ? "true" : "false");
audit:
name: Security Audit
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -135,7 +101,7 @@ jobs:
deny:
name: License & Supply Chain
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -190,16 +156,14 @@ jobs:
security-regressions:
name: Security Regression Tests
needs: [security-scope]
if: needs.security-scope.outputs.run_heavy == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
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 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
with:
prefix-key: sec-audit-security-regressions
- name: Run security regression suite
@@ -208,7 +172,7 @@ jobs:
secrets:
name: Secrets Governance (Gitleaks)
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -403,7 +367,7 @@ jobs:
sbom:
name: SBOM Snapshot
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -468,9 +432,7 @@ jobs:
unsafe-debt:
name: Unsafe Debt Audit
needs: [security-scope]
if: needs.security-scope.outputs.run_heavy == 'true'
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -609,7 +571,7 @@ jobs:
name: Security Required Gate
if: always() && (github.event_name == 'pull_request' || github.event_name == 'push' || github.event_name == 'merge_group')
needs: [audit, deny, security-regressions, secrets, sbom, unsafe-debt]
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Enforce security gate
shell: bash
@@ -627,17 +589,7 @@ jobs:
echo "$item"
done
for item in "${results[@]}"; do
key="${item%%=*}"
result="${item#*=}"
if [ "$key" = "security-regressions" ] || [ "$key" = "unsafe-debt" ]; then
if [ "$result" != "success" ] && [ "$result" != "skipped" ]; then
echo "Security gate failed: $item"
exit 1
fi
continue
fi
if [ "$result" != "success" ]; then
echo "Security gate failed: $item"
exit 1
.github/workflows/sec-codeql.yml
+7 -11
View File
@@ -34,10 +34,16 @@ permissions:
security-events: write
actions: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
codeql:
name: CodeQL Analysis
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 30
steps:
- name: Checkout repository
@@ -57,16 +63,6 @@ jobs:
with:
toolchain: 1.92.0
- name: Ensure native build tools
shell: bash
run: |
SUDO=""
if command -v sudo >/dev/null 2>&1; then
SUDO="sudo"
fi
$SUDO apt-get update
$SUDO apt-get install -y --no-install-recommends build-essential pkg-config
- name: Build
run: cargo build --workspace --all-targets --locked
.github/workflows/sec-vorpal-reviewdog.yml
+7 -1
View File
@@ -82,10 +82,16 @@ permissions:
checks: write
pull-requests: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
vorpal:
name: Vorpal Reviewdog Scan
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 20
steps:
- name: Checkout
.github/workflows/sync-contributors.yml
+1 -1
View File
@@ -17,7 +17,7 @@ permissions:
jobs:
update-notice:
name: Update NOTICE with new contributors
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
steps:
- name: Checkout repository
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
.github/workflows/test-benchmarks.yml
+5 -2
View File
@@ -14,19 +14,22 @@ permissions:
pull-requests: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
benchmarks:
name: Criterion Benchmarks
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
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 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
- name: Run benchmarks
run: cargo bench --locked 2>&1 | tee benchmark_output.txt
.github/workflows/test-e2e.yml
+5 -9
View File
@@ -3,13 +3,6 @@ name: Test E2E
on:
push:
branches: [dev, main]
paths:
- "Cargo.toml"
- "Cargo.lock"
- "deny.toml"
- "src/**"
- "crates/**"
- "tests/**"
workflow_dispatch:
concurrency:
@@ -20,18 +13,21 @@ permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
integration-tests:
name: Integration / E2E Tests
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
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 # v3
- uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
- name: Run integration / E2E tests
run: cargo test --test agent_e2e --locked --verbose
.github/workflows/test-fuzz.yml
+4 -1
View File
@@ -19,12 +19,15 @@ permissions:
issues: write
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
CARGO_TERM_COLOR: always
jobs:
fuzz:
name: Fuzz (${{ matrix.target }})
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 60
strategy:
fail-fast: false
.github/workflows/test-rust-build.yml
+2 -2
View File
@@ -38,7 +38,7 @@ permissions:
jobs:
run:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: ${{ inputs.timeout_minutes }}
steps:
- name: Checkout repository
@@ -53,7 +53,7 @@ jobs:
- name: Restore Rust cache
if: inputs.use_cache
uses: Swatinem/rust-cache@779680da715d629ac1d338a641029a2f4372abb5 # v3
uses: useblacksmith/rust-cache@f53e7f127245d2a269b3d90879ccf259876842d5 # v3
- name: Run command
shell: bash
.github/workflows/workflow-sanity.yml
+45 -3
View File
@@ -19,11 +19,23 @@ concurrency:
permissions:
contents: read
env:
GIT_CONFIG_COUNT: "1"
GIT_CONFIG_KEY_0: core.hooksPath
GIT_CONFIG_VALUE_0: /dev/null
jobs:
no-tabs:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 10
steps:
- name: Normalize git global hooks config
shell: bash
run: |
set -euo pipefail
git config --global --unset-all core.hooksPath || true
- name: Checkout
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
@@ -54,11 +66,41 @@ jobs:
PY
actionlint:
runs-on: [self-hosted, Linux, X64]
runs-on: [self-hosted, aws-india]
timeout-minutes: 10
steps:
- name: Normalize git global hooks config
shell: bash
run: |
set -euo pipefail
git config --global --unset-all core.hooksPath || true
- name: Checkout
uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
- name: Install actionlint binary
shell: bash
run: |
set -euo pipefail
version="1.7.11"
arch="$(uname -m)"
case "$arch" in
x86_64|amd64) archive="actionlint_${version}_linux_amd64.tar.gz" ;;
aarch64|arm64) archive="actionlint_${version}_linux_arm64.tar.gz" ;;
*)
echo "::error::Unsupported architecture: ${arch}"
exit 1
;;
esac
curl -fsSL \
-o "$RUNNER_TEMP/actionlint.tgz" \
"https://github.com/rhysd/actionlint/releases/download/v${version}/${archive}"
tar -xzf "$RUNNER_TEMP/actionlint.tgz" -C "$RUNNER_TEMP" actionlint
chmod +x "$RUNNER_TEMP/actionlint"
echo "$RUNNER_TEMP" >> "$GITHUB_PATH"
"$RUNNER_TEMP/actionlint" -version
- name: Lint GitHub workflows
uses: rhysd/actionlint@393031adb9afb225ee52ae2ccd7a5af5525e03e8 # v1.7.11
shell: bash
run: actionlint -color
.gitignore
+3
View File
@@ -33,3 +33,6 @@ venv/
*.pem
credentials.json
.worktrees/
# Nix
result
AGENTS.md
+3 -3
View File
@@ -240,8 +240,8 @@ 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`.
- `main` is the integration branch for reviewed changes.
- 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).
- After merge/close, clean up task branches/worktrees that are no longer needed.
@@ -251,7 +251,7 @@ All contributors (human or agent) must follow the same collaboration flow:
- Decide merge/close outcomes from repository-local authority in this order: `.github/workflows/**`, GitHub branch protection/rulesets, `docs/pr-workflow.md`, then this `AGENTS.md`.
- External agent skills/templates are execution aids only; they must not override repository-local policy.
- A normal contributor PR targeting `main` is expected; evaluate by intent, scope, and policy compliance.
- A normal contributor PR targeting `main` is a routing defect, not by itself a closure reason; if intent and content are legitimate, retarget to `dev`.
- Direct-close the PR (do not supersede/replay) when high-confidence integrity-risk signals exist:
- unapproved or unrelated repository rebranding attempts (for example replacing project logo/identity assets)
- unauthorized platform-surface expansion (for example introducing `web` apps, dashboards, frontend stacks, or UI surfaces not requested by maintainers)
CLAUDE.md
+23 -87
View File
@@ -1,90 +1,31 @@
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Quick Reference — Build, Test, Lint
```bash
# Build (debug)
cargo build
# Build (release, optimized for size)
cargo build --release
# Lint
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
# Test (all)
cargo test
# Test (single test by name)
cargo test test_name_substring
# Test (single integration test file)
cargo test --test agent_e2e
# Benchmarks
cargo bench
# Full local CI in Docker (recommended before PR)
./dev/ci.sh all
```
Rust edition: 2021. MSRV: 1.87. Binary name: `zeroclaw`. Unsafe code is forbidden (`#![forbid(unsafe_code)]`).
## Workspace Structure
Cargo workspace with two members:
- `.` (root) — the main `zeroclaw` binary crate
- `crates/robot-kit` — `zeroclaw-robot-kit`, a standalone robotics toolkit (drive, vision, speech, sensors, safety)
## Feature Flags
Default features: `channel-lark`, `web-fetch-html2md`. Notable opt-in features:
- `hardware` — USB/serial peripheral support (nusb + tokio-serial)
- `channel-matrix` — Matrix/Element E2EE channel
- `memory-postgres` — PostgreSQL memory backend
- `observability-otel` — OpenTelemetry OTLP traces/metrics
- `browser-native` — Rust-native browser automation (fantoccini/WebDriver)
- `runtime-wasm` — In-process WASM sandbox (wasmi)
- `sandbox-landlock` / `sandbox-bubblewrap` — Linux kernel sandboxing
- `peripheral-rpi` — Raspberry Pi GPIO (rppal, Linux only)
- `whatsapp-web` — Native WhatsApp Web client (wa-rs)
- `probe` — probe-rs for STM32/Nucleo debug probe
- `rag-pdf` — PDF extraction for datasheet RAG
## Architecture Overview
ZeroClaw is a trait-driven, modular autonomous agent runtime. The core pattern: define a trait in `<subsystem>/traits.rs`, implement it in sibling modules, register implementations in a factory function in `<subsystem>/mod.rs`.
Key extension points (traits):
- `src/providers/traits.rs` — `Provider` (model inference backends)
- `src/channels/traits.rs` — `Channel` (messaging platform integrations)
- `src/tools/traits.rs` — `Tool` (agent-callable capabilities)
- `src/memory/traits.rs` — `Memory` (persistence backends)
- `src/observability/traits.rs` — `Observer` (telemetry/metrics)
- `src/runtime/traits.rs` — `RuntimeAdapter` (execution environments)
- `src/peripherals/traits.rs` — `Peripheral` (hardware boards)
**Data flow**: User message arrives via a `Channel` -> `agent/loop_.rs` orchestrates the conversation -> `Provider` generates LLM responses -> `Tool` executions are dispatched -> results flow back through the channel. `SecurityPolicy` (`src/security/policy.rs`) enforces access control across all tool executions. `Config` (`src/config/schema.rs`) is the single source for all runtime configuration and is effectively a public API.
**Provider resilience**: `ReliableProvider` (`src/providers/reliable.rs`) wraps providers with fallback chains and automatic retry. `router.rs` handles model routing across multiple providers.
**Gateway**: `src/gateway/` is an axum-based HTTP server with webhook endpoints, SSE streaming, WebSocket support, and an OpenAI-compatible API layer.
## Engineering Protocol
# CLAUDE.md — ZeroClaw Agent Engineering Protocol
This file defines the default working protocol for Claude agents in this repository.
Scope: entire repository.
## 1) Project Snapshot (Read First)
ZeroClaw is a Rust-first autonomous agent runtime optimized for high performance, efficiency, stability, extensibility, sustainability, and security.
ZeroClaw is a Rust-first autonomous agent runtime optimized for:
- high performance
- high efficiency
- high stability
- high extensibility
- high sustainability
- high security
Core architecture is trait-driven and modular. Most extension work should be done by implementing traits and registering in factory modules.
Key extension points:
- `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:
@@ -202,13 +143,8 @@ Required:
- `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 (native, docker, wasm)
- `crates/robot-kit/` — standalone robotics toolkit crate
- `src/runtime/` — runtime adapters (currently native)
- `docs/` — task-oriented documentation system (hubs, unified TOC, references, operations, security proposals, multilingual guides)
- `dev/` — Docker-based dev environment (`cli.sh`) and local CI runner (`ci.sh`)
- `scripts/ci/` — CI gate scripts (quality gate, delta lint, security regression, docs checks)
- `tests/` — integration tests (e2e, channel routing, config, provider, webhook security)
- `benches/` — criterion benchmarks (`agent_benchmarks.rs`)
- `.github/` — CI, templates, automation workflows
## 4.1 Documentation System Contract (Required)
@@ -304,8 +240,8 @@ 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`.
- `main` is the integration branch for reviewed changes.
- 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).
- After merge/close, clean up task branches/worktrees that are no longer needed.
@@ -315,7 +251,7 @@ All contributors (human or agent) must follow the same collaboration flow:
- Decide merge/close outcomes from repository-local authority in this order: `.github/workflows/**`, GitHub branch protection/rulesets, `docs/pr-workflow.md`, then this `CLAUDE.md`.
- External agent skills/templates are execution aids only; they must not override repository-local policy.
- A normal contributor PR targeting `main` is expected; evaluate by intent, scope, and policy compliance.
- A normal contributor PR targeting `main` is a routing defect, not by itself a closure reason; if intent and content are legitimate, retarget to `dev`.
- Direct-close the PR (do not supersede/replay) when high-confidence integrity-risk signals exist:
- unapproved or unrelated repository rebranding attempts (for example replacing project logo/identity assets)
- unauthorized platform-surface expansion (for example introducing `web` apps, dashboards, frontend stacks, or UI surfaces not requested by maintainers)
Cargo.lock
Generated
+451 -14
View File
@@ -406,6 +406,19 @@ version = "1.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
[[package]]
name = "auto_encoder"
version = "0.1.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f6364e11e0270035ec392151a54f1476e6b3612ef9f4fe09d35e72a8cebcb65"
dependencies = [
"chardetng",
"encoding_rs",
"percent-encoding",
"phf 0.11.3",
"phf_codegen 0.11.3",
]
[[package]]
name = "autocfg"
version = "1.5.0"
@@ -528,6 +541,16 @@ version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a45f9771ced8a774de5e5ebffbe520f52e3943bf5a9a6baa3a5d14a5de1afe6"
[[package]]
name = "bcder"
version = "0.7.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1f7c42c9913f68cf9390a225e81ad56a5c515347287eb98baa710090ca1de86d"
dependencies = [
"bytes",
"smallvec",
]
[[package]]
name = "bech32"
version = "0.11.1"
@@ -815,6 +838,17 @@ dependencies = [
"zeroize",
]
[[package]]
name = "chardetng"
version = "0.1.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "14b8f0b65b7b08ae3c8187e8d77174de20cb6777864c6b832d8ad365999cf1ea"
dependencies = [
"cfg-if",
"encoding_rs",
"memchr",
]
[[package]]
name = "chrono"
version = "0.4.43"
@@ -936,6 +970,15 @@ version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a822ea5bc7590f9d40f1ba12c0dc3c2760f3482c6984db1573ad11031420831"
[[package]]
name = "clipboard-win"
version = "5.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bde03770d3df201d4fb868f2c9c59e66a3e4e2bd06692a0fe701e7103c7e84d4"
dependencies = [
"error-code",
]
[[package]]
name = "cmake"
version = "0.1.57"
@@ -1210,6 +1253,29 @@ dependencies = [
"typenum",
]
[[package]]
name = "cssparser"
version = "0.36.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dae61cf9c0abb83bd659dab65b7e4e38d8236824c85f0f804f173567bda257d2"
dependencies = [
"cssparser-macros",
"dtoa-short",
"itoa",
"phf 0.13.1",
"smallvec",
]
[[package]]
name = "cssparser-macros"
version = "0.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "13b588ba4ac1a99f7f2964d24b3d896ddc6bf847ee3855dbd4366f058cfcd331"
dependencies = [
"quote",
"syn 2.0.116",
]
[[package]]
name = "csv"
version = "1.4.0"
@@ -1574,6 +1640,21 @@ dependencies = [
"litrs",
]
[[package]]
name = "dtoa"
version = "1.0.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4c3cf4824e2d5f025c7b531afcb2325364084a16806f6d47fbc1f5fbd9960590"
[[package]]
name = "dtoa-short"
version = "0.3.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd1511a7b6a56299bd043a9c167a6d2bfb37bf84a6dfceaba651168adfb43c87"
dependencies = [
"dtoa",
]
[[package]]
name = "dunce"
version = "1.0.5"
@@ -1658,6 +1739,12 @@ dependencies = [
"cfg-if",
]
[[package]]
name = "endian-type"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c34f04666d835ff5d62e058c3995147c06f42fe86ff053337632bca83e42702d"
[[package]]
name = "enumflags2"
version = "0.7.12"
@@ -1719,6 +1806,12 @@ dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "error-code"
version = "3.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dea2df4cf52843e0452895c455a1a2cfbb842a1e7329671acf418fdc53ed4c59"
[[package]]
name = "esp-idf-part"
version = "0.6.0"
@@ -1876,12 +1969,38 @@ dependencies = [
"webdriver",
]
[[package]]
name = "fast_html2md"
version = "0.0.58"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "af3a0122fee1bcf6bb9f3d73782e911cce69d95b76a5e29e930af92cd4a8e4e3"
dependencies = [
"auto_encoder",
"futures-util",
"lazy_static",
"lol_html",
"percent-encoding",
"regex",
"url",
]
[[package]]
name = "fastrand"
version = "2.3.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
[[package]]
name = "fd-lock"
version = "4.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ce92ff622d6dadf7349484f42c93271a0d49b7cc4d466a936405bacbe10aa78"
dependencies = [
"cfg-if",
"rustix",
"windows-sys 0.59.0",
]
[[package]]
name = "fdeflate"
version = "0.3.7"
@@ -1932,6 +2051,12 @@ version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
[[package]]
name = "foldhash"
version = "0.2.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
[[package]]
name = "form_urlencoded"
version = "1.2.2"
@@ -2240,7 +2365,7 @@ version = "0.15.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
dependencies = [
"foldhash",
"foldhash 0.1.5",
]
[[package]]
@@ -2248,6 +2373,11 @@ name = "hashbrown"
version = "0.16.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
dependencies = [
"allocator-api2",
"equivalent",
"foldhash 0.2.0",
]
[[package]]
name = "hashify"
@@ -2363,6 +2493,15 @@ dependencies = [
"digest",
]
[[package]]
name = "home"
version = "0.5.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cc627f471c528ff0c4a49e1d5e60450c8f6461dd6d10ba9dcd3a61d3dff7728d"
dependencies = [
"windows-sys 0.61.2",
]
[[package]]
name = "hostname"
version = "0.4.2"
@@ -3079,6 +3218,12 @@ version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
[[package]]
name = "linux-raw-sys"
version = "0.12.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"
[[package]]
name = "litemap"
version = "0.7.5"
@@ -3112,6 +3257,25 @@ version = "0.4.29"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
[[package]]
name = "lol_html"
version = "2.7.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5ff94cb6aef6ee52afd2c69331e9109906d855e82bd241f3110dfdf6185899ab"
dependencies = [
"bitflags 2.11.0",
"cfg-if",
"cssparser",
"encoding_rs",
"foldhash 0.2.0",
"hashbrown 0.16.1",
"memchr",
"mime",
"precomputed-hash",
"selectors",
"thiserror 2.0.18",
]
[[package]]
name = "lopdf"
version = "0.38.0"
@@ -3729,6 +3893,15 @@ version = "1.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "650eef8c711430f1a879fdd01d4745a7deea475becfb90269c06775983bbf086"
[[package]]
name = "nibble_vec"
version = "0.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77a5d83df9f36fe23f0c3648c6bbb8b0298bb5f1939c8f2704431371f4b84d43"
dependencies = [
"smallvec",
]
[[package]]
name = "nix"
version = "0.26.4"
@@ -3936,7 +4109,7 @@ dependencies = [
"core-foundation-sys",
"futures-core",
"io-kit-sys 0.5.0",
"linux-raw-sys",
"linux-raw-sys 0.11.0",
"log",
"once_cell",
"rustix",
@@ -4194,6 +4367,16 @@ dependencies = [
"unicode-normalization",
]
[[package]]
name = "pem"
version = "3.0.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1d30c53c26bc5b31a98cd02d20f25a7c8567146caf63ed593a9d87b2775291be"
dependencies = [
"base64",
"serde_core",
]
[[package]]
name = "percent-encoding"
version = "2.3.2"
@@ -4217,6 +4400,7 @@ version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
dependencies = [
"phf_macros 0.11.3",
"phf_shared 0.11.3",
]
@@ -4235,6 +4419,7 @@ version = "0.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c1562dc717473dbaa4c1f85a36410e03c047b2e7df7f45ee938fbef64ae7fadf"
dependencies = [
"phf_macros 0.13.1",
"phf_shared 0.13.1",
"serde",
]
@@ -4279,6 +4464,32 @@ dependencies = [
"phf_shared 0.13.1",
]
[[package]]
name = "phf_macros"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f84ac04429c13a7ff43785d75ad27569f2951ce0ffd30a3321230db2fc727216"
dependencies = [
"phf_generator 0.11.3",
"phf_shared 0.11.3",
"proc-macro2",
"quote",
"syn 2.0.116",
]
[[package]]
name = "phf_macros"
version = "0.13.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "812f032b54b1e759ccd5f8b6677695d5268c588701effba24601f6932f8269ef"
dependencies = [
"phf_generator 0.13.1",
"phf_shared 0.13.1",
"proc-macro2",
"quote",
"syn 2.0.116",
]
[[package]]
name = "phf_shared"
version = "0.11.3"
@@ -4857,6 +5068,16 @@ version = "0.7.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc33ff2d4973d518d823d61aa239014831e521c75da58e3df4840d3f47749d09"
[[package]]
name = "radix_trie"
version = "0.2.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "c069c179fcdc6a2fe24d8d18305cf085fdbd4f922c041943e203685d6a1c58fd"
dependencies = [
"endian-type",
"nibble_vec",
]
[[package]]
name = "rand"
version = "0.8.5"
@@ -5379,14 +5600,14 @@ dependencies = [
[[package]]
name = "rustix"
version = "1.1.3"
version = "1.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "146c9e247ccc180c1f61615433868c99f3de3ae256a30a43b49f67c2d9171f34"
checksum = "b6fe4565b9518b83ef4f91bb47ce29620ca828bd32cb7e408f0062e9930ba190"
dependencies = [
"bitflags 2.11.0",
"errno",
"libc",
"linux-raw-sys",
"linux-raw-sys 0.12.1",
"windows-sys 0.61.2",
]
@@ -5446,6 +5667,28 @@ version = "1.0.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
[[package]]
name = "rustyline"
version = "17.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e902948a25149d50edc1a8e0141aad50f54e22ba83ff988cf8f7c9ef07f50564"
dependencies = [
"bitflags 2.11.0",
"cfg-if",
"clipboard-win",
"fd-lock",
"home",
"libc",
"log",
"memchr",
"nix 0.30.1",
"radix_trie",
"unicode-segmentation",
"unicode-width 0.2.2",
"utf8parse",
"windows-sys 0.60.2",
]
[[package]]
name = "ruzstd"
version = "0.8.2"
@@ -5591,6 +5834,25 @@ dependencies = [
"libc",
]
[[package]]
name = "selectors"
version = "0.33.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "feef350c36147532e1b79ea5c1f3791373e61cbd9a6a2615413b3807bb164fb7"
dependencies = [
"bitflags 2.11.0",
"cssparser",
"derive_more 2.1.1",
"log",
"new_debug_unreachable",
"phf 0.13.1",
"phf_codegen 0.13.1",
"precomputed-hash",
"rustc-hash",
"servo_arc",
"smallvec",
]
[[package]]
name = "self_cell"
version = "1.2.2"
@@ -5797,6 +6059,15 @@ dependencies = [
"winapi",
]
[[package]]
name = "servo_arc"
version = "0.4.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "170fb83ab34de17dc69aa7c67482b22218ddb85da56546f9bd6b929e32a05930"
dependencies = [
"stable_deref_trait",
]
[[package]]
name = "sha1"
version = "0.10.6"
@@ -5911,6 +6182,12 @@ dependencies = [
"windows-sys 0.60.2",
]
[[package]]
name = "spin"
version = "0.9.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6980e8d7511241f8acf4aebddbb1ff938df5eebe98691418c4468d0b72a96a67"
[[package]]
name = "spki"
version = "0.7.3"
@@ -5952,6 +6229,16 @@ dependencies = [
"pin-project-lite",
]
[[package]]
name = "string-interner"
version = "0.19.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "23de088478b31c349c9ba67816fa55d9355232d63c3afea8bf513e31f0f1d2c0"
dependencies = [
"hashbrown 0.15.5",
"serde",
]
[[package]]
name = "string_cache"
version = "0.8.9"
@@ -6077,9 +6364,9 @@ checksum = "55937e1799185b12863d447f42597ed69d9928686b8d88a1df17376a097d8369"
[[package]]
name = "tempfile"
version = "3.25.0"
version = "3.26.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0136791f7c95b1f6dd99f9cc786b91bb81c3800b639b3478e561ddb7be95e5f1"
checksum = "82a72c767771b47409d2345987fda8628641887d5466101319899796367354a0"
dependencies = [
"fastrand",
"getrandom 0.4.1",
@@ -6276,6 +6563,20 @@ dependencies = [
"whoami",
]
[[package]]
name = "tokio-postgres-rustls"
version = "0.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "04fb792ccd6bbcd4bba408eb8a292f70fc4a3589e5d793626f45190e6454b6ab"
dependencies = [
"ring",
"rustls",
"tokio",
"tokio-postgres",
"tokio-rustls",
"x509-certificate",
]
[[package]]
name = "tokio-rustls"
version = "0.26.4"
@@ -6605,6 +6906,7 @@ version = "0.3.22"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f30143827ddab0d256fd843b7a66d164e9f271cfa0dde49142c5ca0ca291f1e"
dependencies = [
"chrono",
"matchers",
"nu-ansi-term",
"once_cell",
@@ -6781,6 +7083,12 @@ version = "0.1.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7df058c713841ad818f1dc5d3fd88063241cc61f49f5fbea4b951e8cf5a8d71d"
[[package]]
name = "unicode-segmentation"
version = "1.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
[[package]]
name = "unicode-width"
version = "0.1.14"
@@ -7305,7 +7613,17 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "990065f2fe63003fe337b932cfb5e3b80e0b4d0f5ff650e6985b1048f62c8319"
dependencies = [
"leb128fmt",
"wasmparser",
"wasmparser 0.244.0",
]
[[package]]
name = "wasm-encoder"
version = "0.245.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3f9dca005e69bf015e45577e415b9af8c67e8ee3c0e38b5b0add5aa92581ed5c"
dependencies = [
"leb128fmt",
"wasmparser 0.245.1",
]
[[package]]
@@ -7316,8 +7634,8 @@ checksum = "bb0e353e6a2fbdc176932bbaab493762eb1255a7900fe0fea1a2f96c296cc909"
dependencies = [
"anyhow",
"indexmap",
"wasm-encoder",
"wasmparser",
"wasm-encoder 0.244.0",
"wasmparser 0.244.0",
]
[[package]]
@@ -7351,6 +7669,57 @@ dependencies = [
"web-sys",
]
[[package]]
name = "wasmi"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "22bf475363d09d960b48275c4ea9403051add498a9d80c64dbc91edabab9d1d0"
dependencies = [
"spin",
"wasmi_collections",
"wasmi_core",
"wasmi_ir",
"wasmparser 0.228.0",
"wat",
]
[[package]]
name = "wasmi_collections"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "85851acbdffd675a9b699b3590406a1d37fc1e1fd073743c7c9cf47c59caacba"
dependencies = [
"string-interner",
]
[[package]]
name = "wasmi_core"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ef64cf60195d1f937dbaed592a5afce3e6d86868fb8070c5255bc41539d68f9d"
dependencies = [
"libm",
]
[[package]]
name = "wasmi_ir"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5dcb572ce4400e06b5475819f3d6b9048513efbca785f0b9ef3a41747f944fd8"
dependencies = [
"wasmi_core",
]
[[package]]
name = "wasmparser"
version = "0.228.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4abf1132c1fdf747d56bbc1bb52152400c70f336870f968b85e89ea422198ae3"
dependencies = [
"bitflags 2.11.0",
"indexmap",
]
[[package]]
name = "wasmparser"
version = "0.244.0"
@@ -7363,6 +7732,38 @@ dependencies = [
"semver",
]
[[package]]
name = "wasmparser"
version = "0.245.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "4f08c9adee0428b7bddf3890fc27e015ac4b761cc608c822667102b8bfd6995e"
dependencies = [
"bitflags 2.11.0",
"indexmap",
]
[[package]]
name = "wast"
version = "245.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "28cf1149285569120b8ce39db8b465e8a2b55c34cbb586bd977e43e2bc7300bf"
dependencies = [
"bumpalo",
"leb128fmt",
"memchr",
"unicode-width 0.2.2",
"wasm-encoder 0.245.1",
]
[[package]]
name = "wat"
version = "1.245.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd48d1679b6858988cb96b154dda0ec5bbb09275b71db46057be37332d5477be"
dependencies = [
"wast",
]
[[package]]
name = "web-sys"
version = "0.3.85"
@@ -7902,9 +8303,9 @@ dependencies = [
"serde",
"serde_derive",
"serde_json",
"wasm-encoder",
"wasm-encoder 0.244.0",
"wasm-metadata",
"wasmparser",
"wasmparser 0.244.0",
"wit-parser",
]
@@ -7923,7 +8324,7 @@ dependencies = [
"serde_derive",
"serde_json",
"unicode-xid",
"wasmparser",
"wasmparser 0.244.0",
]
[[package]]
@@ -7959,6 +8360,25 @@ dependencies = [
"zeroize",
]
[[package]]
name = "x509-certificate"
version = "0.23.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "66534846dec7a11d7c50a74b7cdb208b9a581cad890b7866430d438455847c85"
dependencies = [
"bcder",
"bytes",
"chrono",
"der",
"hex",
"pem",
"ring",
"signature",
"spki",
"thiserror 1.0.69",
"zeroize",
]
[[package]]
name = "xxhash-rust"
version = "0.8.15"
@@ -8016,6 +8436,7 @@ dependencies = [
name = "zeroclaw"
version = "0.1.7"
dependencies = [
"aho-corasick",
"anyhow",
"async-imap",
"async-trait",
@@ -8032,6 +8453,7 @@ dependencies = [
"dialoguer",
"directories",
"fantoccini",
"fast_html2md",
"futures-util",
"glob",
"hex",
@@ -8041,7 +8463,6 @@ dependencies = [
"image",
"landlock",
"lettre",
"libc",
"mail-parser",
"matrix-sdk",
"mime_guess",
@@ -8067,6 +8488,7 @@ dependencies = [
"rust-embed",
"rustls",
"rustls-pki-types",
"rustyline",
"schemars",
"scopeguard",
"serde",
@@ -8078,6 +8500,7 @@ dependencies = [
"tempfile",
"thiserror 2.0.18",
"tokio",
"tokio-postgres-rustls",
"tokio-rustls",
"tokio-serial",
"tokio-stream",
@@ -8096,9 +8519,11 @@ dependencies = [
"wa-rs-proto",
"wa-rs-tokio-transport",
"wa-rs-ureq-http",
"wasmi",
"webpki-roots 1.0.6",
"which",
"wiremock",
"zip",
]
[[package]]
@@ -8238,6 +8663,18 @@ dependencies = [
"syn 2.0.116",
]
[[package]]
name = "zip"
version = "0.6.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "760394e246e4c28189f19d488c058bf16f564016aefac5d32bb1f3b51d5e9261"
dependencies = [
"byteorder",
"crc32fast",
"crossbeam-utils",
"flate2",
]
[[package]]
name = "zlib-rs"
version = "0.6.2"
Cargo.toml
+24 -3
View File
@@ -26,7 +26,7 @@ tokio-util = { version = "0.7", default-features = false }
tokio-stream = { version = "0.1.18", default-features = false, features = ["fs", "sync"] }
# HTTP client - minimal features
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "native-tls", "blocking", "multipart", "stream", "socks"] }
reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "blocking", "multipart", "stream", "socks"] }
# Matrix client + E2EE decryption
matrix-sdk = { version = "0.16", optional = true, default-features = false, features = ["e2e-encryption", "rustls-tls", "markdown", "sqlite"] }
@@ -46,7 +46,7 @@ schemars = "1.2"
# Logging - minimal
tracing = { version = "0.1", default-features = false }
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "ansi", "env-filter"] }
tracing-subscriber = { version = "0.3", default-features = false, features = ["fmt", "ansi", "env-filter", "chrono"] }
# Observability - Prometheus metrics
prometheus = { version = "0.14", default-features = false }
@@ -61,12 +61,19 @@ urlencoding = "2.1"
# HTML to plain text conversion (web_fetch tool)
nanohtml2text = "0.2"
# Zip archive extraction
zip = { version = "0.6", default-features = false, features = ["deflate"] }
# Optional Rust-native browser automation backend
fantoccini = { version = "0.22.0", optional = true, default-features = false, features = ["rustls-tls"] }
# Optional in-process WASM runtime for sandboxed tool execution
wasmi = { version = "1.0.9", optional = true, default-features = true }
# Error handling
anyhow = "1.0"
thiserror = "2.0"
aho-corasick = "1.1"
# UUID generation
uuid = { version = "1.11", default-features = false, features = ["v4", "std"] }
@@ -106,6 +113,7 @@ cron = "0.15"
# Interactive CLI prompts
dialoguer = { version = "0.12", features = ["fuzzy-select"] }
rustyline = "17.0"
console = "0.16"
# Hardware discovery (device path globbing)
@@ -114,6 +122,9 @@ glob = "0.3"
# Binary discovery (init system detection)
which = "8.0"
# Temporary directory creation (for self-update)
tempfile = "3.14"
# WebSocket client channels (Discord/Lark/DingTalk/Nostr)
tokio-tungstenite = { version = "0.28", features = ["rustls-tls-webpki-roots"] }
futures-util = { version = "0.3", default-features = false, features = ["sink"] }
@@ -161,6 +172,12 @@ 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 }
tempfile = "3.14"
# WASM plugin runtime (optional, enable with --features wasm-tools)
# Uses WASI stdio protocol — tools read JSON from stdin, write JSON to stdout.
wasmtime = { version = "28", optional = true, default-features = false, features = ["cranelift", "runtime"] }
wasmtime-wasi = { version = "28", optional = true, default-features = false, features = ["preview1"] }
# Terminal QR rendering for WhatsApp Web pairing flow.
qrcode = { version = "0.14", optional = true }
@@ -184,7 +201,7 @@ landlock = { version = "0.4", optional = true }
libc = "0.2"
[features]
default = []
default = ["wasm-tools"]
hardware = ["nusb", "tokio-serial"]
channel-matrix = ["dep:matrix-sdk"]
channel-lark = ["dep:prost"]
@@ -195,6 +212,8 @@ peripheral-rpi = ["rppal"]
browser-native = ["dep:fantoccini"]
# Backward-compatible alias for older invocations
fantoccini = ["browser-native"]
# In-process WASM runtime (capability-based sandbox)
runtime-wasm = ["dep:wasmi"]
# Sandbox feature aliases used by cfg(feature = "sandbox-*")
sandbox-landlock = ["dep:landlock"]
sandbox-bubblewrap = []
@@ -204,6 +223,8 @@ landlock = ["sandbox-landlock"]
probe = ["dep:probe-rs"]
# rag-pdf = PDF ingestion for datasheet RAG
rag-pdf = ["dep:pdf-extract"]
# wasm-tools = WASM plugin engine for dynamically-loaded tool packages (WASI stdio protocol)
wasm-tools = ["dep:wasmtime", "dep:wasmtime-wasi"]
# 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"]
Dockerfile
+1 -1
View File
@@ -1,7 +1,7 @@
# syntax=docker/dockerfile:1.7
# ── Stage 1: Build ────────────────────────────────────────────
FROM rust:1.93-slim@sha256:9663b80a1621253d30b146454f903de48f0af925c967be48c84745537cd35d8b AS builder
FROM rust:1.93-slim@sha256:7e6fa79cf81be23fd45d857f75f583d80cfdbb11c91fa06180fd747fda37a61d AS builder
WORKDIR /app
ARG ZEROCLAW_CARGO_FEATURES=""
README.fr.md
-884
View File
@@ -1,884 +0,0 @@
<p align="center">
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>
<h1 align="center">ZeroClaw 🦀</h1>
<p align="center">
<strong>Zéro surcharge. Zéro compromis. 100% Rust. 100% Agnostique.</strong><br>
⚡️ <strong>Fonctionne sur du matériel à 10$ avec <5 Mo de RAM : C'est 99% de mémoire en moins qu'OpenClaw et 98% moins cher qu'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="Licence : MIT ou Apache-2.0" /></a>
<a href="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributeurs" /></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="Offrez-moi un café" /></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://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 : Officiel" /></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">
Construit par des étudiants et membres des communautés Harvard, MIT et Sundai.Club.
</p>
<p align="center">
🌐 <strong>Langues :</strong> <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">
<a href="#démarrage-rapide">Démarrage</a> |
<a href="bootstrap.sh">Configuration en un clic</a> |
<a href="docs/README.md">Hub Documentation</a> |
<a href="docs/SUMMARY.md">Table des matières Documentation</a>
</p>
<p align="center">
<strong>Accès rapides :</strong>
<a href="docs/reference/README.md">Référence</a> ·
<a href="docs/operations/README.md">Opérations</a> ·
<a href="docs/troubleshooting.md">Dépannage</a> ·
<a href="docs/security/README.md">Sécurité</a> ·
<a href="docs/hardware/README.md">Matériel</a> ·
<a href="docs/contributing/README.md">Contribuer</a>
</p>
<p align="center">
<strong>Infrastructure d'assistant IA rapide, légère et entièrement autonome</strong><br />
Déployez n'importe où. Échangez n'importe quoi.
</p>
<p align="center">
ZeroClaw est le <strong>système d'exploitation runtime</strong> pour les workflows agentiques — une infrastructure qui abstrait les modèles, outils, mémoire et exécution pour construire des agents une fois et les exécuter partout.
</p>
<p align="center"><code>Architecture pilotée par traits · runtime sécurisé par défaut · fournisseur/canal/outil interchangeables · tout est pluggable</code></p>
### 📢 Annonces
Utilisez ce tableau pour les avis importants (changements incompatibles, avis de sécurité, fenêtres de maintenance et bloqueurs de version).
| Date (UTC) | Niveau | Avis | Action |
| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 2026-02-19 | _Critique_ | Nous ne sommes **pas affiliés** à `openagen/zeroclaw` ou `zeroclaw.org`. Le domaine `zeroclaw.org` pointe actuellement vers le fork `openagen/zeroclaw`, et ce domaine/dépôt usurpe l'identité de notre site web/projet officiel. | Ne faites pas confiance aux informations, binaires, levées de fonds ou annonces provenant de ces sources. Utilisez uniquement [ce dépôt](https://github.com/zeroclaw-labs/zeroclaw) et nos comptes sociaux vérifiés. |
| 2026-02-21 | _Important_ | Notre site officiel est désormais en ligne : [zeroclawlabs.ai](https://zeroclawlabs.ai). Merci pour votre patience pendant cette attente. Nous constatons toujours des tentatives d'usurpation : ne participez à aucune activité d'investissement/financement au nom de ZeroClaw si elle n'est pas publiée via nos canaux officiels. | Utilisez [ce dépôt](https://github.com/zeroclaw-labs/zeroclaw) comme source unique de vérité. Suivez [X (@zeroclawlabs)](https://x.com/zeroclawlabs?s=21), [Telegram (@zeroclawlabs)](https://t.me/zeroclawlabs), [Facebook (groupe)](https://www.facebook.com/groups/zeroclaw), [Reddit (r/zeroclawlabs)](https://www.reddit.com/r/zeroclawlabs/), et [Xiaohongshu](https://www.xiaohongshu.com/user/profile/67cbfc43000000000d008307?xsec_token=AB73VnYnGNx5y36EtnnZfGmAmS-6Wzv8WMuGpfwfkg6Yc%3D&xsec_source=pc_search) pour les mises à jour officielles. |
| 2026-02-19 | _Important_ | Anthropic a mis à jour les conditions d'utilisation de l'authentification et des identifiants le 2026-02-19. L'authentification OAuth (Free, Pro, Max) est exclusivement destinée à Claude Code et Claude.ai ; l'utilisation de tokens OAuth de Claude Free/Pro/Max dans tout autre produit, outil ou service (y compris Agent SDK) n'est pas autorisée et peut violer les Conditions d'utilisation grand public. | Veuillez temporairement éviter les intégrations OAuth de Claude Code pour prévenir toute perte potentielle. Clause originale : [Authentication and Credential Use](https://code.claude.com/docs/en/legal-and-compliance#authentication-and-credential-use). |
### ✨ Fonctionnalités
- 🏎️ **Runtime Léger par Défaut :** Les workflows CLI courants et de statut s'exécutent dans une enveloppe mémoire de quelques mégaoctets sur les builds de production.
- 💰 **Déploiement Économique :** Conçu pour les cartes à faible coût et les petites instances cloud sans dépendances runtime lourdes.
- ⚡ **Démarrages à Froid Rapides :** Le runtime Rust mono-binaire maintient le démarrage des commandes et démons quasi instantané pour les opérations quotidiennes.
- 🌍 **Architecture Portable :** Un workflow binaire unique sur ARM, x86 et RISC-V avec fournisseurs/canaux/outils interchangeables.
### Pourquoi les équipes choisissent ZeroClaw
- **Léger par défaut :** petit binaire Rust, démarrage rapide, empreinte mémoire faible.
- **Sécurisé par conception :** appairage, sandboxing strict, listes d'autorisation explicites, portée de workspace.
- **Entièrement interchangeable :** les systèmes centraux sont des traits (fournisseurs, canaux, outils, mémoire, tunnels).
- **Aucun verrouillage :** support de fournisseur compatible OpenAI + endpoints personnalisés pluggables.
## Instantané de Benchmark (ZeroClaw vs OpenClaw, Reproductible)
Benchmark rapide sur machine locale (macOS arm64, fév. 2026) normalisé pour matériel edge 0.8 GHz.
| | OpenClaw | NanoBot | PicoClaw | ZeroClaw 🦀 |
| ---------------------------- | ------------- | -------------- | --------------- | --------------------- |
| **Langage** | TypeScript | Python | Go | **Rust** |
| **RAM** | > 1 Go | > 100 Mo | < 10 Mo | **< 5 Mo** |
| **Démarrage (cœur 0.8 GHz)** | > 500s | > 30s | < 1s | **< 10ms** |
| **Taille Binaire** | ~28 Mo (dist) | N/A (Scripts) | ~8 Mo | **3.4 Mo** |
| **Coût** | Mac Mini 599$ | Linux SBC ~50$ | Carte Linux 10$ | **Tout matériel 10$** |
> Notes : Les résultats ZeroClaw sont mesurés sur des builds de production utilisant `/usr/bin/time -l`. OpenClaw nécessite le runtime Node.js (typiquement ~390 Mo de surcharge mémoire supplémentaire), tandis que NanoBot nécessite le runtime Python. PicoClaw et ZeroClaw sont des binaires statiques. Les chiffres RAM ci-dessus sont la mémoire runtime ; les exigences de compilation build-time sont plus élevées.
<p align="center">
<img src="zero-claw.jpeg" alt="Comparaison ZeroClaw vs OpenClaw" width="800" />
</p>
### Mesure locale reproductible
Les affirmations de benchmark peuvent dériver au fil de l'évolution du code et des toolchains, donc mesurez toujours votre build actuel localement :
```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
```
Exemple d'échantillon (macOS arm64, mesuré le 18 février 2026) :
- Taille binaire release : `8.8M`
- `zeroclaw --help` : environ `0.02s` de temps réel, ~`3.9 Mo` d'empreinte mémoire maximale
- `zeroclaw status` : environ `0.01s` de temps réel, ~`4.1 Mo` d'empreinte mémoire maximale
## Prérequis
<details>
<summary><strong>Windows</strong></summary>
### Windows — Requis
1. **Visual Studio Build Tools** (fournit le linker MSVC et le Windows SDK) :
```powershell
winget install Microsoft.VisualStudio.2022.BuildTools
```
Pendant l'installation (ou via le Visual Studio Installer), sélectionnez la charge de travail **"Développement Desktop en C++"**.
2. **Toolchain Rust :**
```powershell
winget install Rustlang.Rustup
```
Après l'installation, ouvrez un nouveau terminal et exécutez `rustup default stable` pour vous assurer que la toolchain stable est active.
3. **Vérifiez** que les deux fonctionnent :
```powershell
rustc --version
cargo --version
```
### Windows — Optionnel
- **Docker Desktop** — requis seulement si vous utilisez le [runtime sandboxé Docker](#support-runtime-actuel) (`runtime.kind = "docker"`). Installez via `winget install Docker.DockerDesktop`.
</details>
<details>
<summary><strong>Linux / macOS</strong></summary>
### Linux / macOS — Requis
1. **Outils de build essentiels :**
- **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 :** Installez les Outils de Ligne de Commande Xcode : `xcode-select --install`
2. **Toolchain Rust :**
```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```
Voir [rustup.rs](https://rustup.rs) pour les détails.
3. **Vérifiez :**
```bash
rustc --version
cargo --version
```
### Linux / macOS — Optionnel
- **Docker** — requis seulement si vous utilisez le [runtime sandboxé Docker](#support-runtime-actuel) (`runtime.kind = "docker"`).
- **Linux (Debian/Ubuntu) :** voir [docs.docker.com](https://docs.docker.com/engine/install/ubuntu/)
- **Linux (Fedora/RHEL) :** voir [docs.docker.com](https://docs.docker.com/engine/install/fedora/)
- **macOS :** installez Docker Desktop via [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/)
</details>
## Démarrage Rapide
### Option 1 : Configuration automatisée (recommandée)
Le script `bootstrap.sh` installe Rust, clone ZeroClaw, le compile, et configure votre environnement de développement initial :
```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/bootstrap.sh | bash
```
Ceci va :
1. Installer Rust (si absent)
2. Cloner le dépôt ZeroClaw
3. Compiler ZeroClaw en mode release
4. Installer `zeroclaw` dans `~/.cargo/bin/`
5. Créer la structure de workspace par défaut dans `~/.zeroclaw/workspace/`
6. Générer un fichier de configuration `~/.zeroclaw/workspace/config.toml` de démarrage
Après le bootstrap, relancez votre shell ou exécutez `source ~/.cargo/env` pour utiliser la commande `zeroclaw` globalement.
### Option 2 : Installation manuelle
<details>
<summary><strong>Cliquez pour voir les étapes d'installation manuelle</strong></summary>
```bash
# 1. Clonez le dépôt
git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
# 2. Compilez en release
cargo build --release --locked
# 3. Installez le binaire
cargo install --path . --locked
# 4. Initialisez le workspace
zeroclaw init
# 5. Vérifiez l'installation
zeroclaw --version
zeroclaw status
```
</details>
### Après l'installation
Une fois installé (via bootstrap ou manuellement), vous devriez voir :
```
~/.zeroclaw/workspace/
├── config.toml # Configuration principale
├── .pairing # Secrets de pairing (généré au premier lancement)
├── logs/ # Journaux de daemon/agent
├── skills/ # Compétences personnalisées
└── memory/ # Stockage de contexte conversationnel
```
**Prochaines étapes :**
1. Configurez vos fournisseurs d'IA dans `~/.zeroclaw/workspace/config.toml`
2. Consultez la [référence de configuration](docs/config-reference.md) pour les options avancées
3. Lancez l'agent : `zeroclaw agent start`
4. Testez via votre canal préféré (voir [référence des canaux](docs/channels-reference.md))
## Configuration
Éditez `~/.zeroclaw/workspace/config.toml` pour configurer les fournisseurs, canaux et comportement du système.
### Référence de Configuration Rapide
```toml
[providers.anthropic]
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"
[providers.openai]
api_key = "sk-..."
model = "gpt-4o"
[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."
[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@bot:matrix.org"
password = "..."
[memory]
kind = "markdown" # ou "sqlite" ou "none"
[runtime]
kind = "native" # ou "docker" (nécessite Docker)
```
**Documents de référence complets :**
- [Référence de Configuration](docs/config-reference.md) — tous les paramètres, validations, valeurs par défaut
- [Référence des Fournisseurs](docs/providers-reference.md) — configurations spécifiques aux fournisseurs d'IA
- [Référence des Canaux](docs/channels-reference.md) — Telegram, Matrix, Slack, Discord et plus
- [Opérations](docs/operations-runbook.md) — surveillance en production, rotation des secrets, mise à l'échelle
### Support Runtime (actuel)
ZeroClaw prend en charge deux backends d'exécution de code :
- **`native`** (par défaut) — exécution de processus directe, chemin le plus rapide, idéal pour les environnements de confiance
- **`docker`** — isolation complète du conteneur, politiques de sécurité renforcées, nécessite Docker
Utilisez `runtime.kind = "docker"` si vous avez besoin d'un sandboxing strict ou de l'isolation réseau. Voir [référence de configuration](docs/config-reference.md#runtime) pour les détails complets.
## Commandes
```bash
# Gestion du workspace
zeroclaw init # Initialise un nouveau workspace
zeroclaw status # Affiche l'état du daemon/agent
zeroclaw config validate # Vérifie la syntaxe et les valeurs de config.toml
# Gestion du daemon
zeroclaw daemon start # Démarre le daemon en arrière-plan
zeroclaw daemon stop # Arrête le daemon en cours d'exécution
zeroclaw daemon restart # Redémarre le daemon (rechargement de config)
zeroclaw daemon logs # Affiche les journaux du daemon
# Gestion de l'agent
zeroclaw agent start # Démarre l'agent (nécessite daemon en cours d'exécution)
zeroclaw agent stop # Arrête l'agent
zeroclaw agent restart # Redémarre l'agent (rechargement de config)
# Opérations de pairing
zeroclaw pairing init # Génère un nouveau secret de pairing
zeroclaw pairing rotate # Fait tourner le secret de pairing existant
# Tunneling (pour exposition publique)
zeroclaw tunnel start # Démarre un tunnel vers le daemon local
zeroclaw tunnel stop # Arrête le tunnel actif
# Diagnostic
zeroclaw doctor # Exécute les vérifications de santé du système
zeroclaw version # Affiche la version et les informations de build
```
Voir [Référence des Commandes](docs/commands-reference.md) pour les options et exemples complets.
## Architecture
```
┌─────────────────────────────────────────────────────────────────┐
│ Canaux (trait) │
│ Telegram │ Matrix │ Slack │ Discord │ Web │ CLI │ Custom │
└─────────────────────────┬───────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Orchestrateur Agent │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Routage │ │ Contexte │ │ Exécution │ │
│ │ Message │ │ Mémoire │ │ Outil │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────┬───────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Fournisseurs │ │ Mémoire │ │ Outils │
│ (trait) │ │ (trait) │ │ (trait) │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ Anthropic │ │ Markdown │ │ Filesystem │
│ OpenAI │ │ SQLite │ │ Bash │
│ Gemini │ │ None │ │ Web Fetch │
│ Ollama │ │ Custom │ │ Custom │
│ Custom │ └──────────────┘ └──────────────┘
└──────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Runtime (trait) │
│ Native │ Docker │
└─────────────────────────────────────────────────────────────────┘
```
**Principes clés :**
- Tout est un **trait** — fournisseurs, canaux, outils, mémoire, tunnels
- Les canaux appellent l'orchestrateur ; l'orchestrateur appelle les fournisseurs + outils
- Le système mémoire gère le contexte conversationnel (markdown, SQLite, ou aucun)
- Le runtime abstrait l'exécution de code (natif ou Docker)
- Aucun verrouillage de fournisseur — échangez Anthropic ↔ OpenAI ↔ Gemini ↔ Ollama sans changement de code
Voir [documentation architecture](docs/architecture.svg) pour les diagrammes détaillés et les détails d'implémentation.
## Exemples
### Telegram Bot
```toml
[channels.telegram]
enabled = true
bot_token = "123456:ABC-DEF..."
allowed_users = [987654321] # Votre Telegram user ID
```
Démarrez le daemon + agent, puis envoyez un message à votre bot sur Telegram :
```
/start
Bonjour ! Pouvez-vous m'aider à écrire un script Python ?
```
Le bot répond avec le code généré par l'IA, exécute les outils si demandé, et conserve le contexte de conversation.
### Matrix (chiffré de bout en bout)
```toml
[channels.matrix]
enabled = true
homeserver_url = "https://matrix.org"
username = "@zeroclaw:matrix.org"
password = "..."
device_name = "zeroclaw-prod"
e2ee_enabled = true
```
Invitez `@zeroclaw:matrix.org` dans une salle chiffrée, et le bot répondra avec le chiffrement complet. Voir [Guide Matrix E2EE](docs/matrix-e2ee-guide.md) pour la configuration de vérification de dispositif.
### Multi-Fournisseur
```toml
[providers.anthropic]
enabled = true
api_key = "sk-ant-..."
model = "claude-sonnet-4-20250514"
[providers.openai]
enabled = true
api_key = "sk-..."
model = "gpt-4o"
[orchestrator]
default_provider = "anthropic"
fallback_providers = ["openai"] # Bascule en cas d'erreur du fournisseur
```
Si Anthropic échoue ou rate-limit, l'orchestrateur bascule automatiquement vers OpenAI.
### Mémoire Personnalisée
```toml
[memory]
kind = "sqlite"
path = "~/.zeroclaw/workspace/memory/conversations.db"
retention_days = 90 # Purge automatique après 90 jours
```
Ou utilisez Markdown pour un stockage lisible par l'humain :
```toml
[memory]
kind = "markdown"
path = "~/.zeroclaw/workspace/memory/"
```
Voir [Référence de Configuration](docs/config-reference.md#memory) pour toutes les options mémoire.
## Support de Fournisseur
| Fournisseur | Statut | Clé API | Modèles Exemple |
| ----------------- | ----------- | ------------------- | ---------------------------------------------------- |
| **Anthropic** | ✅ Stable | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514`, `claude-opus-4-20250514` |
| **OpenAI** | ✅ Stable | `OPENAI_API_KEY` | `gpt-4o`, `gpt-4o-mini`, `o1`, `o1-mini` |
| **Google Gemini** | ✅ Stable | `GOOGLE_API_KEY` | `gemini-2.0-flash-exp`, `gemini-exp-1206` |
| **Ollama** | ✅ Stable | N/A (local) | `llama3.3`, `qwen2.5`, `phi4` |
| **Cerebras** | ✅ Stable | `CEREBRAS_API_KEY` | `llama-3.3-70b` |
| **Groq** | ✅ Stable | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
| **Mistral** | 🚧 Planifié | `MISTRAL_API_KEY` | TBD |
| **Cohere** | 🚧 Planifié | `COHERE_API_KEY` | TBD |
### Endpoints Personnalisés
ZeroClaw prend en charge les endpoints compatibles OpenAI :
```toml
[providers.custom]
enabled = true
api_key = "..."
base_url = "https://api.your-llm-provider.com/v1"
model = "your-model-name"
```
Exemple : utilisez [LiteLLM](https://github.com/BerriAI/litellm) comme proxy pour accéder à n'importe quel LLM via l'interface OpenAI.
Voir [Référence des Fournisseurs](docs/providers-reference.md) pour les détails de configuration complets.
## Support de Canal
| Canal | Statut | Authentification | Notes |
| ------------ | ----------- | ------------------------ | --------------------------------------------------------- |
| **Telegram** | ✅ Stable | Bot Token | Support complet incluant fichiers, images, boutons inline |
| **Matrix** | ✅ Stable | Mot de passe ou Token | Support E2EE avec vérification de dispositif |
| **Slack** | 🚧 Planifié | OAuth ou Bot Token | Accès workspace requis |
| **Discord** | 🚧 Planifié | Bot Token | Permissions guild requises |
| **WhatsApp** | 🚧 Planifié | Twilio ou API officielle | Compte business requis |
| **CLI** | ✅ Stable | Aucun | Interface conversationnelle directe |
| **Web** | 🚧 Planifié | Clé API ou OAuth | Interface de chat basée navigateur |
Voir [Référence des Canaux](docs/channels-reference.md) pour les instructions de configuration complètes.
## Support d'Outil
ZeroClaw fournit des outils intégrés pour l'exécution de code, l'accès au système de fichiers et la récupération web :
| Outil | Description | Runtime Requis |
| -------------------- | --------------------------- | ----------------------------- |
| **bash** | Exécute des commandes shell | Native ou Docker |
| **python** | Exécute des scripts Python | Python 3.8+ (natif) ou Docker |
| **javascript** | Exécute du code Node.js | Node.js 18+ (natif) ou Docker |
| **filesystem_read** | Lit des fichiers | Native ou Docker |
| **filesystem_write** | Écrit des fichiers | Native ou Docker |
| **web_fetch** | Récupère du contenu web | Native ou Docker |
### Sécurité de l'Exécution
- **Runtime Natif** — s'exécute en tant que processus utilisateur du daemon, accès complet au système de fichiers
- **Runtime Docker** — isolation complète du conteneur, systèmes de fichiers et réseaux séparés
Configurez la politique d'exécution dans `config.toml` :
```toml
[runtime]
kind = "docker"
allowed_tools = ["bash", "python", "filesystem_read"] # Liste d'autorisation explicite
```
Voir [Référence de Configuration](docs/config-reference.md#runtime) pour les options de sécurité complètes.
## Déploiement
### Déploiement Local (Développement)
```bash
zeroclaw daemon start
zeroclaw agent start
```
### Déploiement Serveur (Production)
Utilisez systemd pour gérer le daemon et l'agent en tant que services :
```bash
# Installez le binaire
cargo install --path . --locked
# Configurez le workspace
zeroclaw init
# Créez les fichiers de service systemd
sudo cp deployment/systemd/zeroclaw-daemon.service /etc/systemd/system/
sudo cp deployment/systemd/zeroclaw-agent.service /etc/systemd/system/
# Activez et démarrez les services
sudo systemctl enable zeroclaw-daemon zeroclaw-agent
sudo systemctl start zeroclaw-daemon zeroclaw-agent
# Vérifiez le statut
sudo systemctl status zeroclaw-daemon
sudo systemctl status zeroclaw-agent
```
Voir [Guide de Déploiement Réseau](docs/network-deployment.md) pour les instructions de déploiement en production complètes.
### Docker
```bash
# Compilez l'image
docker build -t zeroclaw:latest .
# Exécutez le conteneur
docker run -d \
--name zeroclaw \
-v ~/.zeroclaw/workspace:/workspace \
-e ANTHROPIC_API_KEY=sk-ant-... \
zeroclaw:latest
```
Voir [`Dockerfile`](Dockerfile) pour les détails de construction et les options de configuration.
### Matériel Edge
ZeroClaw est conçu pour fonctionner sur du matériel à faible consommation d'énergie :
- **Raspberry Pi Zero 2 W** — ~512 Mo RAM, cœur ARMv8 simple, <5$ coût matériel
- **Raspberry Pi 4/5** — 1 Go+ RAM, multi-cœur, idéal pour les charges de travail concurrentes
- **Orange Pi Zero 2** — ~512 Mo RAM, quad-core ARMv8, coût ultra-faible
- **SBCs x86 (Intel N100)** — 4-8 Go RAM, builds rapides, support Docker natif
Voir [Guide du Matériel](docs/hardware/README.md) pour les instructions de configuration spécifiques aux dispositifs.
## Tunneling (Exposition Publique)
Exposez votre daemon ZeroClaw local au réseau public via des tunnels sécurisés :
```bash
zeroclaw tunnel start --provider cloudflare
```
Fournisseurs de tunnel supportés :
- **Cloudflare Tunnel** — HTTPS gratuit, aucune exposition de port, support multi-domaine
- **Ngrok** — configuration rapide, domaines personnalisés (plan payant)
- **Tailscale** — réseau maillé privé, pas de port public
Voir [Référence de Configuration](docs/config-reference.md#tunnel) pour les options de configuration complètes.
## Sécurité
ZeroClaw implémente plusieurs couches de sécurité :
### Pairing
Le daemon génère un secret de pairing au premier lancement stocké dans `~/.zeroclaw/workspace/.pairing`. Les clients (agent, CLI) doivent présenter ce secret pour se connecter.
```bash
zeroclaw pairing rotate # Génère un nouveau secret et invalide l'ancien
```
### Sandboxing
- **Runtime Docker** — isolation complète du conteneur avec systèmes de fichiers et réseaux séparés
- **Runtime Natif** — exécute en tant que processus utilisateur, scoped au workspace par défaut
### Listes d'Autorisation
Les canaux peuvent restreindre l'accès par ID utilisateur :
```toml
[channels.telegram]
enabled = true
allowed_users = [123456789, 987654321] # Liste d'autorisation explicite
```
### Chiffrement
- **Matrix E2EE** — chiffrement de bout en bout complet avec vérification de dispositif
- **Transport TLS** — tout le trafic API et tunnel utilise HTTPS/TLS
Voir [Documentation Sécurité](docs/security/README.md) pour les politiques et pratiques complètes.
## Observabilité
ZeroClaw journalise vers `~/.zeroclaw/workspace/logs/` par défaut. Les journaux sont stockés par composant :
```
~/.zeroclaw/workspace/logs/
├── daemon.log # Journaux du daemon (startup, requêtes API, erreurs)
├── agent.log # Journaux de l'agent (routage message, exécution outil)
├── telegram.log # Journaux spécifiques au canal (si activé)
└── matrix.log # Journaux spécifiques au canal (si activé)
```
### Configuration de Journalisation
```toml
[logging]
level = "info" # debug, info, warn, error
path = "~/.zeroclaw/workspace/logs/"
rotation = "daily" # daily, hourly, size
max_size_mb = 100 # Pour rotation basée sur la taille
retention_days = 30 # Purge automatique après N jours
```
Voir [Référence de Configuration](docs/config-reference.md#logging) pour toutes les options de journalisation.
### Métriques (Planifié)
Support de métriques Prometheus pour la surveillance en production à venir. Suivi dans [#234](https://github.com/zeroclaw-labs/zeroclaw/issues/234).
## Compétences (Skills)
ZeroClaw prend en charge les compétences personnalisées — des modules réutilisables qui étendent les capacités du système.
### Définition de Compétence
Les compétences sont stockées dans `~/.zeroclaw/workspace/skills/<nom-compétence>/` avec cette structure :
```
skills/
└── ma-compétence/
├── skill.toml # Métadonnées de compétence (nom, description, dépendances)
├── prompt.md # Prompt système pour l'IA
└── tools/ # Outils personnalisés optionnels
└── mon_outil.py
```
### Exemple de Compétence
```toml
# skills/recherche-web/skill.toml
[skill]
name = "recherche-web"
description = "Recherche sur le web et résume les résultats"
version = "1.0.0"
[dependencies]
tools = ["web_fetch", "bash"]
```
```markdown
<!-- skills/recherche-web/prompt.md -->
Tu es un assistant de recherche. Lorsqu'on te demande de rechercher quelque chose :
1. Utilise web_fetch pour récupérer le contenu
2. Résume les résultats dans un format facile à lire
3. Cite les sources avec des URLs
```
### Utilisation de Compétences
Les compétences sont chargées automatiquement au démarrage de l'agent. Référencez-les par nom dans les conversations :
```
Utilisateur : Utilise la compétence recherche-web pour trouver les dernières actualités IA
Bot : [charge la compétence recherche-web, exécute web_fetch, résume les résultats]
```
Voir la section [Compétences (Skills)](#compétences-skills) pour les instructions de création de compétences complètes.
## Open Skills
ZeroClaw prend en charge les [Open Skills](https://github.com/openagents-com/open-skills) — un système modulaire et agnostique des fournisseurs pour étendre les capacités des agents IA.
### Activer Open Skills
```toml
[skills]
open_skills_enabled = true
# open_skills_dir = "/path/to/open-skills" # optionnel
```
Vous pouvez également surcharger au runtime avec `ZEROCLAW_OPEN_SKILLS_ENABLED` et `ZEROCLAW_OPEN_SKILLS_DIR`.
## Développement
```bash
cargo build # Build de développement
cargo build --release # Build release (codegen-units=1, fonctionne sur tous les dispositifs incluant Raspberry Pi)
cargo build --profile release-fast # Build plus rapide (codegen-units=8, nécessite 16 Go+ RAM)
cargo test # Exécute la suite de tests complète
cargo clippy --locked --all-targets -- -D clippy::correctness
cargo fmt # Format
# Exécute le benchmark de comparaison SQLite vs Markdown
cargo test --test memory_comparison -- --nocapture
```
### Hook pre-push
Un hook git exécute `cargo fmt --check`, `cargo clippy -- -D warnings`, et `cargo test` avant chaque push. Activez-le une fois :
```bash
git config core.hooksPath .githooks
```
### Dépannage de Build (erreurs OpenSSL sur Linux)
Si vous rencontrez une erreur de build `openssl-sys`, synchronisez les dépendances et recompilez avec le lockfile du dépôt :
```bash
git pull
cargo build --release --locked
cargo install --path . --force --locked
```
ZeroClaw est configuré pour utiliser `rustls` pour les dépendances HTTP/TLS ; `--locked` maintient le graphe transitif déterministe sur les environnements vierges.
Pour sauter le hook lorsque vous avez besoin d'un push rapide pendant le développement :
```bash
git push --no-verify
```
## Collaboration & Docs
Commencez par le hub de documentation pour une carte basée sur les tâches :
- Hub de documentation : [`docs/README.md`](docs/README.md)
- Table des matières unifiée docs : [`docs/SUMMARY.md`](docs/SUMMARY.md)
- Référence des commandes : [`docs/commands-reference.md`](docs/commands-reference.md)
- Référence de configuration : [`docs/config-reference.md`](docs/config-reference.md)
- Référence des fournisseurs : [`docs/providers-reference.md`](docs/providers-reference.md)
- Référence des canaux : [`docs/channels-reference.md`](docs/channels-reference.md)
- Runbook des opérations : [`docs/operations-runbook.md`](docs/operations-runbook.md)
- Dépannage : [`docs/troubleshooting.md`](docs/troubleshooting.md)
- Inventaire/classification docs : [`docs/docs-inventory.md`](docs/docs-inventory.md)
- Instantané triage PR/Issue (au 18 février 2026) : [`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
Références de collaboration principales :
- Hub de documentation : [docs/README.md](docs/README.md)
- Modèle de documentation : [docs/doc-template.md](docs/doc-template.md)
- Checklist de modification de documentation : [docs/README.md#4-documentation-change-checklist](docs/README.md#4-documentation-change-checklist)
- Référence de configuration des canaux : [docs/channels-reference.md](docs/channels-reference.md)
- Opérations de salles chiffrées Matrix : [docs/matrix-e2ee-guide.md](docs/matrix-e2ee-guide.md)
- Guide de contribution : [CONTRIBUTING.md](CONTRIBUTING.md)
- Politique de workflow PR : [docs/pr-workflow.md](docs/pr-workflow.md)
- Playbook du relecteur (triage + revue approfondie) : [docs/reviewer-playbook.md](docs/reviewer-playbook.md)
- Carte de propriété et triage CI : [docs/ci-map.md](docs/ci-map.md)
- Politique de divulgation de sécurité : [SECURITY.md](SECURITY.md)
Pour le déploiement et les opérations runtime :
- Guide de déploiement réseau : [docs/network-deployment.md](docs/network-deployment.md)
- Playbook d'agent proxy : [docs/proxy-agent-playbook.md](docs/proxy-agent-playbook.md)
## Soutenir ZeroClaw
Si ZeroClaw aide votre travail et que vous souhaitez soutenir le développement continu, vous pouvez faire un don ici :
<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="Offrez-moi un café" /></a>
### 🙏 Remerciements Spéciaux
Un remerciement sincère aux communautés et institutions qui inspirent et alimentent ce travail open-source :
- **Harvard University** — pour favoriser la curiosité intellectuelle et repousser les limites du possible.
- **MIT** — pour défendre la connaissance ouverte, l'open source, et la conviction que la technologie devrait être accessible à tous.
- **Sundai Club** — pour la communauté, l'énergie, et la volonté incessante de construire des choses qui comptent.
- **Le Monde & Au-Delà** 🌍✨ — à chaque contributeur, rêveur, et constructeur là-bas qui fait de l'open source une force pour le bien. C'est pour vous.
Nous construisons en open source parce que les meilleures idées viennent de partout. Si vous lisez ceci, vous en faites partie. Bienvenue. 🦀❤️
## ⚠️ Dépôt Officiel & Avertissement d'Usurpation d'Identité
**Ceci est le seul dépôt officiel ZeroClaw :**
> <https://github.com/zeroclaw-labs/zeroclaw>
Tout autre dépôt, organisation, domaine ou package prétendant être "ZeroClaw" ou impliquant une affiliation avec ZeroClaw Labs est **non autorisé et non affilié à ce projet**. Les forks non autorisés connus seront listés dans [TRADEMARK.md](TRADEMARK.md).
Si vous rencontrez une usurpation d'identité ou une utilisation abusive de marque, veuillez [ouvrir une issue](https://github.com/zeroclaw-labs/zeroclaw/issues).
---
## Licence
ZeroClaw est sous double licence pour une ouverture maximale et la protection des contributeurs :
| Licence | Cas d'utilisation |
| ---------------------------- | ------------------------------------------------------------ |
| [MIT](LICENSE-MIT) | Open-source, recherche, académique, usage personnel |
| [Apache 2.0](LICENSE-APACHE) | Protection de brevet, institutionnel, déploiement commercial |
Vous pouvez choisir l'une ou l'autre licence. **Les contributeurs accordent automatiquement des droits sous les deux** — voir [CLA.md](CLA.md) pour l'accord de contributeur complet.
### Marque
Le nom **ZeroClaw** et le logo sont des marques déposées de ZeroClaw Labs. Cette licence n'accorde pas la permission de les utiliser pour impliquer une approbation ou une affiliation. Voir [TRADEMARK.md](TRADEMARK.md) pour les utilisations permises et interdites.
### Protections des Contributeurs
- Vous **conservez les droits d'auteur** de vos contributions
- **Concession de brevet** (Apache 2.0) vous protège contre les réclamations de brevet par d'autres contributeurs
- Vos contributions sont **attribuées de manière permanente** dans l'historique des commits et [NOTICE](NOTICE)
- Aucun droit de marque n'est transféré en contribuant
## Contribuer
Voir [CONTRIBUTING.md](CONTRIBUTING.md) et [CLA.md](CLA.md). Implémentez un trait, soumettez une PR :
- Guide de workflow CI : [docs/ci-map.md](docs/ci-map.md)
- Nouveau `Provider` → `src/providers/`
- Nouveau `Channel` → `src/channels/`
- Nouveau `Observer` → `src/observability/`
- Nouveau `Tool` → `src/tools/`
- Nouvelle `Memory` → `src/memory/`
- Nouveau `Tunnel` → `src/tunnel/`
- Nouvelle `Skill` → `~/.zeroclaw/workspace/skills/<n>/`
---
**ZeroClaw** — Zéro surcharge. Zéro compromis. Déployez n'importe où. Échangez n'importe quoi. 🦀
## Historique des Étoiles
<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="Graphique Historique des Étoiles" src="https://api.star-history.com/svg?repos=zeroclaw-labs/zeroclaw&type=date&legend=top-left" />
</picture>
</a>
</p>
README.ja.md
-300
View File
@@ -1,300 +0,0 @@
<p align="center">
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>
<h1 align="center">ZeroClaw 🦀（日本語）</h1>
<p align="center">
<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="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://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">
🌐 言語: <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">
<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>
<p align="center">
<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>
> この文書は `README.md` の内容を、正確性と可読性を重視して日本語に整えた版です（逐語訳ではありません）。
>
> コマンド名、設定キー、API パス、Trait 名などの技術識別子は英語のまま維持しています。
>
> 最終同期日: **2026-02-19**。
## 📢 お知らせボード
重要なお知らせ（互換性破壊変更、セキュリティ告知、メンテナンス時間、リリース阻害事項など）をここに掲載します。
| 日付 (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)。 |
## 概要
ZeroClaw は、高速・省リソース・高拡張性を重視した自律エージェント実行基盤です。ZeroClawはエージェントワークフローのための**ランタイムオペレーティングシステム**です — モデル、ツール、メモリ、実行を抽象化し、エージェントを一度構築すればどこでも実行できるインフラストラクチャです。
- Rust ネイティブ実装、単一バイナリで配布可能
- Trait ベース設計（`Provider` / `Channel` / `Tool` / `Memory` など）
- セキュアデフォルト（ペアリング、明示 allowlist、サンドボックス、スコープ制御）
## ZeroClaw が選ばれる理由
- **軽量ランタイムを標準化**: CLI や `status` などの常用操作は数MB級メモリで動作。
- **低コスト環境に適合**: 低価格ボードや小規模クラウドでも、重い実行基盤なしで運用可能。
- **高速コールドスタート**: Rust 単一バイナリにより、主要コマンドと daemon 起動が非常に速い。
- **高い移植性**: ARM / x86 / RISC-V を同じ運用モデルで扱え、provider/channel/tool を差し替え可能。
## ベンチマークスナップショット（ZeroClaw vs OpenClaw、再現可能）
以下はローカルのクイック比較（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（スクリプト） | ~8MB | **~8.8 MB** |
| **コスト** | Mac Mini $599 | Linux SBC ~$50 | Linux ボード $10 | **任意の $10 ハードウェア** |
> 注記: ZeroClaw の結果は release ビルドを `/usr/bin/time -l` で計測したものです。OpenClaw は Node.js ランタイムが必要で、ランタイム由来だけで通常は約390MBの追加メモリを要します。NanoBot は Python ランタイムが必要です。PicoClaw と ZeroClaw は静的バイナリです。
<p align="center">
<img src="zero-claw.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
```
README のサンプル値（macOS arm64, 2026-02-18）:
- Release バイナリ: `8.8M`
- `zeroclaw --help`: 約 `0.02s`、ピークメモリ 約 `3.9MB`
- `zeroclaw status`: 約 `0.01s`、ピークメモリ 約 `4.1MB`
## ワンクリック導入
```bash
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
# ブラウザ/コールバックフロー（ペーストフォールバック付き）
zeroclaw auth login --provider openai-codex --profile default
zeroclaw auth paste-redirect --provider openai-codex --profile default
# 確認 / リフレッシュ / プロファイル切替
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"
```
## アーキテクチャ
すべてのサブシステムは **Trait** — 設定変更だけで実装を差し替え可能、コード変更不要。
<p align="center">
<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) を参照してください。
README.md
+72 -4
View File
@@ -11,7 +11,7 @@
<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="NOTICE"><img src="https://img.shields.io/badge/contributors-27+-green.svg" alt="Contributors" /></a>
<a href="NOTICE"><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://zeroclawlabs.cn/group.jpg"><img src="https://img.shields.io/badge/WeChat-Group-B7D7A8?logo=wechat&logoColor=white" alt="WeChat Group" /></a>
@@ -25,7 +25,7 @@ Built by students and members of the Harvard, MIT, and Sundai.Club communities.
</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.ru.md">Русский</a> · <a href="README.fr.md">Français</a> · <a href="README.vi.md">Tiếng Việt</a>
🌐 <strong>Languages:</strong> <a href="README.md">English</a> · <a href="docs/i18n/zh-CN/README.md">简体中文</a> · <a href="docs/i18n/ja/README.md">日本語</a> · <a href="docs/i18n/ru/README.md">Русский</a> · <a href="docs/i18n/fr/README.md">Français</a> · <a href="docs/i18n/vi/README.md">Tiếng Việt</a> · <a href="docs/i18n/el/README.md">Ελληνικά</a>
</p>
<p align="center">
@@ -72,6 +72,7 @@ Use this board for important notices (breaking changes, security advisories, mai
- 💰 **Cost-Efficient Deployment:** Designed for low-cost boards and small cloud instances without heavyweight runtime dependencies.
- ⚡ **Fast Cold Starts:** Single-binary Rust runtime keeps command and daemon startup near-instant for daily operations.
- 🌍 **Portable Architecture:** One binary-first workflow across ARM, x86, and RISC-V with swappable providers/channels/tools.
- 🔍 **Research Phase:** Proactive information gathering through tools before response generation — reduces hallucinations by fact-checking first.
### Why teams pick ZeroClaw
@@ -220,6 +221,32 @@ To require binary-only install with no source fallback:
brew install zeroclaw
```
### Linux pre-built installer (beginner-friendly)
For Linux hosts that prefer a pre-built binary (no local Rust build), use the
repository-maintained release installer:
```bash
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install-release.sh | bash
```
What it does:
- Detects your Linux CPU architecture (`x86_64`, `aarch64`, `armv7`)
- Downloads the matching asset from the latest official GitHub release
- Installs `zeroclaw` into a local bin directory (or `/usr/local/bin` if needed)
- Starts `zeroclaw onboard` (skip with `--no-onboard`)
Examples:
```bash
# Install and start onboarding (default)
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install-release.sh | bash
# Install only (no onboarding)
curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/main/scripts/install-release.sh | bash -s -- --no-onboard
```
### One-click bootstrap
```bash
@@ -406,7 +433,7 @@ Every subsystem is a **trait** — swap implementations with a config change, ze
| **AI Models** | `Provider` | Provider catalog via `zeroclaw providers` (built-ins + aliases, plus custom endpoints) | `custom:https://your-api.com` (OpenAI-compatible) or `anthropic-custom:https://your-api.com` |
| **Channels** | `Channel` | CLI, Telegram, Discord, Slack, Mattermost, iMessage, Matrix, Signal, WhatsApp, Linq, Email, IRC, Lark, DingTalk, QQ, Nostr, Webhook | Any messaging API |
| **Memory** | `Memory` | SQLite hybrid search, PostgreSQL backend (configurable storage provider), Lucid bridge, Markdown files, explicit `none` backend, snapshot/hydrate, optional response cache | Any persistence backend |
| **Tools** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, hardware tools | Any capability |
| **Tools** | `Tool` | shell/file/memory, cron/schedule, git, pushover, browser, http_request, screenshot/image_info, composio (opt-in), delegate, hardware tools, **WASM skills** (opt-in) | Any capability |
| **Observability** | `Observer` | Noop, Log, Multi | Prometheus, OTel |
| **Runtime** | `RuntimeAdapter` | Native, Docker (sandboxed) | Additional runtimes can be added via adapter; unsupported kinds fail fast |
| **Security** | `SecurityPolicy` | Gateway pairing, sandbox, allowlists, rate limits, filesystem scoping, encrypted secrets | — |
@@ -657,6 +684,7 @@ keyword_weight = 0.3
# schema = "public"
# table = "memories"
# connect_timeout_secs = 15
# tls = true # true = TLS (cert not verified), false = plain TCP (default)
[gateway]
port = 42617 # default
@@ -974,7 +1002,7 @@ See [aieos.org](https://aieos.org) for the full schema and live examples.
| `providers` | List supported providers and aliases |
| `channel` | List/start/doctor channels and bind Telegram identities |
| `integrations` | Inspect integration setup details |
| `skills` | List/install/remove skills |
| `skills` | List/install/remove skills; supports ClawhHub URLs, local zip files, ZeroMarket registry, git remotes |
| `migrate` | Import data from other runtimes (`migrate openclaw`) |
| `completions` | Generate shell completion scripts (`bash`, `fish`, `zsh`, `powershell`, `elvish`) |
| `hardware` | USB discover/introspect/info commands |
@@ -1021,6 +1049,45 @@ You can also override at runtime with `ZEROCLAW_OPEN_SKILLS_ENABLED`, `ZEROCLAW_
Skill installs are now gated by a built-in static security audit. `zeroclaw skills install <source>` blocks symlinks, script-like files, unsafe markdown link patterns, and high-risk shell payload snippets before accepting a skill. You can run `zeroclaw skills audit <source_or_name>` to validate a local directory or an installed skill manually.
### WASM Skills
ZeroClaw supports WASM-compiled skills installable from the [ZeroMarket](https://zeromarket.vercel.app) registry and zip-based registries like [ClawhHub](https://clawhub.ai):
```bash
# Install from ZeroMarket registry
zeroclaw skill install namespace/name
# Install from ClawhHub (auto-detected by domain)
zeroclaw skill install https://clawhub.ai/steipete/summarize
# Install using ClawhHub short prefix
zeroclaw skill install clawhub:summarize
# Install from a zip file already downloaded locally
zeroclaw skill install ~/Downloads/summarize-1.0.0.zip
# Install from any direct zip URL
zeroclaw skill install zip:https://example.com/my-skill.zip
```
If ClawhHub returns 429 (rate limit) or requires authentication, add to `~/.zeroclaw/config.toml`:
```toml
[skills]
clawhub_token = "your-clawhub-token"
```
Skills are installed to `~/.zeroclaw/workspace/skills/<name>/` and loaded automatically as tools at agent runtime. No system `unzip` binary required — zip extraction is handled in-process.
Build with WASM tool support (enabled by default):
```bash
cargo build --release # wasm-tools enabled by default
cargo build --release --no-default-features # disable wasm-tools for smaller binary
```
Publish your own skill to ZeroMarket: compile to WASM, upload `tool.wasm`, `manifest.json`, and `SKILL.md` via the ZeroMarket upload page. Use `zeroclaw skill new <name>` to scaffold a new skill project.
## Development
```bash
@@ -1069,6 +1136,7 @@ Start from the docs hub for a task-oriented map:
- Unified docs TOC: [`docs/SUMMARY.md`](docs/SUMMARY.md)
- Commands reference: [`docs/commands-reference.md`](docs/commands-reference.md)
- Config reference: [`docs/config-reference.md`](docs/config-reference.md)
- WASM skills guide: [`docs/wasm-tools-guide.md`](docs/wasm-tools-guide.md)
- Providers reference: [`docs/providers-reference.md`](docs/providers-reference.md)
- Channels reference: [`docs/channels-reference.md`](docs/channels-reference.md)
- Operations runbook: [`docs/operations-runbook.md`](docs/operations-runbook.md)
README.ru.md
-300
View File
@@ -1,300 +0,0 @@
<p align="center">
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>
<h1 align="center">ZeroClaw 🦀（Русский）</h1>
<p align="center">
<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="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://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">
🌐 Языки: <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">
<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>
<p align="center">
<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>
> Этот файл — выверенный перевод `README.md` с акцентом на точность и читаемость (не дословный перевод).
>
> Технические идентификаторы (команды, ключи конфигурации, API-пути, имена Trait) сохранены на английском.
>
> Последняя синхронизация: **2026-02-19**.
## 📢 Доска объявлений
Публикуйте здесь важные уведомления (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). |
## О проекте
ZeroClaw — это производительная и расширяемая инфраструктура автономного AI-агента. ZeroClaw — это **операционная система времени выполнения** для агентных рабочих процессов — инфраструктура, абстрагирующая модели, инструменты, память и выполнение, позволяя создавать агентов один раз и запускать где угодно.
- Нативно на Rust, единый бинарник, переносимость между ARM / x86 / RISC-V
- Архитектура на Trait (`Provider`, `Channel`, `Tool`, `Memory` и др.)
- Безопасные значения по умолчанию: pairing, явные allowlist, sandbox и scope-ограничения
## Почему выбирают ZeroClaw
- **Лёгкий runtime по умолчанию**: Повседневные CLI-операции и `status` обычно укладываются в несколько МБ памяти.
- **Оптимизирован для недорогих сред**: Подходит для бюджетных плат и небольших cloud-инстансов без тяжёлой runtime-обвязки.
- **Быстрый cold start**: Архитектура одного Rust-бинарника ускоряет запуск основных команд и daemon-режима.
- **Портативная модель деплоя**: Единый подход для ARM / x86 / RISC-V и возможность менять providers/channels/tools.
## Снимок бенчмарка (ZeroClaw vs OpenClaw, воспроизводимо)
Ниже — быстрый локальный сравнительный срез (macOS arm64, февраль 2026), нормализованный под 0.8GHz edge CPU.
| | 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 получены на release-сборке с помощью `/usr/bin/time -l`. OpenClaw требует Node.js runtime; только этот runtime обычно добавляет около 390MB дополнительного потребления памяти. NanoBot требует Python runtime. PicoClaw и ZeroClaw — статические бинарники.
<p align="center">
<img src="zero-claw.jpeg" alt="Сравнение ZeroClaw и OpenClaw" width="800" />
</p>
### Локально воспроизводимое измерение
Метрики могут меняться вместе с кодом и toolchain, поэтому проверяйте результаты в своей среде:
```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
```
Текущие примерные значения из README (macOS arm64, 2026-02-18):
- Размер release-бинарника: `8.8M`
- `zeroclaw --help`: ~`0.02s`, пик памяти ~`3.9MB`
- `zeroclaw status`: ~`0.01s`, пик памяти ~`4.1MB`
## Установка в 1 клик
```bash
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
# Браузерный/callback-поток с paste-фолбэком
zeroclaw auth login --provider openai-codex --profile default
zeroclaw auth paste-redirect --provider openai-codex --profile default
# Проверка / обновление / переключение профиля
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
# Вставка 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"
```
## Архитектура
Каждая подсистема — это **Trait**: меняйте реализации через конфигурацию, без изменения кода.
<p align="center">
<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).
README.vi.md
-1060
View File
File diff suppressed because it is too large Load Diff
README.zh-CN.md
-305
View File
@@ -1,305 +0,0 @@
<p align="center">
<img src="zeroclaw.png" alt="ZeroClaw" width="200" />
</p>
<h1 align="center">ZeroClaw 🦀（简体中文）</h1>
<p align="center">
<strong>零开销、零妥协；随处部署、万物可换。</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="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://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">
🌐 语言：<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">
<a href="bootstrap.sh">一键部署</a> |
<a href="docs/getting-started/README.md">安装入门</a> |
<a href="docs/README.zh-CN.md">文档总览</a> |
<a href="docs/SUMMARY.md">文档目录</a>
</p>
<p align="center">
<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>
> 本文是对 `README.md` 的人工对齐翻译（强调可读性与准确性，不做逐字直译）。
>
> 技术标识（命令、配置键、API 路径、Trait 名称）保持英文，避免语义漂移。
>
> 最后对齐时间：**2026-02-22**。
## 📢 公告板
用于发布重要通知（破坏性变更、安全通告、维护窗口、版本阻塞问题等）。
| 日期（UTC） | 级别 | 通知 | 处理建议 |
|---|---|---|---|
| 2026-02-19 | _紧急_ | 我们与 `openagen/zeroclaw` 及 `zeroclaw.org` **没有任何关系**。`zeroclaw.org` 当前会指向 `openagen/zeroclaw` 这个 fork，并且该域名/仓库正在冒充我们的官网与官方项目。 | 请不要相信上述来源发布的任何信息、二进制、募资活动或官方声明。请仅以[本仓库](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/) 与 [小红书账号](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 token 用于其他任何产品、工具或服务（包括 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)。 |
## 项目简介
ZeroClaw 是一个高性能、低资源占用、可组合的自主智能体运行时。ZeroClaw 是面向智能代理工作流的**运行时操作系统** — 它抽象了模型、工具、记忆和执行层，使代理可以一次构建、随处运行。
- Rust 原生实现，单二进制部署，跨 ARM / x86 / RISC-V。
- Trait 驱动架构，`Provider` / `Channel` / `Tool` / `Memory` 可替换。
- 安全默认值优先：配对鉴权、显式 allowlist、沙箱与作用域约束。
## 为什么选择 ZeroClaw
- **默认轻量运行时**：常见 CLI 与 `status` 工作流通常保持在几 MB 级内存范围。
- **低成本部署友好**：面向低价板卡与小规格云主机设计，不依赖厚重运行时。
- **冷启动速度快**：Rust 单二进制让常用命令与守护进程启动更接近“秒开”。
- **跨架构可移植**：同一套二进制优先流程覆盖 ARM / x86 / RISC-V，并保持 provider/channel/tool 可替换。
## 基准快照（ZeroClaw vs OpenClaw，可复现）
以下是本地快速基准对比（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（脚本） | ~8MB | **~8.8 MB** |
| **成本** | Mac Mini $599 | Linux SBC ~$50 | Linux 板卡 $10 | **任意 $10 硬件** |
> 说明：ZeroClaw 的数据来自 release 构建，并通过 `/usr/bin/time -l` 测得。OpenClaw 需要 Node.js 运行时环境，仅该运行时通常就会带来约 390MB 的额外内存占用；NanoBot 需要 Python 运行时环境。PicoClaw 与 ZeroClaw 为静态二进制。
<p align="center">
<img src="zero-claw.jpeg" alt="ZeroClaw vs OpenClaw 对比图" 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
```
当前 README 的样例数据（macOS arm64，2026-02-18）：
- Release 二进制：`8.8M`
- `zeroclaw --help`：约 `0.02s`，峰值内存约 `3.9MB`
- `zeroclaw status`：约 `0.01s`，峰值内存约 `4.1MB`
## 一键部署
```bash
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!"
# 启动网关（默认: 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
# 浏览器/回调流程，支持粘贴回退
zeroclaw auth login --provider openai-codex --profile default
zeroclaw auth paste-redirect --provider openai-codex --profile default
# 检查 / 刷新 / 切换 profile
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"
```
## 架构
每个子系统都是一个 **Trait** — 通过配置切换即可更换实现，无需修改代码。
<p align="center">
<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 添加；不支持的类型会快速失败 |
| **安全** | `SecurityPolicy` | Gateway 配对, 沙箱, allowlist, 速率限制, 文件系统作用域, 加密密钥 | — |
| **身份** | `IdentityConfig` | OpenClaw (markdown), AIEOS v1.1 (JSON) | 任意身份格式 |
| **隧道** | `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：
| 层级 | 实现 |
|------|------|
| **向量数据库** | Embeddings 以 BLOB 存储于 SQLite，余弦相似度搜索 |
| **关键词搜索** | 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`
- Gateway 默认要求配对：`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" # sqlite | lucid | markdown | none
auto_save = true
embedding_provider = "none" # none | openai | custom:https://...
[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.zh-CN.md`](docs/README.zh-CN.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)
- 运维手册：[`docs/operations-runbook.md`](docs/operations-runbook.md)
- 故障排查：[`docs/troubleshooting.md`](docs/troubleshooting.md)
- 文档清单与分类：[`docs/docs-inventory.md`](docs/docs-inventory.md)
- 项目 triage 快照（2026-02-18）：[`docs/project-triage-snapshot-2026-02-18.md`](docs/project-triage-snapshot-2026-02-18.md)
## 贡献与许可证
- 贡献指南：[`CONTRIBUTING.md`](CONTRIBUTING.md)
- PR 工作流：[`docs/pr-workflow.md`](docs/pr-workflow.md)
- Reviewer 指南：[`docs/reviewer-playbook.md`](docs/reviewer-playbook.md)
- 许可证：MIT 或 Apache 2.0（见 [`LICENSE-MIT`](LICENSE-MIT)、[`LICENSE-APACHE`](LICENSE-APACHE) 与 [`NOTICE`](NOTICE)）
---
如果你需要完整实现细节（架构图、全部命令、完整 API、开发流程），请直接阅读英文主文档：[`README.md`](README.md)。
SECURITY.md
+14
View File
@@ -32,6 +32,20 @@ Preferred reporting paths:
- Suggested mitigation or patch direction (if known)
- Any known workaround
## Official Channels and Anti-Fraud Notice
Impersonation scams are a real risk in open communities.
Security-critical rule:
- ZeroClaw maintainers will not ask for cryptocurrency, wallet seed phrases, or private financial credentials.
- Treat direct-message payment requests as fraudulent unless independently verified in the repository.
- Verify announcements using repository sources first.
Canonical statement and reporting guidance:
- [docs/security/official-channels-and-fraud-prevention.md](docs/security/official-channels-and-fraud-prevention.md)
## Maintainer Handling Workflow (GitHub-Native)
### 1. Intake and triage (private)
TESTING_TELEGRAM.md
+1 -1
View File
@@ -297,7 +297,7 @@ on: [push, pull_request]
jobs:
test:
runs-on: [self-hosted, Linux, X64]
runs-on: blacksmith-2vcpu-ubuntu-2404
steps:
- uses: actions/checkout@v3
- uses: actions-rs/toolchain@v1
docs/PLUGINS.md
+250
View File
@@ -0,0 +1,250 @@
# ZeroClaw Plugin System
A plugin architecture for ZeroClaw modeled after [OpenClaw's plugin system](https://github.com/openclaw/openclaw), adapted for Rust.
## Overview
The plugin system allows extending ZeroClaw with custom tools, hooks, channels, and providers without modifying the core codebase. Plugins are discovered from standard directories, loaded at startup, and registered with the host through a clean API.
## Architecture
### Key Components
1. **Manifest** (`zeroclaw.plugin.toml`): Declares plugin metadata (id, name, version, description)
2. **Plugin trait**: Defines the contract plugins must implement (`manifest()` + `register()`)
3. **PluginApi**: Passed to `register()` so plugins can contribute tools, hooks, etc.
4. **Discovery**: Scans bundled, global, and workspace extension directories
5. **Registry**: Central store managing loaded plugins, tools, hooks, and diagnostics
6. **Loader**: Orchestrates discovery → filtering → registration with error isolation
### Comparison to OpenClaw
| OpenClaw (TypeScript) | ZeroClaw (Rust) |
|------------------------------------|------------------------------------|
| `openclaw.plugin.json` | `zeroclaw.plugin.toml` |
| `OpenClawPluginDefinition` | `Plugin` trait |
| `OpenClawPluginApi` | `PluginApi` struct |
| `PluginRegistry` (class) | `PluginRegistry` struct |
| `discover()` → `load()` → `register()` | `discover_plugins()` → `load_plugins()` |
| Try/catch isolation | `catch_unwind()` panic isolation |
| `[plugins]` config section | `[plugins]` config section |
## Writing a Plugin
### 1. Create the manifest
`extensions/hello-world/zeroclaw.plugin.toml`:
```toml
id = "hello-world"
name = "Hello World"
description = "Example plugin demonstrating the ZeroClaw plugin API."
version = "0.1.0"
```
### 2. Implement the Plugin trait
`extensions/hello-world/src/lib.rs`:
```rust
use zeroclaw::plugins::{Plugin, PluginApi, PluginManifest};
use zeroclaw::tools::traits::{Tool, ToolResult};
use async_trait::async_trait;
pub struct HelloWorldPlugin {
manifest: PluginManifest,
}
impl HelloWorldPlugin {
pub fn new() -> Self {
Self {
manifest: PluginManifest {
id: "hello-world".into(),
name: Some("Hello World".into()),
description: Some("Example plugin".into()),
version: Some("0.1.0".into()),
config_schema: None,
},
}
}
}
impl Plugin for HelloWorldPlugin {
fn manifest(&self) -> &PluginManifest {
&self.manifest
}
fn register(&self, api: &mut PluginApi) -> anyhow::Result<()> {
api.logger().info("registering hello-world plugin");
api.register_tool(Box::new(HelloTool));
api.register_hook(Box::new(HelloHook));
Ok(())
}
}
// Define your tool
struct HelloTool;
#[async_trait]
impl Tool for HelloTool {
fn name(&self) -> &str { "hello" }
fn description(&self) -> &str { "Greet the user" }
fn parameters_schema(&self) -> serde_json::Value {
serde_json::json!({
"type": "object",
"properties": {
"name": { "type": "string", "description": "Name to greet" }
},
"required": ["name"]
})
}
async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
let name = args.get("name").and_then(|v| v.as_str()).unwrap_or("world");
Ok(ToolResult {
success: true,
output: format!("Hello, {name}!"),
error: None,
})
}
}
// Define your hook
struct HelloHook;
#[async_trait]
impl zeroclaw::hooks::HookHandler for HelloHook {
fn name(&self) -> &str { "hello-world:session-logger" }
async fn on_session_start(&self, session_id: &str, channel: &str) {
tracing::info!(plugin = "hello-world", session_id, channel, "session started");
}
}
```
### 3. Register as a builtin plugin
For now, plugins must be compiled into the binary. In `src/gateway/mod.rs` or wherever plugins are initialized:
```rust
use zeroclaw::plugins::{load_plugins, Plugin};
use hello_world_plugin::HelloWorldPlugin;
let builtin_plugins: Vec<Box<dyn Plugin>> = vec![
Box::new(HelloWorldPlugin::new()),
];
let registry = load_plugins(&config.plugins, workspace_dir, builtin_plugins);
```
### 4. Enable in config
`~/.zeroclaw/config.toml`:
```toml
[plugins]
enabled = true
[plugins.entries.hello-world]
enabled = true
[plugins.entries.hello-world.config]
greeting = "Howdy" # Custom config passed to the plugin
```
## Configuration
### Master Switch
```toml
[plugins]
enabled = true # Set to false to disable all plugin loading
```
### Allowlist / Denylist
```toml
[plugins]
allow = ["hello-world", "my-plugin"] # Only load these (empty = all eligible)
deny = ["bad-plugin"] # Never load these
```
### Per-Plugin Config
```toml
[plugins.entries.my-plugin]
enabled = true
[plugins.entries.my-plugin.config]
api_key = "secret"
timeout_ms = 5000
```
Access in your plugin via `api.plugin_config()`:
```rust
fn register(&self, api: &mut PluginApi) -> anyhow::Result<()> {
let cfg = api.plugin_config();
let api_key = cfg.get("api_key").and_then(|v| v.as_str());
// ...
}
```
## Discovery
Plugins are discovered from:
1. **Bundled**: Compiled-in plugins (registered directly in code)
2. **Global**: `~/.zeroclaw/extensions/`
3. **Workspace**: `<workspace>/.zeroclaw/extensions/`
4. **Custom**: Paths in `plugins.load_paths`
Each directory is scanned for subdirectories containing `zeroclaw.plugin.toml`.
## Error Isolation
Plugins are isolated from the host:
- Panics in `register()` are caught and recorded as diagnostics
- Errors returned from `register()` are logged and the plugin is marked as failed
- A bad plugin won't crash ZeroClaw
## Plugin API
### PluginApi Methods
- `register_tool(tool: Box<dyn Tool>)` — Add a tool to the registry
- `register_hook(handler: Box<dyn HookHandler>)` — Add a lifecycle hook
- `plugin_config() -> &toml::Value` — Access plugin-specific config
- `logger() -> &PluginLogger` — Get a logger scoped to this plugin
### Available Hooks
Implement `zeroclaw::hooks::HookHandler`:
- `on_session_start(session_id, channel)`
- `on_session_end(session_id, channel)`
- `on_tool_call(tool_name, args)`
- `on_tool_result(tool_name, result)`
## Future Extensions
- **Dynamic loading**: Load plugins from `.so`/`.dylib`/`.wasm` at runtime (currently requires compilation)
- **Hot reload**: Reload plugins without restarting ZeroClaw
- **Plugin marketplace**: Discover and install community plugins
- **Sandboxing**: Run untrusted plugins in isolated processes or WASM
## Testing
Run plugin system tests:
```bash
cargo test --lib plugins
```
## Example Plugins
See `extensions/hello-world/` for a complete working example.
## References
- [OpenClaw Plugin System](https://github.com/openclaw/openclaw/tree/main/src/plugins)
- [Issue #1414](https://github.com/zeroclaw-labs/zeroclaw/issues/1414)
docs/README.fr.md
-95
View File
@@ -1,95 +0,0 @@
# Hub de Documentation ZeroClaw
Cette page est le point d'entrée principal du système de documentation.
Dernière mise à jour : **20 février 2026**.
Hubs localisés : [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Русский](README.ru.md) · [Français](README.fr.md) · [Tiếng Việt](i18n/vi/README.md).
## Commencez Ici
| Je veux… | Lire ceci |
| ------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Installer et exécuter ZeroClaw rapidement | [README.md (Démarrage Rapide)](../README.md#quick-start) |
| Bootstrap en une seule commande | [one-click-bootstrap.md](one-click-bootstrap.md) |
| Trouver des commandes par tâche | [commands-reference.md](commands-reference.md) |
| Vérifier rapidement les valeurs par défaut et clés de config | [config-reference.md](config-reference.md) |
| Configurer des fournisseurs/endpoints personnalisés | [custom-providers.md](custom-providers.md) |
| Configurer le fournisseur Z.AI / GLM | [zai-glm-setup.md](zai-glm-setup.md) |
| Utiliser les modèles d'intégration LangGraph | [langgraph-integration.md](langgraph-integration.md) |
| Opérer le runtime (runbook jour-2) | [operations-runbook.md](operations-runbook.md) |
| Dépanner les problèmes d'installation/runtime/canal | [troubleshooting.md](troubleshooting.md) |
| Exécuter la configuration et diagnostics de salles chiffrées Matrix | [matrix-e2ee-guide.md](matrix-e2ee-guide.md) |
| Parcourir les docs par catégorie | [SUMMARY.md](SUMMARY.md) |
| Voir l'instantané docs des PR/issues du projet | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
## Arbre de Décision Rapide (10 secondes)
- Besoin de configuration ou installation initiale ? → [getting-started/README.md](getting-started/README.md)
- Besoin de clés CLI/config exactes ? → [reference/README.md](reference/README.md)
- Besoin d'opérations de production/service ? → [operations/README.md](operations/README.md)
- Vous voyez des échecs ou régressions ? → [troubleshooting.md](troubleshooting.md)
- Vous travaillez sur le durcissement sécurité ou la roadmap ? → [security/README.md](security/README.md)
- Vous travaillez avec des cartes/périphériques ? → [hardware/README.md](hardware/README.md)
- Contribution/revue/workflow CI ? → [contributing/README.md](contributing/README.md)
- Vous voulez la carte complète ? → [SUMMARY.md](SUMMARY.md)
## Collections (Recommandées)
- Démarrage : [getting-started/README.md](getting-started/README.md)
- Catalogues de référence : [reference/README.md](reference/README.md)
- Opérations & déploiement : [operations/README.md](operations/README.md)
- Docs sécurité : [security/README.md](security/README.md)
- Matériel/périphériques : [hardware/README.md](hardware/README.md)
- Contribution/CI : [contributing/README.md](contributing/README.md)
- Instantanés projet : [project/README.md](project/README.md)
## Par Audience
### Utilisateurs / Opérateurs
- [commands-reference.md](commands-reference.md) — recherche de commandes par workflow
- [providers-reference.md](providers-reference.md) — IDs fournisseurs, alias, variables d'environnement d'identifiants
- [channels-reference.md](channels-reference.md) — capacités des canaux et chemins de configuration
- [matrix-e2ee-guide.md](matrix-e2ee-guide.md) — configuration de salles chiffrées Matrix (E2EE) et diagnostics de non-réponse
- [config-reference.md](config-reference.md) — clés de configuration à haute signalisation et valeurs par défaut sécurisées
- [custom-providers.md](custom-providers.md) — modèles d'intégration de fournisseur personnalisé/URL de base
- [zai-glm-setup.md](zai-glm-setup.md) — configuration Z.AI/GLM et matrice d'endpoints
- [langgraph-integration.md](langgraph-integration.md) — intégration de secours pour les cas limites de modèle/appel d'outil
- [operations-runbook.md](operations-runbook.md) — opérations runtime jour-2 et flux de rollback
- [troubleshooting.md](troubleshooting.md) — signatures d'échec courantes et étapes de récupération
### Contributeurs / Mainteneurs
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
### Sécurité / Fiabilité
> Note : cette zone inclut des docs de proposition/roadmap. Pour le comportement actuel, commencez par [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), et [troubleshooting.md](troubleshooting.md).
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [audit-logging.md](audit-logging.md)
- [resource-limits.md](resource-limits.md)
- [security-roadmap.md](security-roadmap.md)
## Navigation Système & Gouvernance
- Table des matières unifiée : [SUMMARY.md](SUMMARY.md)
- Carte de structure docs (langue/partie/fonction) : [structure/README.md](structure/README.md)
- Inventaire/classification de la documentation : [docs-inventory.md](docs-inventory.md)
- Instantané de triage du projet : [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
## Autres langues
- English: [README.md](README.md)
- 简体中文: [README.zh-CN.md](README.zh-CN.md)
- 日本語: [README.ja.md](README.ja.md)
- Русский: [README.ru.md](README.ru.md)
- Tiếng Việt: [i18n/vi/README.md](i18n/vi/README.md)
docs/README.ja.md
-92
View File
@@ -1,92 +0,0 @@
# ZeroClaw ドキュメントハブ（日本語）
このページは日本語のドキュメント入口です。
最終同期日: **2026-02-18**。
> 注: コマンド名・設定キー・API パスは英語のまま記載します。実装の一次情報は英語版ドキュメントを優先してください。
## すぐに参照したい項目
| やりたいこと | 参照先 |
|---|---|
| すぐにセットアップしたい | [../README.ja.md](../README.ja.md) / [../README.md](../README.md) |
| ワンコマンドで導入したい | [one-click-bootstrap.md](one-click-bootstrap.md) |
| コマンドを用途別に確認したい | [commands-reference.md](commands-reference.md) |
| 設定キーと既定値を確認したい | [config-reference.md](config-reference.md) |
| カスタム Provider / endpoint を追加したい | [custom-providers.md](custom-providers.md) |
| Z.AI / GLM Provider を設定したい | [zai-glm-setup.md](zai-glm-setup.md) |
| LangGraph ツール連携を使いたい | [langgraph-integration.md](langgraph-integration.md) |
| 日常運用（runbook）を確認したい | [operations-runbook.md](operations-runbook.md) |
| インストール/実行トラブルを解決したい | [troubleshooting.md](troubleshooting.md) |
| 統合 TOC から探したい | [SUMMARY.md](SUMMARY.md) |
| PR/Issue の現状を把握したい | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
## 10秒ルーティング（まずここ）
- 初回セットアップや導入をしたい → [getting-started/README.md](getting-started/README.md)
- CLI/設定キーを正確に確認したい → [reference/README.md](reference/README.md)
- 本番運用やサービス管理をしたい → [operations/README.md](operations/README.md)
- エラーや不具合を解消したい → [troubleshooting.md](troubleshooting.md)
- セキュリティ方針やロードマップを見たい → [security/README.md](security/README.md)
- ボード/周辺機器を扱いたい → [hardware/README.md](hardware/README.md)
- 貢献・レビュー・CIを確認したい → [contributing/README.md](contributing/README.md)
- 全体マップを見たい → [SUMMARY.md](SUMMARY.md)
## カテゴリ別ナビゲーション（推奨）
- 入門: [getting-started/README.md](getting-started/README.md)
- リファレンス: [reference/README.md](reference/README.md)
- 運用 / デプロイ: [operations/README.md](operations/README.md)
- セキュリティ: [security/README.md](security/README.md)
- ハードウェア: [hardware/README.md](hardware/README.md)
- コントリビュート / CI: [contributing/README.md](contributing/README.md)
- プロジェクトスナップショット: [project/README.md](project/README.md)
## ロール別
### ユーザー / オペレーター
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [operations-runbook.md](operations-runbook.md)
- [troubleshooting.md](troubleshooting.md)
### コントリビューター / メンテナー
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
### セキュリティ / 信頼性
> 注: このセクションには proposal/roadmap 文書が含まれ、想定段階のコマンドや設定が記載される場合があります。現行動作は [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md) を優先してください。
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
## ドキュメント運用 / 分類
- 統合 TOC: [SUMMARY.md](SUMMARY.md)
- ドキュメント構造マップ（言語/カテゴリ/機能）: [structure/README.md](structure/README.md)
- ドキュメント一覧 / 分類: [docs-inventory.md](docs-inventory.md)
## 他言語
- English: [README.md](README.md)
- 简体中文: [README.zh-CN.md](README.zh-CN.md)
- Русский: [README.ru.md](README.ru.md)
- Français: [README.fr.md](README.fr.md)
- Tiếng Việt: [i18n/vi/README.md](i18n/vi/README.md)
docs/README.md
+12 -1
View File
@@ -4,7 +4,7 @@ This page is the primary entry point for the documentation system.
Last refreshed: **February 21, 2026**.
Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Русский](README.ru.md) · [Français](README.fr.md) · [Tiếng Việt](i18n/vi/README.md).
Localized hubs: [简体中文](i18n/zh-CN/README.md) · [日本語](i18n/ja/README.md) · [Русский](i18n/ru/README.md) · [Français](i18n/fr/README.md) · [Tiếng Việt](i18n/vi/README.md) · [Ελληνικά](i18n/el/README.md).
## Start Here
@@ -12,17 +12,22 @@ Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) ·
|---|---|
| Install and run ZeroClaw quickly | [README.md (Quick Start)](../README.md#quick-start) |
| Bootstrap in one command | [one-click-bootstrap.md](one-click-bootstrap.md) |
| Set up on Android (Termux/ADB) | [android-setup.md](android-setup.md) |
| Update or uninstall on macOS | [getting-started/macos-update-uninstall.md](getting-started/macos-update-uninstall.md) |
| Find commands by task | [commands-reference.md](commands-reference.md) |
| Check config defaults and keys quickly | [config-reference.md](config-reference.md) |
| Configure custom providers/endpoints | [custom-providers.md](custom-providers.md) |
| Configure Z.AI / GLM provider | [zai-glm-setup.md](zai-glm-setup.md) |
| Use LangGraph integration patterns | [langgraph-integration.md](langgraph-integration.md) |
| Apply proxy scope safely | [proxy-agent-playbook.md](proxy-agent-playbook.md) |
| Operate runtime (day-2 runbook) | [operations-runbook.md](operations-runbook.md) |
| Operate provider connectivity probes in CI | [operations/connectivity-probes-runbook.md](operations/connectivity-probes-runbook.md) |
| Troubleshoot install/runtime/channel issues | [troubleshooting.md](troubleshooting.md) |
| Run Matrix encrypted-room setup and diagnostics | [matrix-e2ee-guide.md](matrix-e2ee-guide.md) |
| Build deterministic SOP procedures | [sop/README.md](sop/README.md) |
| Browse docs by category | [SUMMARY.md](SUMMARY.md) |
| See project PR/issue docs snapshot | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
| Perform i18n completion for docs changes | [i18n-guide.md](i18n-guide.md) |
## Quick Decision Tree (10 seconds)
@@ -33,6 +38,7 @@ Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) ·
- Working on security hardening or roadmap? → [security/README.md](security/README.md)
- Working with boards/peripherals? → [hardware/README.md](hardware/README.md)
- Contributing/reviewing/CI workflow? → [contributing/README.md](contributing/README.md)
- Building automated SOP workflows? → [sop/README.md](sop/README.md)
- Want the full map? → [SUMMARY.md](SUMMARY.md)
## Collections (Recommended)
@@ -73,6 +79,7 @@ Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) ·
> Note: this area includes proposal/roadmap docs. For current behavior, start with [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), and [troubleshooting.md](troubleshooting.md).
- [security/README.md](security/README.md)
- [security/official-channels-and-fraud-prevention.md](security/official-channels-and-fraud-prevention.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
@@ -84,7 +91,11 @@ Localized hubs: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) ·
- Unified TOC: [SUMMARY.md](SUMMARY.md)
- Docs structure map (language/part/function): [structure/README.md](structure/README.md)
- Docs map by function: [structure/by-function.md](structure/by-function.md)
- Documentation inventory/classification: [docs-inventory.md](docs-inventory.md)
- i18n docs index: [i18n/README.md](i18n/README.md)
- i18n coverage map: [i18n-coverage.md](i18n-coverage.md)
- i18n completion guide: [i18n-guide.md](i18n-guide.md)
- i18n gap backlog: [i18n-gap-backlog.md](i18n-gap-backlog.md)
- Docs audit snapshot (2026-02-24): [docs-audit-2026-02-24.md](docs-audit-2026-02-24.md)
- Project triage snapshot: [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
docs/README.ru.md
-92
View File
@@ -1,92 +0,0 @@
# Документация ZeroClaw (Русский)
Эта страница — русскоязычная точка входа в документацию.
Последняя синхронизация: **2026-02-18**.
> Примечание: команды, ключи конфигурации и API-пути сохраняются на английском. Для первоисточника ориентируйтесь на англоязычные документы.
## Быстрые ссылки
| Что нужно | Куда смотреть |
|---|---|
| Быстро установить и запустить | [../README.ru.md](../README.ru.md) / [../README.md](../README.md) |
| Установить одной командой | [one-click-bootstrap.md](one-click-bootstrap.md) |
| Найти команды по задаче | [commands-reference.md](commands-reference.md) |
| Проверить ключи конфигурации и дефолты | [config-reference.md](config-reference.md) |
| Подключить кастомный provider / endpoint | [custom-providers.md](custom-providers.md) |
| Настроить provider Z.AI / GLM | [zai-glm-setup.md](zai-glm-setup.md) |
| Использовать интеграцию LangGraph | [langgraph-integration.md](langgraph-integration.md) |
| Операционный runbook (day-2) | [operations-runbook.md](operations-runbook.md) |
| Быстро устранить типовые проблемы | [troubleshooting.md](troubleshooting.md) |
| Открыть общий TOC docs | [SUMMARY.md](SUMMARY.md) |
| Посмотреть snapshot PR/Issue | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
## Дерево решений на 10 секунд
- Нужна первая установка и быстрый старт → [getting-started/README.md](getting-started/README.md)
- Нужны точные команды и ключи конфигурации → [reference/README.md](reference/README.md)
- Нужны операции/сервисный режим/деплой → [operations/README.md](operations/README.md)
- Есть ошибки, сбои или регрессии → [troubleshooting.md](troubleshooting.md)
- Нужны материалы по безопасности и roadmap → [security/README.md](security/README.md)
- Работаете с платами и периферией → [hardware/README.md](hardware/README.md)
- Нужны процессы вклада, ревью и CI → [contributing/README.md](contributing/README.md)
- Нужна полная карта docs → [SUMMARY.md](SUMMARY.md)
## Навигация по категориям (рекомендуется)
- Старт и установка: [getting-started/README.md](getting-started/README.md)
- Справочники: [reference/README.md](reference/README.md)
- Операции и деплой: [operations/README.md](operations/README.md)
- Безопасность: [security/README.md](security/README.md)
- Аппаратная часть: [hardware/README.md](hardware/README.md)
- Вклад и CI: [contributing/README.md](contributing/README.md)
- Снимки проекта: [project/README.md](project/README.md)
## По ролям
### Пользователи / Операторы
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [operations-runbook.md](operations-runbook.md)
- [troubleshooting.md](troubleshooting.md)
### Контрибьюторы / Мейнтейнеры
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
### Безопасность / Надёжность
> Примечание: часть документов в этом разделе относится к proposal/roadmap и может содержать гипотетические команды/конфигурации. Для текущего поведения сначала смотрите [config-reference.md](config-reference.md), [operations-runbook.md](operations-runbook.md), [troubleshooting.md](troubleshooting.md).
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
## Инвентаризация и структура docs
- Единый TOC: [SUMMARY.md](SUMMARY.md)
- Карта структуры docs (язык/раздел/функция): [structure/README.md](structure/README.md)
- Инвентарь и классификация docs: [docs-inventory.md](docs-inventory.md)
## Другие языки
- English: [README.md](README.md)
- 简体中文: [README.zh-CN.md](README.zh-CN.md)
- 日本語: [README.ja.md](README.ja.md)
- Français: [README.fr.md](README.fr.md)
- Tiếng Việt: [i18n/vi/README.md](i18n/vi/README.md)
docs/README.vi.md
-96
View File
@@ -1,96 +0,0 @@
# Hub Tài liệu ZeroClaw (Tiếng Việt)
Đây là trang chủ tiếng Việt của hệ thống tài liệu.
Đồng bộ lần cuối: **2026-02-21**.
> Lưu ý: Tên lệnh, khóa cấu hình và đường dẫn API giữ nguyên tiếng Anh. Khi có sai khác, tài liệu tiếng Anh là bản gốc. Cây tài liệu tiếng Việt đầy đủ nằm tại [i18n/vi/](i18n/vi/README.md).
Hub bản địa hóa: [简体中文](README.zh-CN.md) · [日本語](README.ja.md) · [Русский](README.ru.md) · [Français](README.fr.md) · [Tiếng Việt](README.vi.md).
## Tra cứu nhanh
| Tôi muốn… | Xem tài liệu |
| -------------------------------------------------- | ------------------------------------------------------------------------------ |
| Cài đặt và chạy nhanh | [README.vi.md (Khởi động nhanh)](../README.vi.md) / [../README.md](../README.md) |
| Cài đặt bằng một lệnh | [one-click-bootstrap.md](one-click-bootstrap.md) |
| Tìm lệnh theo tác vụ | [commands-reference.md](i18n/vi/commands-reference.md) |
| Kiểm tra giá trị mặc định và khóa cấu hình | [config-reference.md](i18n/vi/config-reference.md) |
| Kết nối provider / endpoint tùy chỉnh | [custom-providers.md](i18n/vi/custom-providers.md) |
| Cấu hình Z.AI / GLM provider | [zai-glm-setup.md](i18n/vi/zai-glm-setup.md) |
| Sử dụng tích hợp LangGraph | [langgraph-integration.md](i18n/vi/langgraph-integration.md) |
| Vận hành hàng ngày (runbook) | [operations-runbook.md](i18n/vi/operations-runbook.md) |
| Khắc phục sự cố cài đặt/chạy/kênh | [troubleshooting.md](i18n/vi/troubleshooting.md) |
| Cấu hình Matrix phòng mã hóa (E2EE) | [matrix-e2ee-guide.md](i18n/vi/matrix-e2ee-guide.md) |
| Xem theo danh mục | [SUMMARY.md](i18n/vi/SUMMARY.md) |
| Xem bản chụp PR/Issue | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
## Tìm nhanh (10 giây)
- Cài đặt lần đầu hoặc khởi động nhanh → [getting-started/README.md](i18n/vi/getting-started/README.md)
- Cần tra cứu lệnh CLI / khóa cấu hình → [reference/README.md](i18n/vi/reference/README.md)
- Cần vận hành / triển khai sản phẩm → [operations/README.md](i18n/vi/operations/README.md)
- Gặp lỗi hoặc hồi quy → [troubleshooting.md](i18n/vi/troubleshooting.md)
- Tìm hiểu bảo mật và lộ trình → [security/README.md](i18n/vi/security/README.md)
- Làm việc với bo mạch / thiết bị ngoại vi → [hardware/README.md](i18n/vi/hardware/README.md)
- Đóng góp / review / quy trình CI → [contributing/README.md](i18n/vi/contributing/README.md)
- Xem toàn bộ bản đồ tài liệu → [SUMMARY.md](i18n/vi/SUMMARY.md)
## Danh mục (Khuyến nghị)
- Bắt đầu: [getting-started/README.md](i18n/vi/getting-started/README.md)
- Tra cứu: [reference/README.md](i18n/vi/reference/README.md)
- Vận hành & triển khai: [operations/README.md](i18n/vi/operations/README.md)
- Bảo mật: [security/README.md](i18n/vi/security/README.md)
- Phần cứng & ngoại vi: [hardware/README.md](i18n/vi/hardware/README.md)
- Đóng góp & CI: [contributing/README.md](i18n/vi/contributing/README.md)
- Ảnh chụp dự án: [project/README.md](i18n/vi/project/README.md)
## Theo vai trò
### Người dùng / Vận hành
- [commands-reference.md](i18n/vi/commands-reference.md) — tra cứu lệnh theo tác vụ
- [providers-reference.md](i18n/vi/providers-reference.md) — ID provider, bí danh, biến môi trường xác thực
- [channels-reference.md](i18n/vi/channels-reference.md) — khả năng kênh và hướng dẫn thiết lập
- [matrix-e2ee-guide.md](i18n/vi/matrix-e2ee-guide.md) — thiết lập phòng mã hóa Matrix (E2EE)
- [config-reference.md](i18n/vi/config-reference.md) — khóa cấu hình quan trọng và giá trị mặc định an toàn
- [custom-providers.md](i18n/vi/custom-providers.md) — mẫu tích hợp provider / base URL tùy chỉnh
- [zai-glm-setup.md](i18n/vi/zai-glm-setup.md) — thiết lập Z.AI/GLM và ma trận endpoint
- [langgraph-integration.md](i18n/vi/langgraph-integration.md) — tích hợp dự phòng cho model/tool-calling
- [operations-runbook.md](i18n/vi/operations-runbook.md) — vận hành runtime hàng ngày và quy trình rollback
- [troubleshooting.md](i18n/vi/troubleshooting.md) — dấu hiệu lỗi thường gặp và cách khắc phục
### Người đóng góp / Bảo trì
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](i18n/vi/pr-workflow.md)
- [reviewer-playbook.md](i18n/vi/reviewer-playbook.md)
- [ci-map.md](i18n/vi/ci-map.md)
- [actions-source-policy.md](i18n/vi/actions-source-policy.md)
### Bảo mật / Độ tin cậy
> Lưu ý: Mục này gồm tài liệu đề xuất/lộ trình, có thể chứa lệnh hoặc cấu hình chưa triển khai. Để biết hành vi thực tế, xem [config-reference.md](i18n/vi/config-reference.md), [operations-runbook.md](i18n/vi/operations-runbook.md) và [troubleshooting.md](i18n/vi/troubleshooting.md) trước.
- [security/README.md](i18n/vi/security/README.md)
- [agnostic-security.md](i18n/vi/agnostic-security.md)
- [frictionless-security.md](i18n/vi/frictionless-security.md)
- [sandboxing.md](i18n/vi/sandboxing.md)
- [audit-logging.md](i18n/vi/audit-logging.md)
- [resource-limits.md](i18n/vi/resource-limits.md)
- [security-roadmap.md](i18n/vi/security-roadmap.md)
## Quản lý tài liệu
- Mục lục thống nhất (TOC): [SUMMARY.md](i18n/vi/SUMMARY.md)
- Bản đồ cấu trúc docs (ngôn ngữ/phần/chức năng): [structure/README.md](structure/README.md)
- Danh mục và phân loại tài liệu: [docs-inventory.md](docs-inventory.md)
## Ngôn ngữ khác
- English: [README.md](README.md)
- 简体中文: [README.zh-CN.md](README.zh-CN.md)
- 日本語: [README.ja.md](README.ja.md)
- Русский: [README.ru.md](README.ru.md)
- Français: [README.fr.md](README.fr.md)
docs/README.zh-CN.md
-92
View File
@@ -1,92 +0,0 @@
# ZeroClaw 文档导航（简体中文）
这是文档系统的中文入口页。
最后对齐：**2026-02-18**。
> 说明：命令、配置键、API 路径保持英文；实现细节以英文文档为准。
## 快速入口
| 我想要… | 建议阅读 |
|---|---|
| 快速安装并运行 | [../README.zh-CN.md](../README.zh-CN.md) / [../README.md](../README.md) |
| 一键安装与初始化 | [one-click-bootstrap.md](one-click-bootstrap.md) |
| 按任务找命令 | [commands-reference.md](commands-reference.md) |
| 快速查看配置默认值与关键项 | [config-reference.md](config-reference.md) |
| 接入自定义 Provider / endpoint | [custom-providers.md](custom-providers.md) |
| 配置 Z.AI / GLM Provider | [zai-glm-setup.md](zai-glm-setup.md) |
| 使用 LangGraph 工具调用集成 | [langgraph-integration.md](langgraph-integration.md) |
| 进行日常运维（runbook） | [operations-runbook.md](operations-runbook.md) |
| 快速排查安装/运行问题 | [troubleshooting.md](troubleshooting.md) |
| 统一目录导航 | [SUMMARY.md](SUMMARY.md) |
| 查看 PR/Issue 扫描快照 | [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md) |
## 10 秒决策树（先看这个）
- 首次安装或快速启动 → [getting-started/README.md](getting-started/README.md)
- 需要精确命令或配置键 → [reference/README.md](reference/README.md)
- 需要部署与服务化运维 → [operations/README.md](operations/README.md)
- 遇到报错、异常或回归 → [troubleshooting.md](troubleshooting.md)
- 查看安全现状与路线图 → [security/README.md](security/README.md)
- 接入板卡与外设 → [hardware/README.md](hardware/README.md)
- 参与贡献、评审与 CI → [contributing/README.md](contributing/README.md)
- 查看完整文档地图 → [SUMMARY.md](SUMMARY.md)
## 按目录浏览（推荐）
- 入门文档： [getting-started/README.md](getting-started/README.md)
- 参考手册： [reference/README.md](reference/README.md)
- 运维与部署： [operations/README.md](operations/README.md)
- 安全文档： [security/README.md](security/README.md)
- 硬件与外设： [hardware/README.md](hardware/README.md)
- 贡献与 CI： [contributing/README.md](contributing/README.md)
- 项目快照： [project/README.md](project/README.md)
## 按角色
### 用户 / 运维
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [operations-runbook.md](operations-runbook.md)
- [troubleshooting.md](troubleshooting.md)
### 贡献者 / 维护者
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
### 安全 / 稳定性
> 说明：本分组内有 proposal/roadmap 文档，可能包含设想中的命令或配置。当前可执行行为请优先阅读 [config-reference.md](config-reference.md)、[operations-runbook.md](operations-runbook.md)、[troubleshooting.md](troubleshooting.md)。
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
## 文档治理与分类
- 统一目录（TOC）：[SUMMARY.md](SUMMARY.md)
- 文档结构图（按语言/分区/功能）：[structure/README.md](structure/README.md)
- 文档清单与分类：[docs-inventory.md](docs-inventory.md)
## 其他语言
- English: [README.md](README.md)
- 日本語: [README.ja.md](README.ja.md)
- Русский: [README.ru.md](README.ru.md)
- Français: [README.fr.md](README.fr.md)
- Tiếng Việt: [i18n/vi/README.md](i18n/vi/README.md)
docs/SUMMARY.fr.md
+59 -53
View File
@@ -4,86 +4,92 @@ Ce fichier constitue la table des matières canonique du système de documentati
> 📖 [English version](SUMMARY.md)
Dernière mise à jour : **18 février 2026**.
Dernière mise à jour : **24 février 2026**.
## Points d'entrée par langue
- Carte de structure docs (langue/partie/fonction) : [structure/README.md](structure/README.md)
- README en anglais : [../README.md](../README.md)
- README en chinois : [../README.zh-CN.md](../README.zh-CN.md)
- README en japonais : [../README.ja.md](../README.ja.md)
- README en russe : [../README.ru.md](../README.ru.md)
- README en français : [../README.fr.md](../README.fr.md)
- README en vietnamien : [../README.vi.md](../README.vi.md)
- README en chinois : [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- README en japonais : [docs/i18n/ja/README.md](i18n/ja/README.md)
- README en russe : [docs/i18n/ru/README.md](i18n/ru/README.md)
- README en français : [docs/i18n/fr/README.md](i18n/fr/README.md)
- README en vietnamien : [docs/i18n/vi/README.md](i18n/vi/README.md)
- README en grec : [docs/i18n/el/README.md](i18n/el/README.md)
- Documentation en anglais : [README.md](README.md)
- Documentation en chinois : [README.zh-CN.md](README.zh-CN.md)
- Documentation en japonais : [README.ja.md](README.ja.md)
- Documentation en russe : [README.ru.md](README.ru.md)
- Documentation en français : [README.fr.md](README.fr.md)
- Documentation en chinois : [i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- Documentation en japonais : [i18n/ja/README.md](i18n/ja/README.md)
- Documentation en russe : [i18n/ru/README.md](i18n/ru/README.md)
- Documentation en français : [i18n/fr/README.md](i18n/fr/README.md)
- Documentation en vietnamien : [i18n/vi/README.md](i18n/vi/README.md)
- Index de localisation : [i18n/README.md](i18n/README.md)
- Carte de couverture i18n : [i18n-coverage.md](i18n-coverage.md)
- Documentation en grec : [i18n/el/README.md](i18n/el/README.md)
- Index i18n : [i18n/README.md](i18n/README.md)
- Couverture i18n : [i18n-coverage.md](i18n-coverage.md)
- Guide i18n : [i18n-guide.md](i18n-guide.md)
- Suivi des écarts : [i18n-gap-backlog.md](i18n-gap-backlog.md)
## Catégories
### 1) Démarrage rapide
- [getting-started/README.md](getting-started/README.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/one-click-bootstrap.md](i18n/fr/one-click-bootstrap.md)
- [i18n/fr/android-setup.md](i18n/fr/android-setup.md)
### 2) Référence des commandes, configuration et intégrations
- [reference/README.md](reference/README.md)
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/commands-reference.md](i18n/fr/commands-reference.md)
- [i18n/fr/providers-reference.md](i18n/fr/providers-reference.md)
- [i18n/fr/channels-reference.md](i18n/fr/channels-reference.md)
- [i18n/fr/config-reference.md](i18n/fr/config-reference.md)
- [i18n/fr/custom-providers.md](i18n/fr/custom-providers.md)
- [i18n/fr/zai-glm-setup.md](i18n/fr/zai-glm-setup.md)
- [i18n/fr/langgraph-integration.md](i18n/fr/langgraph-integration.md)
- [i18n/fr/proxy-agent-playbook.md](i18n/fr/proxy-agent-playbook.md)
### 3) Exploitation et déploiement
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
- [mattermost-setup.md](mattermost-setup.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/operations-runbook.md](i18n/fr/operations-runbook.md)
- [i18n/fr/release-process.md](i18n/fr/release-process.md)
- [i18n/fr/troubleshooting.md](i18n/fr/troubleshooting.md)
- [i18n/fr/network-deployment.md](i18n/fr/network-deployment.md)
- [i18n/fr/mattermost-setup.md](i18n/fr/mattermost-setup.md)
- [i18n/fr/nextcloud-talk-setup.md](i18n/fr/nextcloud-talk-setup.md)
### 4) Conception de la sécurité et propositions
### 4) Sécurité et gouvernance
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/agnostic-security.md](i18n/fr/agnostic-security.md)
- [i18n/fr/frictionless-security.md](i18n/fr/frictionless-security.md)
- [i18n/fr/sandboxing.md](i18n/fr/sandboxing.md)
- [i18n/fr/resource-limits.md](i18n/fr/resource-limits.md)
- [i18n/fr/audit-logging.md](i18n/fr/audit-logging.md)
- [i18n/fr/audit-event-schema.md](i18n/fr/audit-event-schema.md)
- [i18n/fr/security-roadmap.md](i18n/fr/security-roadmap.md)
### 5) Matériel et périphériques
- [hardware/README.md](hardware/README.md)
- [hardware-peripherals-design.md](hardware-peripherals-design.md)
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/hardware-peripherals-design.md](i18n/fr/hardware-peripherals-design.md)
- [i18n/fr/adding-boards-and-tools.md](i18n/fr/adding-boards-and-tools.md)
- [i18n/fr/nucleo-setup.md](i18n/fr/nucleo-setup.md)
- [i18n/fr/arduino-uno-q-setup.md](i18n/fr/arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
### 6) Contribution et CI
- [contributing/README.md](contributing/README.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [i18n/fr/pr-workflow.md](i18n/fr/pr-workflow.md)
- [i18n/fr/reviewer-playbook.md](i18n/fr/reviewer-playbook.md)
- [i18n/fr/ci-map.md](i18n/fr/ci-map.md)
- [i18n/fr/actions-source-policy.md](i18n/fr/actions-source-policy.md)
### 7) État du projet et instantanés
- [project/README.md](project/README.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-inventory.md](docs-inventory.md)
- [docs/i18n/fr/README.md](i18n/fr/README.md)
- [i18n/fr/project-triage-snapshot-2026-02-18.md](i18n/fr/project-triage-snapshot-2026-02-18.md)
- [i18n/fr/docs-audit-2026-02-24.md](i18n/fr/docs-audit-2026-02-24.md)
- [i18n/fr/docs-inventory.md](i18n/fr/docs-inventory.md)
docs/SUMMARY.ja.md
+60 -54
View File
@@ -1,89 +1,95 @@
# ZeroClaw ドキュメント目次（統合目次）
このファイルはドキュメントシステムの正規の目次です。
このファイルはドキュメントシステムの正規目次です。
> 📖 [English version](SUMMARY.md)
最終更新：**2026年2月18日**。
最終更新：**2026年2月24日**。
## 言語別入口
- ドキュメント構造マップ（言語/カテゴリ/機能）: [structure/README.md](structure/README.md)
- 英語 README：[../README.md](../README.md)
- 中国語 README：[../README.zh-CN.md](../README.zh-CN.md)
- 日本語 README：[../README.ja.md](../README.ja.md)
- ロシア語 README：[../README.ru.md](../README.ru.md)
- フランス語 README：[../README.fr.md](../README.fr.md)
- ベトナム語 README：[../README.vi.md](../README.vi.md)
- 中国語 README：[docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- 日本語 README：[docs/i18n/ja/README.md](i18n/ja/README.md)
- ロシア語 README：[docs/i18n/ru/README.md](i18n/ru/README.md)
- フランス語 README：[docs/i18n/fr/README.md](i18n/fr/README.md)
- ベトナム語 README：[docs/i18n/vi/README.md](i18n/vi/README.md)
- ギリシャ語 README：[docs/i18n/el/README.md](i18n/el/README.md)
- 英語ドキュメントハブ：[README.md](README.md)
- 中国語ドキュメントハブ：[README.zh-CN.md](README.zh-CN.md)
- 日本語ドキュメントハブ：[README.ja.md](README.ja.md)
- ロシア語ドキュメントハブ：[README.ru.md](README.ru.md)
- フランス語ドキュメントハブ：[README.fr.md](README.fr.md)
- 中国語ドキュメントハブ：[i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- 日本語ドキュメントハブ：[i18n/ja/README.md](i18n/ja/README.md)
- ロシア語ドキュメントハブ：[i18n/ru/README.md](i18n/ru/README.md)
- フランス語ドキュメントハブ：[i18n/fr/README.md](i18n/fr/README.md)
- ベトナム語ドキュメントハブ：[i18n/vi/README.md](i18n/vi/README.md)
- 国際化ドキュメント索引：[i18n/README.md](i18n/README.md)
- 国際化カバレッジマップ：[i18n-coverage.md](i18n-coverage.md)
- ギリシャ語ドキュメントハブ：[i18n/el/README.md](i18n/el/README.md)
- i18n 索引：[i18n/README.md](i18n/README.md)
- i18n カバレッジ：[i18n-coverage.md](i18n-coverage.md)
- i18n ガイド：[i18n-guide.md](i18n-guide.md)
- i18n ギャップ管理：[i18n-gap-backlog.md](i18n-gap-backlog.md)
## カテゴリ
### 1) はじめに
- [getting-started/README.md](getting-started/README.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/one-click-bootstrap.md](i18n/ja/one-click-bootstrap.md)
- [i18n/ja/android-setup.md](i18n/ja/android-setup.md)
### 2) コマンド・設定リファレンスと統合
- [reference/README.md](reference/README.md)
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/commands-reference.md](i18n/ja/commands-reference.md)
- [i18n/ja/providers-reference.md](i18n/ja/providers-reference.md)
- [i18n/ja/channels-reference.md](i18n/ja/channels-reference.md)
- [i18n/ja/config-reference.md](i18n/ja/config-reference.md)
- [i18n/ja/custom-providers.md](i18n/ja/custom-providers.md)
- [i18n/ja/zai-glm-setup.md](i18n/ja/zai-glm-setup.md)
- [i18n/ja/langgraph-integration.md](i18n/ja/langgraph-integration.md)
- [i18n/ja/proxy-agent-playbook.md](i18n/ja/proxy-agent-playbook.md)
### 3) 運用とデプロイ
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
- [mattermost-setup.md](mattermost-setup.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/operations-runbook.md](i18n/ja/operations-runbook.md)
- [i18n/ja/release-process.md](i18n/ja/release-process.md)
- [i18n/ja/troubleshooting.md](i18n/ja/troubleshooting.md)
- [i18n/ja/network-deployment.md](i18n/ja/network-deployment.md)
- [i18n/ja/mattermost-setup.md](i18n/ja/mattermost-setup.md)
- [i18n/ja/nextcloud-talk-setup.md](i18n/ja/nextcloud-talk-setup.md)
### 4) セキュリティ設計と提案
### 4) セキュリティ設計と統制
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/agnostic-security.md](i18n/ja/agnostic-security.md)
- [i18n/ja/frictionless-security.md](i18n/ja/frictionless-security.md)
- [i18n/ja/sandboxing.md](i18n/ja/sandboxing.md)
- [i18n/ja/resource-limits.md](i18n/ja/resource-limits.md)
- [i18n/ja/audit-logging.md](i18n/ja/audit-logging.md)
- [i18n/ja/audit-event-schema.md](i18n/ja/audit-event-schema.md)
- [i18n/ja/security-roadmap.md](i18n/ja/security-roadmap.md)
### 5) ハードウェアと周辺機器
- [hardware/README.md](hardware/README.md)
- [hardware-peripherals-design.md](hardware-peripherals-design.md)
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/hardware-peripherals-design.md](i18n/ja/hardware-peripherals-design.md)
- [i18n/ja/adding-boards-and-tools.md](i18n/ja/adding-boards-and-tools.md)
- [i18n/ja/nucleo-setup.md](i18n/ja/nucleo-setup.md)
- [i18n/ja/arduino-uno-q-setup.md](i18n/ja/arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
### 6) コントリビューションと CI
- [contributing/README.md](contributing/README.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [i18n/ja/pr-workflow.md](i18n/ja/pr-workflow.md)
- [i18n/ja/reviewer-playbook.md](i18n/ja/reviewer-playbook.md)
- [i18n/ja/ci-map.md](i18n/ja/ci-map.md)
- [i18n/ja/actions-source-policy.md](i18n/ja/actions-source-policy.md)
### 7) プロジェクト状況とスナップショット
- [project/README.md](project/README.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-inventory.md](docs-inventory.md)
- [docs/i18n/ja/README.md](i18n/ja/README.md)
- [i18n/ja/project-triage-snapshot-2026-02-18.md](i18n/ja/project-triage-snapshot-2026-02-18.md)
- [i18n/ja/docs-audit-2026-02-24.md](i18n/ja/docs-audit-2026-02-24.md)
- [i18n/ja/docs-inventory.md](i18n/ja/docs-inventory.md)
docs/SUMMARY.md
+35 -11
View File
@@ -2,25 +2,30 @@
This file is the canonical table of contents for the documentation system.
Last refreshed: **February 18, 2026**.
Last refreshed: **February 25, 2026**.
## Language Entry
- Docs Structure Map (language/part/function): [structure/README.md](structure/README.md)
- Docs Map (by function): [structure/by-function.md](structure/by-function.md)
- English README: [../README.md](../README.md)
- Chinese README: [../README.zh-CN.md](../README.zh-CN.md)
- Japanese README: [../README.ja.md](../README.ja.md)
- Russian README: [../README.ru.md](../README.ru.md)
- French README: [../README.fr.md](../README.fr.md)
- Vietnamese README: [../README.vi.md](../README.vi.md)
- Chinese README: [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- Japanese README: [docs/i18n/ja/README.md](i18n/ja/README.md)
- Russian README: [docs/i18n/ru/README.md](i18n/ru/README.md)
- French README: [docs/i18n/fr/README.md](i18n/fr/README.md)
- Vietnamese README: [docs/i18n/vi/README.md](i18n/vi/README.md)
- Greek README: [docs/i18n/el/README.md](i18n/el/README.md)
- English Docs Hub: [README.md](README.md)
- Chinese Docs Hub: [README.zh-CN.md](README.zh-CN.md)
- Japanese Docs Hub: [README.ja.md](README.ja.md)
- Russian Docs Hub: [README.ru.md](README.ru.md)
- French Docs Hub: [README.fr.md](README.fr.md)
- Chinese Docs Hub: [i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- Japanese Docs Hub: [i18n/ja/README.md](i18n/ja/README.md)
- Russian Docs Hub: [i18n/ru/README.md](i18n/ru/README.md)
- French Docs Hub: [i18n/fr/README.md](i18n/fr/README.md)
- Vietnamese Docs Hub: [i18n/vi/README.md](i18n/vi/README.md)
- Greek Docs Hub: [i18n/el/README.md](i18n/el/README.md)
- i18n Docs Index: [i18n/README.md](i18n/README.md)
- i18n Coverage Map: [i18n-coverage.md](i18n-coverage.md)
- i18n Completion Guide: [i18n-guide.md](i18n-guide.md)
- i18n Gap Backlog: [i18n-gap-backlog.md](i18n-gap-backlog.md)
## Collections
@@ -29,6 +34,8 @@ Last refreshed: **February 18, 2026**.
- [getting-started/README.md](getting-started/README.md)
- [getting-started/macos-update-uninstall.md](getting-started/macos-update-uninstall.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [docker-setup.md](docker-setup.md)
- [android-setup.md](android-setup.md)
### 2) Command/Config References & Integrations
@@ -38,14 +45,17 @@ Last refreshed: **February 18, 2026**.
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [wasm-tools-guide.md](wasm-tools-guide.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [proxy-agent-playbook.md](proxy-agent-playbook.md)
### 3) Operations & Deployment
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [operations/connectivity-probes-runbook.md](operations/connectivity-probes-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
@@ -54,11 +64,13 @@ Last refreshed: **February 18, 2026**.
### 4) Security Design & Proposals
- [security/README.md](security/README.md)
- [security/official-channels-and-fraud-prevention.md](security/official-channels-and-fraud-prevention.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [audit-event-schema.md](audit-event-schema.md)
- [security-roadmap.md](security-roadmap.md)
### 5) Hardware & Peripherals
@@ -68,6 +80,7 @@ Last refreshed: **February 18, 2026**.
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
@@ -80,9 +93,20 @@ Last refreshed: **February 18, 2026**.
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [cargo-slicer-speedup.md](cargo-slicer-speedup.md)
### 7) Project Status & Snapshot
### 7) SOP Runtime & Procedures
- [sop/README.md](sop/README.md)
- [sop/connectivity.md](sop/connectivity.md)
- [sop/syntax.md](sop/syntax.md)
- [sop/observability.md](sop/observability.md)
- [sop/cookbook.md](sop/cookbook.md)
### 8) Project Status & Snapshot
- [project/README.md](project/README.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-audit-2026-02-24.md](docs-audit-2026-02-24.md)
- [i18n-gap-backlog.md](i18n-gap-backlog.md)
- [docs-inventory.md](docs-inventory.md)
docs/SUMMARY.ru.md
+59 -53
View File
@@ -4,86 +4,92 @@
> 📖 [English version](SUMMARY.md)
Последнее обновление: **18 февраля 2026 г.**
Последнее обновление: **24 февраля 2026 г.**
## Языковые точки входа
- Карта структуры docs (язык/раздел/функция): [structure/README.md](structure/README.md)
- README на английском: [../README.md](../README.md)
- README на китайском: [../README.zh-CN.md](../README.zh-CN.md)
- README на японском: [../README.ja.md](../README.ja.md)
- README на русском: [../README.ru.md](../README.ru.md)
- README на французском: [../README.fr.md](../README.fr.md)
- README на вьетнамском: [../README.vi.md](../README.vi.md)
- README на китайском: [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- README на японском: [docs/i18n/ja/README.md](i18n/ja/README.md)
- README на русском: [docs/i18n/ru/README.md](i18n/ru/README.md)
- README на французском: [docs/i18n/fr/README.md](i18n/fr/README.md)
- README на вьетнамском: [docs/i18n/vi/README.md](i18n/vi/README.md)
- README на греческом: [docs/i18n/el/README.md](i18n/el/README.md)
- Документация на английском: [README.md](README.md)
- Документация на китайском: [README.zh-CN.md](README.zh-CN.md)
- Документация на японском: [README.ja.md](README.ja.md)
- Документация на русском: [README.ru.md](README.ru.md)
- Документация на французском: [README.fr.md](README.fr.md)
- Документация на китайском: [i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- Документация на японском: [i18n/ja/README.md](i18n/ja/README.md)
- Документация на русском: [i18n/ru/README.md](i18n/ru/README.md)
- Документация на французском: [i18n/fr/README.md](i18n/fr/README.md)
- Документация на вьетнамском: [i18n/vi/README.md](i18n/vi/README.md)
- Индекс локализации: [i18n/README.md](i18n/README.md)
- Карта покрытия локализации: [i18n-coverage.md](i18n-coverage.md)
- Документация на греческом: [i18n/el/README.md](i18n/el/README.md)
- Индекс i18n: [i18n/README.md](i18n/README.md)
- Карта покрытия i18n: [i18n-coverage.md](i18n-coverage.md)
- Гайд i18n: [i18n-guide.md](i18n-guide.md)
- Трекинг gap: [i18n-gap-backlog.md](i18n-gap-backlog.md)
## Разделы
### 1) Начало работы
- [getting-started/README.md](getting-started/README.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/one-click-bootstrap.md](i18n/ru/one-click-bootstrap.md)
- [i18n/ru/android-setup.md](i18n/ru/android-setup.md)
### 2) Справочник команд, конфигурации и интеграций
- [reference/README.md](reference/README.md)
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/commands-reference.md](i18n/ru/commands-reference.md)
- [i18n/ru/providers-reference.md](i18n/ru/providers-reference.md)
- [i18n/ru/channels-reference.md](i18n/ru/channels-reference.md)
- [i18n/ru/config-reference.md](i18n/ru/config-reference.md)
- [i18n/ru/custom-providers.md](i18n/ru/custom-providers.md)
- [i18n/ru/zai-glm-setup.md](i18n/ru/zai-glm-setup.md)
- [i18n/ru/langgraph-integration.md](i18n/ru/langgraph-integration.md)
- [i18n/ru/proxy-agent-playbook.md](i18n/ru/proxy-agent-playbook.md)
### 3) Эксплуатация и развёртывание
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
- [mattermost-setup.md](mattermost-setup.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/operations-runbook.md](i18n/ru/operations-runbook.md)
- [i18n/ru/release-process.md](i18n/ru/release-process.md)
- [i18n/ru/troubleshooting.md](i18n/ru/troubleshooting.md)
- [i18n/ru/network-deployment.md](i18n/ru/network-deployment.md)
- [i18n/ru/mattermost-setup.md](i18n/ru/mattermost-setup.md)
- [i18n/ru/nextcloud-talk-setup.md](i18n/ru/nextcloud-talk-setup.md)
### 4) Проектирование безопасности и предложения
### 4) Безопасность и управление
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/agnostic-security.md](i18n/ru/agnostic-security.md)
- [i18n/ru/frictionless-security.md](i18n/ru/frictionless-security.md)
- [i18n/ru/sandboxing.md](i18n/ru/sandboxing.md)
- [i18n/ru/resource-limits.md](i18n/ru/resource-limits.md)
- [i18n/ru/audit-logging.md](i18n/ru/audit-logging.md)
- [i18n/ru/audit-event-schema.md](i18n/ru/audit-event-schema.md)
- [i18n/ru/security-roadmap.md](i18n/ru/security-roadmap.md)
### 5) Оборудование и периферия
- [hardware/README.md](hardware/README.md)
- [hardware-peripherals-design.md](hardware-peripherals-design.md)
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/hardware-peripherals-design.md](i18n/ru/hardware-peripherals-design.md)
- [i18n/ru/adding-boards-and-tools.md](i18n/ru/adding-boards-and-tools.md)
- [i18n/ru/nucleo-setup.md](i18n/ru/nucleo-setup.md)
- [i18n/ru/arduino-uno-q-setup.md](i18n/ru/arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
### 6) Участие в проекте и CI
- [contributing/README.md](contributing/README.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [i18n/ru/pr-workflow.md](i18n/ru/pr-workflow.md)
- [i18n/ru/reviewer-playbook.md](i18n/ru/reviewer-playbook.md)
- [i18n/ru/ci-map.md](i18n/ru/ci-map.md)
- [i18n/ru/actions-source-policy.md](i18n/ru/actions-source-policy.md)
### 7) Состояние проекта и снимки
- [project/README.md](project/README.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-inventory.md](docs-inventory.md)
- [docs/i18n/ru/README.md](i18n/ru/README.md)
- [i18n/ru/project-triage-snapshot-2026-02-18.md](i18n/ru/project-triage-snapshot-2026-02-18.md)
- [i18n/ru/docs-audit-2026-02-24.md](i18n/ru/docs-audit-2026-02-24.md)
- [i18n/ru/docs-inventory.md](i18n/ru/docs-inventory.md)
docs/SUMMARY.zh-CN.md
+57 -51
View File
@@ -4,86 +4,92 @@
> 📖 [English version](SUMMARY.md)
最后更新：**2026年2月18日**。
最后更新：**2026年2月24日**。
## 语言入口
- 文档结构图（按语言/分区/功能）：[structure/README.md](structure/README.md)
- 英文 README：[../README.md](../README.md)
- 中文 README：[../README.zh-CN.md](../README.zh-CN.md)
- 日文 README：[../README.ja.md](../README.ja.md)
- 俄文 README：[../README.ru.md](../README.ru.md)
- 法文 README：[../README.fr.md](../README.fr.md)
- 越南文 README：[../README.vi.md](../README.vi.md)
- 中文 README：[docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- 日文 README：[docs/i18n/ja/README.md](i18n/ja/README.md)
- 俄文 README：[docs/i18n/ru/README.md](i18n/ru/README.md)
- 法文 README：[docs/i18n/fr/README.md](i18n/fr/README.md)
- 越南文 README：[docs/i18n/vi/README.md](i18n/vi/README.md)
- 希腊文 README：[docs/i18n/el/README.md](i18n/el/README.md)
- 英文文档中心：[README.md](README.md)
- 中文文档中心：[README.zh-CN.md](README.zh-CN.md)
- 日文文档中心：[README.ja.md](README.ja.md)
- 俄文文档中心：[README.ru.md](README.ru.md)
- 法文文档中心：[README.fr.md](README.fr.md)
- 中文文档中心：[i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- 日文文档中心：[i18n/ja/README.md](i18n/ja/README.md)
- 俄文文档中心：[i18n/ru/README.md](i18n/ru/README.md)
- 法文文档中心：[i18n/fr/README.md](i18n/fr/README.md)
- 越南文文档中心：[i18n/vi/README.md](i18n/vi/README.md)
- 希腊文文档中心：[i18n/el/README.md](i18n/el/README.md)
- 国际化文档索引：[i18n/README.md](i18n/README.md)
- 国际化覆盖图：[i18n-coverage.md](i18n-coverage.md)
- 国际化执行指南：[i18n-guide.md](i18n-guide.md)
- 国际化缺口追踪：[i18n-gap-backlog.md](i18n-gap-backlog.md)
## 分类
### 1) 快速入门
- [getting-started/README.md](getting-started/README.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/one-click-bootstrap.md](i18n/zh-CN/one-click-bootstrap.md)
- [i18n/zh-CN/android-setup.md](i18n/zh-CN/android-setup.md)
### 2) 命令 / 配置参考与集成
- [reference/README.md](reference/README.md)
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/commands-reference.md](i18n/zh-CN/commands-reference.md)
- [i18n/zh-CN/providers-reference.md](i18n/zh-CN/providers-reference.md)
- [i18n/zh-CN/channels-reference.md](i18n/zh-CN/channels-reference.md)
- [i18n/zh-CN/config-reference.md](i18n/zh-CN/config-reference.md)
- [i18n/zh-CN/custom-providers.md](i18n/zh-CN/custom-providers.md)
- [i18n/zh-CN/zai-glm-setup.md](i18n/zh-CN/zai-glm-setup.md)
- [i18n/zh-CN/langgraph-integration.md](i18n/zh-CN/langgraph-integration.md)
- [i18n/zh-CN/proxy-agent-playbook.md](i18n/zh-CN/proxy-agent-playbook.md)
### 3) 运维与部署
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
- [mattermost-setup.md](mattermost-setup.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/operations-runbook.md](i18n/zh-CN/operations-runbook.md)
- [i18n/zh-CN/release-process.md](i18n/zh-CN/release-process.md)
- [i18n/zh-CN/troubleshooting.md](i18n/zh-CN/troubleshooting.md)
- [i18n/zh-CN/network-deployment.md](i18n/zh-CN/network-deployment.md)
- [i18n/zh-CN/mattermost-setup.md](i18n/zh-CN/mattermost-setup.md)
- [i18n/zh-CN/nextcloud-talk-setup.md](i18n/zh-CN/nextcloud-talk-setup.md)
### 4) 安全设计与提案
### 4) 安全设计与治理
- [security/README.md](security/README.md)
- [agnostic-security.md](agnostic-security.md)
- [frictionless-security.md](frictionless-security.md)
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [security-roadmap.md](security-roadmap.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/agnostic-security.md](i18n/zh-CN/agnostic-security.md)
- [i18n/zh-CN/frictionless-security.md](i18n/zh-CN/frictionless-security.md)
- [i18n/zh-CN/sandboxing.md](i18n/zh-CN/sandboxing.md)
- [i18n/zh-CN/resource-limits.md](i18n/zh-CN/resource-limits.md)
- [i18n/zh-CN/audit-logging.md](i18n/zh-CN/audit-logging.md)
- [i18n/zh-CN/audit-event-schema.md](i18n/zh-CN/audit-event-schema.md)
- [i18n/zh-CN/security-roadmap.md](i18n/zh-CN/security-roadmap.md)
### 5) 硬件与外设
- [hardware/README.md](hardware/README.md)
- [hardware-peripherals-design.md](hardware-peripherals-design.md)
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/hardware-peripherals-design.md](i18n/zh-CN/hardware-peripherals-design.md)
- [i18n/zh-CN/adding-boards-and-tools.md](i18n/zh-CN/adding-boards-and-tools.md)
- [i18n/zh-CN/nucleo-setup.md](i18n/zh-CN/nucleo-setup.md)
- [i18n/zh-CN/arduino-uno-q-setup.md](i18n/zh-CN/arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
### 6) 贡献与 CI
- [contributing/README.md](contributing/README.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [../CONTRIBUTING.md](../CONTRIBUTING.md)
- [pr-workflow.md](pr-workflow.md)
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [i18n/zh-CN/pr-workflow.md](i18n/zh-CN/pr-workflow.md)
- [i18n/zh-CN/reviewer-playbook.md](i18n/zh-CN/reviewer-playbook.md)
- [i18n/zh-CN/ci-map.md](i18n/zh-CN/ci-map.md)
- [i18n/zh-CN/actions-source-policy.md](i18n/zh-CN/actions-source-policy.md)
### 7) 项目状态与快照
- [project/README.md](project/README.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-inventory.md](docs-inventory.md)
- [docs/i18n/zh-CN/README.md](i18n/zh-CN/README.md)
- [i18n/zh-CN/project-triage-snapshot-2026-02-18.md](i18n/zh-CN/project-triage-snapshot-2026-02-18.md)
- [i18n/zh-CN/docs-audit-2026-02-24.md](i18n/zh-CN/docs-audit-2026-02-24.md)
- [i18n/zh-CN/docs-inventory.md](i18n/zh-CN/docs-inventory.md)
docs/actions-source-policy.md
+6 -4
View File
@@ -23,7 +23,7 @@ Selected allowlist patterns:
- `softprops/action-gh-release@*`
- `sigstore/cosign-installer@*`
- `Checkmarx/vorpal-reviewdog-github-action@*`
- `Swatinem/rust-cache@*`
- `useblacksmith/*` (Blacksmith self-hosted runner infrastructure)
## Change Control Export
@@ -78,11 +78,13 @@ Latest sweep notes:
- 2026-02-21: Added manual Vorpal reviewdog workflow for targeted secure-coding checks on supported file types
- Added allowlist pattern: `Checkmarx/vorpal-reviewdog-github-action@*`
- Workflow uses pinned source: `Checkmarx/vorpal-reviewdog-github-action@8cc292f337a2f1dea581b4f4bd73852e7becb50d` (v1.2.0)
- 2026-02-26: Standardized runner/action sources for cache and Docker build paths
- Added allowlist pattern: `Swatinem/rust-cache@*`
- Docker build jobs use `docker/setup-buildx-action` and `docker/build-push-action`
- 2026-02-17: Rust dependency cache migrated from `Swatinem/rust-cache` to `useblacksmith/rust-cache`
- No new allowlist pattern required (`useblacksmith/*` already allowlisted)
- 2026-02-16: Hidden dependency discovered in `release.yml`: `sigstore/cosign-installer@...`
- Added allowlist pattern: `sigstore/cosign-installer@*`
- 2026-02-16: Blacksmith migration blocked workflow execution
- Added allowlist pattern: `useblacksmith/*` for self-hosted runner infrastructure
- Actions: `useblacksmith/setup-docker-builder@v1`, `useblacksmith/build-push-action@v2`
- 2026-02-17: Security audit reproducibility/freshness balance update
- Added allowlist pattern: `rustsec/audit-check@*`
- Replaced inline `cargo install cargo-audit` execution with pinned `rustsec/audit-check@69366f33c96575abad1ee0dba8212993eecbe998` in `security.yml`
docs/channels-reference.md
+99 -16
View File
@@ -37,22 +37,46 @@ cli = true
Each channel is enabled by creating its sub-table (for example, `[channels_config.telegram]`).
## In-Chat Runtime Model Switching (Telegram / Discord)
One ZeroClaw runtime can serve multiple channels at once: if you configure several
channel sub-tables, `zeroclaw channel start` launches all of them in the same process.
Channel startup is best-effort: a single channel init failure is reported and skipped,
while remaining channels continue running.
When running `zeroclaw channel start` (or daemon mode), Telegram and Discord now support sender-scoped runtime switching:
## In-Chat Runtime Commands
When running `zeroclaw channel start` (or daemon mode), runtime commands include:
Telegram/Discord sender-scoped model routing:
- `/models` — show available providers and current selection
- `/models <provider>` — switch provider for the current sender session
- `/model` — show current model and cached model IDs (if available)
- `/model <model-id>` — switch model for the current sender session
- `/new` — clear conversation history and start a fresh session
Supervised tool approvals (all non-CLI channels):
- `/approve-request <tool-name>` — create a pending approval request
- `/approve-confirm <request-id>` — confirm pending request (same sender + same chat/channel only)
- `/approve-pending` — list pending requests for your current sender+chat/channel scope
- `/approve <tool-name>` — direct one-step approve + persist (`autonomy.auto_approve`, compatibility path)
- `/unapprove <tool-name>` — revoke and remove persisted approval
- `/approvals` — inspect runtime grants, persisted approval lists, and excluded tools
Notes:
- Switching provider or model clears only that sender's in-memory conversation history to avoid cross-model context contamination.
- `/new` clears the sender's conversation history without changing provider or model selection.
- Model cache previews come from `zeroclaw models refresh --provider <ID>`.
- These are runtime chat commands, not CLI subcommands.
- Natural-language approval intents are supported with strict parsing and policy control:
- `direct` mode (default): `授权工具 shell` grants immediately.
- `request_confirm` mode: `授权工具 shell` creates pending request, then confirm with request ID.
- `disabled` mode: approval-management must use slash commands.
- You can override natural-language approval mode per channel via `[autonomy].non_cli_natural_language_approval_mode_by_channel`.
- Approval commands are intercepted before LLM execution, so the model cannot self-escalate permissions through tool calls.
- You can restrict who can use approval-management commands via `[autonomy].non_cli_approval_approvers`.
- Configure natural-language approval mode via `[autonomy].non_cli_natural_language_approval_mode`.
- `autonomy.non_cli_excluded_tools` is reloaded from `config.toml` at runtime; `/approvals` shows the currently effective list.
- Each incoming message injects a runtime tool-availability snapshot into the system prompt, derived from the same exclusion policy used by execution.
## Inbound Image Marker Protocol
@@ -76,23 +100,23 @@ Operational notes:
Matrix and Lark support are controlled at compile time.
- Default builds are lean (`default = []`) and do not include Matrix/Lark.
- Typical local check with only hardware support:
- Default builds include Lark/Feishu (`default = ["channel-lark"]`), while Matrix remains opt-in.
- For a lean local build without Matrix/Lark:
```bash
cargo check --features hardware
cargo check --no-default-features --features hardware
```
- Enable Matrix explicitly when needed:
- Enable Matrix explicitly in a custom feature set:
```bash
cargo check --features hardware,channel-matrix
cargo check --no-default-features --features hardware,channel-matrix
```
- Enable Lark explicitly when needed:
- Enable Lark explicitly in a custom feature set:
```bash
cargo check --features hardware,channel-lark
cargo check --no-default-features --features hardware,channel-lark
```
If `[channels_config.matrix]`, `[channels_config.lark]`, or `[channels_config.feishu]` is present but the corresponding feature is not compiled in, `zeroclaw channel list`, `zeroclaw channel doctor`, and `zeroclaw channel start` will report that the channel is intentionally skipped for this build.
@@ -142,6 +166,27 @@ Field names differ by channel:
- `allowed_contacts` (iMessage)
- `allowed_pubkeys` (Nostr)
### Group-Chat Trigger Policy (Telegram/Discord/Slack/Mattermost/Lark/Feishu)
These channels support an explicit `group_reply` policy:
- `mode = "all_messages"`: reply to all group messages (subject to channel allowlist checks).
- `mode = "mention_only"`: in groups, require explicit bot mention.
- `allowed_sender_ids`: sender IDs that bypass mention gating in groups.
Important behavior:
- `allowed_sender_ids` only bypasses mention gating.
- Sender allowlists (`allowed_users`) are still enforced first.
Example shape:
```toml
[channels_config.telegram.group_reply]
mode = "mention_only" # all_messages | mention_only
allowed_sender_ids = ["123456789", "987"] # optional; "*" allowed
```
---
## 4. Per-Channel Config Examples
@@ -154,8 +199,12 @@ bot_token = "123456:telegram-token"
allowed_users = ["*"]
stream_mode = "off" # optional: off | partial
draft_update_interval_ms = 1000 # optional: edit throttle for partial streaming
mention_only = false # optional: require @mention in groups
mention_only = false # legacy fallback; used when group_reply.mode is not set
interrupt_on_new_message = false # optional: cancel in-flight same-sender same-chat request
[channels_config.telegram.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender IDs that bypass mention gate
```
Telegram notes:
@@ -171,7 +220,11 @@ bot_token = "discord-bot-token"
guild_id = "123456789012345678" # optional
allowed_users = ["*"]
listen_to_bots = false
mention_only = false
mention_only = false # legacy fallback; used when group_reply.mode is not set
[channels_config.discord.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender IDs that bypass mention gate
```
### 4.3 Slack
@@ -182,6 +235,10 @@ bot_token = "xoxb-..."
app_token = "xapp-..." # optional
channel_id = "C1234567890" # optional: single channel; omit or "*" for all accessible channels
allowed_users = ["*"]
[channels_config.slack.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender IDs that bypass mention gate
```
Slack listen behavior:
@@ -197,6 +254,11 @@ url = "https://mm.example.com"
bot_token = "mattermost-token"
channel_id = "channel-id" # required for listening
allowed_users = ["*"]
mention_only = false # legacy fallback; used when group_reply.mode is not set
[channels_config.mattermost.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender IDs that bypass mention gate
```
### 4.5 Matrix
@@ -209,6 +271,7 @@ user_id = "@zeroclaw:matrix.example.com" # optional, recommended for E2EE
device_id = "DEVICEID123" # optional, recommended for E2EE
room_id = "!room:matrix.example.com" # or room alias (#ops:matrix.example.com)
allowed_users = ["*"]
mention_only = false # optional: when true, only DM / @mention / reply-to-bot
```
See [Matrix E2EE Guide](./matrix-e2ee-guide.md) for encrypted-room troubleshooting.
@@ -308,34 +371,44 @@ verify_tls = true
```toml
[channels_config.lark]
app_id = "cli_xxx"
app_secret = "xxx"
app_id = "your_lark_app_id"
app_secret = "your_lark_app_secret"
encrypt_key = "" # optional
verification_token = "" # optional
allowed_users = ["*"]
mention_only = false # optional: require @mention in groups (DMs always allowed)
mention_only = false # legacy fallback; used when group_reply.mode is not set
use_feishu = false
receive_mode = "websocket" # or "webhook"
port = 8081 # required for webhook mode
[channels_config.lark.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender open_ids that bypass mention gate
```
### 4.12 Feishu
```toml
[channels_config.feishu]
app_id = "cli_xxx"
app_secret = "xxx"
app_id = "your_lark_app_id"
app_secret = "your_lark_app_secret"
encrypt_key = "" # optional
verification_token = "" # optional
allowed_users = ["*"]
receive_mode = "websocket" # or "webhook"
port = 8081 # required for webhook mode
[channels_config.feishu.group_reply]
mode = "all_messages" # optional: all_messages | mention_only
allowed_sender_ids = [] # optional: sender open_ids that bypass mention gate
```
Migration note:
- Legacy config `[channels_config.lark] use_feishu = true` is still supported for backward compatibility.
- Prefer `[channels_config.feishu]` for new setups.
- Inbound `image` messages are converted to multimodal markers (`[IMAGE:data:image/...;base64,...]`).
- If image download fails, ZeroClaw forwards fallback text instead of silently dropping the message.
### 4.13 Nostr
@@ -385,8 +458,18 @@ allowed_users = ["*"]
app_id = "qq-app-id"
app_secret = "qq-app-secret"
allowed_users = ["*"]
receive_mode = "webhook" # webhook (default) or websocket (legacy fallback)
environment = "production" # production (default) or sandbox
```
Notes:
- `webhook` mode is now the default and serves inbound callbacks at `POST /qq`.
- Set `environment = "sandbox"` to target `https://sandbox.api.sgroup.qq.com` for unpublished bot testing.
- QQ validation challenge payloads (`op = 13`) are auto-signed using `app_secret`.
- `X-Bot-Appid` is checked when present and must match `app_id`.
- Set `receive_mode = "websocket"` to keep the legacy gateway WS receive path.
### 4.16 Nextcloud Talk
```toml
docs/ci-map.md
+52 -14
View File
@@ -13,6 +13,8 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
- `.github/workflows/ci-run.yml` (`CI`)
- Purpose: Rust validation (`cargo fmt --all -- --check`, `cargo clippy --locked --all-targets -- -D clippy::correctness`, strict delta lint gate on changed Rust lines, `test`, release build smoke) + docs quality checks when docs change (`markdownlint` blocks only issues on changed lines; link check scans only links added on changed lines)
- Additional behavior: for Rust-impacting PRs and pushes, `CI Required Gate` requires `lint` + `test` + `build` (no PR build-only bypass)
- Additional behavior: rust-cache is partitioned per job role via `prefix-key` to reduce cache churn across lint/test/build/flake-probe lanes
- Additional behavior: emits `test-flake-probe` artifact from single-retry probe when tests fail; optional blocking can be enabled with repository variable `CI_BLOCK_ON_FLAKE_SUSPECTED=true`
- Additional behavior: PRs that change `.github/workflows/**` require at least one approving review from a login in `WORKFLOW_OWNER_LOGINS` (repository variable fallback: `theonlyhennygod,willsarg`)
- Additional behavior: PRs that change root license files (`LICENSE-APACHE`, `LICENSE-MIT`) must be authored by `willsarg`
- Additional behavior: lint gates run before `test`/`build`; when lint/docs gates fail on PRs, CI posts an actionable feedback comment with failing gate names and local fix commands
@@ -29,18 +31,39 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
- `.github/workflows/pub-docker-img.yml` (`Docker`)
- Purpose: PR Docker smoke check on `dev`/`main` PRs and publish images on tag pushes (`v*`) only
- Additional behavior: `ghcr_publish_contract_guard.py` enforces GHCR publish contract from `.github/release/ghcr-tag-policy.json` (`vX.Y.Z`, `sha-<12>`, `latest` digest parity + rollback mapping evidence)
- Additional behavior: `ghcr_vulnerability_gate.py` enforces policy-driven Trivy gate + parity checks from `.github/release/ghcr-vulnerability-policy.json` and emits `ghcr-vulnerability-gate` audit evidence
- `.github/workflows/feature-matrix.yml` (`Feature Matrix`)
- Purpose: compile-time matrix validation for `default`, `whatsapp-web`, `browser-native`, and `nightly-all-features` lanes
- Additional behavior: each lane emits machine-readable result artifacts; summary lane aggregates owner routing from `.github/release/nightly-owner-routing.json`
- Additional behavior: supports `compile` (merge-gate) and `nightly` (integration-oriented) profiles with bounded retry policy and trend snapshot artifact (`nightly-history.json`)
- Additional behavior: required-check mapping is anchored to stable job name `Feature Matrix Summary`; lane jobs stay informational
- `.github/workflows/nightly-all-features.yml` (`Nightly All-Features`)
- Purpose: legacy/dev-only nightly template; primary nightly signal is emitted by `feature-matrix.yml` nightly profile
- Additional behavior: owner routing + escalation policy is documented in `docs/operations/nightly-all-features-runbook.md`
- `.github/workflows/sec-audit.yml` (`Security Audit`)
- Purpose: dependency advisories (`rustsec/audit-check`, pinned SHA) and policy/license checks (`cargo deny`)
- Purpose: dependency advisories (`rustsec/audit-check`, pinned SHA), policy/license checks (`cargo deny`), gitleaks-based secrets governance (allowlist policy metadata + expiry guard), and SBOM snapshot artifacts (`CycloneDX` + `SPDX`)
- `.github/workflows/sec-codeql.yml` (`CodeQL Analysis`)
- Purpose: scheduled/manual static analysis for security findings
- Purpose: static analysis for security findings on PR/push (Rust/codeql paths) plus scheduled/manual runs
- `.github/workflows/ci-connectivity-probes.yml` (`Connectivity Probes`)
- Purpose: legacy manual wrapper for provider endpoint probe diagnostics (delegates to config-driven probe engine)
- Output: uploads `connectivity-report.json` and `connectivity-summary.md`
- Usage: prefer `CI Provider Connectivity` for scheduled + PR/push coverage
- `.github/workflows/ci-change-audit.yml` (`CI/CD Change Audit`)
- Purpose: machine-auditable diff report for CI/security workflow changes (line churn, new `uses:` references, unpinned action-policy violations, pipe-to-shell policy violations, broad `permissions: write-all` grants, new `pull_request_target` trigger introductions, new secret references)
- `.github/workflows/ci-provider-connectivity.yml` (`CI Provider Connectivity`)
- Purpose: scheduled/manual/provider-list probe matrix with downloadable JSON/Markdown artifacts for provider endpoint reachability
- `.github/workflows/ci-reproducible-build.yml` (`CI Reproducible Build`)
- Purpose: deterministic build drift probe (double clean-build hash comparison) with structured artifacts
- `.github/workflows/ci-supply-chain-provenance.yml` (`CI Supply Chain Provenance`)
- Purpose: release-fast artifact provenance statement generation + keyless signature bundle for supply-chain traceability
- `.github/workflows/ci-rollback.yml` (`CI Rollback Guard`)
- Purpose: deterministic rollback plan generation with guarded execute mode, marker-tag option, rollback audit artifacts, and dispatch contract for canary-abort auto-triggering
- `.github/workflows/sec-vorpal-reviewdog.yml` (`Sec Vorpal Reviewdog`)
- Purpose: manual secure-coding feedback scan for supported non-Rust files (`.py`, `.js`, `.jsx`, `.ts`, `.tsx`) using reviewdog annotations
- Noise control: excludes common test/fixture paths and test file patterns by default (`include_tests=false`)
- `.github/workflows/pub-release.yml` (`Release`)
- Purpose: build release artifacts in verification mode (manual/scheduled) and publish GitHub releases on tag push or manual publish mode
- `.github/workflows/pub-homebrew-core.yml` (`Pub Homebrew Core`)
- Purpose: manual, bot-owned Homebrew core formula bump PR flow for tagged releases
- Guardrail: release tag must match `Cargo.toml` version
- `.github/workflows/pr-label-policy-check.yml` (`Label Policy Sanity`)
- Purpose: validate shared contributor-tier policy in `.github/label-policy.json` and ensure label workflows consume that policy
- `.github/workflows/test-rust-build.yml` (`Rust Reusable Job`)
@@ -75,10 +98,11 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
## Trigger Map
- `CI`: push to `dev` and `main`, PRs to `dev` and `main`
- `CI`: push to `dev` and `main`, PRs to `dev` and `main`, merge queue `merge_group` for `dev`/`main`
- `Docker`: tag push (`v*`) for publish, matching PRs to `dev`/`main` for smoke build, manual dispatch for smoke only
- `Feature Matrix`: PR/push on Rust + workflow paths, merge queue, weekly schedule, manual dispatch
- `Nightly All-Features`: daily schedule and manual dispatch
- `Release`: tag push (`v*`), weekly schedule (verification-only), manual dispatch (verification or publish)
- `Pub Homebrew Core`: manual dispatch only
- `Security Audit`: push to `dev` and `main`, PRs to `dev` and `main`, weekly schedule
- `Sec Vorpal Reviewdog`: manual dispatch only
- `Workflow Sanity`: PR/push when `.github/workflows/**`, `.github/*.yml`, or `.github/*.yaml` change
@@ -95,29 +119,43 @@ Merge-blocking checks should stay small and deterministic. Optional checks are u
1. `CI Required Gate` failing: start with `.github/workflows/ci-run.yml`.
2. Docker failures on PRs: inspect `.github/workflows/pub-docker-img.yml` `pr-smoke` job.
- For tag-publish failures, inspect `ghcr-publish-contract.json` / `audit-event-ghcr-publish-contract.json`, `ghcr-vulnerability-gate.json` / `audit-event-ghcr-vulnerability-gate.json`, and Trivy artifacts from `pub-docker-img.yml`.
3. Release failures (tag/manual/scheduled): inspect `.github/workflows/pub-release.yml` and the `prepare` job outputs.
4. Homebrew formula publish failures: inspect `.github/workflows/pub-homebrew-core.yml` summary output and bot token/fork variables.
5. Security failures: inspect `.github/workflows/sec-audit.yml` and `deny.toml`.
6. Workflow syntax/lint failures: inspect `.github/workflows/workflow-sanity.yml`.
7. PR intake failures: inspect `.github/workflows/pr-intake-checks.yml` sticky comment and run logs.
8. Label policy parity failures: inspect `.github/workflows/pr-label-policy-check.yml`.
9. Docs failures in CI: inspect `docs-quality` job logs in `.github/workflows/ci-run.yml`.
10. Strict delta lint failures in CI: inspect `lint-strict-delta` job logs and compare with `BASE_SHA` diff scope.
4. Security failures: inspect `.github/workflows/sec-audit.yml` and `deny.toml`.
5. Workflow syntax/lint failures: inspect `.github/workflows/workflow-sanity.yml`.
6. PR intake failures: inspect `.github/workflows/pr-intake-checks.yml` sticky comment and run logs.
7. Label policy parity failures: inspect `.github/workflows/pr-label-policy-check.yml`.
8. Docs failures in CI: inspect `docs-quality` job logs in `.github/workflows/ci-run.yml`.
9. Strict delta lint failures in CI: inspect `lint-strict-delta` job logs and compare with `BASE_SHA` diff scope.
## Maintenance Rules
- Keep merge-blocking checks deterministic and reproducible (`--locked` where applicable).
- Keep merge-queue compatibility explicit by supporting `merge_group` on required workflows (`ci-run`, `sec-audit`, and `sec-codeql`).
- Keep PRs mapped to Linear issue keys (`RMN-*`/`CDV-*`/`COM-*`) via PR intake checks.
- Keep `deny.toml` advisory ignore entries in object form with explicit reasons (enforced by `deny_policy_guard.py`).
- Keep deny ignore governance metadata current in `.github/security/deny-ignore-governance.json` (owner/reason/expiry/ticket enforced by `deny_policy_guard.py`).
- Keep gitleaks allowlist governance metadata current in `.github/security/gitleaks-allowlist-governance.json` (owner/reason/expiry/ticket enforced by `secrets_governance_guard.py`).
- Keep audit event schema + retention metadata aligned with `docs/audit-event-schema.md` (`emit_audit_event.py` envelope + workflow artifact policy).
- Keep rollback operations guarded and reversible (`ci-rollback.yml` defaults to `dry-run`; `execute` is manual and policy-gated).
- Keep canary policy thresholds and sample-size rules current in `.github/release/canary-policy.json`.
- Keep GHCR tag taxonomy and immutability policy current in `.github/release/ghcr-tag-policy.json` and `docs/operations/ghcr-tag-policy.md`.
- Keep GHCR vulnerability gate policy current in `.github/release/ghcr-vulnerability-policy.json` and `docs/operations/ghcr-vulnerability-policy.md`.
- Keep pre-release stage transition policy + matrix coverage + transition audit semantics current in `.github/release/prerelease-stage-gates.json`.
- Keep required check naming stable and documented in `docs/operations/required-check-mapping.md` before changing branch protection settings.
- Follow `docs/release-process.md` for verify-before-publish release cadence and tag discipline.
- Keep merge-blocking rust quality policy aligned across `.github/workflows/ci-run.yml`, `dev/ci.sh`, and `.githooks/pre-push` (`./scripts/ci/rust_quality_gate.sh` + `./scripts/ci/rust_strict_delta_gate.sh`).
- Use `./scripts/ci/rust_strict_delta_gate.sh` (or `./dev/ci.sh lint-delta`) as the incremental strict merge gate for changed Rust lines.
- Run full strict lint audits regularly via `./scripts/ci/rust_quality_gate.sh --strict` (for example through `./dev/ci.sh lint-strict`) and track cleanup in focused PRs.
- Keep docs markdown gating incremental via `./scripts/ci/docs_quality_gate.sh` (block changed-line issues, report baseline issues separately).
- Keep docs link gating incremental via `./scripts/ci/collect_changed_links.py` + lychee (check only links added on changed lines).
- Keep docs deploy policy current in `.github/release/docs-deploy-policy.json`, `docs/operations/docs-deploy-policy.md`, and `docs/operations/docs-deploy-runbook.md`.
- Prefer explicit workflow permissions (least privilege).
- Keep Actions source policy restricted to approved allowlist patterns (see `docs/actions-source-policy.md`).
- Use path filters for expensive workflows when practical.
- Keep docs quality checks low-noise (incremental markdown + incremental added-link checks).
- Keep dependency update volume controlled (grouping + PR limits).
- Install third-party CI tooling through repository-managed pinned installers with checksum verification (for example `scripts/ci/install_gitleaks.sh`, `scripts/ci/install_syft.sh`); avoid remote `curl | sh` patterns.
- Avoid mixing onboarding/community automation with merge-gating logic.
## Automation Side-Effect Controls
docs/commands-reference.md
+74 -9
View File
@@ -2,7 +2,7 @@
This reference is derived from the current CLI surface (`zeroclaw --help`).
Last verified: **February 21, 2026**.
Last verified: **February 25, 2026**.
## Top-Level Commands
@@ -61,9 +61,11 @@ Tip:
### `gateway` / `daemon`
- `zeroclaw gateway [--host <HOST>] [--port <PORT>]`
- `zeroclaw gateway [--host <HOST>] [--port <PORT>] [--new-pairing]`
- `zeroclaw daemon [--host <HOST>] [--port <PORT>]`
`--new-pairing` clears all stored paired tokens and forces generation of a fresh pairing code on gateway startup.
### `estop`
- `zeroclaw estop` (engage `kill-all`)
@@ -123,6 +125,10 @@ Notes:
- `zeroclaw doctor traces [--limit <N>] [--event <TYPE>] [--contains <TEXT>]`
- `zeroclaw doctor traces --id <TRACE_ID>`
Provider connectivity matrix CI/local helper:
- `python3 scripts/ci/provider_connectivity_matrix.py --binary target/release-fast/zeroclaw --contract .github/connectivity/probe-contract.json`
`doctor traces` reads runtime tool/model diagnostics from `observability.runtime_trace_path`.
### `channel`
@@ -134,13 +140,39 @@ Notes:
- `zeroclaw channel add <type> <json>`
- `zeroclaw channel remove <name>`
Runtime in-chat commands (Telegram/Discord while channel server is running):
Runtime in-chat commands while channel server is running:
- `/models`
- `/models <provider>`
- `/model`
- `/model <model-id>`
- `/new`
- Telegram/Discord sender-session routing:
- `/models`
- `/models <provider>`
- `/model`
- `/model <model-id>`
- `/new`
- Supervised tool approvals (all non-CLI channels):
- `/approve-request <tool-name>` (create pending approval request)
- `/approve-confirm <request-id>` (confirm pending request; same sender + same chat/channel only)
- `/approve-pending` (list pending requests in current sender+chat/channel scope)
- `/approve <tool-name>` (direct one-step grant + persist to `autonomy.auto_approve`, compatibility path)
- `/unapprove <tool-name>` (revoke + remove from `autonomy.auto_approve`)
- `/approvals` (show runtime + persisted approval state)
- Natural-language approval behavior is controlled by `[autonomy].non_cli_natural_language_approval_mode`:
- `direct` (default): `授权工具 shell` / `approve tool shell` immediately grants
- `request_confirm`: natural-language approval creates pending request, then confirm with request ID
- `disabled`: natural-language approval commands are ignored (slash commands only)
- Optional per-channel override: `[autonomy].non_cli_natural_language_approval_mode_by_channel`
Approval safety behavior:
- Runtime approval commands are parsed and executed **before** LLM inference in the channel loop.
- Pending requests are sender+chat/channel scoped and expire automatically.
- Confirmation requires the same sender in the same chat/channel that created the request.
- Once approved and persisted, the tool remains approved across restarts until revoked.
- Optional policy gate: `[autonomy].non_cli_approval_approvers` can restrict who may execute approval-management commands.
Startup behavior for multiple channels:
- `zeroclaw channel start` starts all configured channels in one process.
- If one channel fails initialization, other channels continue to start.
- If all configured channels fail initialization, startup exits with an error.
Channel runtime also watches `config.toml` and hot-applies updates to:
- `default_provider`
@@ -162,7 +194,38 @@ Channel runtime also watches `config.toml` and hot-applies updates to:
- `zeroclaw skills install <source>`
- `zeroclaw skills remove <name>`
`<source>` accepts git remotes (`https://...`, `http://...`, `ssh://...`, and `git@host:owner/repo.git`) or a local filesystem path.
`<source>` accepts:
| Format | Example | Notes |
|---|---|---|
| **ClawhHub profile URL** | `https://clawhub.ai/steipete/summarize` | Auto-detected by domain; downloads zip from ClawhHub API |
| **ClawhHub short prefix** | `clawhub:summarize` | Short form; slug is the skill name on ClawhHub |
| **Direct zip URL** | `zip:https://example.com/skill.zip` | Any HTTPS URL returning a zip archive |
| **Local zip file** | `/path/to/skill.zip` | Zip file already downloaded to local disk |
| **Registry packages** | `namespace/name` or `namespace/name@version` | Fetched from the configured registry (default: ZeroMarket) |
| **Git remotes** | `https://github.com/…`, `git@host:owner/repo.git` | Cloned with `git clone --depth 1` |
| **Local filesystem paths** | `./my-skill` or `/abs/path/skill` | Directory copied and audited |
**ClawhHub install examples:**
```bash
# Install by profile URL (slug extracted from last path segment)
zeroclaw skill install https://clawhub.ai/steipete/summarize
# Install using short prefix
zeroclaw skill install clawhub:summarize
# Install from a zip already downloaded locally
zeroclaw skill install ~/Downloads/summarize-1.0.0.zip
```
If the ClawhHub API returns 429 (rate limit) or requires authentication, set `clawhub_token` in `[skills]` config (see [config reference](config-reference.md#skills)).
**Zip-based install behavior:**
- If the zip contains `_meta.json` (OpenClaw convention), name/version/author are read from it.
- A minimal `SKILL.toml` is written automatically if neither `SKILL.toml` nor `SKILL.md` is present in the zip.
Registry packages are installed to `~/.zeroclaw/workspace/skills/<name>/`.
`skills install` always runs a built-in static security audit before the skill is accepted. The audit blocks:
- symlinks inside the skill package
@@ -170,6 +233,8 @@ Channel runtime also watches `config.toml` and hot-applies updates to:
- high-risk command snippets (for example pipe-to-shell payloads)
- markdown links that escape the skill root, point to remote markdown, or target script files
> **Note:** The security audit applies to directory-based installs (local paths, git remotes). Zip-based installs (ClawhHub, direct zip URLs, local zip files) perform path-traversal safety checks during extraction but do not run the full static audit — review zip contents manually for untrusted sources.
Use `skills audit` to manually validate a candidate skill directory (or an installed skill by name) before sharing it.
Skill manifests (`SKILL.toml`) support `prompts` and `[[tools]]`; both are injected into the agent system prompt at runtime, so the model can follow skill instructions without manually reading skill files.
docs/config-reference.md
+325 -6
View File
@@ -2,7 +2,7 @@
This is a high-signal reference for common config sections and defaults.
Last verified: **February 21, 2026**.
Last verified: **February 25, 2026**.
Config path resolution at startup:
@@ -23,8 +23,17 @@ Schema export command:
| Key | Default | Notes |
|---|---|---|
| `default_provider` | `openrouter` | provider ID or alias |
| `provider_api` | unset | Optional API mode for `custom:<url>` providers: `openai-chat-completions` or `openai-responses` |
| `default_model` | `anthropic/claude-sonnet-4-6` | model routed through selected provider |
| `default_temperature` | `0.7` | model temperature |
| `model_support_vision` | unset (`None`) | Vision support override for active provider/model |
Notes:
- `model_support_vision = true` forces vision support on (e.g. Ollama running `llava`).
- `model_support_vision = false` forces vision support off.
- Unset keeps the provider's built-in default.
- Environment override: `ZEROCLAW_MODEL_SUPPORT_VISION` or `MODEL_SUPPORT_VISION` (values: `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`).
## `[observability]`
@@ -71,20 +80,24 @@ Operational note for container users:
- If your `config.toml` sets an explicit custom provider like `custom:https://.../v1`, a default `PROVIDER=openrouter` from Docker/container env will no longer replace it.
- Use `ZEROCLAW_PROVIDER` when you intentionally want runtime env to override a non-default configured provider.
- For OpenAI-compatible Responses fallback transport:
- `ZEROCLAW_RESPONSES_WEBSOCKET=1` forces websocket-first mode (`wss://.../responses`) for compatible providers.
- `ZEROCLAW_RESPONSES_WEBSOCKET=0` forces HTTP-only mode.
- Unset = auto (websocket-first only when endpoint host is `api.openai.com`, then HTTP fallback if websocket fails).
## `[agent]`
| Key | Default | Purpose |
|---|---|---|
| `compact_context` | `false` | When true: bootstrap_max_chars=6000, rag_chunk_limit=2. Use for 13B or smaller models |
| `max_tool_iterations` | `10` | Maximum tool-call loop turns per user message across CLI, gateway, and channels |
| `compact_context` | `true` | When true: bootstrap_max_chars=6000, rag_chunk_limit=2. Use for 13B or smaller models |
| `max_tool_iterations` | `20` | Maximum tool-call loop turns per user message across CLI, gateway, and channels |
| `max_history_messages` | `50` | Maximum conversation history messages retained per session |
| `parallel_tools` | `false` | Enable parallel tool execution within a single iteration |
| `tool_dispatcher` | `auto` | Tool dispatch strategy |
Notes:
- Setting `max_tool_iterations = 0` falls back to safe default `10`.
- Setting `max_tool_iterations = 0` falls back to safe default `20`.
- If a channel message exceeds this value, the runtime returns: `Agent exceeded maximum tool iterations (<value>)`.
- In CLI, gateway, and channel tool loops, multiple independent tool calls are executed concurrently by default when the pending calls do not require approval gating; result order remains stable.
- `parallel_tools` applies to the `Agent::turn()` API surface. It does not gate the runtime loop used by CLI, gateway, or channel handlers.
@@ -135,6 +148,97 @@ Notes:
- Corrupted/unreadable estop state falls back to fail-closed `kill_all`.
- Use CLI command `zeroclaw estop` to engage and `zeroclaw estop resume` to clear levels.
## `[security.url_access]`
| Key | Default | Purpose |
|---|---|---|
| `block_private_ip` | `true` | Block local/private/link-local/multicast addresses by default |
| `allow_cidrs` | `[]` | CIDR ranges allowed to bypass private-IP blocking (`100.64.0.0/10`, `198.18.0.0/15`) |
| `allow_domains` | `[]` | Domain patterns that bypass private-IP blocking before DNS checks (`internal.example`, `*.svc.local`) |
| `allow_loopback` | `false` | Permit loopback targets (`localhost`, `127.0.0.1`, `::1`) |
Notes:
- This policy is shared by `browser_open`, `http_request`, and `web_fetch`.
- Tool-level allowlists still apply. `allow_domains` / `allow_cidrs` only override private/local blocking.
- DNS rebinding protection remains enabled: resolved local/private IPs are denied unless explicitly allowlisted.
Example:
```toml
[security.url_access]
block_private_ip = true
allow_cidrs = ["100.64.0.0/10", "198.18.0.0/15"]
allow_domains = ["internal.example", "*.svc.local"]
allow_loopback = false
```
## `[security.syscall_anomaly]`
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `true` | Enable syscall anomaly detection over command output telemetry |
| `strict_mode` | `false` | Emit anomaly when denied syscalls are observed even if in baseline |
| `alert_on_unknown_syscall` | `true` | Alert on syscall names not present in baseline |
| `max_denied_events_per_minute` | `5` | Threshold for denied-syscall spike alerts |
| `max_total_events_per_minute` | `120` | Threshold for total syscall-event spike alerts |
| `max_alerts_per_minute` | `30` | Global alert budget guardrail per rolling minute |
| `alert_cooldown_secs` | `20` | Cooldown between identical anomaly alerts |
| `log_path` | `syscall-anomalies.log` | JSONL anomaly log path |
| `baseline_syscalls` | built-in allowlist | Expected syscall profile; unknown entries trigger alerts |
Notes:
- Detection consumes seccomp/audit hints from command `stdout`/`stderr`.
- Numeric syscall IDs in Linux audit lines are mapped to common x86_64 names when available.
- Alert budget and cooldown reduce duplicate/noisy events during repeated retries.
- `max_denied_events_per_minute` must be less than or equal to `max_total_events_per_minute`.
Example:
```toml
[security.syscall_anomaly]
enabled = true
strict_mode = false
alert_on_unknown_syscall = true
max_denied_events_per_minute = 5
max_total_events_per_minute = 120
max_alerts_per_minute = 30
alert_cooldown_secs = 20
log_path = "syscall-anomalies.log"
baseline_syscalls = ["read", "write", "openat", "close", "execve", "futex"]
```
## `[security.perplexity_filter]`
Lightweight, opt-in adversarial suffix filter that runs before provider calls in channel and gateway message pipelines.
| Key | Default | Purpose |
|---|---|---|
| `enable_perplexity_filter` | `false` | Enable pre-LLM statistical suffix anomaly blocking |
| `perplexity_threshold` | `18.0` | Character-class bigram perplexity threshold |
| `suffix_window_chars` | `64` | Trailing character window used for anomaly scoring |
| `min_prompt_chars` | `32` | Minimum prompt length before filter is evaluated |
| `symbol_ratio_threshold` | `0.20` | Minimum punctuation ratio in suffix window for blocking |
Notes:
- This filter is disabled by default to preserve baseline latency/behavior.
- The detector combines character-class perplexity with GCG-like token heuristics.
- Inputs are blocked only when anomaly conditions are met; normal natural-language prompts pass.
- Typical per-message overhead is designed to stay under `50ms` in debug-safe local tests and substantially lower in release builds.
Example:
```toml
[security.perplexity_filter]
enable_perplexity_filter = true
perplexity_threshold = 16.5
suffix_window_chars = 72
min_prompt_chars = 40
symbol_ratio_threshold = 0.25
```
## `[agents.<name>]`
Delegate sub-agent configurations. Each key under `[agents]` defines a named sub-agent that the primary agent can delegate to.
@@ -173,10 +277,52 @@ model = "qwen2.5-coder:32b"
temperature = 0.2
```
## `[research]`
Research phase allows the agent to gather information through tools before generating the main response.
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | Enable research phase |
| `trigger` | `never` | Research trigger strategy: `never`, `always`, `keywords`, `length`, `question` |
| `keywords` | `["find", "search", "check", "investigate"]` | Keywords that trigger research (when trigger = `keywords`) |
| `min_message_length` | `50` | Minimum message length to trigger research (when trigger = `length`) |
| `max_iterations` | `5` | Maximum tool calls during research phase |
| `show_progress` | `true` | Show research progress to user |
Notes:
- Research phase is **disabled by default** (`trigger = never`).
- When enabled, the agent first gathers facts through tools (grep, file_read, shell, memory search), then responds using the collected context.
- Research runs before the main agent turn and does not count toward `agent.max_tool_iterations`.
- Trigger strategies:
- `never` — research disabled (default)
- `always` — research on every user message
- `keywords` — research when message contains any keyword from the list
- `length` — research when message length exceeds `min_message_length`
- `question` — research when message contains '?'
Example:
```toml
[research]
enabled = true
trigger = "keywords"
keywords = ["find", "show", "check", "how many"]
max_iterations = 3
show_progress = true
```
The agent will research the codebase before responding to queries like:
- "Find all TODO in src/"
- "Show contents of main.rs"
- "How many files in the project?"
## `[runtime]`
| Key | Default | Purpose |
|---|---|---|
| `kind` | `native` | Runtime backend: `native`, `docker`, or `wasm` |
| `reasoning_enabled` | unset (`None`) | Global reasoning/thinking override for providers that support explicit controls |
Notes:
@@ -184,6 +330,65 @@ Notes:
- `reasoning_enabled = false` explicitly disables provider-side reasoning for supported providers (currently `ollama`, via request field `think: false`).
- `reasoning_enabled = true` explicitly requests reasoning for supported providers (`think: true` on `ollama`).
- Unset keeps provider defaults.
- Deprecated compatibility alias: `runtime.reasoning_level` is still accepted but should be migrated to `provider.reasoning_level`.
- `runtime.kind = "wasm"` enables capability-bounded module execution and disables shell/process style execution.
### `[runtime.wasm]`
| Key | Default | Purpose |
|---|---|---|
| `tools_dir` | `"tools/wasm"` | Workspace-relative directory containing `.wasm` modules |
| `fuel_limit` | `1000000` | Instruction budget per module invocation |
| `memory_limit_mb` | `64` | Per-module memory cap (MB) |
| `max_module_size_mb` | `50` | Maximum allowed `.wasm` file size (MB) |
| `allow_workspace_read` | `false` | Allow WASM host calls to read workspace files (future-facing) |
| `allow_workspace_write` | `false` | Allow WASM host calls to write workspace files (future-facing) |
| `allowed_hosts` | `[]` | Explicit network host allowlist for WASM host calls (future-facing) |
Notes:
- `allowed_hosts` entries must be normalized `host` or `host:port` strings; wildcards, schemes, and paths are rejected when `runtime.wasm.security.strict_host_validation = true`.
- Invocation-time capability overrides are controlled by `runtime.wasm.security.capability_escalation_mode`:
- `deny` (default): reject escalation above runtime baseline.
- `clamp`: reduce requested capabilities to baseline.
### `[runtime.wasm.security]`
| Key | Default | Purpose |
|---|---|---|
| `require_workspace_relative_tools_dir` | `true` | Require `runtime.wasm.tools_dir` to be workspace-relative and reject `..` traversal |
| `reject_symlink_modules` | `true` | Block symlinked `.wasm` module files during execution |
| `reject_symlink_tools_dir` | `true` | Block execution when `runtime.wasm.tools_dir` is itself a symlink |
| `strict_host_validation` | `true` | Fail config/invocation on invalid host entries instead of dropping them |
| `capability_escalation_mode` | `"deny"` | Escalation policy: `deny` or `clamp` |
| `module_hash_policy` | `"warn"` | Module integrity policy: `disabled`, `warn`, or `enforce` |
| `module_sha256` | `{}` | Optional map of module names to pinned SHA-256 digests |
Notes:
- `module_sha256` keys must match module names (without `.wasm`) and use `[A-Za-z0-9_-]` only.
- `module_sha256` values must be 64-character hexadecimal SHA-256 strings.
- `module_hash_policy = "warn"` allows execution but logs missing/mismatched digests.
- `module_hash_policy = "enforce"` blocks execution on missing/mismatched digests and requires at least one pin.
WASM profile templates:
- `dev/config.wasm.dev.toml`
- `dev/config.wasm.staging.toml`
- `dev/config.wasm.prod.toml`
## `[provider]`
| Key | Default | Purpose |
|---|---|---|
| `reasoning_level` | unset (`None`) | Reasoning effort/level override for providers that support explicit levels (currently OpenAI Codex `/responses`) |
Notes:
- Supported values: `minimal`, `low`, `medium`, `high`, `xhigh` (case-insensitive).
- When set, overrides `ZEROCLAW_CODEX_REASONING_EFFORT` for OpenAI Codex requests.
- Unset falls back to `ZEROCLAW_CODEX_REASONING_EFFORT` if present, otherwise defaults to `xhigh`.
- If both `provider.reasoning_level` and deprecated `runtime.reasoning_level` are set, provider-level value wins.
## `[skills]`
@@ -192,6 +397,7 @@ Notes:
| `open_skills_enabled` | `false` | Opt-in loading/sync of community `open-skills` repository |
| `open_skills_dir` | unset | Optional local path for `open-skills` (defaults to `$HOME/open-skills` when enabled) |
| `prompt_injection_mode` | `full` | Skill prompt verbosity: `full` (inline instructions/tools) or `compact` (name/description/location only) |
| `clawhub_token` | unset | Optional Bearer token for authenticated ClawhHub skill downloads |
Notes:
@@ -203,6 +409,14 @@ Notes:
- Precedence for enable flag: `ZEROCLAW_OPEN_SKILLS_ENABLED` → `skills.open_skills_enabled` in `config.toml` → default `false`.
- `prompt_injection_mode = "compact"` is recommended on low-context local models to reduce startup prompt size while keeping skill files available on demand.
- Skill loading and `zeroclaw skills install` both apply a static security audit. Skills that contain symlinks, script-like files, high-risk shell payload snippets, or unsafe markdown link traversal are rejected.
- `clawhub_token` is sent as `Authorization: Bearer <token>` when downloading from ClawhHub. Obtain a token from [https://clawhub.ai](https://clawhub.ai) after signing in. Required if the API returns 429 (rate-limited) or 401 (unauthorized) for anonymous requests.
**ClawhHub token example:**
```toml
[skills]
clawhub_token = "your-token-here"
```
## `[composio]`
@@ -271,8 +485,8 @@ Notes:
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | Enable `browser_open` tool (opens URLs in the system browser without scraping) |
| `allowed_domains` | `[]` | Allowed domains for `browser_open` (exact/subdomain match, or `"*"` for all public domains) |
| `enabled` | `false` | Enable browser tools (`browser_open` and `browser`) |
| `allowed_domains` | `[]` | Allowed domains for `browser_open` and `browser` (exact/subdomain match, or `"*"` for all public domains) |
| `session_name` | unset | Browser session name (for agent-browser automation) |
| `backend` | `agent_browser` | Browser automation backend: `"agent_browser"`, `"rust_native"`, `"computer_use"`, or `"auto"` |
| `native_headless` | `true` | Headless mode for rust-native backend |
@@ -293,6 +507,7 @@ Notes:
Notes:
- `browser_open` is a simple URL opener; `browser` is full browser automation (open/click/type/scroll/screenshot).
- When `backend = "computer_use"`, the agent delegates browser actions to the sidecar at `computer_use.endpoint`.
- `allow_remote_endpoint = false` (default) rejects any non-loopback endpoint to prevent accidental public exposure.
- Use `window_allowlist` to restrict which OS windows the sidecar can interact with.
@@ -305,12 +520,52 @@ Notes:
| `allowed_domains` | `[]` | Allowed domains for HTTP requests (exact/subdomain match, or `"*"` for all public domains) |
| `max_response_size` | `1000000` | Maximum response size in bytes (default: 1 MB) |
| `timeout_secs` | `30` | Request timeout in seconds |
| `user_agent` | `ZeroClaw/1.0` | User-Agent header for outbound HTTP requests |
Notes:
- Deny-by-default: if `allowed_domains` is empty, all HTTP requests are rejected.
- Use exact domain or subdomain matching (e.g. `"api.example.com"`, `"example.com"`), or `"*"` to allow any public domain.
- Local/private targets are still blocked even when `"*"` is configured.
- Shell `curl`/`wget` are classified as high-risk and may be blocked by autonomy policy. Prefer `http_request` for direct HTTP calls.
## `[web_fetch]`
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | Enable `web_fetch` for page-to-text extraction |
| `provider` | `fast_html2md` | Fetch/render backend: `fast_html2md`, `nanohtml2text`, `firecrawl` |
| `api_key` | unset | API key for provider backends that require it (e.g. `firecrawl`) |
| `api_url` | unset | Optional API URL override (self-hosted/alternate endpoint) |
| `allowed_domains` | `["*"]` | Domain allowlist (`"*"` allows all public domains) |
| `blocked_domains` | `[]` | Denylist applied before allowlist |
| `max_response_size` | `500000` | Maximum returned payload size in bytes |
| `timeout_secs` | `30` | Request timeout in seconds |
| `user_agent` | `ZeroClaw/1.0` | User-Agent header for fetch requests |
Notes:
- `web_fetch` is optimized for summarization/data extraction from web pages.
- Redirect targets are revalidated against allow/deny domain policy.
- Local/private network targets remain blocked even when `allowed_domains = ["*"]`.
## `[web_search]`
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | Enable `web_search_tool` |
| `provider` | `duckduckgo` | Search backend: `duckduckgo`, `brave`, `firecrawl` |
| `api_key` | unset | Generic provider key (used by `firecrawl`, fallback for `brave`) |
| `api_url` | unset | Optional API URL override |
| `brave_api_key` | unset | Dedicated Brave key (required for `provider = "brave"` unless `api_key` is set) |
| `max_results` | `5` | Maximum search results returned (clamped to 1-10) |
| `timeout_secs` | `15` | Request timeout in seconds |
| `user_agent` | `ZeroClaw/1.0` | User-Agent header for search requests |
Notes:
- If DuckDuckGo returns `403`/`429` in your network, switch provider to `brave` or `firecrawl`.
- `web_search` finds candidate URLs; pair it with `web_fetch` for page content extraction.
## `[gateway]`
@@ -321,6 +576,14 @@ Notes:
| `require_pairing` | `true` | require pairing before bearer auth |
| `allow_public_bind` | `false` | block accidental public exposure |
## `[gateway.node_control]` (experimental)
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | enable node-control scaffold endpoint (`POST /api/node-control`) |
| `auth_token` | `null` | optional extra shared token checked via `X-Node-Control-Token` |
| `allowed_node_ids` | `[]` | allowlist for `node.describe`/`node.invoke` (`[]` accepts any) |
## `[autonomy]`
| Key | Default | Purpose |
@@ -336,6 +599,10 @@ Notes:
| `block_high_risk_commands` | `true` | hard block for high-risk commands |
| `auto_approve` | `[]` | tool operations always auto-approved |
| `always_ask` | `[]` | tool operations that always require approval |
| `non_cli_excluded_tools` | `[]` | tools hidden from non-CLI channel tool specs |
| `non_cli_approval_approvers` | `[]` | optional allowlist for who can run non-CLI approval-management commands |
| `non_cli_natural_language_approval_mode` | `direct` | natural-language behavior for approval-management commands (`direct`, `request_confirm`, `disabled`) |
| `non_cli_natural_language_approval_mode_by_channel` | `{}` | per-channel override map for natural-language approval mode |
Notes:
@@ -345,6 +612,25 @@ Notes:
- `allowed_commands` entries can be command names (for example, `"git"`), explicit executable paths (for example, `"/usr/bin/antigravity"`), or `"*"` to allow any command name/path (risk gates still apply).
- Shell separator/operator parsing is quote-aware. Characters like `;` inside quoted arguments are treated as literals, not command separators.
- Unquoted shell chaining/operators are still enforced by policy checks (`;`, `|`, `&&`, `||`, background chaining, and redirects).
- In supervised mode on non-CLI channels, operators can persist human-approved tools with:
- One-step flow: `/approve <tool>`.
- Two-step flow: `/approve-request <tool>` then `/approve-confirm <request-id>` (same sender + same chat/channel).
Both paths write to `autonomy.auto_approve` and remove the tool from `autonomy.always_ask`.
- `non_cli_natural_language_approval_mode` controls how strict natural-language approval intents are:
- `direct` (default): natural-language approval grants immediately (private-chat friendly).
- `request_confirm`: natural-language approval creates a pending request that needs explicit confirm.
- `disabled`: natural-language approval commands are rejected; use slash commands only.
- `non_cli_natural_language_approval_mode_by_channel` can override that mode for specific channels (keys are channel names like `telegram`, `discord`, `slack`).
- Example: keep global `direct`, but force `discord = "request_confirm"` for team chats.
- `non_cli_approval_approvers` can restrict who is allowed to run approval commands (`/approve*`, `/unapprove`, `/approvals`):
- `*` allows all channel-admitted senders.
- `alice` allows sender `alice` on any channel.
- `telegram:alice` allows only that channel+sender pair.
- `telegram:*` allows any sender on Telegram.
- `*:alice` allows `alice` on any channel.
- Use `/unapprove <tool>` to remove persisted approval from `autonomy.auto_approve`.
- `/approve-pending` lists pending requests for the current sender+chat/channel scope.
- If a tool remains unavailable after approval, check `autonomy.non_cli_excluded_tools` (runtime `/approvals` shows this list). Channel runtime reloads this list from `config.toml` automatically.
```toml
[autonomy]
@@ -380,6 +666,7 @@ Use route hints so integrations can keep stable names while model IDs evolve.
| `hint` | _required_ | Task hint name (e.g. `"reasoning"`, `"fast"`, `"code"`, `"summarize"`) |
| `provider` | _required_ | Provider to route to (must match a known provider name) |
| `model` | _required_ | Model to use with that provider |
| `max_tokens` | unset | Optional per-route output token cap forwarded to provider APIs |
| `api_key` | unset | Optional API key override for this route's provider |
### `[[embedding_routes]]`
@@ -400,6 +687,7 @@ embedding_model = "hint:semantic"
hint = "reasoning"
provider = "openrouter"
model = "provider/model-id"
max_tokens = 8192
[[embedding_routes]]
hint = "semantic"
@@ -490,6 +778,12 @@ Notes:
- When a timeout occurs, users receive: `⚠️ Request timed out while waiting for the model. Please try again.`
- Telegram-only interruption behavior is controlled with `channels_config.telegram.interrupt_on_new_message` (default `false`).
When enabled, a newer message from the same sender in the same chat cancels the in-flight request and preserves interrupted user context.
- Telegram/Discord/Slack/Mattermost/Lark/Feishu support `[channels_config.<channel>.group_reply]`:
- `mode = "all_messages"` or `mode = "mention_only"`
- `allowed_sender_ids = ["..."]` to bypass mention gating in groups
- `allowed_users` allowlist checks still run first
- Legacy `mention_only` flags (Telegram/Discord/Mattermost/Lark) remain supported as fallback only.
If `group_reply.mode` is set, it takes precedence over legacy `mention_only`.
- While `zeroclaw channel start` is running, updates to `default_provider`, `default_model`, `default_temperature`, `api_key`, `api_url`, and `reliability.*` are hot-applied from `config.toml` on the next inbound message.
### `[channels_config.nostr]`
@@ -629,6 +923,31 @@ Notes:
- Place `.md`/`.txt` datasheet files named by board (e.g. `nucleo-f401re.md`, `rpi-gpio.md`) in `datasheet_dir` for RAG retrieval.
- See [hardware-peripherals-design.md](hardware-peripherals-design.md) for board protocol and firmware notes.
## `[agents_ipc]`
Inter-process communication for independent ZeroClaw agents on the same host.
| Key | Default | Purpose |
|---|---|---|
| `enabled` | `false` | Enable IPC tools (`agents_list`, `agents_send`, `agents_inbox`, `state_get`, `state_set`) |
| `db_path` | `~/.zeroclaw/agents.db` | Shared SQLite database path (all agents on this host share one file) |
| `staleness_secs` | `300` | Agents not seen within this window are considered offline (seconds) |
Notes:
- When `enabled = false` (default), no IPC tools are registered and no database is created.
- All agents that share a `db_path` can discover each other and exchange messages.
- Agent identity is derived from `workspace_dir` (SHA-256 hash), not user-supplied.
Example:
```toml
[agents_ipc]
enabled = true
db_path = "~/.zeroclaw/agents.db"
staleness_secs = 300
```
## Security-Relevant Defaults
- deny-by-default channel allowlists (`[]` means deny all)
docs/docs-inventory.md
+59 -28
View File
@@ -1,34 +1,57 @@
# ZeroClaw Documentation Inventory
This inventory classifies docs by intent so readers can quickly distinguish runtime-contract guides from design proposals.
This inventory classifies documentation by intent and canonical location.
Last reviewed: **February 18, 2026**.
Last reviewed: **February 24, 2026**.
## Classification Legend
- **Current Guide/Reference**: intended to match current runtime behavior
- **Policy/Process**: collaboration or governance rules
- **Proposal/Roadmap**: design exploration; may include hypothetical commands
- **Snapshot**: time-bound operational report
- **Policy/Process**: contribution or governance contract
- **Proposal/Roadmap**: exploratory or planned behavior
- **Snapshot/Audit**: time-bound status and gap analysis
- **Compatibility Shim**: path preserved for backward navigation
## Documentation Entry Points
## Entry Points
### Product root
| Doc | Type | Audience |
|---|---|---|
| `README.md` | Current Guide | all readers |
| `README.zh-CN.md` | Current Guide (localized) | Chinese readers |
| `README.ja.md` | Current Guide (localized) | Japanese readers |
| `README.ru.md` | Current Guide (localized) | Russian readers |
| `README.vi.md` | Current Guide (localized) | Vietnamese readers |
| `docs/README.md` | Current Guide (hub) | all readers |
| `docs/README.zh-CN.md` | Current Guide (localized hub) | Chinese readers |
| `docs/README.ja.md` | Current Guide (localized hub) | Japanese readers |
| `docs/README.ru.md` | Current Guide (localized hub) | Russian readers |
| `docs/README.vi.md` | Current Guide (localized hub) | Vietnamese readers |
| `docs/SUMMARY.md` | Current Guide (unified TOC) | all readers |
| `docs/structure/README.md` | Current Guide (structure map) | all readers |
| `docs/i18n/zh-CN/README.md` | Current Guide (localized) | Chinese readers |
| `docs/i18n/ja/README.md` | Current Guide (localized) | Japanese readers |
| `docs/i18n/ru/README.md` | Current Guide (localized) | Russian readers |
| `docs/i18n/fr/README.md` | Current Guide (localized) | French readers |
| `docs/i18n/vi/README.md` | Current Guide (localized) | Vietnamese readers |
| `docs/i18n/el/README.md` | Current Guide (localized) | Greek readers |
## Collection Index Docs
### Docs system
| Doc | Type | Audience |
|---|---|---|
| `docs/README.md` | Current Guide (hub) | all readers |
| `docs/SUMMARY.md` | Current Guide (unified TOC) | all readers |
| `docs/structure/README.md` | Current Guide (structure map) | maintainers |
| `docs/structure/by-function.md` | Current Guide (function map) | maintainers/operators |
| `docs/i18n-guide.md` | Current Guide (i18n completion contract) | contributors/agents |
| `docs/i18n/README.md` | Current Guide (locale index) | maintainers/translators |
| `docs/i18n-coverage.md` | Current Guide (coverage matrix) | maintainers/translators |
## Locale Hubs (Canonical)
| Locale | Canonical hub | Type |
|---|---|---|
| `zh-CN` | `docs/i18n/zh-CN/README.md` | Current Guide (localized hub scaffold) |
| `ja` | `docs/i18n/ja/README.md` | Current Guide (localized hub scaffold) |
| `ru` | `docs/i18n/ru/README.md` | Current Guide (localized hub scaffold) |
| `fr` | `docs/i18n/fr/README.md` | Current Guide (localized hub scaffold) |
| `vi` | `docs/i18n/vi/README.md` | Current Guide (full localized tree) |
| `el` | `docs/i18n/el/README.md` | Current Guide (full localized tree) |
Compatibility shims such as `docs/SUMMARY.<locale>.md` and `docs/vi/**` remain valid but are non-canonical.
## Collection Index Docs (English canonical)
| Doc | Type | Audience |
|---|---|---|
@@ -39,31 +62,39 @@ Last reviewed: **February 18, 2026**.
| `docs/hardware/README.md` | Current Guide | hardware builders |
| `docs/contributing/README.md` | Current Guide | contributors/reviewers |
| `docs/project/README.md` | Current Guide | maintainers |
| `docs/sop/README.md` | Current Guide | operators/automation maintainers |
## Current Guides & References
| Doc | Type | Audience |
|---|---|---|
| `docs/one-click-bootstrap.md` | Current Guide | users/operators |
| `docs/android-setup.md` | Current Guide | Android users/operators |
| `docs/commands-reference.md` | Current Reference | users/operators |
| `docs/providers-reference.md` | Current Reference | users/operators |
| `docs/channels-reference.md` | Current Reference | users/operators |
| `docs/nextcloud-talk-setup.md` | Current Guide | operators |
| `docs/config-reference.md` | Current Reference | operators |
| `docs/custom-providers.md` | Current Integration Guide | integration developers |
| `docs/zai-glm-setup.md` | Current Provider Setup Guide | users/operators |
| `docs/langgraph-integration.md` | Current Integration Guide | integration developers |
| `docs/proxy-agent-playbook.md` | Current Operations Playbook | operators/maintainers |
| `docs/operations-runbook.md` | Current Guide | operators |
| `docs/operations/connectivity-probes-runbook.md` | Current CI/ops Runbook | maintainers/operators |
| `docs/troubleshooting.md` | Current Guide | users/operators |
| `docs/network-deployment.md` | Current Guide | operators |
| `docs/mattermost-setup.md` | Current Guide | operators |
| `docs/nextcloud-talk-setup.md` | Current Guide | operators |
| `docs/cargo-slicer-speedup.md` | Current Build/CI Guide | maintainers |
| `docs/adding-boards-and-tools.md` | Current Guide | hardware builders |
| `docs/arduino-uno-q-setup.md` | Current Guide | hardware builders |
| `docs/nucleo-setup.md` | Current Guide | hardware builders |
| `docs/hardware-peripherals-design.md` | Current Design Spec | hardware contributors |
| `docs/datasheets/README.md` | Current Hardware Index | hardware builders |
| `docs/datasheets/nucleo-f401re.md` | Current Hardware Reference | hardware builders |
| `docs/datasheets/arduino-uno.md` | Current Hardware Reference | hardware builders |
| `docs/datasheets/esp32.md` | Current Hardware Reference | hardware builders |
| `docs/audit-event-schema.md` | Current CI/Security Reference | maintainers/security reviewers |
| `docs/security/official-channels-and-fraud-prevention.md` | Current Security Guide | users/operators |
## Policy / Process Docs
@@ -87,18 +118,18 @@ These are valuable context, but **not strict runtime contracts**.
| `docs/frictionless-security.md` | Proposal |
| `docs/security-roadmap.md` | Roadmap |
## Snapshot Docs
## Snapshot / Audit Docs
| Doc | Type |
|---|---|
| `docs/project-triage-snapshot-2026-02-18.md` | Snapshot |
| `docs/docs-audit-2026-02-24.md` | Snapshot (docs architecture audit) |
| `docs/i18n-gap-backlog.md` | Snapshot (i18n depth gap tracking) |
## Maintenance Recommendations
## Maintenance Contract
1. Update `commands-reference` whenever CLI surface changes.
2. Update `providers-reference` when provider catalog/aliases/env vars change.
3. Update `channels-reference` when channel support or allowlist semantics change.
4. Keep snapshots date-stamped and immutable.
5. Mark proposal docs clearly to avoid being mistaken for runtime contracts.
6. Keep localized README/docs-hub links aligned when adding new core docs.
7. Update `docs/SUMMARY.md` and collection indexes whenever new major docs are added.
1. Update `docs/SUMMARY.md` and nearest category index when adding a major doc.
2. Keep locale navigation parity across all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`, `el`).
3. Use `docs/i18n-guide.md` whenever docs IA/shared wording changes.
4. Keep canonical localized hubs under `docs/i18n/<locale>/`; treat shim paths as compatibility only.
5. Keep snapshots date-stamped and immutable; add newer snapshots instead of rewriting historical ones.
docs/getting-started/README.md
+3 -1
View File
@@ -7,7 +7,8 @@ For first-time setup and quick orientation.
1. Main overview and quick start: [../../README.md](../../README.md)
2. One-click setup and dual bootstrap mode: [../one-click-bootstrap.md](../one-click-bootstrap.md)
3. Update or uninstall on macOS: [macos-update-uninstall.md](macos-update-uninstall.md)
4. Find commands by tasks: [../commands-reference.md](../commands-reference.md)
4. Set up on Android (Termux/ADB): [../android-setup.md](../android-setup.md)
5. Find commands by tasks: [../commands-reference.md](../commands-reference.md)
## Choose Your Path
@@ -32,3 +33,4 @@ For first-time setup and quick orientation.
- Runtime operations: [../operations/README.md](../operations/README.md)
- Reference catalogs: [../reference/README.md](../reference/README.md)
- macOS lifecycle tasks: [macos-update-uninstall.md](macos-update-uninstall.md)
- Android setup path: [../android-setup.md](../android-setup.md)
docs/i18n/README.md
+19 -3
View File
@@ -2,14 +2,30 @@
Canonical localized documentation trees live here.
Top-level parity status: **all supported locales are 0-gap against `docs/*.md` baseline** (last validated 2026-02-24).
Narrative depth status: **enhanced bridge rollout completed for `zh-CN`/`ja`/`ru`/`fr`**.
## Locales
- Vietnamese: [vi/README.md](vi/README.md)
- 简体中文 (Chinese): [zh-CN/README.md](zh-CN/README.md)
- 日本語 (Japanese): [ja/README.md](ja/README.md)
- Русский (Russian): [ru/README.md](ru/README.md)
- Français (French): [fr/README.md](fr/README.md)
- Tiếng Việt (Vietnamese): [vi/README.md](vi/README.md)
- Ελληνικά (Greek): [el/README.md](el/README.md)
## Structure
- Docs structure map (language/part/function): [../structure/README.md](../structure/README.md)
- Canonical Vietnamese tree: `docs/i18n/vi/`
- Compatibility Vietnamese paths: `docs/vi/` and `docs/*.vi.md`
- Canonical locale trees:
- `docs/i18n/zh-CN/`
- `docs/i18n/ja/`
- `docs/i18n/ru/`
- `docs/i18n/fr/`
- `docs/i18n/vi/`
- `docs/i18n/el/`
- Docs-root compatibility shims are limited to paths like `docs/SUMMARY.<locale>.md` when retained.
See overall coverage and conventions in [../i18n-coverage.md](../i18n-coverage.md).
See remaining localization depth gaps in [../i18n-gap-backlog.md](../i18n-gap-backlog.md).
For required execution steps, use [../i18n-guide.md](../i18n-guide.md).
docs/i18n/el/actions-source-policy.md
+2 -2
View File
@@ -25,7 +25,7 @@
- `softprops/action-gh-release@*`
- `sigstore/cosign-installer@*`
- `Checkmarx/vorpal-reviewdog-github-action@*`
- `Swatinem/rust-cache@*`
- `useblacksmith/*` (Υποδομή Blacksmith)
## Διαδικασία Ελέγχου Αλλαγών
@@ -74,7 +74,7 @@ gh api repos/zeroclaw-labs/zeroclaw/actions/permissions/selected-actions
## Ιστορικό Αλλαγών
- **2026-02-21**: Προσθήκη `Checkmarx/vorpal-reviewdog-github-action@*` για στοχευμένους ελέγχους ασφαλείας.
- **2026-02-26**: Τυποποίηση runner/action για Rust cache και Docker builds με `Swatinem/rust-cache`, `docker/setup-buildx-action`, `docker/build-push-action`.
- **2026-02-17**: Μετάβαση στο `useblacksmith/rust-cache` για τη διαχείριση προσωρινής μνήμης Rust.
- **2026-02-16**: Προσθήκη `sigstore/cosign-installer@*` για την υπογραφή εκδόσεων.
- **2026-02-17**: Αντικατάσταση του `cargo install cargo-audit` με την ενέργεια `rustsec/audit-check@*`.
docs/i18n/el/commands-reference.md
+6
View File
@@ -38,6 +38,12 @@
> [!TIP]
> Κατά τη διάρκεια της συνομιλίας, μπορείτε να αιτηθείτε την αλλαγή του μοντέλου (π.χ. "use gpt-4") και ο πράκτορας θα προσαρμόσει τις ρυθμίσεις του δυναμικά.
### 2.1 `gateway` / `daemon`
- `zeroclaw gateway [--host <HOST>] [--port <PORT>] [--new-pairing]`
- `zeroclaw daemon [--host <HOST>] [--port <PORT>]`
- Το `--new-pairing` καθαρίζει όλα τα αποθηκευμένα paired tokens και δημιουργεί νέο pairing code κατά την εκκίνηση του gateway.
### 3. `cron` (Προγραμματισμός Εργασιών)
Δυνατότητα αυτοματισμού εντολών:
docs/i18n/fr/commands-reference.md
+4
View File
@@ -16,3 +16,7 @@ Source anglaise:
- Les noms de commandes, flags et clés de config restent en anglais.
- La définition finale du comportement est la source anglaise.
## Mise à jour récente
- `zeroclaw gateway` prend en charge `--new-pairing` pour effacer les tokens appairés et générer un nouveau code d'appairage.
docs/i18n/ja/commands-reference.md
+4
View File
@@ -16,3 +16,7 @@
- コマンド名・フラグ名・設定キーは英語のまま保持します。
- 挙動の最終定義は英語版原文を優先します。
## 最新更新
- `zeroclaw gateway` は `--new-pairing` をサポートし、既存のペアリングトークンを消去して新しいペアリングコードを生成できます。
docs/i18n/ru/commands-reference.md
+4
View File
@@ -16,3 +16,7 @@
- Имена команд, флагов и ключей конфигурации сохраняются на английском.
- Финальная спецификация поведения — в английском оригинале.
## Последнее обновление
- `zeroclaw gateway` поддерживает `--new-pairing`: флаг очищает сохранённые paired-токены и генерирует новый код сопряжения.
docs/i18n/vi/README.md
+16 -6
View File
@@ -10,14 +10,18 @@
| Tôi muốn… | Xem tài liệu |
|---|---|
| Cài đặt và chạy nhanh | [../../../README.vi.md](../../../README.vi.md) / [../../../README.md](../../../README.md) |
| Cài đặt và chạy nhanh | [docs/i18n/vi/README.md](README.md) / [../../../README.md](../../../README.md) |
| Cài đặt bằng một lệnh | [one-click-bootstrap.md](one-click-bootstrap.md) |
| Cài đặt trên Android (Termux/ADB) | [android-setup.md](android-setup.md) |
| Tìm lệnh theo tác vụ | [commands-reference.md](commands-reference.md) |
| Kiểm tra giá trị mặc định và khóa cấu hình | [config-reference.md](config-reference.md) |
| Kết nối provider / endpoint tùy chỉnh | [custom-providers.md](custom-providers.md) |
| Cấu hình Z.AI / GLM provider | [zai-glm-setup.md](zai-glm-setup.md) |
| Sử dụng tích hợp LangGraph | [langgraph-integration.md](langgraph-integration.md) |
| Thiết lập Nextcloud Talk | [nextcloud-talk-setup.md](nextcloud-talk-setup.md) |
| Cấu hình proxy theo phạm vi an toàn | [proxy-agent-playbook.md](proxy-agent-playbook.md) |
| Vận hành hàng ngày (runbook) | [operations-runbook.md](operations-runbook.md) |
| Vận hành probe kết nối provider trong CI | [operations/connectivity-probes-runbook.md](operations/connectivity-probes-runbook.md) |
| Khắc phục sự cố cài đặt/chạy/kênh | [troubleshooting.md](troubleshooting.md) |
| Cấu hình Matrix phòng mã hóa (E2EE) | [matrix-e2ee-guide.md](matrix-e2ee-guide.md) |
| Xem theo danh mục | [SUMMARY.md](SUMMARY.md) |
@@ -53,6 +57,7 @@
- [channels-reference.md](channels-reference.md) — khả năng kênh và hướng dẫn thiết lập
- [matrix-e2ee-guide.md](matrix-e2ee-guide.md) — thiết lập phòng mã hóa Matrix (E2EE)
- [config-reference.md](config-reference.md) — khóa cấu hình quan trọng và giá trị mặc định an toàn
- [wasm-tools-guide.md](wasm-tools-guide.md) — tạo, cài đặt và xuất bản WASM skills
- [custom-providers.md](custom-providers.md) — mẫu tích hợp provider / base URL tùy chỉnh
- [zai-glm-setup.md](zai-glm-setup.md) — thiết lập Z.AI/GLM và ma trận endpoint
- [langgraph-integration.md](langgraph-integration.md) — tích hợp dự phòng cho model/tool-calling
@@ -83,12 +88,17 @@
- Mục lục thống nhất (TOC): [SUMMARY.md](SUMMARY.md)
- Bản đồ cấu trúc docs (ngôn ngữ/phần/chức năng): [../../structure/README.md](../../structure/README.md)
- Danh mục và phân loại tài liệu: [docs-inventory.md](../../docs-inventory.md)
- Danh mục và phân loại tài liệu: [docs-inventory.md](docs-inventory.md)
- Checklist hoàn thiện i18n: [i18n-guide.md](i18n-guide.md)
- Bản đồ độ phủ i18n: [i18n-coverage.md](i18n-coverage.md)
- Backlog thiếu hụt i18n: [i18n-gap-backlog.md](i18n-gap-backlog.md)
- Snapshot kiểm toán tài liệu (2026-02-24): [docs-audit-2026-02-24.md](docs-audit-2026-02-24.md)
## Ngôn ngữ khác
- English: [README.md](../../README.md)
- 简体中文: [README.zh-CN.md](../../README.zh-CN.md)
- 日本語: [README.ja.md](../../README.ja.md)
- Русский: [README.ru.md](../../README.ru.md)
- Français: [README.fr.md](../../README.fr.md)
- 简体中文: [../zh-CN/README.md](../zh-CN/README.md)
- 日本語: [../ja/README.md](../ja/README.md)
- Русский: [../ru/README.md](../ru/README.md)
- Français: [../fr/README.md](../fr/README.md)
- Ελληνικά: [../el/README.md](../el/README.md)
docs/i18n/vi/SUMMARY.md
+18 -2
View File
@@ -7,7 +7,7 @@
## Điểm vào
- Bản đồ cấu trúc docs (ngôn ngữ/phần/chức năng): [../../structure/README.md](../../structure/README.md)
- README tiếng Việt: [../../../README.vi.md](../../../README.vi.md)
- README tiếng Việt: [docs/i18n/vi/README.md](README.md)
- Docs hub tiếng Việt: [README.md](README.md)
## Danh mục
@@ -16,6 +16,7 @@
- [getting-started/README.md](getting-started/README.md)
- [one-click-bootstrap.md](one-click-bootstrap.md)
- [android-setup.md](android-setup.md)
### 2) Lệnh / Cấu hình / Tích hợp
@@ -23,15 +24,18 @@
- [commands-reference.md](commands-reference.md)
- [providers-reference.md](providers-reference.md)
- [channels-reference.md](channels-reference.md)
- [nextcloud-talk-setup.md](nextcloud-talk-setup.md)
- [config-reference.md](config-reference.md)
- [custom-providers.md](custom-providers.md)
- [zai-glm-setup.md](zai-glm-setup.md)
- [langgraph-integration.md](langgraph-integration.md)
- [proxy-agent-playbook.md](proxy-agent-playbook.md)
### 3) Vận hành & Triển khai
- [operations/README.md](operations/README.md)
- [operations-runbook.md](operations-runbook.md)
- [operations/connectivity-probes-runbook.md](operations/connectivity-probes-runbook.md)
- [release-process.md](release-process.md)
- [troubleshooting.md](troubleshooting.md)
- [network-deployment.md](network-deployment.md)
@@ -46,6 +50,7 @@
- [sandboxing.md](sandboxing.md)
- [resource-limits.md](resource-limits.md)
- [audit-logging.md](audit-logging.md)
- [audit-event-schema.md](audit-event-schema.md)
- [security-roadmap.md](security-roadmap.md)
### 5) Phần cứng & Ngoại vi
@@ -55,6 +60,7 @@
- [adding-boards-and-tools.md](adding-boards-and-tools.md)
- [nucleo-setup.md](nucleo-setup.md)
- [arduino-uno-q-setup.md](arduino-uno-q-setup.md)
- [datasheets/README.md](datasheets/README.md)
- [datasheets/nucleo-f401re.md](datasheets/nucleo-f401re.md)
- [datasheets/arduino-uno.md](datasheets/arduino-uno.md)
- [datasheets/esp32.md](datasheets/esp32.md)
@@ -67,11 +73,21 @@
- [reviewer-playbook.md](reviewer-playbook.md)
- [ci-map.md](ci-map.md)
- [actions-source-policy.md](actions-source-policy.md)
- [cargo-slicer-speedup.md](cargo-slicer-speedup.md)
### 7) Dự án
- [project/README.md](project/README.md)
- [proxy-agent-playbook.md](proxy-agent-playbook.md)
- [project-triage-snapshot-2026-02-18.md](project-triage-snapshot-2026-02-18.md)
- [docs-audit-2026-02-24.md](docs-audit-2026-02-24.md)
### 8) Quản trị tài liệu & i18n
- [docs-inventory.md](docs-inventory.md)
- [doc-template.md](doc-template.md)
- [i18n-guide.md](i18n-guide.md)
- [i18n-coverage.md](i18n-coverage.md)
- [i18n-gap-backlog.md](i18n-gap-backlog.md)
## Ngôn ngữ khác
docs/i18n/vi/actions-source-policy.md
+6 -4
View File
@@ -22,7 +22,7 @@ Các mẫu allowlist được chọn:
- `rhysd/actionlint@*`
- `softprops/action-gh-release@*`
- `sigstore/cosign-installer@*`
- `Swatinem/rust-cache@*`
- `useblacksmith/*` (cơ sở hạ tầng self-hosted runner Blacksmith)
## Xuất kiểm soát thay đổi
@@ -74,11 +74,13 @@ Nếu gặp phải, chỉ thêm action tin cậy còn thiếu cụ thể đó, c
Ghi chú quét gần đây nhất:
- 2026-02-26: Chuẩn hóa runner/action cho cache Rust và Docker build
- Đã thêm mẫu allowlist: `Swatinem/rust-cache@*`
- Docker build dùng `docker/setup-buildx-action` và `docker/build-push-action`
- 2026-02-17: Cache phụ thuộc Rust được migrate từ `Swatinem/rust-cache` sang `useblacksmith/rust-cache`
- Không cần mẫu allowlist mới (`useblacksmith/*` đã có trong allowlist)
- 2026-02-16: Phụ thuộc ẩn được phát hiện trong `release.yml`: `sigstore/cosign-installer@...`
- Đã thêm mẫu allowlist: `sigstore/cosign-installer@*`
- 2026-02-16: Migration Blacksmith chặn thực thi workflow
- Đã thêm mẫu allowlist: `useblacksmith/*` cho cơ sở hạ tầng self-hosted runner
- Actions: `useblacksmith/setup-docker-builder@v1`, `useblacksmith/build-push-action@v2`
- 2026-02-17: Cập nhật cân bằng tính tái tạo/độ tươi của security audit
- Đã thêm mẫu allowlist: `rustsec/audit-check@*`
- Thay thế thực thi nội tuyến `cargo install cargo-audit` bằng `rustsec/audit-check@69366f33c96575abad1ee0dba8212993eecbe998` được pin trong `security.yml`
docs/i18n/vi/ci-map.md
+1 -1
View File
@@ -117,7 +117,7 @@ Các kiểm tra chặn merge nên giữ nhỏ và mang tính quyết định. C
- Giữ các kiểm tra chặn merge mang tính quyết định và tái tạo được (`--locked` khi áp dụng được).
- Đảm bảo tương thích merge queue bằng cách hỗ trợ `merge_group` cho các workflow bắt buộc (`ci-run`, `sec-audit`, `sec-codeql`).
- PR intake checks không bắt buộc liên kết với hệ thống ticket bên ngoài.
- Bắt buộc PR liên kết với Linear issue key (`RMN-*`/`CDV-*`/`COM-*`) qua PR intake checks.
- Bắt buộc entry `advisories.ignore` trong `deny.toml` dùng object có `id` + `reason` (được kiểm tra bởi `deny_policy_guard.py`).
- Giữ metadata governance cho deny ignore trong `.github/security/deny-ignore-governance.json` luôn cập nhật (owner/reason/expiry/ticket được kiểm tra bởi `deny_policy_guard.py`).
- Giữ metadata quản trị allowlist gitleaks trong `.github/security/gitleaks-allowlist-governance.json` luôn cập nhật (owner/reason/expiry/ticket được kiểm tra bởi `secrets_governance_guard.py`).
docs/i18n/vi/commands-reference.md
+3 -1
View File
@@ -46,9 +46,11 @@ Xác minh lần cuối: **2026-02-20**.
### `gateway` / `daemon`
- `zeroclaw gateway [--host <HOST>] [--port <PORT>]`
- `zeroclaw gateway [--host <HOST>] [--port <PORT>] [--new-pairing]`
- `zeroclaw daemon [--host <HOST>] [--port <PORT>]`
`--new-pairing` sẽ xóa toàn bộ token đã ghép đôi và tạo mã ghép đôi mới khi gateway khởi động.
### `service`
- `zeroclaw service install`
docs/i18n/vi/config-reference.md
+31 -3
View File
@@ -25,6 +25,14 @@ Lệnh xuất schema:
| `default_provider` | `openrouter` | ID hoặc bí danh provider |
| `default_model` | `anthropic/claude-sonnet-4-6` | Model định tuyến qua provider đã chọn |
| `default_temperature` | `0.7` | Nhiệt độ model |
| `model_support_vision` | chưa đặt (`None`) | Ghi đè hỗ trợ vision cho provider/model đang dùng |
Lưu ý:
- `model_support_vision = true` bật vision (ví dụ Ollama chạy `llava`).
- `model_support_vision = false` tắt vision.
- Để trống giữ mặc định của provider.
- Biến môi trường: `ZEROCLAW_MODEL_SUPPORT_VISION` hoặc `MODEL_SUPPORT_VISION` (giá trị: `true`/`false`/`1`/`0`/`yes`/`no`/`on`/`off`).
## `[observability]`
@@ -65,15 +73,15 @@ Lưu ý cho người dùng container:
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `compact_context` | `false` | Khi bật: bootstrap_max_chars=6000, rag_chunk_limit=2. Dùng cho model 13B trở xuống |
| `max_tool_iterations` | `10` | Số vòng lặp tool-call tối đa mỗi tin nhắn trên CLI, gateway và channels |
| `compact_context` | `true` | Khi bật: bootstrap_max_chars=6000, rag_chunk_limit=2. Dùng cho model 13B trở xuống |
| `max_tool_iterations` | `20` | Số vòng lặp tool-call tối đa mỗi tin nhắn trên CLI, gateway và channels |
| `max_history_messages` | `50` | Số tin nhắn lịch sử tối đa giữ lại mỗi phiên |
| `parallel_tools` | `false` | Bật thực thi tool song song trong một lượt |
| `tool_dispatcher` | `auto` | Chiến lược dispatch tool |
Lưu ý:
- Đặt `max_tool_iterations = 0` sẽ dùng giá trị mặc định an toàn `10`.
- Đặt `max_tool_iterations = 0` sẽ dùng giá trị mặc định an toàn `20`.
- Nếu tin nhắn kênh vượt giá trị này, runtime trả về: `Agent exceeded maximum tool iterations (<value>)`.
- Trong vòng lặp tool của CLI, gateway và channel, các lời gọi tool độc lập được thực thi đồng thời mặc định khi không cần phê duyệt; thứ tự kết quả giữ ổn định.
- `parallel_tools` áp dụng cho API `Agent::turn()`. Không ảnh hưởng đến vòng lặp runtime của CLI, gateway hay channel.
@@ -128,6 +136,18 @@ Lưu ý:
- `reasoning_enabled = true` yêu cầu reasoning tường minh (`think: true` trên `ollama`).
- Để trống giữ mặc định của provider.
## `[provider]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `reasoning_level` | chưa đặt (`None`) | Ghi đè mức reasoning cho provider hỗ trợ mức (hiện tại OpenAI Codex `/responses`) |
Lưu ý:
- Giá trị hỗ trợ: `minimal`, `low`, `medium`, `high`, `xhigh` (không phân biệt hoa/thường).
- Khi đặt, ghi đè `ZEROCLAW_CODEX_REASONING_EFFORT` cho OpenAI Codex.
- Để trống sẽ dùng `ZEROCLAW_CODEX_REASONING_EFFORT` nếu có, nếu không mặc định `xhigh`.
## `[skills]`
| Khóa | Mặc định | Mục đích |
@@ -259,6 +279,14 @@ Lưu ý:
| `require_pairing` | `true` | Yêu cầu ghép nối trước khi xác thực bearer |
| `allow_public_bind` | `false` | Chặn lộ public do vô ý |
## `[gateway.node_control]` (thử nghiệm)
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật endpoint scaffold node-control (`POST /api/node-control`) |
| `auth_token` | `null` | Shared token bổ sung, kiểm qua header `X-Node-Control-Token` |
| `allowed_node_ids` | `[]` | Allowlist cho `node.describe`/`node.invoke` (`[]` = chấp nhận mọi node) |
## `[autonomy]`
| Khóa | Mặc định | Mục đích |
docs/i18n/zh-CN/commands-reference.md
+4
View File
@@ -16,3 +16,7 @@
- 命令名、参数名、配置键保持英文。
- 行为细节以英文原文为准。
## 最近更新
- `zeroclaw gateway` 新增 `--new-pairing` 参数，可清空已配对 token 并在网关启动时生成新的配对码。
docs/operations/feature-matrix-runbook.md
+1 -1
View File
@@ -66,7 +66,7 @@ Verification commands:
1. Open `feature-matrix-summary.md` and identify failed lane(s), owner, and failing command.
2. Download lane artifact (`nightly-result-<lane>.json`) for exact command + exit code.
3. Reproduce locally with the exact command and toolchain lock (`--locked`).
4. Attach local reproduction logs + fix PR link to the active tracking thread (issue/PR discussion).
4. Attach local reproduction logs + fix PR link to the active Linear execution issue.
## High-Frequency Failure Classes
docs/ros2-integration-guidance.md
+48
View File
@@ -0,0 +1,48 @@
# ROS2 Integration Guidance
This note captures the recommended integration shape for ROS2/ROS1 environments.
It is intentionally architecture-focused and keeps ZeroClaw core boundaries stable.
## Recommendation
Use the plugin/adapter route first.
- Keep robotics transport in an integration crate or module that bridges ROS topics/services/actions to ZeroClaw tools/channels/runtime adapters.
- Keep high-frequency control loops in ROS-native execution contexts.
- Use ZeroClaw for planning, orchestration, policy, and guarded action dispatch.
Deep core coupling should be a last resort and only justified by measured latency limits that cannot be met with a bridge.
## Why This Is The Default
- Upgrade safety: trait-based adapters survive upstream changes better than core patches.
- Blast-radius control: transport details stay outside security/runtime core modules.
- Reproducibility: integration behavior is easier to test and rollback when isolated.
- Security posture: approval, policy, and gating remain centralized in existing ZeroClaw paths.
## Real-Time Boundary Rule
Do not route hard real-time motor/safety loops through LLM turn latency.
- ROS node graph handles tight-loop control and watchdogs.
- ZeroClaw emits intent-level commands and receives summarized state.
- Safety-critical stop paths stay local to robot runtime regardless of agent health.
## Suggested Baseline Architecture
1. ROS2 bridge node subscribes to high-rate sensor topics.
2. Bridge performs local reduction/windowing and forwards compact summaries to ZeroClaw.
3. ZeroClaw decides intent/tool calls under existing policy and approval constraints.
4. Bridge translates approved intents into ROS commands with bounded command-rate limits.
5. Telemetry and fault states flow back into ZeroClaw for reasoning and auditability.
## Escalation Criteria For Core Integration
Consider deeper ZeroClaw runtime integration only when all are true:
- Measured bridge overhead is a validated bottleneck under production-like load.
- Required latency/jitter budgets are written and reproducible.
- The proposed core change has clear rollback and subsystem ownership.
- Security and policy guarantees remain equivalent or stronger.
If those conditions are not met, stay with adapter/plugin integration.
docs/security/README.md
+2
View File
@@ -7,6 +7,7 @@ This section mixes current hardening guidance and proposal/roadmap documents.
For current runtime behavior, start here:
- Repository security policy and vulnerability handling workflow: [../../SECURITY.md](../../SECURITY.md)
- Official channels and fraud-prevention statement: [official-channels-and-fraud-prevention.md](official-channels-and-fraud-prevention.md)
- Private vulnerability report template: [private-vulnerability-report-template.md](private-vulnerability-report-template.md)
- 私密漏洞报告模板（中文）: [private-vulnerability-report-template.zh-CN.md](private-vulnerability-report-template.zh-CN.md)
- Advisory maintainer checklist: [advisory-maintainer-checklist.md](advisory-maintainer-checklist.md)
@@ -18,6 +19,7 @@ For current runtime behavior, start here:
- Troubleshooting: [../troubleshooting.md](../troubleshooting.md)
- CI/Security audit event schema: [../audit-event-schema.md](../audit-event-schema.md)
- Syscall anomaly detection: [./syscall-anomaly-detection.md](./syscall-anomaly-detection.md)
- Perplexity suffix filter: [./perplexity-filter.md](./perplexity-filter.md)
## Proposal / Roadmap Docs
docs/security/official-channels-and-fraud-prevention.md
+44
View File
@@ -0,0 +1,44 @@
# Official Channels And Fraud Prevention
This page is the evergreen security statement for community safety and impersonation defense.
## Fraud Warning
Scammers may impersonate ZeroClaw maintainers, contributors, or community members.
Assume fraud if someone claiming to represent ZeroClaw asks for:
- cryptocurrency transfers
- wallet access or seed phrases
- private financial information
- private credentials outside official security reporting flow
ZeroClaw maintainers do not request money or private wallet/financial credentials via direct messages.
## Official Sources Of Truth
Use these sources to verify announcements:
- GitHub repository: `zeroclaw-labs/zeroclaw`
- GitHub Security policy and advisories: [../../SECURITY.md](../../SECURITY.md)
Treat third-party links and social posts as untrusted until confirmed in the GitHub repository.
## How To Verify Announcements
1. Check whether the same announcement exists in GitHub issues, PRs, releases, or docs.
2. Confirm the posting account is an expected project maintainer/org account.
3. Prefer links that originate from repository pages rather than forwarded DMs.
## Reporting Suspicious Activity
If you see impersonation attempts or scam outreach:
1. Do not engage or send funds/data.
2. Capture evidence (screenshots, usernames, URLs, timestamps).
3. Open a GitHub issue in `zeroclaw-labs/zeroclaw` with sanitized details.
For vulnerability disclosure, use private reporting:
- Security policy: [../../SECURITY.md](../../SECURITY.md)
- Private report template: [private-vulnerability-report-template.md](private-vulnerability-report-template.md)
docs/security/perplexity-filter.md
+45
View File
@@ -0,0 +1,45 @@
# Perplexity Filter (Opt-In)
ZeroClaw provides an opt-in lightweight statistical filter that detects
adversarial suffixes (for example, GCG-style optimized gibberish tails)
before messages are sent to an LLM provider.
## Scope
- Applies to channel and gateway inbound messages before provider execution.
- Does not require external model calls or heavyweight guard models.
- Disabled by default for compatibility and latency predictability.
## How It Works
The filter evaluates a trailing prompt window using:
1. Character-class bigram perplexity.
2. Suffix punctuation ratio.
3. GCG-like token pattern checks (mixed punctuation + letters + digits).
The message is blocked only when anomaly criteria are met.
## Config
```toml
[security.perplexity_filter]
enable_perplexity_filter = true
perplexity_threshold = 16.5
suffix_window_chars = 72
min_prompt_chars = 40
symbol_ratio_threshold = 0.25
```
## Latency
The implementation is O(n) over prompt length and avoids network calls.
Local debug-safe regression includes a strict `<50ms` budget test for a
typical multi-sentence prompt payload.
## Tuning Guidance
- Increase `perplexity_threshold` if you see false positives.
- Increase `symbol_ratio_threshold` to reduce blocking of technical strings.
- Increase `min_prompt_chars` to ignore short prompts where statistics are weak.
- Keep the feature disabled unless you explicitly need this extra defense layer.
docs/structure/README.md
+68 -65
View File
@@ -1,87 +1,90 @@
# ZeroClaw Docs Structure Map
This page defines the documentation structure across three axes:
This page defines the canonical documentation layout and compatibility layers.
1. Language
2. Part (category)
3. Function (document intent)
Last refreshed: **February 24, 2026**.
Last refreshed: **February 22, 2026**.
Companion indexes:
- Function-oriented map: [by-function.md](by-function.md)
- Hub entry point: [../README.md](../README.md)
- Unified TOC: [../SUMMARY.md](../SUMMARY.md)
## 1) By Language
## 1) Directory Spine (Canonical)
| Language | Entry point | Canonical tree | Notes |
|---|---|---|---|
| English | `docs/README.md` | `docs/` | Source-of-truth runtime behavior docs are authored in English first. |
| Chinese (`zh-CN`) | `docs/README.zh-CN.md` | `docs/` localized hub + selected localized docs | Uses localized hub and shared category structure. |
| Japanese (`ja`) | `docs/README.ja.md` | `docs/` localized hub + selected localized docs | Uses localized hub and shared category structure. |
| Russian (`ru`) | `docs/README.ru.md` | `docs/` localized hub + selected localized docs | Uses localized hub and shared category structure. |
| French (`fr`) | `docs/README.fr.md` | `docs/` localized hub + selected localized docs | Uses localized hub and shared category structure. |
| Vietnamese (`vi`) | `docs/i18n/vi/README.md` | `docs/i18n/vi/` | Full Vietnamese tree is canonical under `docs/i18n/vi/`; `docs/vi/` and `docs/*.vi.md` are compatibility paths. |
### Layer A: global entry points
## 2) By Part (Category)
- Root product landing: `README.md` (language switch links into `docs/i18n/<locale>/README.md`)
- Docs hub: `docs/README.md`
- Unified TOC: `docs/SUMMARY.md`
These directories are the primary navigation modules by product area.
### Layer B: category collections (English source-of-truth)
- `docs/getting-started/` for initial setup and first-run flows
- `docs/reference/` for command/config/provider/channel reference indexes
- `docs/operations/` for day-2 operations, deployment, and troubleshooting entry points
- `docs/security/` for security guidance and security-oriented navigation
- `docs/hardware/` for board/peripheral implementation and hardware workflows
- `docs/contributing/` for contribution and CI/review processes
- `docs/project/` for project snapshots, planning context, and status-oriented docs
- `docs/getting-started/`
- `docs/reference/`
- `docs/operations/`
- `docs/security/`
- `docs/hardware/`
- `docs/contributing/`
- `docs/project/`
- `docs/sop/`
## 3) By Function (Document Intent)
### Layer C: canonical locale trees
Use this grouping to decide where new docs belong.
- `docs/i18n/zh-CN/`
- `docs/i18n/ja/`
- `docs/i18n/ru/`
- `docs/i18n/fr/`
- `docs/i18n/vi/`
- `docs/i18n/el/`
### Runtime Contract (current behavior)
### Layer D: compatibility shims (non-canonical)
- `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/SUMMARY.<locale>.md` (if retained)
- `docs/vi/**`
- legacy localized docs-root files where present
### Setup / Integration Guides
Use compatibility paths for backward links only. New localized edits should target `docs/i18n/<locale>/**`.
- `docs/custom-providers.md`
- `docs/zai-glm-setup.md`
- `docs/langgraph-integration.md`
- `docs/network-deployment.md`
- `docs/matrix-e2ee-guide.md`
- `docs/mattermost-setup.md`
- `docs/nextcloud-talk-setup.md`
## 2) Language Topology
### Policy / Process
| Locale | Root landing | Canonical docs hub | Coverage level | Notes |
|---|---|---|---|---|
| `en` | `README.md` | `docs/README.md` | Full source | Authoritative runtime-contract wording |
| `zh-CN` | `docs/i18n/zh-CN/README.md` | `docs/i18n/zh-CN/README.md` | Hub-level scaffold | Runtime-contract docs mainly shared in English |
| `ja` | `docs/i18n/ja/README.md` | `docs/i18n/ja/README.md` | Hub-level scaffold | Runtime-contract docs mainly shared in English |
| `ru` | `docs/i18n/ru/README.md` | `docs/i18n/ru/README.md` | Hub-level scaffold | Runtime-contract docs mainly shared in English |
| `fr` | `docs/i18n/fr/README.md` | `docs/i18n/fr/README.md` | Hub-level scaffold | Runtime-contract docs mainly shared in English |
| `vi` | `docs/i18n/vi/README.md` | `docs/i18n/vi/README.md` | Full localized tree | `docs/vi/**` kept as compatibility layer |
| `el` | `docs/i18n/el/README.md` | `docs/i18n/el/README.md` | Full localized tree | Greek full tree is canonical in `docs/i18n/el/**` |
- `docs/pr-workflow.md`
- `docs/reviewer-playbook.md`
- `docs/ci-map.md`
- `docs/actions-source-policy.md`
## 3) Category Intent Map
### Proposals / Roadmaps
| Category | Canonical index | Intent |
|---|---|---|
| Getting Started | `docs/getting-started/README.md` | first-run and install flows |
| Reference | `docs/reference/README.md` | commands/config/providers/channels and integration references |
| Operations | `docs/operations/README.md` | day-2 operations, release, troubleshooting runbooks |
| Security | `docs/security/README.md` | current hardening guidance + proposal boundary |
| Hardware | `docs/hardware/README.md` | boards, peripherals, datasheets navigation |
| Contributing | `docs/contributing/README.md` | PR/review/CI policy and process |
| Project | `docs/project/README.md` | time-bound snapshots and planning audit history |
| SOP | `docs/sop/README.md` | SOP runtime contract and procedure docs |
- `docs/sandboxing.md`
- `docs/resource-limits.md`
- `docs/audit-logging.md`
- `docs/agnostic-security.md`
- `docs/frictionless-security.md`
- `docs/security-roadmap.md`
## 4) Placement Rules
### Snapshots / Time-Bound Reports
1. Runtime behavior docs go in English canonical paths first.
2. Every new major doc must be linked from:
- the nearest category index (`docs/<category>/README.md`)
- `docs/SUMMARY.md`
- `docs/docs-inventory.md`
3. Locale navigation changes must update all supported locales (`en`, `zh-CN`, `ja`, `ru`, `fr`, `vi`, `el`).
4. For localized hubs/summaries, canonical path is always `docs/i18n/<locale>/`.
5. Keep compatibility shims aligned when touched; do not introduce new primary content under compatibility-only paths.
- `docs/project-triage-snapshot-2026-02-18.md`
## 5) Governance Links
### Assets / Templates
- `docs/datasheets/`
- `docs/doc-template.md`
## Placement Rules (Quick)
- New runtime behavior docs must be linked from the appropriate category index and `docs/SUMMARY.md`.
- Navigation changes must preserve locale parity across `docs/README*.md` and `docs/SUMMARY*.md`.
- Vietnamese full localization lives in `docs/i18n/vi/`; compatibility files should point to canonical paths.
- i18n docs index: [../i18n/README.md](../i18n/README.md)
- i18n coverage matrix: [../i18n-coverage.md](../i18n-coverage.md)
- i18n completion checklist: [../i18n-guide.md](../i18n-guide.md)
- i18n gap backlog: [../i18n-gap-backlog.md](../i18n-gap-backlog.md)
- docs inventory/classification: [../docs-inventory.md](../docs-inventory.md)
docs/structure/by-function.md
+65
View File
@@ -0,0 +1,65 @@
# ZeroClaw Docs By Function
This index groups documentation by operational function instead of folder path.
Use this when you know what you need to do, but not where the doc lives.
## Setup And Onboarding
- Core quick start: [../../README.md](../../README.md)
- Docs hub: [../README.md](../README.md)
- One-click bootstrap: [../one-click-bootstrap.md](../one-click-bootstrap.md)
- Android setup: [../android-setup.md](../android-setup.md)
- Docker setup: [../docker-setup.md](../docker-setup.md)
- Getting started collection: [../getting-started/README.md](../getting-started/README.md)
## Commands, Config, And Providers
- Commands reference: [../commands-reference.md](../commands-reference.md)
- Config reference: [../config-reference.md](../config-reference.md)
- Providers reference: [../providers-reference.md](../providers-reference.md)
- Channels reference: [../channels-reference.md](../channels-reference.md)
- Custom providers: [../custom-providers.md](../custom-providers.md)
- Z.AI/GLM setup: [../zai-glm-setup.md](../zai-glm-setup.md)
- Reference collection: [../reference/README.md](../reference/README.md)
## Operations And Deployment
- Operations runbook: [../operations-runbook.md](../operations-runbook.md)
- Troubleshooting: [../troubleshooting.md](../troubleshooting.md)
- Network deployment: [../network-deployment.md](../network-deployment.md)
- Release process: [../release-process.md](../release-process.md)
- Operations collection: [../operations/README.md](../operations/README.md)
## Security And Trust
- Security collection: [../security/README.md](../security/README.md)
- Official channels and fraud prevention: [../security/official-channels-and-fraud-prevention.md](../security/official-channels-and-fraud-prevention.md)
- Security roadmap: [../security-roadmap.md](../security-roadmap.md)
- Sandboxing: [../sandboxing.md](../sandboxing.md)
- Audit logging: [../audit-logging.md](../audit-logging.md)
- Resource limits: [../resource-limits.md](../resource-limits.md)
## Hardware And Peripherals
- Hardware collection: [../hardware/README.md](../hardware/README.md)
- Add boards/tools: [../adding-boards-and-tools.md](../adding-boards-and-tools.md)
- Nucleo setup: [../nucleo-setup.md](../nucleo-setup.md)
- Arduino setup: [../arduino-uno-q-setup.md](../arduino-uno-q-setup.md)
- Datasheets index: [../datasheets/README.md](../datasheets/README.md)
## Contributing And CI
- Contribution collection: [../contributing/README.md](../contributing/README.md)
- PR workflow: [../pr-workflow.md](../pr-workflow.md)
- Reviewer playbook: [../reviewer-playbook.md](../reviewer-playbook.md)
- CI map: [../ci-map.md](../ci-map.md)
- Actions source policy: [../actions-source-policy.md](../actions-source-policy.md)
## Localization And Information Architecture
- i18n index: [../i18n/README.md](../i18n/README.md)
- i18n coverage map: [../i18n-coverage.md](../i18n-coverage.md)
- i18n guide: [../i18n-guide.md](../i18n-guide.md)
- Docs inventory: [../docs-inventory.md](../docs-inventory.md)
- Docs structure map: [README.md](README.md)
docs/troubleshooting.md
+91
View File
@@ -192,6 +192,97 @@ zeroclaw channel doctor
Then verify channel-specific credentials + allowlist fields in config.
## Web Access Issues
### `curl`/`wget` blocked in shell tool
Symptom:
- tool output includes `Command blocked: high-risk command is disallowed by policy`
- model says `curl`/`wget` is blocked
Why this happens:
- `curl`/`wget` are high-risk shell commands and may be blocked by autonomy policy.
Preferred fix:
- use purpose-built tools instead of shell fetch:
- `http_request` for direct API/HTTP calls
- `web_fetch` for page content extraction/summarization
Minimal config:
```toml
[http_request]
enabled = true
allowed_domains = ["*"]
[web_fetch]
enabled = true
provider = "fast_html2md"
allowed_domains = ["*"]
```
### `web_search_tool` fails with `403`/`429`
Symptom:
- tool output includes `DuckDuckGo search failed with status: 403` (or `429`)
Why this happens:
- some networks/proxies/rate limits block DuckDuckGo HTML search endpoint traffic.
Fix options:
1. Switch provider to Brave (recommended when you have an API key):
```toml
[web_search]
enabled = true
provider = "brave"
brave_api_key = "<SECRET>"
```
2. Switch provider to Firecrawl (if enabled in your build):
```toml
[web_search]
enabled = true
provider = "firecrawl"
api_key = "<SECRET>"
```
3. Keep DuckDuckGo for search, but use `web_fetch` to read pages once you have URLs.
### `web_fetch`/`http_request` says host is not allowed
Symptom:
- errors like `Host '<domain>' is not in http_request.allowed_domains`
- or `web_fetch tool is enabled but no allowed_domains are configured`
Fix:
- include exact domains or `"*"` for public internet access:
```toml
[http_request]
enabled = true
allowed_domains = ["*"]
[web_fetch]
enabled = true
allowed_domains = ["*"]
blocked_domains = []
```
Security notes:
- local/private network targets are blocked even with `"*"`
- keep explicit domain allowlists in production environments when possible
## Service Mode
### Service installed but not running
docs/vi/config-reference.md
-519
View File
@@ -1,519 +0,0 @@
# Tham khảo cấu hình ZeroClaw
Các mục cấu hình thường dùng và giá trị mặc định.
Xác minh lần cuối: **2026-02-19**.
Thứ tự tìm config khi khởi động:
1. Biến `ZEROCLAW_WORKSPACE` (nếu được đặt)
2. Marker `~/.zeroclaw/active_workspace.toml` (nếu có)
3. Mặc định `~/.zeroclaw/config.toml`
ZeroClaw ghi log đường dẫn config đã giải quyết khi khởi động ở mức `INFO`:
- `Config loaded` với các trường: `path`, `workspace`, `source`, `initialized`
Lệnh xuất schema:
- `zeroclaw config schema` (xuất JSON Schema draft 2020-12 ra stdout)
## Khóa chính
| Khóa | Mặc định | Ghi chú |
|---|---|---|
| `default_provider` | `openrouter` | ID hoặc bí danh provider |
| `default_model` | `anthropic/claude-sonnet-4-6` | Model định tuyến qua provider đã chọn |
| `default_temperature` | `0.7` | Nhiệt độ model |
## `[observability]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `backend` | `none` | Backend quan sát: `none`, `noop`, `log`, `prometheus`, `otel`, `opentelemetry` hoặc `otlp` |
| `otel_endpoint` | `http://localhost:4318` | Endpoint OTLP HTTP khi backend là `otel` |
| `otel_service_name` | `zeroclaw` | Tên dịch vụ gửi đến OTLP collector |
Lưu ý:
- `backend = "otel"` dùng OTLP HTTP export với blocking exporter client để span và metric có thể được gửi an toàn từ context ngoài Tokio.
- Bí danh `opentelemetry` và `otlp` trỏ đến cùng backend OTel.
Ví dụ:
```toml
[observability]
backend = "otel"
otel_endpoint = "http://localhost:4318"
otel_service_name = "zeroclaw"
```
## Ghi đè provider qua biến môi trường
Provider cũng có thể chọn qua biến môi trường. Thứ tự ưu tiên:
1. `ZEROCLAW_PROVIDER` (ghi đè tường minh, luôn thắng khi có giá trị)
2. `PROVIDER` (dự phòng kiểu cũ, chỉ áp dụng khi provider trong config chưa đặt hoặc vẫn là `openrouter`)
3. `default_provider` trong `config.toml`
Lưu ý cho người dùng container:
- Nếu `config.toml` đặt provider tùy chỉnh như `custom:https://.../v1`, biến `PROVIDER=openrouter` mặc định từ Docker/container sẽ không thay thế nó.
- Dùng `ZEROCLAW_PROVIDER` khi cố ý muốn biến môi trường ghi đè provider đã cấu hình.
## `[agent]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `compact_context` | `false` | Khi bật: bootstrap_max_chars=6000, rag_chunk_limit=2. Dùng cho model 13B trở xuống |
| `max_tool_iterations` | `10` | Số vòng lặp tool-call tối đa mỗi tin nhắn trên CLI, gateway và channels |
| `max_history_messages` | `50` | Số tin nhắn lịch sử tối đa giữ lại mỗi phiên |
| `parallel_tools` | `false` | Bật thực thi tool song song trong một lượt |
| `tool_dispatcher` | `auto` | Chiến lược dispatch tool |
Lưu ý:
- Đặt `max_tool_iterations = 0` sẽ dùng giá trị mặc định an toàn `10`.
- Nếu tin nhắn kênh vượt giá trị này, runtime trả về: `Agent exceeded maximum tool iterations (<value>)`.
- Trong vòng lặp tool của CLI, gateway và channel, các lời gọi tool độc lập được thực thi đồng thời mặc định khi không cần phê duyệt; thứ tự kết quả giữ ổn định.
- `parallel_tools` áp dụng cho API `Agent::turn()`. Không ảnh hưởng đến vòng lặp runtime của CLI, gateway hay channel.
## `[agents.<name>]`
Cấu hình agent phụ (sub-agent). Mỗi khóa dưới `[agents]` định nghĩa một agent phụ có tên mà agent chính có thể ủy quyền.
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `provider` | _bắt buộc_ | Tên provider (ví dụ `"ollama"`, `"openrouter"`, `"anthropic"`) |
| `model` | _bắt buộc_ | Tên model cho agent phụ |
| `system_prompt` | chưa đặt | System prompt tùy chỉnh cho agent phụ (tùy chọn) |
| `api_key` | chưa đặt | API key tùy chỉnh (mã hóa khi `secrets.encrypt = true`) |
| `temperature` | chưa đặt | Temperature tùy chỉnh cho agent phụ |
| `max_depth` | `3` | Độ sâu đệ quy tối đa cho ủy quyền lồng nhau |
| `agentic` | `false` | Bật chế độ vòng lặp tool-call nhiều lượt cho agent phụ |
| `allowed_tools` | `[]` | Danh sách tool được phép ở chế độ agentic |
| `max_iterations` | `10` | Số vòng tool-call tối đa cho chế độ agentic |
Lưu ý:
- `agentic = false` giữ nguyên hành vi ủy quyền prompt→response đơn lượt.
- `agentic = true` yêu cầu ít nhất một mục khớp trong `allowed_tools`.
- Tool `delegate` bị loại khỏi allowlist của agent phụ để tránh vòng lặp ủy quyền.
```toml
[agents.researcher]
provider = "openrouter"
model = "anthropic/claude-sonnet-4-6"
system_prompt = "You are a research assistant."
max_depth = 2
agentic = true
allowed_tools = ["web_search", "http_request", "file_read"]
max_iterations = 8
[agents.coder]
provider = "ollama"
model = "qwen2.5-coder:32b"
temperature = 0.2
```
## `[runtime]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `reasoning_enabled` | chưa đặt (`None`) | Ghi đè toàn cục cho reasoning/thinking trên provider hỗ trợ |
Lưu ý:
- `reasoning_enabled = false` tắt tường minh reasoning phía provider cho provider hỗ trợ (hiện tại `ollama`, qua trường `think: false`).
- `reasoning_enabled = true` yêu cầu reasoning tường minh (`think: true` trên `ollama`).
- Để trống giữ mặc định của provider.
## `[skills]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `open_skills_enabled` | `false` | Cho phép tải/đồng bộ kho `open-skills` cộng đồng |
| `open_skills_dir` | chưa đặt | Đường dẫn cục bộ cho `open-skills` (mặc định `$HOME/open-skills` khi bật) |
Lưu ý:
- Mặc định an toàn: ZeroClaw **không** clone hay đồng bộ `open-skills` trừ khi `open_skills_enabled = true`.
- Ghi đè qua biến môi trường:
- `ZEROCLAW_OPEN_SKILLS_ENABLED` chấp nhận `1/0`, `true/false`, `yes/no`, `on/off`.
- `ZEROCLAW_OPEN_SKILLS_DIR` ghi đè đường dẫn kho khi có giá trị.
- Thứ tự ưu tiên: `ZEROCLAW_OPEN_SKILLS_ENABLED` → `skills.open_skills_enabled` trong `config.toml` → mặc định `false`.
## `[composio]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật công cụ OAuth do Composio quản lý |
| `api_key` | chưa đặt | API key Composio cho tool `composio` |
| `entity_id` | `default` | `user_id` mặc định gửi khi gọi connect/execute |
Lưu ý:
- Tương thích ngược: `enable = true` kiểu cũ được chấp nhận như bí danh cho `enabled = true`.
- Nếu `enabled = false` hoặc thiếu `api_key`, tool `composio` không được đăng ký.
- ZeroClaw yêu cầu Composio v3 tools với `toolkit_versions=latest` và thực thi với `version="latest"` để tránh bản tool mặc định cũ.
- Luồng thông thường: gọi `connect`, hoàn tất OAuth trên trình duyệt, rồi chạy `execute` cho hành động mong muốn.
- Nếu Composio trả lỗi thiếu connected-account, gọi `list_accounts` (tùy chọn với `app`) và truyền `connected_account_id` trả về cho `execute`.
## `[cost]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật theo dõi chi phí |
| `daily_limit_usd` | `10.00` | Giới hạn chi tiêu hàng ngày (USD) |
| `monthly_limit_usd` | `100.00` | Giới hạn chi tiêu hàng tháng (USD) |
| `warn_at_percent` | `80` | Cảnh báo khi chi tiêu đạt tỷ lệ phần trăm này |
| `allow_override` | `false` | Cho phép vượt ngân sách khi dùng cờ `--override` |
Lưu ý:
- Khi `enabled = true`, runtime theo dõi ước tính chi phí mỗi yêu cầu và áp dụng giới hạn ngày/tháng.
- Tại ngưỡng `warn_at_percent`, cảnh báo được gửi nhưng yêu cầu vẫn tiếp tục.
- Khi đạt giới hạn, yêu cầu bị từ chối trừ khi `allow_override = true` và cờ `--override` được truyền.
## `[identity]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `format` | `openclaw` | Định dạng danh tính: `"openclaw"` (mặc định) hoặc `"aieos"` |
| `aieos_path` | chưa đặt | Đường dẫn file AIEOS JSON (tương đối với workspace) |
| `aieos_inline` | chưa đặt | AIEOS JSON nội tuyến (thay thế cho đường dẫn file) |
Lưu ý:
- Dùng `format = "aieos"` với `aieos_path` hoặc `aieos_inline` để tải tài liệu danh tính AIEOS / OpenClaw.
- Chỉ nên đặt một trong hai `aieos_path` hoặc `aieos_inline`; `aieos_path` được ưu tiên.
## `[multimodal]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `max_images` | `4` | Số marker ảnh tối đa mỗi yêu cầu |
| `max_image_size_mb` | `5` | Giới hạn kích thước ảnh trước khi mã hóa base64 |
| `allow_remote_fetch` | `false` | Cho phép tải ảnh từ URL `http(s)` trong marker |
Lưu ý:
- Runtime chấp nhận marker ảnh trong tin nhắn với cú pháp: ``[IMAGE:<source>]``.
- Nguồn hỗ trợ:
- Đường dẫn file cục bộ (ví dụ ``[IMAGE:/tmp/screenshot.png]``)
- Data URI (ví dụ ``[IMAGE:data:image/png;base64,...]``)
- URL từ xa chỉ khi `allow_remote_fetch = true`
- Kiểu MIME cho phép: `image/png`, `image/jpeg`, `image/webp`, `image/gif`, `image/bmp`.
- Khi provider đang dùng không hỗ trợ vision, yêu cầu thất bại với lỗi capability có cấu trúc (`capability=vision`) thay vì bỏ qua ảnh.
## `[browser]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật tool `browser_open` (mở URL trong trình duyệt mặc định hệ thống, không thu thập dữ liệu) |
| `allowed_domains` | `[]` | Tên miền cho phép cho `browser_open` (khớp chính xác hoặc subdomain) |
| `session_name` | chưa đặt | Tên phiên trình duyệt (cho tự động hóa agent-browser) |
| `backend` | `agent_browser` | Backend tự động hóa: `"agent_browser"`, `"rust_native"`, `"computer_use"` hoặc `"auto"` |
| `native_headless` | `true` | Chế độ headless cho backend rust-native |
| `native_webdriver_url` | `http://127.0.0.1:9515` | URL endpoint WebDriver cho backend rust-native |
| `native_chrome_path` | chưa đặt | Đường dẫn Chrome/Chromium tùy chọn cho backend rust-native |
### `[browser.computer_use]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `endpoint` | `http://127.0.0.1:8787/v1/actions` | Endpoint sidecar cho hành động computer-use (chuột/bàn phím/screenshot cấp OS) |
| `api_key` | chưa đặt | Bearer token tùy chọn cho sidecar computer-use (mã hóa khi lưu) |
| `timeout_ms` | `15000` | Thời gian chờ mỗi hành động (mili giây) |
| `allow_remote_endpoint` | `false` | Cho phép endpoint từ xa/công khai cho sidecar |
| `window_allowlist` | `[]` | Danh sách cho phép tiêu đề cửa sổ/tiến trình gửi đến sidecar |
| `max_coordinate_x` | chưa đặt | Giới hạn trục X cho hành động dựa trên tọa độ (tùy chọn) |
| `max_coordinate_y` | chưa đặt | Giới hạn trục Y cho hành động dựa trên tọa độ (tùy chọn) |
Lưu ý:
- Khi `backend = "computer_use"`, agent ủy quyền hành động trình duyệt cho sidecar tại `computer_use.endpoint`.
- `allow_remote_endpoint = false` (mặc định) từ chối mọi endpoint không phải loopback để tránh lộ ra ngoài.
- Dùng `window_allowlist` để giới hạn cửa sổ OS mà sidecar có thể tương tác.
## `[http_request]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật tool `http_request` cho tương tác API |
| `allowed_domains` | `[]` | Tên miền cho phép (khớp chính xác hoặc subdomain) |
| `max_response_size` | `1000000` | Kích thước response tối đa (byte, mặc định: 1 MB) |
| `timeout_secs` | `30` | Thời gian chờ yêu cầu (giây) |
Lưu ý:
- Mặc định từ chối tất cả: nếu `allowed_domains` rỗng, mọi yêu cầu HTTP bị từ chối.
- Dùng khớp tên miền chính xác hoặc subdomain (ví dụ `"api.example.com"`, `"example.com"`).
## `[gateway]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `host` | `127.0.0.1` | Địa chỉ bind |
| `port` | `3000` | Cổng lắng nghe gateway |
| `require_pairing` | `true` | Yêu cầu ghép nối trước khi xác thực bearer |
| `allow_public_bind` | `false` | Chặn lộ public do vô ý |
## `[autonomy]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `level` | `supervised` | `read_only`, `supervised` hoặc `full` |
| `workspace_only` | `true` | Giới hạn ghi/lệnh trong phạm vi workspace |
| `allowed_commands` | _bắt buộc để chạy shell_ | Danh sách lệnh được phép |
| `forbidden_paths` | `[]` | Danh sách đường dẫn bị cấm |
| `max_actions_per_hour` | `100` | Ngân sách hành động mỗi giờ |
| `max_cost_per_day_cents` | `1000` | Giới hạn chi tiêu mỗi ngày (cent) |
| `require_approval_for_medium_risk` | `true` | Yêu cầu phê duyệt cho lệnh rủi ro trung bình |
| `block_high_risk_commands` | `true` | Chặn cứng lệnh rủi ro cao |
| `auto_approve` | `[]` | Thao tác tool luôn được tự động phê duyệt |
| `always_ask` | `[]` | Thao tác tool luôn yêu cầu phê duyệt |
Lưu ý:
- `level = "full"` bỏ qua phê duyệt rủi ro trung bình cho shell execution, nhưng vẫn áp dụng guardrail đã cấu hình.
- Phân tích toán tử/dấu phân cách shell nhận biết dấu ngoặc kép. Ký tự như `;` trong đối số được trích dẫn được xử lý là ký tự, không phải dấu phân cách lệnh.
- Toán tử chuỗi shell không trích dẫn vẫn được kiểm tra bởi policy (`;`, `|`, `&&`, `||`, chạy nền và chuyển hướng).
## `[memory]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `backend` | `sqlite` | `sqlite`, `lucid`, `markdown`, `none` |
| `auto_save` | `true` | Chỉ lưu đầu vào người dùng (đầu ra assistant bị loại) |
| `embedding_provider` | `none` | `none`, `openai` hoặc endpoint tùy chỉnh |
| `embedding_model` | `text-embedding-3-small` | ID model embedding, hoặc tuyến `hint:<name>` |
| `embedding_dimensions` | `1536` | Kích thước vector mong đợi cho model embedding đã chọn |
| `vector_weight` | `0.7` | Trọng số vector trong xếp hạng kết hợp |
| `keyword_weight` | `0.3` | Trọng số từ khóa trong xếp hạng kết hợp |
Lưu ý:
- Chèn ngữ cảnh memory bỏ qua khóa auto-save `assistant_resp*` kiểu cũ để tránh tóm tắt do model tạo bị coi là sự thật.
## `[[model_routes]]` và `[[embedding_routes]]`
Route hint giúp tên tích hợp ổn định khi model ID thay đổi.
### `[[model_routes]]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `hint` | _bắt buộc_ | Tên hint tác vụ (ví dụ `"reasoning"`, `"fast"`, `"code"`, `"summarize"`) |
| `provider` | _bắt buộc_ | Provider đích (phải khớp tên provider đã biết) |
| `model` | _bắt buộc_ | Model sử dụng với provider đó |
| `api_key` | chưa đặt | API key tùy chỉnh cho provider của route này (tùy chọn) |
### `[[embedding_routes]]`
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `hint` | _bắt buộc_ | Tên route hint (ví dụ `"semantic"`, `"archive"`, `"faq"`) |
| `provider` | _bắt buộc_ | Embedding provider (`"none"`, `"openai"` hoặc `"custom:<url>"`) |
| `model` | _bắt buộc_ | Model embedding sử dụng với provider đó |
| `dimensions` | chưa đặt | Ghi đè kích thước embedding cho route này (tùy chọn) |
| `api_key` | chưa đặt | API key tùy chỉnh cho provider của route này (tùy chọn) |
```toml
[memory]
embedding_model = "hint:semantic"
[[model_routes]]
hint = "reasoning"
provider = "openrouter"
model = "provider/model-id"
[[embedding_routes]]
hint = "semantic"
provider = "openai"
model = "text-embedding-3-small"
dimensions = 1536
```
Chiến lược nâng cấp:
1. Giữ hint ổn định (`hint:reasoning`, `hint:semantic`).
2. Chỉ cập nhật `model = "...phiên-bản-mới..."` trong mục route.
3. Kiểm tra bằng `zeroclaw doctor` trước khi khởi động lại/triển khai.
## `[query_classification]`
Tự động định tuyến tin nhắn đến hint `[[model_routes]]` theo mẫu nội dung.
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật phân loại truy vấn tự động |
| `rules` | `[]` | Quy tắc phân loại (đánh giá theo thứ tự ưu tiên) |
Mỗi rule trong `rules`:
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `hint` | _bắt buộc_ | Phải khớp giá trị hint trong `[[model_routes]]` |
| `keywords` | `[]` | Khớp chuỗi con không phân biệt hoa thường |
| `patterns` | `[]` | Khớp chuỗi chính xác phân biệt hoa thường (cho code fence, từ khóa như `"fn "`) |
| `min_length` | chưa đặt | Chỉ khớp nếu độ dài tin nhắn ≥ N ký tự |
| `max_length` | chưa đặt | Chỉ khớp nếu độ dài tin nhắn ≤ N ký tự |
| `priority` | `0` | Rule ưu tiên cao hơn được kiểm tra trước |
```toml
[query_classification]
enabled = true
[[query_classification.rules]]
hint = "reasoning"
keywords = ["explain", "analyze", "why"]
min_length = 200
priority = 10
[[query_classification.rules]]
hint = "fast"
keywords = ["hi", "hello", "thanks"]
max_length = 50
priority = 5
```
## `[channels_config]`
Cấu hình kênh cấp cao nằm dưới `channels_config`.
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `message_timeout_secs` | `300` | Thời gian chờ cơ bản (giây) cho xử lý tin nhắn kênh; runtime tự điều chỉnh theo độ sâu tool-loop (lên đến 4x) |
Ví dụ:
- `[channels_config.telegram]`
- `[channels_config.discord]`
- `[channels_config.whatsapp]`
- `[channels_config.email]`
Lưu ý:
- Mặc định `300s` tối ưu cho LLM chạy cục bộ (Ollama) vốn chậm hơn cloud API.
- Ngân sách timeout runtime là `message_timeout_secs * scale`, trong đó `scale = min(max_tool_iterations, 4)` và tối thiểu `1`.
- Việc điều chỉnh này tránh timeout sai khi lượt LLM đầu chậm/retry nhưng các lượt tool-loop sau vẫn cần hoàn tất.
- Nếu dùng cloud API (OpenAI, Anthropic, v.v.), có thể giảm xuống `60` hoặc thấp hơn.
- Giá trị dưới `30` bị giới hạn thành `30` để tránh timeout liên tục.
- Khi timeout xảy ra, người dùng nhận: `⚠️ Request timed out while waiting for the model. Please try again.`
- Hành vi ngắt chỉ Telegram được điều khiển bằng `channels_config.telegram.interrupt_on_new_message` (mặc định `false`).
Khi bật, tin nhắn mới từ cùng người gửi trong cùng chat sẽ hủy yêu cầu đang xử lý và giữ ngữ cảnh người dùng bị ngắt.
- Khi `zeroclaw channel start` đang chạy, thay đổi `default_provider`, `default_model`, `default_temperature`, `api_key`, `api_url` và `reliability.*` được áp dụng nóng từ `config.toml` ở tin nhắn tiếp theo.
Xem ma trận kênh và hành vi allowlist chi tiết tại [channels-reference.md](channels-reference.md).
### `[channels_config.whatsapp]`
WhatsApp hỗ trợ hai backend dưới cùng một bảng config.
Chế độ Cloud API (webhook Meta):
| Khóa | Bắt buộc | Mục đích |
|---|---|---|
| `access_token` | Có | Bearer token Meta Cloud API |
| `phone_number_id` | Có | ID số điện thoại Meta |
| `verify_token` | Có | Token xác minh webhook |
| `app_secret` | Tùy chọn | Bật xác minh chữ ký webhook (`X-Hub-Signature-256`) |
| `allowed_numbers` | Khuyến nghị | Số điện thoại cho phép gửi đến (`[]` = từ chối tất cả, `"*"` = cho phép tất cả) |
Chế độ WhatsApp Web (client gốc):
| Khóa | Bắt buộc | Mục đích |
|---|---|---|
| `session_path` | Có | Đường dẫn phiên SQLite lưu trữ lâu dài |
| `pair_phone` | Tùy chọn | Số điện thoại cho luồng pair-code (chỉ chữ số) |
| `pair_code` | Tùy chọn | Mã pair tùy chỉnh (nếu không sẽ tự tạo) |
| `allowed_numbers` | Khuyến nghị | Số điện thoại cho phép gửi đến (`[]` = từ chối tất cả, `"*"` = cho phép tất cả) |
Lưu ý:
- WhatsApp Web yêu cầu build flag `whatsapp-web`.
- Nếu cả Cloud lẫn Web đều có cấu hình, Cloud được ưu tiên để tương thích ngược.
## `[hardware]`
Cấu hình truy cập phần cứng vật lý (STM32, probe, serial).
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật truy cập phần cứng |
| `transport` | `none` | Chế độ truyền: `"none"`, `"native"`, `"serial"` hoặc `"probe"` |
| `serial_port` | chưa đặt | Đường dẫn cổng serial (ví dụ `"/dev/ttyACM0"`) |
| `baud_rate` | `115200` | Tốc độ baud serial |
| `probe_target` | chưa đặt | Chip đích cho probe (ví dụ `"STM32F401RE"`) |
| `workspace_datasheets` | `false` | Bật RAG datasheet workspace (đánh chỉ mục PDF schematic để AI tra cứu chân) |
Lưu ý:
- Dùng `transport = "serial"` với `serial_port` cho kết nối USB-serial.
- Dùng `transport = "probe"` với `probe_target` cho nạp qua debug-probe (ví dụ ST-Link).
- Xem [hardware-peripherals-design.md](hardware-peripherals-design.md) để biết chi tiết giao thức.
## `[peripherals]`
Bo mạch ngoại vi trở thành tool agent khi được bật.
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `enabled` | `false` | Bật hỗ trợ ngoại vi (bo mạch trở thành tool agent) |
| `boards` | `[]` | Danh sách cấu hình bo mạch |
| `datasheet_dir` | chưa đặt | Đường dẫn tài liệu datasheet (tương đối workspace) cho RAG |
Mỗi mục trong `boards`:
| Khóa | Mặc định | Mục đích |
|---|---|---|
| `board` | _bắt buộc_ | Loại bo mạch: `"nucleo-f401re"`, `"rpi-gpio"`, `"esp32"`, v.v. |
| `transport` | `serial` | Kiểu truyền: `"serial"`, `"native"`, `"websocket"` |
| `path` | chưa đặt | Đường dẫn serial: `"/dev/ttyACM0"`, `"/dev/ttyUSB0"` |
| `baud` | `115200` | Tốc độ baud cho serial |
```toml
[peripherals]
enabled = true
datasheet_dir = "docs/datasheets"
[[peripherals.boards]]
board = "nucleo-f401re"
transport = "serial"
path = "/dev/ttyACM0"
baud = 115200
[[peripherals.boards]]
board = "rpi-gpio"
transport = "native"
```
Lưu ý:
- Đặt file `.md`/`.txt` datasheet đặt tên theo bo mạch (ví dụ `nucleo-f401re.md`, `rpi-gpio.md`) trong `datasheet_dir` cho RAG.
- Xem [hardware-peripherals-design.md](hardware-peripherals-design.md) để biết giao thức bo mạch và ghi chú firmware.
## Giá trị mặc định liên quan bảo mật
- Allowlist kênh mặc định từ chối tất cả (`[]` nghĩa là từ chối tất cả)
- Gateway mặc định yêu cầu ghép nối
- Mặc định chặn public bind
## Lệnh kiểm tra
Sau khi chỉnh config:
```bash
zeroclaw status
zeroclaw doctor
zeroclaw channel doctor
zeroclaw service restart
```
## Tài liệu liên quan
- [channels-reference.md](channels-reference.md)
- [providers-reference.md](providers-reference.md)
- [operations-runbook.md](operations-runbook.md)
- [troubleshooting.md](troubleshooting.md)
docs/wasm-tools-guide.md
+689
View File
@@ -0,0 +1,689 @@
# WASM Tools Guide
This guide covers everything you need to build, install, and use WASM-based tools
(skills) in ZeroClaw. WASM tools let you extend the agent with custom capabilities
written in any language that compiles to WebAssembly — without modifying ZeroClaw's
core source code.
---
## Table of Contents
1. [How It Works](#1-how-it-works)
2. [Prerequisites](#2-prerequisites)
3. [Creating a Tool](#3-creating-a-tool)
- [Scaffold from template](#31-scaffold-from-template)
- [Protocol: stdin / stdout](#32-protocol-stdin--stdout)
- [manifest.json](#33-manifestjson)
- [Template: Rust](#34-template-rust)
- [Template: TypeScript](#35-template-typescript)
- [Template: Go](#36-template-go)
- [Template: Python](#37-template-python)
4. [Building](#4-building)
5. [Testing Locally](#5-testing-locally)
6. [Installing](#6-installing)
- [From a local path](#61-install-from-a-local-path)
- [From a git repository](#62-install-from-a-git-repository)
- [From ZeroMarket registry](#63-install-from-zeromarket-registry)
7. [How ZeroClaw Loads and Uses the Tool](#7-how-zeroclaw-loads-and-uses-the-tool)
8. [Directory Layout Reference](#8-directory-layout-reference)
9. [Configuration (`[wasm]` section)](#9-configuration-wasm-section)
10. [Security Model](#10-security-model)
11. [Troubleshooting](#11-troubleshooting)
---
## 1. How It Works
```
┌─────────────────────────────────────────────────────────────┐
│ Your WASM tool (.wasm binary) │
│ │
│ stdin ← JSON args from LLM │
│ stdout → JSON result { success, output, error } │
└───────────────────────┬─────────────────────────────────────┘
│ WASI stdio protocol
┌───────────────────────▼─────────────────────────────────────┐
│ ZeroClaw WASM engine (wasmtime + WASI) │
│ │
│ • loads tool.wasm + manifest.json from skills/ directory │
│ • registers the tool with the agent's tool registry │
│ • invokes the tool when the LLM selects it │
│ • enforces memory, fuel, and output size limits │
└─────────────────────────────────────────────────────────────┘
```
The key insight: **no custom SDK or ABI boilerplate**. Any language that can read
from stdin and write to stdout works. The only contract is the JSON shape described
in [section 2](#32-protocol-stdin--stdout).
---
## 2. Prerequisites
| Requirement | Purpose |
|---|---|
| ZeroClaw built with `--features wasm-tools` | Enables the WASM runtime |
| `wasmtime` CLI | Local testing (`zeroclaw skill test`) |
| Language-specific toolchain | Building `.wasm` from source |
Install `wasmtime` CLI:
```bash
# macOS / Linux
curl https://wasmtime.dev/install.sh -sSf | bash
# Or via cargo
cargo install wasmtime-cli
```
Enable WASM support at compile time:
```bash
cargo build --release --features wasm-tools
```
---
## 3. Creating a Tool
### 3.1 Scaffold from template
```bash
zeroclaw skill new <name> --template <typescript|rust|go|python>
```
Example:
```bash
zeroclaw skill new weather_lookup --template rust
```
This creates a new directory `./weather_lookup/` with all boilerplate files ready
to build. The `--template` flag defaults to `typescript` if omitted.
Supported templates:
| Template | Runtime | Build tool |
|---|---|---|
| `typescript` | Javy (JS → WASM) | `npm run build` |
| `rust` | native wasm32-wasip1 | `cargo build` |
| `go` | TinyGo | `tinygo build` |
| `python` | componentize-py | `componentize-py` |
---
### 3.2 Protocol: stdin / stdout
Every WASM tool must follow this single contract:
**Input** (written to the tool's stdin by ZeroClaw):
```json
{ "param1": "value1", "param2": 42 }
```
The shape of the input object is whatever you define in `manifest.json` under
`parameters`. ZeroClaw passes the LLM-provided argument object verbatim.
**Output** (read from the tool's stdout by ZeroClaw):
```json
{ "success": true, "output": "result text shown to LLM", "error": null }
{ "success": false, "output": "", "error": "reason" }
```
| Field | Type | Required | Description |
|---|---|---|---|
| `success` | bool | yes | `true` if tool completed normally |
| `output` | string | yes | Result text forwarded to the LLM |
| `error` | string or null | yes | Error message when `success` is `false` |
---
### 3.3 manifest.json
Every tool must ship a `manifest.json` alongside `tool.wasm`. This file tells
ZeroClaw the tool's name, description, and the JSON Schema for its parameters.
```json
{
"name": "weather_lookup",
"description": "Fetches the current weather for a given city name.",
"version": "1",
"parameters": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name to look up (e.g. Hanoi, Tokyo)"
},
"units": {
"type": "string",
"enum": ["metric", "imperial"],
"description": "Temperature unit system"
}
},
"required": ["city"]
},
"homepage": "https://github.com/yourname/weather_lookup"
}
```
| Field | Required | Description |
|---|---|---|
| `name` | yes | snake_case tool name exposed to the LLM |
| `description` | yes | Human-readable description (shown to LLM for tool selection) |
| `version` | no | Manifest format version, default `"1"` |
| `parameters` | yes | JSON Schema for the tool's input parameters |
| `homepage` | no | Optional URL shown in `zeroclaw skill list` |
The `name` field is the identifier the LLM uses when it decides to call your tool.
Keep it descriptive and unique.
---
### 3.4 Template: Rust
**Scaffolded files:** `Cargo.toml`, `src/lib.rs`, `.cargo/config.toml`
`src/lib.rs`:
```rust
use std::io::{self, Read, Write};
use serde::{Deserialize, Serialize};
#[derive(Deserialize)]
struct Args {
city: String,
#[serde(default)]
units: String,
}
#[derive(Serialize)]
struct ToolResult {
success: bool,
output: String,
error: Option<String>,
}
fn main() {
let mut buf = String::new();
io::stdin().read_to_string(&mut buf).unwrap();
let result = match serde_json::from_str::<Args>(&buf) {
Ok(args) => run(args),
Err(e) => ToolResult {
success: false,
output: String::new(),
error: Some(format!("invalid input: {e}")),
},
};
io::stdout()
.write_all(serde_json::to_string(&result).unwrap().as_bytes())
.unwrap();
}
fn run(args: Args) -> ToolResult {
// Your logic here
ToolResult {
success: true,
output: format!("Weather in {}: sunny 28°C", args.city),
error: None,
}
}
```
**Build:**
```bash
# Add the target once
rustup target add wasm32-wasip1
# Build
cargo build --target wasm32-wasip1 --release
cp target/wasm32-wasip1/release/weather_lookup.wasm tool.wasm
```
---
### 3.5 Template: TypeScript
**Scaffolded files:** `package.json`, `tsconfig.json`, `src/index.ts`
`src/index.ts`:
```typescript
// Read input from stdin (Javy provides Javy.IO)
const input = JSON.parse(
new TextDecoder().decode(Javy.IO.readSync())
);
function run(args: Record<string, unknown>): string {
const city = String(args["city"] ?? "");
// Your logic here
return `Weather in ${city}: sunny 28°C`;
}
try {
const output = run(input);
Javy.IO.writeSync(
new TextEncoder().encode(
JSON.stringify({ success: true, output, error: null })
)
);
} catch (err) {
Javy.IO.writeSync(
new TextEncoder().encode(
JSON.stringify({ success: false, output: "", error: String(err) })
)
);
}
```
**Build:**
```bash
# Install Javy: https://github.com/bytecodealliance/javy/releases
npm install
npm run build # → tool.wasm
```
---
### 3.6 Template: Go
**Scaffolded files:** `go.mod`, `main.go`
`main.go`:
```go
package main
import (
"encoding/json"
"fmt"
"io"
"os"
)
type Args struct {
City string `json:"city"`
Units string `json:"units"`
}
type ToolResult struct {
Success bool `json:"success"`
Output string `json:"output"`
Error *string `json:"error"`
}
func main() {
data, _ := io.ReadAll(os.Stdin)
var args Args
if err := json.Unmarshal(data, &args); err != nil {
msg := err.Error()
out, _ := json.Marshal(ToolResult{Error: &msg})
os.Stdout.Write(out)
return
}
result := run(args)
out, _ := json.Marshal(result)
os.Stdout.Write(out)
}
func run(args Args) ToolResult {
return ToolResult{
Success: true,
Output: fmt.Sprintf("Weather in %s: sunny 28°C", args.City),
}
}
```
**Build:**
```bash
# Install TinyGo: https://tinygo.org/getting-started/install/
tinygo build -o tool.wasm -target wasi .
```
---
### 3.7 Template: Python
**Scaffolded files:** `app.py`, `requirements.txt`
`app.py`:
```python
import sys
import json
def run(args: dict) -> str:
city = str(args.get("city", ""))
# Your logic here
return f"Weather in {city}: sunny 28°C"
def main():
raw = sys.stdin.read()
try:
args = json.loads(raw)
output = run(args)
result = {"success": True, "output": output, "error": None}
except Exception as exc:
result = {"success": False, "output": "", "error": str(exc)}
sys.stdout.write(json.dumps(result))
if __name__ == "__main__":
main()
```
**Build:**
```bash
pip install componentize-py
componentize-py -d wit/ -w zeroclaw-skill componentize app -o tool.wasm
```
---
## 4. Building
After editing your tool logic, build it into `tool.wasm`:
| Template | Build command | Output |
|---|---|---|
| Rust | `cargo build --target wasm32-wasip1 --release && cp target/wasm32-wasip1/release/*.wasm tool.wasm` | `tool.wasm` |
| TypeScript | `npm run build` | `tool.wasm` |
| Go | `tinygo build -o tool.wasm -target wasi .` | `tool.wasm` |
| Python | `componentize-py -d wit/ -w zeroclaw-skill componentize app -o tool.wasm` | `tool.wasm` |
The output must always be named `tool.wasm` at the root of the skill directory.
---
## 5. Testing Locally
Before installing, test the tool directly without starting the full ZeroClaw agent:
```bash
zeroclaw skill test . --args '{"city":"Hanoi","units":"metric"}'
```
You can also test an installed skill by name:
```bash
zeroclaw skill test weather_lookup --args '{"city":"Tokyo"}'
```
Or test a specific tool inside a multi-tool skill:
```bash
zeroclaw skill test . --tool my_tool_name --args '{"city":"Paris"}'
```
Under the hood, `skill test` pipes the JSON args into `wasmtime run tool.wasm` via
stdin and prints the raw stdout response. This lets you iterate quickly without
restarting the agent.
You can also test manually using `wasmtime` directly:
```bash
echo '{"city":"Hanoi"}' | wasmtime tool.wasm
```
Expected output:
```json
{"success":true,"output":"Weather in Hanoi: sunny 28°C","error":null}
```
---
## 6. Installing
### 6.1 Install from a local path
```bash
zeroclaw skill install ./weather_lookup
```
This copies your skill directory into `<workspace>/skills/weather_lookup/`.
ZeroClaw will auto-discover it on next startup.
### 6.2 Install from a git repository
```bash
zeroclaw skill install https://github.com/yourname/weather_lookup.git
```
ZeroClaw clones the repository into the skills directory and scans for WASM tools.
### 6.3 Install from ZeroMarket registry
```bash
# Format: namespace/package-name
zeroclaw skill install acme/weather-lookup
# With a specific version
zeroclaw skill install acme/weather-lookup@0.2.1
```
ZeroClaw fetches the package index from the configured registry URL, then downloads
`tool.wasm` and `manifest.json` for each tool in the package.
**Verify the install:**
```bash
zeroclaw skill list
```
---
## 7. How ZeroClaw Loads and Uses the Tool
### 7.1 Startup discovery
Every time the ZeroClaw agent starts, it scans the `skills/` directory and loads
all valid WASM tools automatically. No config change or restart command is needed
after installation.
```
<workspace>/
└── skills/
└── weather_lookup/ ← skill package root
├── SKILL.toml
└── tools/
└── weather_lookup/ ← individual tool directory
├── tool.wasm ← compiled WASM binary
└── manifest.json ← tool metadata
```
A simpler "dev layout" is also supported (useful right after building):
```
<workspace>/
└── skills/
└── weather_lookup/
├── tool.wasm
└── manifest.json
```
### 7.2 Tool registration
After discovery, each `WasmTool` is registered in the agent's tool registry
alongside built-in tools like `shell`, `file`, `web_fetch`, etc. The LLM sees
all registered tools equally — it has no way to distinguish a built-in tool from
a WASM plugin.
### 7.3 LLM tool selection
When a user sends a message, the agent attaches the full tool registry (including
all WASM tools) to the LLM context. The LLM reads each tool's `name` and
`description` from the manifest and decides which tool to call based on the
user's request.
Example conversation:
```
User: What is the weather in Hanoi right now?
Agent: [internally, LLM selects tool "weather_lookup" with args {"city":"Hanoi"}]
ZeroClaw calls weather_lookup WASM tool:
stdin → {"city":"Hanoi"}
stdout ← {"success":true,"output":"Weather in Hanoi: sunny 28°C","error":null}
Agent: The current weather in Hanoi is sunny with a temperature of 28°C.
```
### 7.4 Invocation flow
```
LLM decides to call "weather_lookup"
│
▼
WasmTool::execute(args: JSON)
│
├─ serialize args to stdin bytes
├─ spin up wasmtime WASI sandbox
├─ write stdin → WASM process
├─ read stdout ← WASM process (capped at 1 MiB)
├─ enforce fuel limit (≈ 1 billion instructions)
├─ enforce wall-clock timeout (30 seconds)
└─ deserialize ToolResult JSON
│
▼
Agent formats output and responds to user
```
### 7.5 Error handling
If a tool fails (non-zero exit, invalid JSON, timeout, fuel exhaustion), ZeroClaw
logs a warning and returns the error to the LLM. The agent continues running —
a broken plugin never crashes the process.
---
## 8. Directory Layout Reference
**Installed layout** (created by `zeroclaw skill install`):
```
skills/
└── <skill-name>/
├── SKILL.toml ← package metadata (shown in skill list)
└── tools/
└── <tool-name>/
├── tool.wasm ← WASM binary
└── manifest.json ← tool metadata
```
**Dev layout** (for quick iteration, right after `cargo build`):
```
skills/
└── <skill-name>/
├── tool.wasm
└── manifest.json
```
Both layouts are discovered automatically. Use dev layout while developing, switch
to installed layout for distribution.
---
## 9. Configuration (`[wasm]` section)
Add this section to your `zeroclaw.toml` to tune WASM tool behavior:
```toml
[wasm]
# Disable all WASM tools (default: true)
enabled = true
# Maximum memory per invocation in MiB, clamped 1–256 (default: 64)
memory_limit_mb = 64
# CPU fuel budget — roughly one unit per WASM instruction (default: 1_000_000_000)
fuel_limit = 1_000_000_000
# Registry URL used by `zeroclaw skill install namespace/package`
registry_url = "https://registry.zeromarket.dev"
```
To disable all WASM tools without uninstalling them:
```toml
[wasm]
enabled = false
```
---
## 10. Security Model
WASM tools run inside a strict WASI sandbox enforced by wasmtime:
| Constraint | Default |
|---|---|
| Filesystem access | **Denied** — no preopened directories |
| Network sockets | **Denied** — WASI network not enabled |
| Max memory | 64 MiB (configurable, max 256 MiB) |
| Max CPU instructions | ~1 billion (configurable) |
| Max wall-clock time | 30 seconds hard limit |
| Max output size | 1 MiB |
| Registry transport | HTTPS only — HTTP is rejected |
| Registry path traversal | Tool names validated before writing to disk |
A malicious or buggy WASM tool cannot:
- Read or write files on the host
- Make network connections
- Access environment variables
- Consume unbounded CPU or memory
- Crash the ZeroClaw process
---
## 11. Troubleshooting
**`WASM tools are not enabled in this build`**
Recompile with the feature flag:
```bash
cargo build --release
```
**`wasmtime` not found during `skill test`**
Install the wasmtime CLI:
```bash
curl https://wasmtime.dev/install.sh -sSf | bash
# or
cargo install wasmtime-cli
```
**`WASM module must export '_start'`**
Your binary must be compiled as a WASI executable (not a library). For Rust, ensure
your `Cargo.toml` does **not** set `crate-type = ["cdylib"]` — use the default
binary crate instead. For Go, use `tinygo build -target wasi` (not `wasm`).
**`WASM tool wrote nothing to stdout`**
Your tool exited without writing a JSON result. Check that your `run()` function
always writes to stdout before returning, including in error paths.
**Tool not appearing in `zeroclaw skill list`**
- Verify `manifest.json` exists alongside `tool.wasm`
- Validate the JSON is well-formed: `cat manifest.json | python3 -m json.tool`
- Restart the agent — tools are discovered at startup
**`curl failed` during registry install**
Ensure `curl` is installed and the registry URL uses HTTPS. Custom registries must
be reachable and return the expected package index JSON format.
extensions/hello-world/src/lib.rs
+121
View File
@@ -0,0 +1,121 @@
//! Hello World — example ZeroClaw plugin.
//!
//! Demonstrates the minimal plugin contract:
//! 1. Implement `Plugin` (manifest + register)
//! 2. In `register()`, use `PluginApi` to contribute tools and hooks
//!
//! To enable this plugin, add to `~/.zeroclaw/config.toml`:
//!
//! ```toml
//! [plugins]
//! enabled = true
//!
//! [plugins.entries.hello-world]
//! enabled = true
//! ```
use async_trait::async_trait;
use zeroclaw::hooks::{HookHandler, HookResult};
use zeroclaw::plugins::{Plugin, PluginApi, PluginManifest};
use zeroclaw::tools::traits::{Tool, ToolResult, ToolSpec};
// ── Manifest ─────────────────────────────────────────────────────────────────
fn manifest() -> PluginManifest {
PluginManifest {
id: "hello-world".into(),
name: Some("Hello World".into()),
description: Some("Example plugin demonstrating the ZeroClaw plugin API.".into()),
version: Some("0.1.0".into()),
config_schema: None,
}
}
// ── Tool ─────────────────────────────────────────────────────────────────────
/// A simple tool that greets the user.
struct HelloTool;
#[async_trait]
impl Tool for HelloTool {
fn name(&self) -> &str {
"hello"
}
fn description(&self) -> &str {
"Greet the user by name."
}
fn parameters_schema(&self) -> serde_json::Value {
serde_json::json!({
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name to greet"
}
},
"required": ["name"]
})
}
async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
let name = args
.get("name")
.and_then(|v| v.as_str())
.unwrap_or("world");
Ok(ToolResult {
success: true,
output: format!("Hello, {name}!"),
error: None,
})
}
}
// ── Hook ─────────────────────────────────────────────────────────────────────
/// A hook that logs when a session starts.
struct HelloHook;
#[async_trait]
impl HookHandler for HelloHook {
fn name(&self) -> &str {
"hello-world:session-logger"
}
async fn on_session_start(&self, session_id: &str, channel: &str) {
tracing::info!(
plugin = "hello-world",
session_id = %session_id,
channel = %channel,
"session started"
);
}
}
// ── Plugin ───────────────────────────────────────────────────────────────────
pub struct HelloWorldPlugin {
manifest: PluginManifest,
}
impl HelloWorldPlugin {
pub fn new() -> Self {
Self {
manifest: manifest(),
}
}
}
impl Plugin for HelloWorldPlugin {
fn manifest(&self) -> &PluginManifest {
&self.manifest
}
fn register(&self, api: &mut PluginApi) -> anyhow::Result<()> {
api.logger().info("registering hello-world plugin");
api.register_tool(Box::new(HelloTool));
api.register_hook(Box::new(HelloHook));
Ok(())
}
}
extensions/hello-world/zeroclaw.plugin.toml
+4
View File
@@ -0,0 +1,4 @@
id = "hello-world"
name = "Hello World"
description = "Example plugin demonstrating the ZeroClaw plugin API."
version = "0.1.0"
flake.nix
+30 -40
View File
@@ -8,54 +8,44 @@
nixpkgs.url = "nixpkgs/nixos-unstable";
};
outputs = { flake-utils, fenix, nixpkgs, ... }:
let
nixosModule = { pkgs, ... }: {
nixpkgs.overlays = [ fenix.overlays.default ];
environment.systemPackages = [
(pkgs.fenix.stable.withComponents [
"cargo"
"clippy"
"rust-src"
"rustc"
"rustfmt"
])
pkgs.rust-analyzer
];
};
in
flake-utils.lib.eachDefaultSystem (system:
outputs =
{
self,
flake-utils,
fenix,
nixpkgs,
}:
flake-utils.lib.eachDefaultSystem (
system:
let
pkgs = import nixpkgs {
inherit system;
overlays = [ fenix.overlays.default ];
overlays = [
fenix.overlays.default
(import ./overlay.nix)
];
};
rustToolchain = pkgs.fenix.stable.withComponents [
"cargo"
"clippy"
"rust-src"
"rustc"
"rustfmt"
];
in {
packages.default = fenix.packages.${system}.stable.toolchain;
in
{
formatter = pkgs.nixfmt-tree;
packages = {
default = self.packages.${system}.zeroclaw;
inherit (pkgs)
zeroclaw
zeroclaw-web
;
};
devShells.default = pkgs.mkShell {
inputsFrom = [ pkgs.zeroclaw ];
packages = [
rustToolchain
pkgs.rust-analyzer
];
};
}) // {
nixosConfigurations = {
nixos = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [ nixosModule ];
};
nixos-aarch64 = nixpkgs.lib.nixosSystem {
system = "aarch64-linux";
modules = [ nixosModule ];
};
};
}
)
// {
overlays.default = import ./overlay.nix;
};
}

Some files were not shown because too many files have changed in this diff Show More